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

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+# 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,12 +1,15 @@
 # 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 with a code
 
-Pairing support requires SDK 0.1.0-preview.2 or newer. The currently registered
+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.
 
@@ -72,10 +75,10 @@ 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' });
 ```
 
@@ -100,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.
@@ -122,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.
 
-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. 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:
@@ -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,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.2
+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;
@@ -82,6 +83,7 @@ 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. */
@@ -150,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;
@@ -355,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.2",
+  "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;
-}