@robono/linked-apps 0.1.0-preview.1 → 0.1.0-preview.3

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+# 0.1.0-preview.3
+
+- `watch()` now uses an authenticated persistent WebSocket and automatic recovery.
+- Acknowledgements follow successful processing and cursor persistence. Reconnects
+  replay missed events; token refresh and account switching are handled explicitly.
+- Remove `configureBackgroundDelivery`, `verifyWebhook` and `pollIntervalMs`.
+  No webhook delivery option remains. Use a backend watcher for your own app's push.
+- Global WebSocket is used in supported runtimes; other hosts can inject a factory.
+- Self-service registration and code pairing require no delivery endpoint setup.
+
+# 0.1.0-preview.2
+
+- Add `beginPairing`, `pollPairing`, and cancellable `waitForPairing`.
+- Codes expire after five minutes and require owner approval in Robono.
+- Bind exchange to the originating client and PKCE verifier, enforce polling backoff,
+  and serialize concurrent polls. Existing callback and messaging APIs remain supported.
+- Pairing uses the existing Robono login. No extra SMS check or callback URL required.
+
 # Changelog
 
 ## 0.1.0-preview.1

package/INTEGRATION.md

@@ -1,19 +1,25 @@
 # Integrating an independent app
 
-Use a separate registration for development and production. Robono supplies its
-functions URL, client ID and reviewed redirect URI/scopes. Client IDs are public.
-A backend webhook signing secret is confidential and must never enter a mobile bundle.
+Register at https://www.robono.com/linked-apps/manage. Developer signup, email
+verification and two-factor authentication are self-service. Registration returns an
+active client ID and functions URL immediately. No Bridge organization, subscription,
+API key or manual activation is required. Use separate development and production
+registrations. Client IDs are public; each user must still approve account access.
+Live updates use an authenticated connection opened by your SDK. No incoming endpoint or delivery configuration is required.
 
-## Link an account
+## Link an account with a code
+
+Use SDK 0.1.0-preview.3 or newer for persistent connections. The currently registered
+client ID is public; users never need a developer account. Pairing-only clients
+use an empty `redirect_uris` list and do not need callback URLs.
 
 ```ts
 import { RobonoLinkedApps, secureTokenStore, nativeCryptoProvider } from '@robono/linked-apps';
 import * as SecureStore from 'expo-secure-store';
 import * as Crypto from 'expo-crypto';
-import { Linking } from 'react-native';
 
-const ot = new RobonoLinkedApps({
-  functionsUrl: config.robonoFunctionsUrl,
+const robono = new RobonoLinkedApps({
+  functionsUrl: 'https://vzoqxavqacydtwypjsrd.supabase.co/functions/v1',
   clientId: config.robonoClientId,
   tokenStore: secureTokenStore(SecureStore, 'robono.linked.account.primary'),
   crypto: nativeCryptoProvider({
@@ -21,39 +27,58 @@ const ot = new RobonoLinkedApps({
     digest: (_, bytes) => Crypto.digest(Crypto.CryptoDigestAlgorithm.SHA256, new Uint8Array(bytes)),
   }),
 });
-const link = await ot.beginLink('com.example.app://robono/callback',
+const pairing = await robono.beginPairing(
   ['account:read', 'messages:read', 'messages:send', 'receipts:write']);
-// Keep the verifier/state in Keychain/Keystore across the app switch.
-await SecureStore.setItemAsync('robono.pending-link', JSON.stringify(link.pending));
-await Linking.openURL(link.authorizationUrl);
-// In your callback handler, after matching the registered route:
-const pending = JSON.parse((await SecureStore.getItemAsync('robono.pending-link'))!);
-await ot.completeLink(callbackUrl, pending);
-await SecureStore.deleteItemAsync('robono.pending-link');
+// Show pairing.userCode with a five-minute expiry indication.
+// Tell the user: Robono > Linked apps > Connect an app > enter this code.
+// Optional: open pairing.verificationAppUrl to take them to Robono.
+await SecureStore.setItemAsync('robono.pending-pair', JSON.stringify(pairing.pending));
+const controller = new AbortController();
+// Abort when this screen closes, the account changes, or the app backgrounds.
+const tokens = await robono.waitForPairing(pairing.pending, controller.signal);
+await SecureStore.deleteItemAsync('robono.pending-pair');
+// Connected. Tokens are already saved by the configured TokenStore.
 ```
 
-The native adapters are dependency-injected: bare React Native can supply equivalent
-Keychain/Keystore and cryptography implementations. Never use Math.random or ordinary
-AsyncStorage for credentials/verifiers. Choose platform key accessibility according
-to your app's background needs; never opt into backup/sync of account secrets.
-
-Register the callback on **both iOS and Android**. Prefer an owned HTTPS universal/app
-link where possible. Private native schemes must be unique reverse-domain names;
-PKCE protects code redemption from interception. Never accept arbitrary callback
-hosts, skip state verification, or copy a Robono phone session into your app.
-
-Only one SDK instance owns a connected account's refresh sequence. Multiple runtimes
-or processes must coordinate access to secure storage. A lost refresh response or
-crash before the rotated pair is persisted may require relinking; retrying a spent
-refresh token revokes the grant. Do not automatically repeat token exchanges.
+If backgrounded while the user opens Robono, cancel polling, preserve pending
+state securely, then resume `waitForPairing` on foreground if it has not expired.
+Use one poller per pairing and one SDK instance per connected account. You can
+call `pollPairing` directly; it returns `pending` or `connected` and updates the
+pending state's interval and next-poll time. Persist those updates if resuming
+across process restarts. Network failures are surfaced: offer a retry with
+backoff while the code remains valid. Never spin on errors.
+
+Robono authenticates the owner using its existing phone session. A signed-out
+user signs in through Robono's normal login first. There is no extra SMS check
+for account linking. The code does not itself authorize access: the user must
+review the app, account, and permissions and choose Allow connection in Robono.
+Never request the user's Robono login code, password, or phone-session token.
+
+The visible code expires after five minutes. The device code and PKCE verifier
+are secrets; never show, log, put them in URLs, or send them to analytics. Native
+clients use Keychain/Keystore; browser/server hosts must supply equivalent secure
+storage. Only the app that initiated pairing can exchange the approved request.
+Do not call completion repeatedly after receiving tokens. If the successful
+exchange response is lost, start a new pairing; a consumed code cannot be reused.
+
+HTTP clients: POST `linked-app-pair` with client_id, scopes, S256 code_challenge
+and code_challenge_method. Poll `linked-app-token` using grant_type
+`urn:ietf:params:oauth:grant-type:device_code`, client_id, device_code and
+code_verifier. Wait at least the returned interval (initially five seconds).
+`authorization_pending` means keep waiting; `slow_down` increases the interval
+by five seconds (up to sixty). Stop on `access_denied`, `expired_token`, or
+`invalid_grant`. A 429 requires backoff. Only a successful response contains tokens.
+
+The older registered-callback `beginLink` / `completeLink` APIs remain supported
+for existing clients. New code pairing requires no callback handler.
 
 ## Display and send
 
 ```ts
-const snapshot = await ot.conversations();
-const page = await ot.messages(conversationId, { limit: 50 });
+const snapshot = await robono.conversations();
+const page = await robono.messages(conversationId, { limit: 50 });
 // Generate and persist this ID before sending; use it again on every retry.
-const result = await ot.send({ conversationId, messageKind: 'text',
+const result = await robono.send({ conversationId, messageKind: 'text',
   clientMessageId: durableOutgoingId, textBody: 'Hello' });
 ```
 
@@ -78,10 +103,10 @@ actual listening. Use `delivered` and `read` for their corresponding user states
 
 ```ts
 const controller = new AbortController();
-const watching = ot.watch({
+const watching = robono.watch({
   signal: controller.signal,
   cursorStore: persistedCursors, // keyed by grant ID
-  onResync: async () => reconcile(await ot.conversations()),
+  onResync: async () => reconcile(await robono.conversations()),
   onEvents: async events => {
     // Deduplicate message IDs. Fetch only relevant current pages; remove unavailable
     // or deleted content. Do not notify for receipt-only events or your own messages.
@@ -100,42 +125,67 @@ reported. Walkie-talkie replacement can invalidate an earlier message even if it
 was previously downloaded. Read all pages with `has_more` using both returned page
 markers; preserve microsecond timestamps as strings. Do not synthesize timestamps.
 
-Polling stores its cursor only after successful processing. A callback can run again
+The watcher stores its cursor only after successful processing. A callback can run again
 after a crash, so make local writes idempotent. Failed callbacks keep the previous
 cursor. Abort does not advance past unfinished work. Grant changes terminate the old
 watcher; cursors and cached data must never move to a different account.
 
-## Background notices
+## Live connections and background notifications
 
-1. Configure a reviewed HTTPS backend webhook with Robono.
-2. Your backend associates a grant with an authenticated account in your own service.
-   Verify it by calling `account.get` using that account's linked token; never trust
-   a client-supplied grant ID to route another user's notifications.
-3. Call `configureBackgroundDelivery(true)` after the mapping is ready.
-4. Verify the **raw** webhook body before parsing/queuing it:
+`watch()` opens a TLS WebSocket to `/linked-app-stream`, authenticates with the
+linked account token, and resumes from its saved cursor. The SDK reconnects with
+backoff, including routine server rotation. No webhook is offered.
 
-```ts
-import { verifyWebhook } from '@robono/linked-apps';
-const hint = await verifyWebhook({ body: rawBody,
-  timestamp: request.headers.get('x-robono-timestamp')!,
-  signature: request.headers.get('x-robono-signature')!,
-  secret: backendOnlySigningKey });
-// Check expected client_id; atomically deduplicate hint.id and enqueue the hint.
-// Return 2xx only after the queue write commits.
-```
+Modern browsers, React Native and Node.js 22+ supply WebSocket. Other runtimes may
+inject `webSocket: url => new WebSocketImplementation(url)` in the SDK constructor.
+Do not disable TLS verification. Stop a phone's watcher when backgrounded; resume
+it on foreground. A phone operating system can suspend its sockets.
+
+For notifications while your phone app is suspended, your backend can run the same
+watcher and send a content-free hint through your app's APNs/FCM/Expo credentials.
+This uses an outbound connection to Robono, with no URL to register. First verify
+the account/grant using `account()` before routing hints to your own user's devices.
+Disclose server-side account access and protect its credentials. Use one token
+owner to coordinate refreshes; do not let independent phone/server processes rotate
+the same refresh token. Relay through that owner, or pair separately for each host.
+
+Keep separate cursor stores for independent consumers. Maximum three connections
+per grant. Events are retained for seven days. A longer absence triggers a fresh
+snapshot, not silent event loss. Callbacks must be idempotent. The stream carries
+change IDs, not message content; fetch the authoritative messages via the API.
+Keep companion hints silent by default to avoid duplicating Robono's alerts.
+Background execution and notification timing remain subject to iOS/Android rules.
 
-The signature covers `timestamp + '.' + rawBody` with HMAC-SHA256, accepted within
-five minutes. Delivery IDs remain stable across retries; attempt timestamps change.
-Reject replayed IDs after verification, check client identity, limit request size and
-retain dedup IDs for at least seven days. Invalid signatures receive no processing.
+### Protocol for clients not using the SDK
 
-5. Send a content-free sync hint through **your app's** APNs/FCM/Expo credentials.
-6. On wake/resume, call `events(cursor)` or restart `watch`; do not trust a webhook's
-   cursor as proof you already applied earlier events. Never overwrite the local
-   cursor with the pushed cursor. Keep Robono notifications as the default alert and
-   companion hints silent to avoid duplicate sounds.
+Connect to `wss://vzoqxavqacydtwypjsrd.supabase.co/functions/v1/linked-app-stream`
+without query parameters. Within ten seconds send this JSON text frame:
+
+```json
+{"type":"authenticate","version":1,"access_token":"rla_…","cursor":null}
+```
 
-Disconnect: call `ot.disconnect()`; clear your local cached account content and stop
+Use the last successfully processed cursor string, or null for initial sync. Never
+put tokens in URLs or subprotocols. Require `messages:read` permission. The server
+sends `{"type":"ready","grant_id":"…","heartbeat_seconds":15}`; verify the grant.
+A `{"type":"page","page":…}` frame contains the same page as `events.poll`.
+For initial sync or `resync_required`, reconcile conversations and current histories.
+Otherwise apply its events, preserving their order and deduplicating IDs. Save the
+page cursor only after processing succeeds, then send
+`{"type":"ack","cursor":"<saved cursor>"}`. There is at most one outstanding page
+and at most 100 events per page. ACK within 60 seconds or reconnect from the previous
+saved cursor. Respond to `{"type":"ping"}` with `{"type":"pong"}`.
+
+On `{"type":"reconnect"}`, reconnect with jitter from your saved cursor. The
+current hosting environment rotates connections after about 85 seconds. The SDK
+handles this. An error frame contains `error` and HTTP-style `status`; stop on
+invalid/revoked credentials or insufficient permission. Back off on temporary
+failures/rate limits. Rotate nearly expired access tokens through the existing
+refresh API, then reconnect. Messages retained during interruptions are replayed.
+`events(cursor)` remains available for a one-time reconciliation; `watch()` uses
+the persistent connection rather than repeatedly polling the HTTP API.
+
+Disconnect: call `robono.disconnect()`; clear your local cached account content and stop
 watchers after revocation succeeds. A lost response may require retry/relink UI; a
 user can always revoke from Robono's Linked apps screen. Account deletion, revoked
 permissions or `invalid_token` must not trigger repeated unauthorized background work.

package/README.md

@@ -1,12 +1,12 @@
 # @robono/linked-apps
 
 Robono's user-authorized messaging API client, for independent applications.
-Developer preview. Requires a reviewed app registration and an activated Robono environment.
+Developer preview. Register your app at https://www.robono.com/linked-apps/manage to receive an active client ID. Each user must approve their own Robono account connection.
 SDK installation alone does not enable account access.
 
 Supports PKCE account linking, rotating credentials, typed conversations/messages,
 text/voice/file sending, signed media upload/download, receipts, resumable change
-watching, backend delivery subscription, webhook verification and revocation.
+watching over authenticated WebSockets and revocation.
 No dependency on Matrix, TalkOpen, Loop, Expo or a specific UI framework.
 
 Build/test from the repository:
@@ -17,8 +17,10 @@ npm --prefix packages/linked-apps test
 
 Use one `RobonoLinkedApps` instance per connected account. Inject a Keychain/Keystore
 `TokenStore` and native `CryptoProvider`; adapters are exported. Browser/server
-runtimes may use WebCrypto. Securely persist pending PKCE verifier/state before
-opening Robono; validate the callback using `completeLink`.
+runtimes may use WebCrypto. Use `beginPairing` to obtain a code, show it to the user, then call
+`waitForPairing` to finish after approval in Robono. Store pending state securely.
+Robono reuses its normal login; account linking adds no SMS verification.
+Registered callback linking remains available for existing clients.
 
 [Integration guide](./INTEGRATION.md) ·
 [API reference](https://robono.com/api-reference-viewer.html?spec=linked-apps) ·
@@ -26,10 +28,11 @@ opening Robono; validate the callback using `completeLink`.
 
 The watcher is explicit and cancellable. Stop on background/logout; resume on a push
 hint or foreground. It checkpoints only after successful consumer callbacks, so
-callbacks must tolerate redelivery. Backends verify webhook signatures and deduplicate
-stable delivery IDs before pushing through their own app credentials. Never ship a
-webhook signing key in mobile code. Hints contain no message text and should not
-produce sounds by themselves.
+callbacks must tolerate redelivery. The SDK opens the connection, authenticates without
+putting tokens in URLs, and reconnects from the last saved cursor. No webhook setup
+or delivery endpoint is supported. For background notifications, a developer backend
+can run the watcher and use its own app's push credentials. Phone sockets may be
+suspended by the operating system. See the integration guide for secure token ownership.
 
 Send retries must retain the original UUID. Refresh requests are serialized within
 one instance; coordinate across processes yourself. A lost refresh response can
@@ -40,7 +43,7 @@ require relinking because reusing a spent refresh token revokes the grant.
 The official distribution channel is npm. Install this exact preview version:
 
 ```sh
-npm install --save-exact @robono/linked-apps@0.1.0-preview.1
+npm install --save-exact @robono/linked-apps@0.1.0-preview.3
 ```
 
 Preview releases use the `preview` tag. Pin the version and commit your lockfile; review release notes and test before updating. The Robono website does not distribute SDK archives.

package/dist/delivery.d.ts

@@ -24,7 +24,6 @@ export interface WatchOptions {
     /** Reconcile the conversation list and currently open message pages. */
     onResync(): Promise<void>;
     onError?(error: unknown): void;
-    pollIntervalMs?: number;
 }
 export declare function waitForPoll(ms: number, signal: AbortSignal): Promise<void>;
 /** Dependency injection keeps the SDK usable in Expo and bare native apps. */

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import { type EventPage, type WatchOptions } from "./delivery.js";
+import { type LinkedSocketFactory } from "./stream.js";
 import type { ConversationPage, Message, MessagePage, Receipt, UploadTicket } from "./types.js";
 export * from "./types.js";
 export * from "./delivery.js";
-export * from "./webhook.js";
+export type { LinkedSocket, LinkedSocketFactory } from "./stream.js";
 export type Scope = "account:read" | "messages:read" | "messages:send" | "receipts:write";
 export type Tokens = {
     accessToken: string;
@@ -28,6 +29,21 @@ export interface PendingLink {
     state: string;
     expiresAt: string;
 }
+/** Secret pending state: keep in secure storage, never display or log it. */
+export interface PendingPairing {
+    clientId: string;
+    deviceCode: string;
+    verifier: string;
+    expiresAt: string;
+    interval: number;
+    nextPollAt: number;
+}
+export type PairingResult = {
+    status: "pending";
+} | {
+    status: "connected";
+    tokens: Tokens;
+};
 export interface SendMessage {
     conversationId: string;
     messageKind: "text" | "voice" | "image" | "video" | "document";
@@ -58,6 +74,7 @@ export declare class RobonoLinkedApps {
     private readonly options;
     private readonly baseUrl;
     private readonly fetcher;
+    private pairingPolls;
     private refreshPending;
     constructor(options: {
         functionsUrl: string;
@@ -66,8 +83,27 @@ export declare class RobonoLinkedApps {
         crypto?: CryptoProvider;
         fetch?: typeof fetch;
         timeoutMs?: number;
+        webSocket?: LinkedSocketFactory;
     });
     private post;
+    /** Show only userCode. The user approves inside their signed-in Robono app. */
+    beginPairing(scopes: Scope[], signal?: AbortSignal): Promise<{
+        userCode: string;
+        verificationUrl: string;
+        verificationAppUrl: string;
+        pending: {
+            clientId: string;
+            deviceCode: string;
+            verifier: string;
+            expiresAt: string;
+            interval: number;
+            nextPollAt: number;
+        };
+    }>;
+    /** Returns pending until approval. Concurrent calls share one token exchange. */
+    pollPairing(pending: PendingPairing, signal?: AbortSignal): Promise<PairingResult>;
+    /** Cancel when leaving the pairing screen. Never polls in the background implicitly. */
+    waitForPairing(pending: PendingPairing, signal: AbortSignal): Promise<Tokens>;
     beginLink(redirectUri: string, scopes: Scope[]): Promise<{
         authorizationUrl: string;
         requestId: string;
@@ -116,11 +152,9 @@ export declare class RobonoLinkedApps {
         receipts: Receipt[];
     }>;
     events(cursor: string | null, signal?: AbortSignal): Promise<EventPage>;
-    configureBackgroundDelivery(enabled: boolean): Promise<{
-        enabled: boolean;
-    }>;
-    /** Run while active; stop on background, resume on foreground or a push hint.
-     * Callbacks must tolerate redelivery. Cursor advances only after success.
+    /** Open a live connection, replay missed events, and reconnect automatically.
+     * On phones, stop on suspension/logout; a backend may keep watching for push.
+     * Checkpoints and acknowledgements happen only after successful callbacks.
      */
     watch(options: WatchOptions): Promise<void>;
     disconnect(): Promise<void>;

package/dist/index.js

@@ -1,7 +1,7 @@
 import { waitForPoll } from "./delivery.js";
+import { consumeStream } from "./stream.js";
 export * from "./types.js";
 export * from "./delivery.js";
-export * from "./webhook.js";
 export class RobonoLinkedAppError extends Error {
     code;
     status;
@@ -47,6 +47,7 @@ export class RobonoLinkedApps {
     options;
     baseUrl;
     fetcher;
+    pairingPolls = new Map();
     refreshPending = null;
     constructor(options) {
         this.options = options;
@@ -92,6 +93,90 @@ export class RobonoLinkedApps {
             signal?.removeEventListener("abort", cancel);
         }
     }
+    /** Show only userCode. The user approves inside their signed-in Robono app. */
+    async beginPairing(scopes, signal) {
+        if (!scopes.length || scopes.some((scope) => !scopeNames.has(scope))) {
+            throw new Error("Select supported permissions.");
+        }
+        const crypto = this.options.crypto ?? webCryptoProvider();
+        const verifier = hex(crypto.randomBytes(32));
+        const challenge = base64url(await crypto.sha256(new TextEncoder().encode(verifier)));
+        const result = await this.post("linked-app-pair", {
+            client_id: this.options.clientId, scopes,
+            code_challenge: challenge, code_challenge_method: "S256",
+        }, undefined, signal);
+        const interval = Math.max(5, result.interval);
+        return {
+            userCode: result.user_code,
+            verificationUrl: result.verification_uri,
+            verificationAppUrl: result.verification_app_uri,
+            pending: {
+                clientId: this.options.clientId, deviceCode: result.device_code, verifier,
+                expiresAt: result.expires_at, interval, nextPollAt: Date.now() + interval * 1000,
+            },
+        };
+    }
+    /** Returns pending until approval. Concurrent calls share one token exchange. */
+    async pollPairing(pending, signal) {
+        if (pending.clientId !== this.options.clientId ||
+            !Number.isFinite(Date.parse(pending.expiresAt)) ||
+            Date.parse(pending.expiresAt) <= Date.now()) {
+            throw new RobonoLinkedAppError("expired_token", 400);
+        }
+        if (signal?.aborted)
+            throw new RobonoLinkedAppError("cancelled", 400);
+        const existing = this.pairingPolls.get(pending.deviceCode);
+        if (existing)
+            return existing;
+        if (Date.now() < pending.nextPollAt)
+            return { status: "pending" };
+        const operation = (async () => {
+            pending.nextPollAt = Date.now() + Math.max(5, pending.interval) * 1000;
+            try {
+                const wire = await this.post("linked-app-token", {
+                    client_id: this.options.clientId,
+                    grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+                    device_code: pending.deviceCode, code_verifier: pending.verifier,
+                }, undefined, signal);
+                const tokens = await this.save(wire);
+                return { status: "connected", tokens };
+            }
+            catch (error) {
+                if (error instanceof RobonoLinkedAppError &&
+                    ["authorization_pending", "slow_down"].includes(error.code)) {
+                    if (error.code === "slow_down")
+                        pending.interval = Math.min(60, pending.interval + 5);
+                    return { status: "pending" };
+                }
+                throw error;
+            }
+            finally {
+                pending.nextPollAt = Date.now() + Math.max(5, pending.interval) * 1000;
+            }
+        })();
+        this.pairingPolls.set(pending.deviceCode, operation);
+        try {
+            return await operation;
+        }
+        finally {
+            this.pairingPolls.delete(pending.deviceCode);
+        }
+    }
+    /** Cancel when leaving the pairing screen. Never polls in the background implicitly. */
+    async waitForPairing(pending, signal) {
+        while (!signal.aborted) {
+            if (Date.parse(pending.expiresAt) <= Date.now()) {
+                throw new RobonoLinkedAppError("expired_token", 400);
+            }
+            await waitForPoll(Math.max(0, Math.min(pending.nextPollAt, Date.parse(pending.expiresAt)) - Date.now()), signal);
+            if (signal.aborted)
+                break;
+            const result = await this.pollPairing(pending, signal);
+            if (result.status === "connected")
+                return result.tokens;
+        }
+        throw new RobonoLinkedAppError("cancelled", 400);
+    }
     async beginLink(redirectUri, scopes) {
         if (!scopes.length || scopes.some((scope) => !scopeNames.has(scope))) {
             throw new Error("Select supported permissions.");
@@ -270,52 +355,72 @@ export class RobonoLinkedApps {
     events(cursor, signal) {
         return this.call("events.poll", { cursor }, signal);
     }
-    configureBackgroundDelivery(enabled) {
-        return this.call("delivery.configure", { enabled });
-    }
-    /** Run while active; stop on background, resume on foreground or a push hint.
-     * Callbacks must tolerate redelivery. Cursor advances only after success.
+    /** Open a live connection, replay missed events, and reconnect automatically.
+     * On phones, stop on suspension/logout; a backend may keep watching for push.
+     * Checkpoints and acknowledgements happen only after successful callbacks.
      */
     async watch(options) {
-        const tokens = await this.options.tokenStore.get();
-        if (!tokens)
+        const initial = await this.options.tokenStore.get();
+        if (!initial)
             throw new RobonoLinkedAppError("not_connected", 401);
-        const grantId = tokens.grantId;
-        let cursor = await options.cursorStore.get(grantId);
+        const grantId = initial.grantId;
+        const factory = this.options.webSocket ?? ((url) => new WebSocket(url));
+        if (!this.options.webSocket && typeof globalThis.WebSocket !== "function") {
+            throw new Error("Provide a WebSocket implementation for this runtime.");
+        }
+        const streamUrl = this.baseUrl.replace(/^http/, "ws") + "/linked-app-stream";
+        const current = async () => {
+            const tokens = await this.options.tokenStore.get();
+            if (!tokens || tokens.grantId !== grantId)
+                throw new RobonoLinkedAppError("not_connected", 401);
+            return tokens;
+        };
         let failures = 0;
         while (!options.signal.aborted) {
+            let sessionToken = "";
             try {
-                const current = await this.options.tokenStore.get();
-                if (!current || current.grantId !== grantId) {
+                let tokens = await current();
+                if (tokens.expiresAt <= Date.now() + 30_000)
+                    tokens = await this.refresh();
+                if (tokens.grantId !== grantId)
                     throw new RobonoLinkedAppError("not_connected", 401);
-                }
-                const page = await this.events(cursor, options.signal);
-                if (options.signal.aborted)
-                    return;
-                if (cursor === null || page.resync_required)
-                    await options.onResync();
-                else if (page.events.length)
-                    await options.onEvents(page.events);
+                sessionToken = tokens.accessToken;
+                let cursor = await options.cursorStore.get(grantId);
+                await consumeStream({ url: streamUrl, factory, tokens, cursor, signal: options.signal,
+                    onPage: async (page) => {
+                        await current();
+                        if (options.signal.aborted)
+                            return;
+                        if (cursor === null || page.resync_required)
+                            await options.onResync();
+                        else if (page.events.length)
+                            await options.onEvents(page.events);
+                        await current();
+                        if (options.signal.aborted)
+                            return;
+                        await options.cursorStore.set(grantId, page.cursor);
+                        cursor = page.cursor;
+                        failures = 0;
+                    },
+                });
                 if (options.signal.aborted)
                     return;
-                await options.cursorStore.set(grantId, page.cursor);
-                cursor = page.cursor;
-                failures = 0;
-                if (page.has_more)
-                    continue;
             }
             catch (error) {
                 if (options.signal.aborted)
                     return;
-                if (error instanceof RobonoLinkedAppError &&
-                    [400, 401, 403].includes(error.status))
+                if (error instanceof RobonoLinkedAppError && error.code === "invalid_token") {
+                    const tokens = await current();
+                    // Another request may have rotated the token used by this socket.
+                    if (tokens.accessToken !== sessionToken || tokens.expiresAt <= Date.now() + 30_000)
+                        continue;
+                }
+                if (error instanceof RobonoLinkedAppError && [400, 401, 403].includes(error.status))
                     throw error;
                 options.onError?.(error);
                 failures++;
             }
-            await waitForPoll(failures
-                ? Math.min(30_000, 1000 * 2 ** Math.min(failures, 5))
-                : Math.max(1000, options.pollIntervalMs ?? 1000), options.signal);
+            await waitForPoll(failures ? Math.min(30_000, 1000 * 2 ** Math.min(failures, 5)) : 250 + Math.floor(Math.random() * 500), options.signal);
         }
     }
     async disconnect() {

package/dist/stream.d.ts

@@ -0,0 +1,14 @@
+import { type Tokens } from "./index.js";
+import type { EventPage } from "./delivery.js";
+/** Supported by browser, React Native and modern Node WebSocket implementations. */
+export type LinkedSocket = Pick<WebSocket, "readyState" | "onopen" | "onmessage" | "onerror" | "onclose" | "send" | "close">;
+export type LinkedSocketFactory = (url: string) => LinkedSocket;
+/** One connection; the caller owns replay/checkpoints and reconnect backoff. */
+export declare function consumeStream(input: {
+    url: string;
+    factory: LinkedSocketFactory;
+    tokens: Tokens;
+    cursor: string | null;
+    signal: AbortSignal;
+    onPage(page: EventPage): Promise<void>;
+}): Promise<void>;

package/dist/stream.js

@@ -0,0 +1,84 @@
+import { RobonoLinkedAppError } from "./index.js";
+/** One connection; the caller owns replay/checkpoints and reconnect backoff. */
+export async function consumeStream(input) {
+    if (input.signal.aborted)
+        return;
+    const socket = input.factory(input.url);
+    let ended = false, ready = false, processing = false, chain = Promise.resolve();
+    let settle;
+    const completion = new Promise((resolve, reject) => { settle = (error) => error ? reject(error) : resolve(); });
+    let watchdog;
+    const finish = (error) => {
+        if (ended)
+            return;
+        ended = true;
+        clearTimeout(watchdog);
+        input.signal.removeEventListener("abort", abort);
+        try {
+            socket.close(1000);
+        }
+        catch { /* Already disconnected. */ }
+        // No overlapping callbacks when the next connection resumes.
+        void chain.then(() => settle(error), (callbackError) => settle(callbackError));
+    };
+    const touch = () => {
+        clearTimeout(watchdog);
+        watchdog = setTimeout(() => finish(new RobonoLinkedAppError("stream_timeout", 503)), 40_000);
+    };
+    const abort = () => finish();
+    input.signal.addEventListener("abort", abort, { once: true });
+    touch();
+    socket.onopen = () => {
+        if (ended || input.signal.aborted)
+            return finish();
+        socket.send(JSON.stringify({ type: "authenticate", version: 1, access_token: input.tokens.accessToken, cursor: input.cursor }));
+    };
+    socket.onmessage = (event) => {
+        if (ended)
+            return;
+        try {
+            if (typeof event.data !== "string" || event.data.length > 256_000)
+                throw new Error();
+            const frame = JSON.parse(event.data);
+            touch();
+            if (frame.type === "error")
+                return finish(new RobonoLinkedAppError(typeof frame.error === "string" ? frame.error : "stream_error", Number(frame.status) || 503));
+            if (frame.type === "reconnect")
+                return finish();
+            if (frame.type === "ready") {
+                if (ready || frame.grant_id !== input.tokens.grantId)
+                    throw new Error();
+                ready = true;
+                return;
+            }
+            if (!ready)
+                throw new Error();
+            if (frame.type === "ping") {
+                socket.send(JSON.stringify({ type: "pong" }));
+                return;
+            }
+            const page = frame.page;
+            if (frame.type !== "page" || processing || !page || !Array.isArray(page.events) || page.events.length > 100 ||
+                typeof page.cursor !== "string" || !/^(0|[1-9][0-9]{0,17})$/.test(page.cursor) || typeof page.has_more !== "boolean")
+                throw new Error();
+            processing = true;
+            chain = chain.then(async () => {
+                if (input.signal.aborted)
+                    return;
+                await input.onPage(page);
+                processing = false;
+                if (!ended && !input.signal.aborted && socket.readyState === 1)
+                    socket.send(JSON.stringify({ type: "ack", cursor: page.cursor }));
+            });
+            void chain.catch(finish);
+        }
+        catch {
+            finish(new RobonoLinkedAppError("invalid_stream", 400));
+        }
+    };
+    socket.onerror = () => finish(new RobonoLinkedAppError("stream_unavailable", 503));
+    socket.onclose = (event) => finish(event.code === 1000 ? undefined : new RobonoLinkedAppError("stream_disconnected", 503));
+    if (input.signal.aborted)
+        abort();
+    return completion;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robono/linked-apps",
-  "version": "0.1.0-preview.1",
+  "version": "0.1.0-preview.3",
   "private": false,
   "description": "User-authorized companion-app access to Robono (development preview)",
   "type": "module",

package/dist/webhook.d.ts

@@ -1,19 +0,0 @@
-export type DeliveryHint = {
-    version: 1;
-    id: string;
-    type: "sync_available";
-    client_id: string;
-    grant_id: string;
-    cursor: string;
-};
-/** SERVER ONLY. Verify the exact raw request body, before parsing or using it.
- * Keep signing keys on your backend. Deduplicate id after durably queuing the hint.
- */
-export declare function verifyWebhook(input: {
-    body: string;
-    timestamp: string;
-    signature: string;
-    secret: string;
-    nowMs?: number;
-    crypto?: Crypto;
-}): Promise<DeliveryHint>;

package/dist/webhook.js

@@ -1,22 +0,0 @@
-/** SERVER ONLY. Verify the exact raw request body, before parsing or using it.
- * Keep signing keys on your backend. Deduplicate id after durably queuing the hint.
- */
-export async function verifyWebhook(input) {
-    const engine = input.crypto ?? globalThis.crypto;
-    const timestamp = Number(input.timestamp);
-    if (input.secret.length < 32 || !/^\d{10}$/.test(input.timestamp) ||
-        Math.abs((input.nowMs ?? Date.now()) / 1000 - timestamp) > 300 ||
-        !/^v1=[a-f0-9]{64}$/.test(input.signature) || input.body.length > 8192)
-        throw new Error("Invalid webhook");
-    const key = await engine.subtle.importKey("raw", new TextEncoder().encode(input.secret), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
-    const bytes = Uint8Array.from(input.signature.slice(3).match(/../g), (part) => parseInt(part, 16));
-    if (!await engine.subtle.verify("HMAC", key, bytes, new TextEncoder().encode(`${input.timestamp}.${input.body}`)))
-        throw new Error("Invalid webhook");
-    const data = JSON.parse(input.body);
-    if (data.version !== 1 || data.type !== "sync_available" ||
-        typeof data.id !== "string" ||
-        typeof data.client_id !== "string" || typeof data.grant_id !== "string" ||
-        typeof data.cursor !== "string" || !/^\d+$/.test(data.cursor))
-        throw new Error("Invalid webhook");
-    return data;
-}