API reference - GBG Documentation

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>

Queries the host for available capabilities. Default timeout: 5,000 ms. Returns empty {} in standalone mode.

`bridge.hasCapability(id)` / `bridge.getCapability(id)` / `bridge.getCapabilities()`

hasCapability(id: string): boolean
getCapability(id: string): CapabilityInfo | undefined
getCapabilities(): CapabilityMap

Check capabilities based on the last discoverCapabilities() result.

`bridge.request(action, data, options?)`

async request(
  action: string,
  data: Record<string, unknown>,
  options?: RequestOptions,
): Promise<ResponsePayload>

Sends a request to the host and waits for a correlated response. Default timeout: 30,000 ms. Throws: BridgeError with appropriate code on timeout, error, unsupported, or cancelled status.

`bridge.emit(action, data)`

emit(action: string, data: Record<string, unknown>): void

Sends a fire-and-forget event to the host.

`bridge.on(action, callback)`

on(action: string, callback: (data: Record<string, unknown>) => void): () => void

Subscribes to events from the host. Returns an unsubscribe function.

`bridge.getMessageLog()` / `bridge.onMessageLog(callback)`

getMessageLog(): ReadonlyArray<BridgeMessage>
onMessageLog(callback: (message: BridgeMessage, direction: 'sent' | 'received') => void): () => void

Debugging tools. The log is capped at 500 messages. Only one onMessageLog callback at a time.

`bridge.destroy()`

Cleans up all resources. The instance is unusable after calling this.

`detectEnvironment`

function detectEnvironment(): Environment

Detection order: 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;
}

See Error handling for all error codes and handling patterns.

`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.

​Core package: @gbgplc-internal/ggo-native-bridge

​NativeBridge

​NativeBridge.getInstance(options?)

​NativeBridge.resetInstance()

​Properties

​bridge.discoverCapabilities(timeoutMs?)

​bridge.hasCapability(id) / bridge.getCapability(id) / bridge.getCapabilities()

​bridge.request(action, data, options?)

​bridge.emit(action, data)

​bridge.on(action, callback)

​bridge.getMessageLog() / bridge.onMessageLog(callback)

​bridge.destroy()

​detectEnvironment

​BridgeError

​CAPABILITY_IDS

​Types

​React package: @gbgplc-internal/ggo-native-bridge-react

​BridgeProvider

​useBridge()

​useCapability(capabilityId)

​useNativeCamera(type: 'document' | 'selfie')

​useBridgeEvent(action, callback)