@nority/bridge-sdk 0.2.0 → 0.2.1

package/README.md

@@ -68,18 +68,92 @@ const bridge = new NorityBridge({
   backendUrl: "wss://api.nority.ai/v1/bridge",
   dataDir: "./bridge-data",
   agent: new MyAdapter(),
-  onPairingToken: (info) => {
+  onPairingInfo: (info) => {
     console.log(`Pair: ${info.deeplinkUrl} (expires ${info.expiresAt})`);
   },
 });
 
 await bridge.start();
+// Bridge is now connected and handling conversations
 ```
 
-On first run, the SDK generates an Ed25519 identity, enters the pairing flow, and calls `onPairingToken` with a QR/deeplink URL. After the user approves in the Nority app, the bridge receives a durable credential and connects automatically.
+On first run, the SDK generates an Ed25519 identity, enters the pairing flow, and calls `onPairingInfo` with a QR/deeplink URL. `start()` blocks until the user approves in the Nority app and the bridge connects.
 
 On subsequent runs, the SDK loads the stored credential, mints a fresh JWT via challenge-response, reconnects, replays missed events, and resumes normal operation.
 
+## Layered API
+
+The SDK exposes three levels of abstraction. Most developers only need `NorityBridge`.
+
+### `NorityBridge` — managed (recommended)
+
+Handles everything: pairing, credential persistence, auth, transport, conversations. `start()` blocks until fully connected regardless of whether pairing was needed.
+
+```ts
+import { NorityBridge } from "@nority/bridge-sdk";
+
+const bridge = new NorityBridge({
+  backendUrl: "wss://api.nority.ai/v1/bridge",
+  dataDir: "./bridge-data",
+  agent: myAdapter,
+  onPairingInfo: (info) => console.log(`Scan: ${info.deeplinkUrl}`),
+});
+
+await bridge.start();   // blocks until connected
+await bridge.stop();    // graceful shutdown
+```
+
+### `PairingClient` — standalone pairing
+
+Use this when you want to control the pairing ceremony yourself — embed the QR in your own UI, store the credential in your own database, or skip pairing entirely with pre-provisioned credentials.
+
+```ts
+import { PairingClient } from "@nority/bridge-sdk";
+
+const pairing = new PairingClient({
+  backendUrl: "wss://api.nority.ai/v1/bridge",
+  dataDir: "./bridge-data",
+  onPairingInfo: (info) => renderQRCode(info.deeplinkUrl),
+});
+
+const result = await pairing.pair();  // blocks until user approves
+// result.credential — durable bridge credential
+// result.identity   — Ed25519 keypair
+// result.initialToken — first JWT (pass as seedJwt to BridgeConnection)
+```
+
+**Methods:**
+- `pair()` — performs the pairing ceremony. Resolves when the user approves. Single-flight (throws if called while already pairing).
+- `cancel()` — cancels in-progress pairing. Rejects the pending `pair()` promise. Idempotent.
+- `regenerateToken()` — closes the WebSocket, opens a new one, sends a fresh `pair_request`. Returns updated `PairingInfo`.
+- `getPairingInfo()` — returns current pairing info or `null`.
+
+### `BridgeConnection` — standalone connection
+
+Use this when you already have a credential (pre-provisioned from a dashboard, stored in your own secret manager, or obtained via `PairingClient`).
+
+```ts
+import { BridgeConnection } from "@nority/bridge-sdk";
+
+const connection = new BridgeConnection({
+  backendUrl: "wss://api.nority.ai/v1/bridge",
+  dataDir: "./bridge-data",
+  credential: process.env.BRIDGE_CREDENTIAL,
+  privateKeyPem: fs.readFileSync("./bridge-key.pem", "utf-8"),
+  agent: myAdapter,
+  seedJwt: cachedToken,  // optional — skip first challenge-response
+});
+
+await connection.connect();    // blocks until connected
+await connection.disconnect(); // graceful shutdown
+```
+
+**Methods:**
+- `connect()` — authenticates via challenge-response, opens authenticated WebSocket, sends replay request. Resolves when connected.
+- `disconnect()` — closes connection, stops reconnection, aborts active agent invocations. Idempotent.
+- `getState()` — returns current state (`idle | connecting | connected | reconnecting | blocked | failed | stopped`).
+- `createProactiveTurnFrame(conversationId, request)` — creates an `assistant_turn_start` frame for bridge-initiated turns.
+
 ## Key concepts
 
 | Concept | Description |
@@ -141,16 +215,56 @@ idle → pairing → connecting → connected
 
 ## Configuration
 
+### `BridgeConfig` (for `NorityBridge`)
+
 ```ts
 interface BridgeConfig {
-  backendUrl: string;            // Nority backend WebSocket URL
-  dataDir: string;               // Directory for durable state (identity, keys)
-  agent: AgentAdapter;           // Your adapter implementation
-  onPairingToken?: (info) => void;  // Called when pairing token is ready
-  logger?: BridgeLogger;         // Structured logging
-  webSocketFactory?: WebSocketFactory;  // Custom WebSocket creation
-  heartbeatIntervalMs?: number;  // Default: 15000
-  idleTimeoutMs?: number;        // Default: 45000
+  backendUrl: string;                          // Nority backend WebSocket URL
+  dataDir: string;                             // Directory for durable state (identity, keys)
+  agent: AgentAdapter;                         // Your adapter implementation
+  onPairingInfo?: (pairing: PairingInfo) => void; // Called when pairing token is ready
+  logger?: BridgeLogger;                       // Structured logging
+  webSocketFactory?: WebSocketFactory;         // Custom WebSocket creation
+  fetchImplementation?: typeof fetch;          // Custom fetch (for auth challenge-response)
+  clock?: () => Date;                          // Custom clock (for testing)
+  pairingTokenFactory?: () => string;          // Custom pairing token generator
+  backoffRandom?: () => number;                // Custom RNG for reconnect backoff jitter
+  heartbeatIntervalMs?: number;                // Default: 15000
+  idleTimeoutMs?: number;                      // Default: 45000
+}
+```
+
+### `PairingClientConfig`
+
+```ts
+interface PairingClientConfig {
+  backendUrl: string;
+  dataDir: string;
+  onPairingInfo?: (info: PairingInfo) => void;
+  logger?: BridgeLogger;
+  webSocketFactory?: WebSocketFactory;
+  clock?: () => Date;
+  pairingTokenFactory?: () => string;
+}
+```
+
+### `BridgeConnectionConfig`
+
+```ts
+interface BridgeConnectionConfig {
+  backendUrl: string;
+  dataDir: string;
+  credential: string;
+  privateKeyPem: string;
+  agent: AgentAdapter;
+  logger?: BridgeLogger;
+  seedJwt?: AccessTokenRecord;
+  fetchImplementation?: typeof fetch;
+  webSocketFactory?: WebSocketFactory;
+  clock?: () => Date;
+  backoffRandom?: () => number;
+  heartbeatIntervalMs?: number;
+  idleTimeoutMs?: number;
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nority/bridge-sdk",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Public SDK for building Nority bridge implementations",
   "main": "./dist/index.js",