API reference

package com.gbg.gbgbridge.core

public class BridgeHost(
  public val configuration: BridgeConfiguration,
  capabilitiesProvider: (() -> Map<String, BridgeCapabilityInfo>)? = null,
)

public constructor(hostVersion: String)

val host = BridgeHost(hostVersion = "1.0.0")

// Declare support by setting handlers
host.documentCapture.handler = { request ->
  host.documentCapture.awaitCompletion()
}

public constructor(
  configuration: BridgeConfiguration,
  capabilitiesProvider: (() -> Map<String, BridgeCapabilityInfo>)? = null,
)

val host = BridgeHost(
  configuration = BridgeConfiguration(
    hostVersion = "1.0.0",
    capabilities = mapOf(
      "camera.document" to BridgeCapabilityInfo(supported = true, version = "1.0"),
    ),
  ),
)

val host = BridgeHost(
  configuration = BridgeConfiguration(hostVersion = "1.0.0"),
  capabilitiesProvider = {
    mapOf(
      "nfc.read" to BridgeCapabilityInfo(
        supported = nfcAdapter?.isEnabled == true,
        version = "1.0",
      ),
    )
  },
)

public val configuration: BridgeConfiguration

public var delegate: BridgeHostDelegate?

public val capabilities: Map<String, BridgeCapabilityInfo>

public val receivedMessages: List<BridgeMessage>

public val pendingRequests: List<BridgeMessage>

public var lastError: String? // private set

public val documentCapture: CaptureCapability

public val selfieCapture: CaptureCapability

public fun attach(
  webView: WebView,
  client: BridgeWebViewConfigurator.BootstrapInjectingWebViewClient? = null,
)

val webView = WebView(context)
host.attach(webView)
webView.loadUrl(journeyUrl)

public fun detach()

public fun dispose()

override fun onDestroy() {
  try {
    bridgeHost.dispose()
  } catch (e: Exception) {
    Log.w("Bridge", "dispose() failed during teardown", e)
  }
  super.onDestroy()
}

public fun register(handler: BridgeCapabilityHandler)

host.register(DocumentCaptureHandler())

public fun unregister(action: String)

public fun registerCustomCapability(
  action: String,
  version: String? = null,
  handler: (BridgeMessage, BridgeResponder) -> Unit,
)

host.registerCustomCapability("nfc.read", version = "1.0") { request, responder ->
  // Handle NFC read request
  responder.respond(
    status = BridgeResponseStatus.SUCCESS,
    data = mapOf("chipRead" to JsonPrimitive(true)),
  )
}

public fun sendEvent(action: String, data: Map<String, JsonElement>? = null)

host.sendEvent(
  action = "host.ready",
  data = mapOf("timestamp" to JsonPrimitive(System.currentTimeMillis())),
)

public fun respond(
  to: String,
  status: BridgeResponseStatus,
  data: Map<String, JsonElement>? = null,
  error: BridgeErrorPayload? = null,
)

host.respond(
  to = request.correlationId,
  status = BridgeResponseStatus.SUCCESS,
  data = mapOf("imageBase64" to JsonPrimitive(base64Image)),
)

public fun respond(
  to: String,
  action: String,
  status: BridgeResponseStatus,
  data: Map<String, JsonElement>? = null,
  error: BridgeErrorPayload? = null,
)

public fun clearError()

package com.gbg.gbgbridge.webview

public object BridgeWebViewConfigurator

public fun configure(
  webView: WebView,
  bootstrapScript: String? = null,
  client: BootstrapInjectingWebViewClient? = null,
)

window.GBGBridge = window.GBGBridge || {}; window.GBGBridge.receive = window.GBGBridge.receive || function(){};

public open class BootstrapInjectingWebViewClient(
  private val bootstrapScript: String,
) : WebViewClient()

class JourneyClient(bootstrap: String) : BootstrapInjectingWebViewClient(bootstrap) {
  override fun shouldOverrideUrlLoading(
    view: WebView, request: WebResourceRequest
  ): Boolean {
    val url = request.url ?: return true
    return url.host != "journey.example.com"
  }
}

host.attach(webView, client = JourneyClient(myBootstrap))

package com.gbg.gbgbridge.capabilities

public class CaptureCapability(
  public val id: String,
  public val actionId: String,
  initialVersion: String? = null,
)

public fun buildCapabilityInfo(): BridgeCapabilityInfo

public suspend fun awaitCompletion(): CaptureResult

host.documentCapture.handler = { request ->
  showCaptureUi()
  host.documentCapture.awaitCompletion()
}

public fun complete(result: CaptureResult)

// In a camera capture callback (after hopping to the main thread):
host.documentCapture.complete(
  CaptureResult.Document(
    imageData = imageBytes,
    width = 1920,
    height = 1080,
  ),
)

public fun cancelIfBusy(reason: String = "Request cancelled")

public sealed class CaptureResult

public data class Document(
  val imageData: ByteArray,
  val width: Int,
  val height: Int,
  val mimeType: String = "image/png",
) : CaptureResult()

{
  "imageBase64": "<base64-encoded image>",
  "imageWidth": 1920,
  "imageHeight": 1080,
  "mimeType": "image/png"
}

public data class Selfie(
  val previewImageData: ByteArray,
  val width: Int,
  val height: Int,
  val mimeType: String = "image/jpeg",
  val encryptedBlob: ByteArray,
  val unencryptedBlob: ByteArray,
) : CaptureResult()

{
  "imageBase64": "<base64>",
  "imageWidth": 640,
  "imageHeight": 480,
  "mimeType": "image/jpeg",
  "encryptedBlobBase64": "<base64>",
  "unencryptedBlobBase64": "<base64>"
}

public data class Cancelled(val reason: String) : CaptureResult()

public data class Failed(
  val code: String,
  val message: String,
  val recoverable: Boolean,
) : CaptureResult()

public enum class PermissionState(public val wireValue: String)

public object CameraDetector

public fun check(context: Context): CameraDetector.Result

public data class Result(
  val hardwareAvailable: Boolean,
  val permissionState: PermissionState,
)

val camera = CameraDetector.check(context)
host.documentCapture.permissionState = camera.permissionState
host.selfieCapture.permissionState = camera.permissionState

package com.gbg.gbgbridge.core

public data class BridgeConfiguration(
  val hostVersion: String,
  val capabilities: Map<String, BridgeCapabilityInfo> = emptyMap(),
  val bootstrapScript: String? = null,
  val allowedOrigins: List<String>? = null,
)

@Serializable
public data class BridgeCapabilityInfo(
  val supported: Boolean,
  val version: String? = null,
  val constraints: Map<String, JsonElement>? = null,
  val permissionState: String? = null,
)

@Serializable
public data class BridgeMessage(
  val version: String,
  val correlationId: String,
  val type: BridgeMessageType,
  val timestamp: Long,
  val payload: BridgePayload,
)

@Serializable
public data class BridgePayload(
  val action: String,
  val data: Map<String, JsonElement>? = null,
  val status: BridgeResponseStatus? = null,
  val error: BridgeErrorPayload? = null,
  val options: BridgeRequestOptions? = null,
)

@Serializable
public data class BridgeErrorPayload(
  val code: String,
  val message: String,
  val recoverable: Boolean,
)

@Serializable
public data class BridgeRequestOptions(
  val timeout: Double? = null,
  val fallbackAllowed: Boolean? = null,
)

@Serializable
public enum class BridgeMessageType

@Serializable
public enum class BridgeResponseStatus

import kotlinx.serialization.json.*

val data: Map<String, JsonElement> = mapOf(
  "name" to JsonPrimitive("John Doe"),
  "age" to JsonPrimitive(30),
  "verified" to JsonPrimitive(true),
  "documents" to buildJsonArray {
    addJsonObject {
      put("type", "passport")
      put("number", "AB123456")
    }
  },
  "metadata" to JsonNull,
)

val side = request.payload.data?.get("side")?.jsonPrimitive?.contentOrNull
val attempts = request.payload.data?.get("attempts")?.jsonPrimitive?.intOrNull

public interface BridgeCapabilityHandler {
  public val action: String

  @MainThread
  public fun handle(request: BridgeMessage, responder: BridgeResponder)
}

public val action: String

public fun handle(request: BridgeMessage, responder: BridgeResponder)

class DocumentCaptureHandler : BridgeCapabilityHandler {
  override val action = "camera.document.capture"

  override fun handle(request: BridgeMessage, responder: BridgeResponder) {
    // Extract parameters from the request
    val side = request.payload.data?.get("side")?.jsonPrimitive?.contentOrNull

    // Launch asynchronous capture (your implementation), retaining the responder
    captureDocument(
      onSuccess = { imageBytes ->
        Handler(Looper.getMainLooper()).post {
          responder.respond(
            status = BridgeResponseStatus.SUCCESS,
            data = mapOf(
              "imageBase64" to JsonPrimitive(
                Base64.encodeToString(imageBytes, Base64.NO_WRAP)
              ),
            ),
          )
        }
      },
      onFailure = { error ->
        Handler(Looper.getMainLooper()).post {
          responder.respond(
            status = BridgeResponseStatus.ERROR,
            error = BridgeErrorPayload(
              code = "CAPTURE_FAILED",
              message = error.message ?: "Capture failed",
              recoverable = true,
            ),
          )
        }
      },
    )
  }
}

public interface BridgeResponder {
  @MainThread
  public fun respond(
    status: BridgeResponseStatus,
    data: Map<String, JsonElement>? = null,
    error: BridgeErrorPayload? = null,
  )
}

public interface BridgeHostDelegate {
  public fun onMessage(host: BridgeHost, message: BridgeMessage) {}

  public fun onMessageSent(host: BridgeHost, message: BridgeMessage) {}

  public fun onUnhandledRequest(host: BridgeHost, request: BridgeMessage) {}

  public fun onError(host: BridgeHost, error: Throwable) {}
}

public class CapabilityQueryHandler(
  private val capabilitiesProvider: () -> Map<String, BridgeCapabilityInfo>,
  private val hostVersion: String,
) : BridgeCapabilityHandler

{
  "environment": "android",
  "hostVersion": "1.0.0",
  "capabilities": {
    "camera.document": {
      "supported": true,
      "version": "1.0",
      "permissionState": "granted"
    },
    "camera.selfie": {
      "supported": false,
      "version": null
    }
  }
}