@robono/linked-apps 0.1.0-preview.1

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0-preview.1
+
+First distributable developer preview: user approval with PKCE, scoped messaging and media, receipts, secure native adapters, rotating credentials, resumable synchronization, verified background hints, and revocation. Requires an approved Robono registration and an activated environment.

package/INTEGRATION.md

@@ -0,0 +1,141 @@
+# 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.
+
+## Link an account
+
+```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,
+  clientId: config.robonoClientId,
+  tokenStore: secureTokenStore(SecureStore, 'robono.linked.account.primary'),
+  crypto: nativeCryptoProvider({
+    getRandomBytes: Crypto.getRandomBytes,
+    digest: (_, bytes) => Crypto.digest(Crypto.CryptoDigestAlgorithm.SHA256, new Uint8Array(bytes)),
+  }),
+});
+const link = await ot.beginLink('com.example.app://robono/callback',
+  ['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');
+```
+
+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.
+
+## Display and send
+
+```ts
+const snapshot = await ot.conversations();
+const page = await ot.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',
+  clientMessageId: durableOutgoingId, textBody: 'Hello' });
+```
+
+Show the allowed tools from each network's capabilities and connection status. The
+server remains authoritative: never infer a successful delivery from a successful
+send acknowledgement. Do not reveal another user's block. The API does not create
+connections, bypass parental permissions, unblock contacts or change network rules.
+
+For voice, retain the original recording and its measured duration, request an upload
+ticket, upload the bytes, then send `messageKind:'voice'` with `mediaObjectId:ticket.media.id`.
+Use `uploadBytes(ticket,bytes,mimeType)` or the equivalent native file streaming PUT to
+`ticket.signedUrl`. Send **no account Authorization header** to that URL. If a send
+times out, query/retry with the same message ID; do not record/upload/send a new copy
+just because confirmation was lost. The existing server checks enforce format, size,
+ownership, conversation membership and voice restrictions.
+
+Download only when needed. A playback URL has an expiry, is sensitive, and may become
+unavailable according to network retention. Only call `receipt(id,'heard')` after
+actual listening. Use `delivered` and `read` for their corresponding user states.
+
+## Synchronize
+
+```ts
+const controller = new AbortController();
+const watching = ot.watch({
+  signal: controller.signal,
+  cursorStore: persistedCursors, // keyed by grant ID
+  onResync: async () => reconcile(await ot.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.
+    await applyAuthoritativeChanges(events);
+  },
+  onError: reportTransientSyncFailure,
+});
+// Stop on background/logout/account change. Resume on foreground or a push hint.
+controller.abort();
+await watching;
+```
+
+`onResync` must reconcile active conversations and any visible message pages. Clear
+stale local histories when `history_cleared_at` advances or a deleted conversation is
+reported. Walkie-talkie replacement can invalidate an earlier message even if its ID
+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
+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
+
+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:
+
+```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.
+```
+
+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.
+
+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.
+
+Disconnect: call `ot.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/LICENSE

@@ -0,0 +1,130 @@
+ROBONO SDK LICENSE AGREEMENT
+Version 1.0, July 20, 2026
+
+Copyright (c) 2026 Add to Loop LLC. All rights reserved.
+
+This Robono SDK License Agreement (the "Agreement") is between Add to Loop LLC,
+operating the Robono service ("Robono"), and the person or entity that downloads,
+installs, copies, or uses the Software ("You"). By downloading, installing,
+copying, or using the Software, You accept this Agreement. If You do not accept
+it, do not use the Software.
+
+1. Definitions
+
+"Software" means this Robono software development kit, its documentation, and
+any updates Robono provides under this Agreement.
+
+"Robono Service" means the messaging interoperability, routing, policy,
+conversion, delivery, and related services operated or expressly authorized by
+Robono.
+
+"Application" means a product or service owned or controlled by You that is
+authorized to connect to the Robono Service.
+
+2. Limited License
+
+Subject to this Agreement, Robono grants You a limited, non-exclusive,
+non-transferable, non-sublicensable, revocable license to:
+
+(a) install, copy, and use the Software internally to develop, test, and
+operate an Application that communicates with the Robono Service; and
+
+(b) reproduce and distribute the portions of the Software that are necessarily
+included in Your Application, solely in compiled, minified, bundled, or object
+code form and solely as needed for that Application to communicate with the
+Robono Service.
+
+No right is granted to distribute the Software as a standalone product or SDK.
+
+3. Restrictions
+
+You may not, and may not permit another person to:
+
+(a) sell, rent, lease, sublicense, publish, or redistribute the Software as a
+standalone product, library, SDK, or service;
+
+(b) use the Software or a modified or derivative version of it to develop,
+provide, or support a product or service that competes with the Robono Service;
+
+(c) use the Software to bypass Robono, avoid applicable usage controls or fees,
+or access the Robono Service without authorization;
+
+(d) remove or alter copyright, trademark, attribution, or proprietary notices;
+
+(e) reverse engineer, decompile, or disassemble the Software except to the
+limited extent applicable law expressly prohibits this restriction; or
+
+(f) use the Software in violation of applicable law, the rights of another
+person, or the terms governing access to the Robono Service.
+
+4. Ownership and Reserved Rights
+
+The Software is licensed, not sold. Robono and its licensors retain all right,
+title, and interest in the Software and all related intellectual property.
+Except for the limited rights expressly granted in Section 2, all rights are
+reserved.
+
+No patent license is granted except the minimum license, if any, necessarily
+required to exercise the rights expressly granted in Section 2, and that
+limited patent license applies only while the Software is used with an
+authorized Robono Service.
+
+5. Service Access
+
+This Agreement does not itself grant an account, API credentials, service
+availability, support, or a right to access the Robono Service. Service access
+may be governed by additional terms, plans, limits, and policies. Robono may
+suspend or terminate access to protect users, systems, legal compliance, or the
+integrity of the Robono Service.
+
+6. Updates and Support
+
+Robono is not required to provide maintenance, updates, support, or continued
+availability of any version of the Software unless separately agreed in
+writing.
+
+7. Term and Termination
+
+This Agreement continues until terminated. Your rights terminate automatically
+if You breach this Agreement. On termination, You must stop using the Software
+and delete copies under Your control, except for copies necessarily contained
+in previously distributed Applications. Sections 3, 4, 8, 9, 10, and 11
+survive termination.
+
+8. Disclaimer of Warranties
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE SOFTWARE IS PROVIDED "AS IS" AND
+"AS AVAILABLE," WITHOUT WARRANTIES OF ANY KIND, EXPRESS, IMPLIED, OR
+STATUTORY, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE, TITLE, AND NON-INFRINGEMENT.
+
+9. Limitation of Liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, ROBONO WILL NOT BE LIABLE FOR INDIRECT,
+INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES, OR FOR LOSS
+OF DATA, REVENUE, PROFITS, GOODWILL, OR BUSINESS OPPORTUNITY, ARISING FROM OR
+RELATING TO THE SOFTWARE. ROBONO'S TOTAL LIABILITY RELATING TO THE SOFTWARE
+WILL NOT EXCEED THE GREATER OF ONE HUNDRED U.S. DOLLARS (US $100) OR THE AMOUNT
+YOU PAID ROBONO FOR THE SOFTWARE DURING THE TWELVE MONTHS BEFORE THE EVENT
+GIVING RISE TO THE CLAIM. THESE LIMITATIONS APPLY TO THE MAXIMUM EXTENT
+PERMITTED BY LAW.
+
+10. Governing Law
+
+This Agreement is governed by the laws of the State of Florida, excluding its
+conflict-of-laws rules. The state and federal courts located in Palm Beach
+County, Florida have exclusive jurisdiction, and each party consents to their
+jurisdiction and venue.
+
+11. General
+
+You may not assign this Agreement without Robono's prior written consent.
+Robono may assign this Agreement in connection with a reorganization, transfer
+of intellectual property, financing, merger, acquisition, or sale of all or
+substantially all of the relevant assets. If a provision is unenforceable, it
+will be enforced to the maximum extent permitted and the remaining provisions
+will remain effective. A waiver must be in writing. This Agreement is the
+entire agreement concerning the Software unless You and Robono sign a separate
+written agreement that expressly replaces it.
+
+Questions about this license may be submitted at https://robono.com/contact.

package/README.md

@@ -0,0 +1,48 @@
+# @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.
+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.
+No dependency on Matrix, TalkOpen, Loop, Expo or a specific UI framework.
+
+Build/test from the repository:
+
+```
+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`.
+
+[Integration guide](./INTEGRATION.md) ·
+[API reference](https://robono.com/api-reference-viewer.html?spec=linked-apps) ·
+[Developer documentation](https://robono.com/linked-apps)
+
+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.
+
+Send retries must retain the original UUID. Refresh requests are serialized within
+one instance; coordinate across processes yourself. A lost refresh response can
+require relinking because reusing a spent refresh token revokes the grant.
+
+## Preview distribution
+
+The official distribution channel is npm. Install this exact preview version:
+
+```sh
+npm install --save-exact @robono/linked-apps@0.1.0-preview.1
+```
+
+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.

package/dist/delivery.d.ts

@@ -0,0 +1,39 @@
+import type { CryptoProvider, TokenStore } from "./index.js";
+export interface LinkedEvent {
+    id: string;
+    type: "messages.changed" | "receipts.changed" | "conversations.changed";
+    conversation_id: string | null;
+    message_id: string | null;
+    created_at: string;
+}
+export interface EventPage {
+    events: LinkedEvent[];
+    cursor: string;
+    has_more: boolean;
+    resync_required?: boolean;
+}
+export interface CursorStore {
+    /** Key by grant ID; never share a cursor between accounts or grants. */
+    get(grantId: string): Promise<string | null>;
+    set(grantId: string, cursor: string): Promise<void>;
+}
+export interface WatchOptions {
+    signal: AbortSignal;
+    cursorStore: CursorStore;
+    onEvents(events: LinkedEvent[]): Promise<void>;
+    /** 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. */
+export declare function secureTokenStore(storage: {
+    getItemAsync(key: string): Promise<string | null>;
+    setItemAsync(key: string, value: string): Promise<void>;
+    deleteItemAsync(key: string): Promise<void>;
+}, key: string): TokenStore;
+export declare function nativeCryptoProvider(native: {
+    getRandomBytes(length: number): Uint8Array;
+    digest(algorithm: "SHA-256", bytes: Uint8Array): Promise<ArrayBuffer>;
+}): CryptoProvider;

package/dist/delivery.js

@@ -0,0 +1,39 @@
+export async function waitForPoll(ms, signal) {
+    if (signal.aborted)
+        return;
+    await new Promise((resolve) => {
+        const done = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        signal.addEventListener("abort", done, { once: true });
+        if (signal.aborted)
+            done();
+    });
+}
+/** Dependency injection keeps the SDK usable in Expo and bare native apps. */
+export function secureTokenStore(storage, key) {
+    if (!/^[A-Za-z0-9._-]{1,120}$/.test(key)) {
+        throw new Error("Use a unique, stable secure-storage key for each account.");
+    }
+    return {
+        async get() {
+            const value = await storage.getItemAsync(key);
+            return value ? JSON.parse(value) : null;
+        },
+        async set(tokens) {
+            if (tokens)
+                await storage.setItemAsync(key, JSON.stringify(tokens));
+            else
+                await storage.deleteItemAsync(key);
+        },
+    };
+}
+export function nativeCryptoProvider(native) {
+    return {
+        randomBytes: (length) => native.getRandomBytes(length),
+        sha256: async (bytes) => new Uint8Array(await native.digest("SHA-256", bytes)),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,127 @@
+import { type EventPage, type WatchOptions } from "./delivery.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 Scope = "account:read" | "messages:read" | "messages:send" | "receipts:write";
+export type Tokens = {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+    refreshExpiresAt: string;
+    grantId: string;
+    scopes: Scope[];
+};
+export interface TokenStore {
+    /** Use the device Keychain/Keystore. Never AsyncStorage, URLs or logs. */
+    get(): Promise<Tokens | null>;
+    set(tokens: Tokens | null): Promise<void>;
+}
+export interface CryptoProvider {
+    randomBytes(length: number): Uint8Array;
+    sha256(bytes: Uint8Array): Promise<Uint8Array>;
+}
+export interface PendingLink {
+    clientId: string;
+    redirectUri: string;
+    verifier: string;
+    state: string;
+    expiresAt: string;
+}
+export interface SendMessage {
+    conversationId: string;
+    messageKind: "text" | "voice" | "image" | "video" | "document";
+    /** Persist this UUID with the outgoing message. Reuse it for every retry. */
+    clientMessageId: string;
+    textBody?: string;
+    mediaObjectId?: string;
+    replyToMessageId?: string;
+}
+export interface MediaUpload {
+    conversationId: string;
+    mediaKind: "voice" | "image" | "video" | "document";
+    mimeType: string;
+    sizeBytes: number;
+    fileName?: string;
+    durationMs?: number;
+    waveform?: number[];
+}
+export type ApiRecord = Record<string, unknown>;
+export declare class RobonoLinkedAppError extends Error {
+    code: string;
+    status: number;
+    constructor(code: string, status: number);
+}
+export declare function webCryptoProvider(): CryptoProvider;
+/** One instance per connected account. Watching starts only when explicitly requested. */
+export declare class RobonoLinkedApps {
+    private readonly options;
+    private readonly baseUrl;
+    private readonly fetcher;
+    private refreshPending;
+    constructor(options: {
+        functionsUrl: string;
+        clientId: string;
+        tokenStore: TokenStore;
+        crypto?: CryptoProvider;
+        fetch?: typeof fetch;
+        timeoutMs?: number;
+    });
+    private post;
+    beginLink(redirectUri: string, scopes: Scope[]): Promise<{
+        authorizationUrl: string;
+        requestId: string;
+        pending: {
+            clientId: string;
+            redirectUri: string;
+            verifier: string;
+            state: string;
+            expiresAt: string;
+        };
+    }>;
+    completeLink(callback: string, pending: PendingLink): Promise<Tokens>;
+    private save;
+    refresh(): Promise<Tokens>;
+    private call;
+    account(): Promise<{
+        account: {
+            id: string;
+            display_name: string | null;
+            phone: string;
+        };
+        grant_id: string;
+        scopes: Scope[];
+    }>;
+    conversations(): Promise<ConversationPage>;
+    messages(conversationId: string, page?: {
+        before?: string;
+        beforeId?: string;
+        limit?: number;
+    }): Promise<MessagePage>;
+    message(conversationId: string, messageId: string): Promise<{
+        message: Message;
+        messages: Message[];
+    }>;
+    send(input: SendMessage): Promise<{
+        message: Message;
+    }>;
+    createUpload(input: MediaUpload): Promise<UploadTicket>;
+    /** Upload exactly the bytes described in the ticket. No Robono bearer is sent to storage. */
+    uploadBytes(ticket: UploadTicket, bytes: Uint8Array, mimeType: string, signal?: AbortSignal): Promise<void>;
+    download(messageId: string): Promise<{
+        signedUrl: string;
+        expiresIn: number;
+    }>;
+    receipt(messageId: string, state: "delivered" | "read" | "heard"): Promise<{
+        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.
+     */
+    watch(options: WatchOptions): Promise<void>;
+    disconnect(): Promise<void>;
+}

package/dist/index.js

@@ -0,0 +1,325 @@
+import { waitForPoll } from "./delivery.js";
+export * from "./types.js";
+export * from "./delivery.js";
+export * from "./webhook.js";
+export class RobonoLinkedAppError extends Error {
+    code;
+    status;
+    constructor(code, status) {
+        super(`Robono request failed (${code})`);
+        this.code = code;
+        this.status = status;
+    }
+}
+const scopeNames = new Set([
+    "account:read",
+    "messages:read",
+    "messages:send",
+    "receipts:write",
+]);
+const hex = (bytes) => Array.from(bytes, (x) => x.toString(16).padStart(2, "0")).join("");
+function base64url(bytes) {
+    const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+    let result = "", bits = 0, value = 0;
+    for (const byte of bytes) {
+        value = (value << 8) | byte;
+        bits += 8;
+        while (bits >= 6) {
+            bits -= 6;
+            result += alphabet[(value >>> bits) & 63];
+        }
+    }
+    if (bits)
+        result += alphabet[(value << (6 - bits)) & 63];
+    return result;
+}
+export function webCryptoProvider() {
+    if (!globalThis.crypto?.subtle) {
+        throw new Error("A secure CryptoProvider is required on this platform.");
+    }
+    return {
+        randomBytes: (length) => globalThis.crypto.getRandomValues(new Uint8Array(length)),
+        sha256: async (bytes) => new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", new Uint8Array(bytes))),
+    };
+}
+/** One instance per connected account. Watching starts only when explicitly requested. */
+export class RobonoLinkedApps {
+    options;
+    baseUrl;
+    fetcher;
+    refreshPending = null;
+    constructor(options) {
+        this.options = options;
+        const url = new URL(options.functionsUrl);
+        if (url.username || url.password || url.search || url.hash ||
+            !(url.protocol === "https:" ||
+                (url.protocol === "http:" &&
+                    ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)))) {
+            throw new Error("Use an HTTPS Robono functions URL (HTTP is allowed only for local tests).");
+        }
+        this.baseUrl = url.toString().replace(/\/$/, "");
+        this.fetcher = options.fetch ?? globalThis.fetch;
+    }
+    async post(endpoint, body, token, signal) {
+        const controller = new AbortController();
+        const cancel = () => controller.abort();
+        signal?.addEventListener("abort", cancel, { once: true });
+        if (signal?.aborted)
+            controller.abort();
+        const timeout = setTimeout(cancel, this.options.timeoutMs ?? 30_000);
+        try {
+            const response = await this.fetcher(`${this.baseUrl}/${endpoint}`, {
+                method: "POST",
+                redirect: "error",
+                signal: controller.signal,
+                headers: {
+                    "content-type": "application/json",
+                    ...(token ? { authorization: `Bearer ${token}` } : {}),
+                },
+                body: JSON.stringify(body),
+            });
+            const data = await response.json();
+            if (!response.ok) {
+                const code = typeof data.error === "string"
+                    ? data.error
+                    : data.error?.code ?? "request_failed";
+                throw new RobonoLinkedAppError(code, response.status);
+            }
+            return data;
+        }
+        finally {
+            clearTimeout(timeout);
+            signal?.removeEventListener("abort", cancel);
+        }
+    }
+    async beginLink(redirectUri, scopes) {
+        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)), 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,
+            redirect_uri: redirectUri,
+            scopes,
+            state,
+            code_challenge: challenge,
+            code_challenge_method: "S256",
+        });
+        return {
+            authorizationUrl: result.authorization_url,
+            requestId: result.request_id,
+            pending: {
+                clientId: this.options.clientId,
+                redirectUri,
+                verifier,
+                state,
+                expiresAt: result.expires_at,
+            },
+        };
+    }
+    async completeLink(callback, pending) {
+        const url = new URL(callback), expected = new URL(pending.redirectUri);
+        if (pending.clientId !== this.options.clientId ||
+            Date.parse(pending.expiresAt) <= Date.now() ||
+            url.protocol !== expected.protocol || url.host !== expected.host ||
+            url.pathname !== expected.pathname ||
+            url.username || url.password || url.hash ||
+            url.searchParams.getAll("state").length !== 1 ||
+            url.searchParams.get("state") !== pending.state ||
+            [...expected.searchParams].some(([k, v]) => url.searchParams.get(k) !== v)) {
+            throw new RobonoLinkedAppError("invalid_callback", 400);
+        }
+        if (url.searchParams.has("error")) {
+            throw new RobonoLinkedAppError("access_denied", 400);
+        }
+        const code = url.searchParams.get("code");
+        if (url.searchParams.getAll("code").length !== 1 || !code ||
+            !/^rlc_[a-f0-9]{64}$/.test(code)) {
+            throw new RobonoLinkedAppError("invalid_callback", 400);
+        }
+        return this.save(await this.post("linked-app-token", {
+            client_id: this.options.clientId,
+            grant_type: "authorization_code",
+            redirect_uri: pending.redirectUri,
+            code,
+            code_verifier: pending.verifier,
+        }));
+    }
+    async save(wire) {
+        const tokens = {
+            accessToken: wire.access_token,
+            refreshToken: wire.refresh_token,
+            expiresAt: Date.now() + wire.expires_in * 1000,
+            refreshExpiresAt: wire.refresh_expires_at,
+            grantId: wire.grant_id,
+            scopes: wire.scope.split(" "),
+        };
+        await this.options.tokenStore.set(tokens);
+        return tokens;
+    }
+    async refresh() {
+        if (this.refreshPending)
+            return this.refreshPending;
+        this.refreshPending = (async () => {
+            const tokens = await this.options.tokenStore.get();
+            if (!tokens)
+                throw new RobonoLinkedAppError("not_connected", 401);
+            try {
+                return await this.save(await this.post("linked-app-token", {
+                    client_id: this.options.clientId,
+                    grant_type: "refresh_token",
+                    refresh_token: tokens.refreshToken,
+                }));
+            }
+            catch (error) {
+                if (error instanceof RobonoLinkedAppError &&
+                    error.code === "invalid_grant")
+                    await this.options.tokenStore.set(null);
+                throw error;
+            }
+        })();
+        try {
+            return await this.refreshPending;
+        }
+        finally {
+            this.refreshPending = null;
+        }
+    }
+    async call(operation, input = {}, signal) {
+        let tokens = await this.options.tokenStore.get();
+        if (!tokens)
+            throw new RobonoLinkedAppError("not_connected", 401);
+        if (tokens.expiresAt <= Date.now() + 30_000)
+            tokens = await this.refresh();
+        // No blind retries: a timeout may occur after a successful send. The host
+        // retains the original clientMessageId and explicitly retries that message.
+        return this.post("linked-app-api", { version: 1, operation, input }, tokens.accessToken, signal);
+    }
+    account() {
+        return this.call("account.get");
+    }
+    conversations() {
+        return this.call("conversations.list");
+    }
+    messages(conversationId, page = {}) {
+        return this.call("messages.list", { conversationId, ...page });
+    }
+    message(conversationId, messageId) {
+        return this.call("messages.get", { conversationId, messageId });
+    }
+    send(input) {
+        if (!/^[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(input.clientMessageId))
+            throw new Error("A stable clientMessageId UUID is required.");
+        return this.call("messages.send", {
+            ...input,
+            inputSource: "external",
+        });
+    }
+    createUpload(input) {
+        return this.call("media.upload", input);
+    }
+    /** Upload exactly the bytes described in the ticket. No Robono bearer is sent to storage. */
+    async uploadBytes(ticket, bytes, mimeType, signal) {
+        const url = new URL(ticket.signedUrl);
+        if (url.protocol !== "https:" ||
+            url.origin !== new URL(this.baseUrl).origin ||
+            !url.pathname.startsWith("/storage/v1/object/upload/sign/"))
+            throw new Error("Invalid upload destination");
+        if (ticket.media.size_bytes !== undefined &&
+            bytes.byteLength !== ticket.media.size_bytes)
+            throw new Error("Upload size does not match ticket");
+        if (ticket.media.mime_type && mimeType !== ticket.media.mime_type) {
+            throw new Error("Upload type does not match ticket");
+        }
+        const controller = new AbortController();
+        const cancel = () => controller.abort();
+        const timer = setTimeout(cancel, 120_000);
+        signal?.addEventListener("abort", cancel, { once: true });
+        if (signal?.aborted)
+            controller.abort();
+        try {
+            const response = await this.fetcher(url.toString(), {
+                method: "PUT",
+                redirect: "error",
+                signal: controller.signal,
+                headers: { "content-type": mimeType, "x-upsert": "false" },
+                body: new Uint8Array(bytes),
+            });
+            await response.body?.cancel();
+            if (!response.ok) {
+                throw new RobonoLinkedAppError("upload_failed", response.status);
+            }
+        }
+        finally {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", cancel);
+        }
+    }
+    download(messageId) {
+        return this.call("media.download", { messageId });
+    }
+    receipt(messageId, state) {
+        return this.call("receipts.update", {
+            messageId,
+            heard: state === "heard",
+            deliveredOnly: state === "delivered",
+        });
+    }
+    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.
+     */
+    async watch(options) {
+        const tokens = await this.options.tokenStore.get();
+        if (!tokens)
+            throw new RobonoLinkedAppError("not_connected", 401);
+        const grantId = tokens.grantId;
+        let cursor = await options.cursorStore.get(grantId);
+        let failures = 0;
+        while (!options.signal.aborted) {
+            try {
+                const current = await this.options.tokenStore.get();
+                if (!current || current.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);
+                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))
+                    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);
+        }
+    }
+    async disconnect() {
+        await this.call("connection.revoke");
+        await this.options.tokenStore.set(null);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,120 @@
+export interface Receipt {
+    id?: string;
+    recipient_user_id?: string | null;
+    child_app_connection_id?: string | null;
+    delivered_at?: string | null;
+    seen_at?: string | null;
+    read_at?: string | null;
+    heard_at?: string | null;
+}
+export interface Media {
+    id: string;
+    media_kind?: string;
+    mime_type?: string;
+    size_bytes?: number;
+    file_name?: string | null;
+    duration_ms?: number | null;
+    width?: number | null;
+    height?: number | null;
+    waveform?: number[] | null;
+    upload_state?: string;
+    server_expires_at?: string | null;
+    deleted_from_storage_at?: string | null;
+    signed_url?: string;
+    signed_url_expires_at?: string;
+}
+export interface Message {
+    id: string;
+    conversation_id: string;
+    sender_kind: string;
+    sender_user_id?: string | null;
+    child_app_connection_id?: string | null;
+    client_message_id?: string | null;
+    message_kind: "text" | "voice" | "image" | "video" | "document";
+    text_body?: string | null;
+    media_object_id?: string | null;
+    created_at: string;
+    active_in_walkie_talkie?: boolean;
+    reply_to_message_id?: string | null;
+    local_only?: boolean;
+    local_send_state?: string;
+    media_objects: Media | null;
+    message_receipts: Receipt[];
+    message_reactions: Array<{
+        id: string;
+        user_id: string;
+        emoji: string;
+        created_at: string;
+        updated_at: string;
+    }>;
+    message_speech_artifacts: Array<{
+        id: string;
+        artifact_kind: string;
+        language_code?: string;
+        text_body?: string | null;
+        media_objects: Media | null;
+    }>;
+}
+export interface Conversation {
+    id: string;
+    mode: "history" | "walkie_talkie";
+    title?: string | null;
+    updated_at?: string;
+    unread_count?: number;
+    blocked_by_you: boolean;
+    user_preferences: {
+        muted_at?: string | null;
+        blurred_at?: string | null;
+        history_cleared_at?: string | null;
+    };
+    conversation_members: Array<{
+        id: string;
+        member_kind: string;
+        user_id?: string | null;
+        child_app_connection_id?: string | null;
+        left_at?: string | null;
+        app_users: {
+            display_name?: string | null;
+            phone_e164?: string;
+            avatar_url?: string | null;
+            deleted_at?: string | null;
+        };
+        child_app_connections: {
+            child_original_name?: string;
+            status?: string;
+            disconnected_at?: string | null;
+            external_account_deleted_at?: string | null;
+            external_avatar_url?: string | null;
+            capabilities?: Record<string, unknown>;
+            monitoring_disclosure?: unknown;
+            child_apps: {
+                name?: string;
+            };
+        } | null;
+    }>;
+}
+export interface ConversationPage {
+    conversations: Conversation[];
+    messages: Message[];
+    deletedConversations: Array<{
+        conversationId: string;
+        historyClearedAt: string | null;
+    }>;
+}
+export interface MessagePage {
+    messages: Message[];
+    has_more: boolean;
+    next_before: string | null;
+    next_before_id: string | null;
+}
+export interface UploadTicket {
+    media: Media;
+    signedUrl: string;
+    token: string;
+    path: string;
+    thumbnailUpload: {
+        signedUrl: string;
+        token: string;
+        path: string;
+    } | null;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/webhook.d.ts

@@ -0,0 +1,19 @@
+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

@@ -0,0 +1,22 @@
+/** 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;
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@robono/linked-apps",
+  "version": "0.1.0-preview.1",
+  "private": false,
+  "description": "User-authorized companion-app access to Robono (development preview)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "INTEGRATION.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm test"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://robono.com/linked-apps",
+  "bugs": {
+    "url": "https://robono.com/contact",
+    "email": "support@robono.com"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "preview"
+  },
+  "keywords": [
+    "robono",
+    "messaging",
+    "linked-apps",
+    "sdk",
+    "typescript"
+  ],
+  "author": {
+    "name": "Add to Loop LLC",
+    "email": "support@robono.com",
+    "url": "https://robono.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IMLX16/robono-sdks.git",
+    "directory": "packages/linked-apps"
+  },
+  "sideEffects": false,
+  "devDependencies": {
+    "typescript": "6.0.3"
+  }
+}