@robono/linked-apps 0.1.0-preview.2 → 0.1.0-preview.4

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+# 0.1.0-preview.4
+
+- Add direct integration through `app` details in SDK configuration. No developer
+  account, website registration, issued client ID or manual activation is needed.
+- Use Robono's public service URL by default. Existing `clientId` integrations and
+  explicitly selected development servers remain supported.
+- Normalize and bind app details to a stable internal identity. Direct integrations
+  use code pairing; user consent, PKCE, access scopes and revocation stay intact.
+- Validate returned identity and preserve pairing/refresh across SDK restarts.
+
+# 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`.

package/INTEGRATION.md

@@ -1,14 +1,22 @@
 # 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.
+Install `@robono/linked-apps@0.1.0-preview.4` and supply your app details in SDK
+configuration. No Robono developer account, website registration, API key, issued
+client ID, callback URL or manual activation is needed. The SDK uses Robono's
+published service address by default. This connects to Robono app accounts, not
+the Robono Bridge network API.
+
+App details are supplied by your app; Robono does not certify ownership of the name
+or URLs. Use accurate names and public HTTPS website/privacy-policy links. Robono
+creates its internal client identifier automatically. Keep these details stable:
+a changed profile has a different identifier and needs new account connections.
+For development, use a distinct app name and separate secure credential storage.
+Your users still approve access inside Robono. Installing the SDK grants no access.
 
 ## Link an account with a code
 
-Pairing support requires SDK 0.1.0-preview.2 or newer. 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.
+Direct integration requires SDK 0.1.0-preview.4 or newer. Existing integrations
+with registered client IDs remain supported, but new integrations should use `app`.
 
 ```ts
 import { RobonoLinkedApps, secureTokenStore, nativeCryptoProvider } from '@robono/linked-apps';
@@ -16,8 +24,12 @@ import * as SecureStore from 'expo-secure-store';
 import * as Crypto from 'expo-crypto';
 
 const robono = new RobonoLinkedApps({
-  functionsUrl: 'https://vzoqxavqacydtwypjsrd.supabase.co/functions/v1',
-  clientId: config.robonoClientId,
+  app: {
+    name: 'Your App',
+    developerName: 'Your Company',
+    websiteUrl: 'https://example.com',
+    privacyUrl: 'https://example.com/privacy',
+  },
   tokenStore: secureTokenStore(SecureStore, 'robono.linked.account.primary'),
   crypto: nativeCryptoProvider({
     getRandomBytes: Crypto.getRandomBytes,
@@ -58,24 +70,29 @@ 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
+HTTP clients: POST `linked-app-pair` with `app` (name, developerName, websiteUrl,
+privacyUrl), scopes, S256 code_challenge and code_challenge_method. Do not send a
+client_id with app. Save the returned client_id with the pending secret state; no
+separate client-registration call is required. Poll `linked-app-token` using grant_type
+`urn:ietf:params:oauth:grant-type:device_code`, the returned 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.
+The older `clientId` configuration and registered-callback `beginLink` / `completeLink`
+APIs remain supported for existing clients. Do not combine `app` and `clientId`.
+Direct integration uses code pairing and requires no callback handler. The internal
+identifier is public; authorization still depends on PKCE and explicit account approval.
+An app name or client ID is not proof of app ownership.
 
 ## 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' });
 ```
 
@@ -100,10 +117,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.
@@ -122,42 +139,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.
 
-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.
+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.
 
-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.
+### Protocol for clients not using the SDK
+
+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. Install the SDK and supply your app details through `app` in its configuration. No developer account, website registration, issued client ID or manual activation is required. Each user approves 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:
@@ -28,10 +28,11 @@ Registered callback linking remains available for existing clients.
 
 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
@@ -42,9 +43,9 @@ 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.2
+npm install --save-exact @robono/linked-apps@0.1.0-preview.4
 ```
 
 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.
 
-The SDK is covered by the included Robono SDK License Agreement. This package contains no client secret or credentials. Robono supplies the registered client ID and environment URL separately.
+The SDK is covered by the included Robono SDK License Agreement. This package contains no client secret or credentials. The default Robono service URL is built in. Existing registered client IDs remain compatible; new integrations use app details.

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/identity.d.ts

@@ -0,0 +1,13 @@
+/** App-supplied display details, not verified ownership or a credential. */
+export interface AppIdentity {
+    name: string;
+    developerName: string;
+    websiteUrl: string;
+    privacyUrl: string;
+}
+export declare function normalizeAppIdentity(app: AppIdentity): AppIdentity;
+/** Stable identifier derived from display details; never proof of app ownership. */
+export declare function directAppIdentity(app: AppIdentity, sha256: (bytes: Uint8Array) => Promise<Uint8Array>): Promise<{
+    clientId: string;
+    profile: AppIdentity;
+}>;

package/dist/identity.js

@@ -0,0 +1,28 @@
+export function normalizeAppIdentity(app) {
+    if (!app || typeof app !== "object" || Array.isArray(app))
+        throw new Error("Provide your app details.");
+    const label = (value, max) => {
+        if (typeof value !== "string" || !value.trim() || value.length > max || /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/.test(value))
+            throw new Error("Invalid app details.");
+        return value.trim();
+    };
+    const website = (value) => {
+        const url = new URL(label(value, 2048));
+        if (url.protocol !== "https:" || url.username || url.password || url.hash ||
+            !url.hostname.includes(".") || /^(\d+\.){3}\d+$/.test(url.hostname) || url.hostname.includes(":"))
+            throw new Error("Use a public HTTPS website and privacy-policy URL.");
+        return url.toString();
+    };
+    return { name: label(app.name, 100), developerName: label(app.developerName, 150),
+        websiteUrl: website(app.websiteUrl), privacyUrl: website(app.privacyUrl) };
+}
+/** Stable identifier derived from display details; never proof of app ownership. */
+export async function directAppIdentity(app, sha256) {
+    const profile = normalizeAppIdentity(app);
+    const bytes = await sha256(new TextEncoder().encode(JSON.stringify([
+        "robono-direct-app-v1", profile.name, profile.developerName, profile.websiteUrl, profile.privacyUrl,
+    ])));
+    const hex = Array.from(bytes, b => b.toString(16).padStart(2, "0")).join("");
+    const clientId = `${hex.slice(0, 8)}-${hex.slice(8, 12)}-8${hex.slice(13, 16)}-8${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+    return { clientId, profile };
+}

package/dist/index.d.ts

@@ -1,8 +1,11 @@
+import { type AppIdentity } from "./identity.js";
+export type { AppIdentity } from "./identity.js";
 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;
@@ -73,16 +76,23 @@ export declare class RobonoLinkedApps {
     private readonly options;
     private readonly baseUrl;
     private readonly fetcher;
+    private readonly app?;
+    private identityPending?;
     private pairingPolls;
     private refreshPending;
     constructor(options: {
-        functionsUrl: string;
-        clientId: string;
+        functionsUrl?: string;
+        /** Direct integration: app details replace website registration. */
+        app?: AppIdentity;
+        /** Compatibility for existing registered integrations. Use app for new integrations. */
+        clientId?: string;
         tokenStore: TokenStore;
         crypto?: CryptoProvider;
         fetch?: typeof fetch;
         timeoutMs?: number;
+        webSocket?: LinkedSocketFactory;
     });
+    private clientIdentity;
     private post;
     /** Show only userCode. The user approves inside their signed-in Robono app. */
     beginPairing(scopes: Scope[], signal?: AbortSignal): Promise<{
@@ -150,11 +160,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,8 @@
+import { directAppIdentity, normalizeAppIdentity } from "./identity.js";
 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,11 +48,16 @@ export class RobonoLinkedApps {
     options;
     baseUrl;
     fetcher;
+    app;
+    identityPending;
     pairingPolls = new Map();
     refreshPending = null;
     constructor(options) {
         this.options = options;
-        const url = new URL(options.functionsUrl);
+        if (Boolean(options.app) === Boolean(options.clientId))
+            throw new Error("Provide app details or an existing clientId, not both.");
+        this.app = options.app ? normalizeAppIdentity(options.app) : undefined;
+        const url = new URL(options.functionsUrl ?? "https://vzoqxavqacydtwypjsrd.supabase.co/functions/v1");
         if (url.username || url.password || url.search || url.hash ||
             !(url.protocol === "https:" ||
                 (url.protocol === "http:" &&
@@ -61,6 +67,15 @@ export class RobonoLinkedApps {
         this.baseUrl = url.toString().replace(/\/$/, "");
         this.fetcher = options.fetch ?? globalThis.fetch;
     }
+    clientIdentity() {
+        if (this.options.clientId)
+            return Promise.resolve(this.options.clientId);
+        if (!this.identityPending) {
+            const crypto = this.options.crypto ?? webCryptoProvider();
+            this.identityPending = directAppIdentity(this.app, bytes => crypto.sha256(bytes)).then(result => result.clientId);
+        }
+        return this.identityPending;
+    }
     async post(endpoint, body, token, signal) {
         const controller = new AbortController();
         const cancel = () => controller.abort();
@@ -102,23 +117,25 @@ export class RobonoLinkedApps {
         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,
+            ...(this.app ? { app: this.app } : { client_id: await this.clientIdentity() }), scopes,
             code_challenge: challenge, code_challenge_method: "S256",
         }, undefined, signal);
+        if (this.app && result.client_id !== await this.clientIdentity())
+            throw new RobonoLinkedAppError("invalid_client_identity", 400);
         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,
+                clientId: await this.clientIdentity(), 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 ||
+        if (pending.clientId !== await this.clientIdentity() ||
             !Number.isFinite(Date.parse(pending.expiresAt)) ||
             Date.parse(pending.expiresAt) <= Date.now()) {
             throw new RobonoLinkedAppError("expired_token", 400);
@@ -134,7 +151,7 @@ export class RobonoLinkedApps {
             pending.nextPollAt = Date.now() + Math.max(5, pending.interval) * 1000;
             try {
                 const wire = await this.post("linked-app-token", {
-                    client_id: this.options.clientId,
+                    client_id: await this.clientIdentity(),
                     grant_type: "urn:ietf:params:oauth:grant-type:device_code",
                     device_code: pending.deviceCode, code_verifier: pending.verifier,
                 }, undefined, signal);
@@ -178,6 +195,8 @@ export class RobonoLinkedApps {
         throw new RobonoLinkedAppError("cancelled", 400);
     }
     async beginLink(redirectUri, scopes) {
+        if (this.app)
+            throw new Error("Direct integrations use beginPairing; redirect linking requires an existing registered clientId.");
         if (!scopes.length || scopes.some((scope) => !scopeNames.has(scope))) {
             throw new Error("Select supported permissions.");
         }
@@ -185,7 +204,7 @@ export class RobonoLinkedApps {
         const verifier = hex(crypto.randomBytes(32)), state = hex(crypto.randomBytes(32));
         const challenge = base64url(await crypto.sha256(new TextEncoder().encode(verifier)));
         const result = await this.post("linked-app-authorize", {
-            client_id: this.options.clientId,
+            client_id: await this.clientIdentity(),
             redirect_uri: redirectUri,
             scopes,
             state,
@@ -196,7 +215,7 @@ export class RobonoLinkedApps {
             authorizationUrl: result.authorization_url,
             requestId: result.request_id,
             pending: {
-                clientId: this.options.clientId,
+                clientId: await this.clientIdentity(),
                 redirectUri,
                 verifier,
                 state,
@@ -206,7 +225,7 @@ export class RobonoLinkedApps {
     }
     async completeLink(callback, pending) {
         const url = new URL(callback), expected = new URL(pending.redirectUri);
-        if (pending.clientId !== this.options.clientId ||
+        if (pending.clientId !== await this.clientIdentity() ||
             Date.parse(pending.expiresAt) <= Date.now() ||
             url.protocol !== expected.protocol || url.host !== expected.host ||
             url.pathname !== expected.pathname ||
@@ -225,7 +244,7 @@ export class RobonoLinkedApps {
             throw new RobonoLinkedAppError("invalid_callback", 400);
         }
         return this.save(await this.post("linked-app-token", {
-            client_id: this.options.clientId,
+            client_id: await this.clientIdentity(),
             grant_type: "authorization_code",
             redirect_uri: pending.redirectUri,
             code,
@@ -253,7 +272,7 @@ export class RobonoLinkedApps {
                 throw new RobonoLinkedAppError("not_connected", 401);
             try {
                 return await this.save(await this.post("linked-app-token", {
-                    client_id: this.options.clientId,
+                    client_id: await this.clientIdentity(),
                     grant_type: "refresh_token",
                     refresh_token: tokens.refreshToken,
                 }));
@@ -355,52 +374,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.2",
+  "version": "0.1.0-preview.4",
   "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;
-}