Documentation Index
Fetch the complete documentation index at: https://docs.go.gbgplc.com/llms.txt
Use this file to discover all available pages before exploring further.
This reference covers every public export in the TypeScript Bridge SDK — the core @gbgplc-internal/ggo-native-bridge package and the React bindings in @gbgplc-internal/ggo-native-bridge-react. Use it alongside the TypeScript Bridge SDK overview when you need exact type signatures, options, or return shapes.
Core package: @gbgplc-internal/ggo-native-bridge
The package is published as an ES module with no dependencies and runs in the browser only. The example import below names the public exports referenced throughout the rest of this section:
import {
NativeBridge, detectEnvironment, BridgeError, BridgeErrorCode,
toBridgeErrorCode, CAPABILITY_IDS,
} from '@gbgplc-internal/ggo-native-bridge';
NativeBridge
The main bridge class. Singleton — use NativeBridge.getInstance() to obtain the instance.
NativeBridge.getInstance(options?)
Returns the singleton bridge instance. Creates it on the first call; subsequent calls return the existing instance (ignoring options).
static getInstance(options?: NativeBridgeOptions): NativeBridge
| Parameter | Type | Default | Description |
|---|
options.environment | Environment | Auto-detected | Override environment detection |
options.channel | MessageChannel | Auto-created | Custom transport channel (testing) |
options.iframeAllowedOrigins | string[] | [] | Allowed origins for incoming iframe messages |
options.iframeTargetOrigin | string | window.location.origin | Target origin for outgoing iframe messages |
NativeBridge.resetInstance()
Destroys the current singleton and resets to null. For testing only.
Properties
| Property | Type | Description |
|---|
environment | Environment | The detected host environment |
isEmbedded | boolean | true for ios, android, iframe; false for standalone |
bridge.discoverCapabilities(timeoutMs?)
async discoverCapabilities(timeoutMs?: number): Promise<CapabilityMap>
{} in standalone mode.
bridge.hasCapability(id) / bridge.getCapability(id) / bridge.getCapabilities()
hasCapability(id: string): boolean
getCapability(id: string): CapabilityInfo | undefined
getCapabilities(): CapabilityMap
discoverCapabilities() result.
bridge.request(action, data, options?)
async request(
action: string,
data: Record<string, unknown>,
options?: RequestOptions,
): Promise<ResponsePayload>
BridgeError with appropriate code on timeout, error, unsupported, or cancelled status.
bridge.emit(action, data)
emit(action: string, data: Record<string, unknown>): void
bridge.on(action, callback)
on(action: string, callback: (data: Record<string, unknown>) => void): () => void
bridge.getMessageLog() / bridge.onMessageLog(callback)
getMessageLog(): ReadonlyArray<BridgeMessage>
onMessageLog(callback: (message: BridgeMessage, direction: 'sent' | 'received') => void): () => void
onMessageLog callback at a time.
bridge.destroy()
Cleans up all resources. The instance is unusable after calling this.
detectEnvironment
function detectEnvironment(): Environment
window undefined → standalone, webkit.messageHandlers.gbgBridge → ios, GBGBridge.postMessage → android, window !== window.parent → iframe, otherwise standalone.
BridgeError
class BridgeError extends Error {
readonly code: BridgeErrorCode;
readonly recoverable: boolean;
readonly correlationId?: string;
}
CAPABILITY_IDS
const CAPABILITY_IDS: {
readonly CAMERA_DOCUMENT: 'camera.document';
readonly CAMERA_SELFIE: 'camera.selfie';
readonly NFC_READ: 'nfc.read';
readonly BIOMETRIC_AUTH: 'biometric.auth';
readonly DEVICE_ATTESTATION: 'device.attestation';
readonly LOCATION_GPS: 'location.gps';
readonly STORAGE_SECURE: 'storage.secure';
readonly ANALYTICS_FORWARD: 'analytics.forward';
}
Types
type Environment = 'ios' | 'android' | 'iframe' | 'standalone';
type BridgeMessageType = 'request' | 'response' | 'event';
type ResponseStatus = 'success' | 'error' | 'cancelled' | 'unsupported' | 'acknowledged';
interface CapabilityInfo {
supported: boolean;
version?: string;
constraints?: Record<string, unknown>;
permissionState?: string;
}
type CapabilityMap = Record<string, CapabilityInfo>;
interface RequestOptions {
timeout?: number;
fallbackAllowed?: boolean;
}
interface BridgeMessage {
version: '1.0';
correlationId: string;
type: BridgeMessageType;
timestamp: number;
payload: RequestPayload | ResponsePayload | EventPayload;
}
interface MessageChannel {
send(message: BridgeMessage): void;
onMessage(callback: (message: BridgeMessage) => void): void;
destroy(): void;
}
React package: @gbgplc-internal/ggo-native-bridge-react
Peer dependencies: react@19.x, @gbgplc-internal/ggo-native-bridge@>=0.1.0
import {
BridgeProvider, useBridge, useCapability, useNativeCamera, useBridgeEvent,
} from '@gbgplc-internal/ggo-native-bridge-react';
BridgeProvider
| Prop | Type | Default | Description |
|---|
children | ReactNode | — | Child components |
options | NativeBridgeOptions | undefined | Options passed to NativeBridge.getInstance() |
discoverOnMount | boolean | true | Auto-discover capabilities on mount |
useBridge()
Returns BridgeContextValue:
| Field | Type | Description |
|---|
bridge | NativeBridge | The bridge singleton |
environment | Environment | Detected environment |
isEmbedded | boolean | Whether inside a host |
capabilities | CapabilityMap | Discovered capabilities |
capabilitiesReady | boolean | true once discovery completes |
hasCapability | (id: string) => boolean | Check capability support |
useCapability(capabilityId)
Returns { supported: boolean; ready: boolean; version?: string }.
useNativeCamera(type: 'document' | 'selfie')
Returns { isNativeAvailable: boolean; requestCapture: (data?) => Promise<ResponsePayload> }.
Uses 120-second timeout and fallbackAllowed: true. Works outside <BridgeProvider> (returns isNativeAvailable: false).
useBridgeEvent(action, callback)
Subscribes to host events. Manages lifecycle automatically. Uses useRef internally so the callback doesn’t need memoization.
See React hooks guide for detailed usage examples.
