Capability Handling

import { CAPABILITY_IDS } from "@gbg/go-bridge-web";
// CAPABILITY_IDS.CAMERA_DOCUMENT === "camera.document"

import { BridgeHostProvider } from "@gbg/go-bridge-web-react";
import { CAPABILITY_IDS } from "@gbg/go-bridge-web";

<BridgeHostProvider
  iframe={iframe}
  allowedOrigins={[...]}
  hostVersion="1.0.0"
  capabilities={{
    [CAPABILITY_IDS.CAMERA_DOCUMENT]: { supported: true, version: "1.0" },
    [CAPABILITY_IDS.CAMERA_SELFIE]: { supported: true, version: "1.0" },
  }}
>
  {/* ... */}
</BridgeHostProvider>

import { useBridgeCapability } from "@gbg/go-bridge-web-react";

function DocumentCaptureHandler() {
  useBridgeCapability("camera.document.capture", {
    handle: async (request, responder) => {
      const data = (request.payload as { data: Record<string, unknown> }).data;
      const side = data.side as string;
      const image = await captureDocument(side);
      responder.success({ image });
    },
  });
  return null;
}

capability ID  →  appears in capabilities prop, capability.query response
                  e.g. "camera.document"

action ID      →  appears in useBridgeCapability(...), payload.action
                  e.g. "camera.document.capture"

import { useBridgeHost } from "@gbg/go-bridge-web-react";
import { useEffect } from "react";

function NFCSupport() {
  const host = useBridgeHost();
  useEffect(() => {
    if (!host) return;
    if (!("NDEFReader" in window)) return; // browser doesn't support NFC

    host.registerCustomCapability("nfc.read", "1.0", {
      handle: async (_request, responder) => {
        try {
          const reader = new (window as any).NDEFReader();
          const chipData = await reader.scan();
          responder.success({ mrz: chipData.mrz });
        } catch (err) {
          responder.error({
            code: "INTERNAL_ERROR",
            message: String(err),
            recoverable: true,
          });
        }
      },
    });
  }, [host]);
  return null;
}

constructorCapabilities ∪ (customCapabilities \ keys(constructorCapabilities))

useBridgeCapability("camera.document.capture", {
  handle: async (_request, responder) => {
    const image = await captureDocument();
    responder.success({ imageBase64: image, mimeType: "image/jpeg" });
  },
});

handle: async (_request, responder) => {
  responder.acknowledge();
  const result = await reallyLongRunningCapture(); // 10+ seconds
  responder.success({ image: result });
}

handle: async (_request, responder) => {
  await iThrowSometimes(); // throws → SDK responds with HANDLER_FAILURE
  responder.success({}); // never reached
}

{
  "status": "error",
  "error": {
    "code": "HANDLER_FAILURE",
    "message": "...",
    "recoverable": false
  }
}

async function getCameraPermissionState(): Promise<string> {
  if (!navigator.permissions) return "prompt"; // older browsers
  try {
    const status = await navigator.permissions.query({ name: "camera" as PermissionName });
    return status.state; // "granted" | "denied" | "prompt"
  } catch {
    return "prompt";
  }
}

function JourneyView({ journeyUrl }: { journeyUrl: string }) {
  const [iframe, setIframe] = useState<HTMLIFrameElement | null>(null);
  const [permissionState, setPermissionState] = useState("prompt");

  useEffect(() => {
    getCameraPermissionState().then(setPermissionState);
  }, []);

  return (
    <BridgeHostProvider
      key={permissionState}  // remount on permission change to apply
      iframe={iframe}
      allowedOrigins={[new URL(journeyUrl).origin]}
      hostVersion="1.0.0"
      capabilities={{
        "camera.document": {
          supported: true,
          version: "1.0",
          permissionState,
        },
      }}
    >
      <DocumentCaptureHandler />
      <iframe ref={setIframe} src={journeyUrl} allow="camera" />
    </BridgeHostProvider>
  );
}

const status = await navigator.permissions.query({ name: "camera" as PermissionName });
status.onchange = () => {
  setPermissionState(status.state);
};

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

capabilities: {
  "camera.document": { supported: true, version: "1.0" },
  "nfc.read": { supported: false, version: null },
  "biometric.auth": { supported: false, version: null },
}

If host declares camera.document.supported = true:
    Journey delegates capture to host via bridge
Else:
    Journey runs in-iframe capture using getUserMedia

If camera.document.permissionState == "denied":
    Show "Camera access is blocked — enable it in browser settings"
    before starting the capture step

useBridgeCapability("camera.document.capture", {
  handle: async (_request, responder) => {
    if (!navigator.mediaDevices) {
      responder.unsupported("Camera API not available in this browser");
      return;
    }
    // ... proceed with capture
  },
});

import { useBridgeCapability } from "@gbg/go-bridge-web-react";
import { useRef, useState } from "react";
import type { BridgeResponder } from "@gbg/go-bridge-web";

function DocumentCaptureHandler() {
  const responderRef = useRef<BridgeResponder | null>(null);
  const [active, setActive] = useState(false);

  useBridgeCapability("camera.document.capture", {
    handle: async (_request, responder) => {
      if (responderRef.current) {
        responder.error({
          code: "BUSY",
          message: "A document capture is already in progress",
          recoverable: true,
        });
        return;
      }
      responderRef.current = responder;
      setActive(true);
    },
  });

  function complete(image: string) {
    responderRef.current?.success({ imageBase64: image });
    responderRef.current = null;
    setActive(false);
  }

  // ... render capture UI when active
}