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

# API reference

> Complete reference for all public exports from the TypeScript Bridge SDK

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](/docs/go-v2/developer-integration/sdks/typescript-sdk) 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:

```typescript theme={null}
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`).

```typescript theme={null}
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?)`

```typescript theme={null}
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()`

```typescript theme={null}
hasCapability(id: string): boolean
getCapability(id: string): CapabilityInfo | undefined
getCapabilities(): CapabilityMap
```

Check capabilities based on the last `discoverCapabilities()` result.

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

```typescript theme={null}
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)`

```typescript theme={null}
emit(action: string, data: Record<string, unknown>): void
```

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

#### `bridge.on(action, callback)`

```typescript theme={null}
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)`

```typescript theme={null}
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`

```typescript theme={null}
function detectEnvironment(): Environment
```

Detection order: `window` undefined → `standalone`, `webkit.messageHandlers.gbgBridge` → `ios`, `GBGBridge.postMessage` → `android`, `window !== window.parent` → `iframe`, otherwise `standalone`.

***

### `BridgeError`

```typescript theme={null}
class BridgeError extends Error {
  readonly code: BridgeErrorCode;
  readonly recoverable: boolean;
  readonly correlationId?: string;
}
```

See [Error handling](/docs/go-v2/developer-integration/sdks/typescript/error-handling) for all error codes and handling patterns.

***

### `CAPABILITY_IDS`

```typescript theme={null}
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

```typescript theme={null}
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`

```typescript theme={null}
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](/docs/go-v2/developer-integration/sdks/typescript/react) for detailed usage examples.