@robono/server 0.8.0 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.8.1
+
+- Simplifies the public implementation path while retaining the complete endpoint, authorization, event, and testing contracts.
+- Renames the public client-side API reference and removes unnecessary infrastructure terminology.
+
 ## 0.8.0
 
 - Added typed external-user export and deletion operations with status lookup.

package/README.md

@@ -1,12 +1,10 @@
 # `@robono/server`
 
-Headless Node/TypeScript SDK for connecting an existing app or closed ecosystem to Robono Bridge. It provides typed API calls, bounded retries, idempotency, restriction checks, speech tools, webhook verification, and the protected client adapter.
+Headless Node/TypeScript SDK for connecting an existing app or private ecosystem to Robono Bridge.
 
-## License in plain English
+## License
 
-You may use this SDK to build, test, and operate an authorized application that connects to Robono. You may not redistribute it as a standalone SDK, use it to bypass Robono, or use it to build a competing bridge service. Service access, pricing, maintenance, and support are separate. If you and Robono sign a written agreement that expressly replaces this SDK license, that agreement controls to the extent it says so. The included `LICENSE` is the complete, controlling text.
-
-See the [SDK license FAQ](https://robono.com/sdk-license) for procurement guidance and the route for organization terms.
+Licensed for authorized Robono integrations. Redistribution as a standalone SDK, bypassing Robono, and competing bridge services are prohibited. See the included `LICENSE` and [license FAQ](https://robono.com/sdk-license).
 
 Robono's own app and third-party connected apps appear as endpoints in the same directory. Your product keeps its existing accounts, screens, storage, safety rules, and notifications.
 
@@ -16,10 +14,7 @@ Robono's own app and third-party connected apps appear as endpoints in the same
 npm install @robono/server
 ```
 
-The package includes `SBOM.spdx.json`, a machine-readable inventory of its
-production components.
-
-The package is ESM-only and supports Node.js 18+ and Deno 2.x through npm compatibility, including Supabase Edge Functions:
+The package is ESM-only, supports Node.js 18+ and Deno 2.x through npm compatibility, and includes TypeScript declarations and `SBOM.spdx.json`.
 
 CommonJS applications must use a dynamic import:
 
@@ -27,13 +22,6 @@ CommonJS applications must use a dynamic import:
 const { RobonoServer } = await import("@robono/server");
 ```
 
-```ts
-import {
-  createRobonoBackendAdapter,
-  RobonoServer,
-} from "npm:@robono/server@0.8.0";
-```
-
 ## Discover endpoints
 
 ```ts
@@ -91,129 +79,33 @@ const result = await robono.endpointMessages.send({
 }, { idempotencyKey: messageOperationId });
 ```
 
-The normalized `connection.connection_id` is valid for SDK state and subsequent unified calls. Endpoint-specific methods remain available for integrations that need lower-level control.
+The normalized `connection.connection_id` is valid for subsequent unified SDK calls.
 
 The unified send validates negotiated message type, text length, media size, duration, MIME type, and attachment count before making the API request. For media composed as one message, give every item the same `attachment_batch.id`, its zero-based `index`, and the common `count`.
-
-New server-only integrations can use the normalized namespaces for the rest of the lifecycle without branching on endpoint type:
-
-```ts
-const page = await robono.endpointConnections.list({
-  external_user_id: user.id,
-  limit: 50,
-});
-
-const history = await robono.endpointMessages.list({
-  connection,
-  external_user_id: user.id,
-  limit: 50,
-});
-
-const firstMessage = history.messages[0];
-if (firstMessage) {
-  await robono.endpointMessages.mark({
-    connection,
-    external_user_id: user.id,
-    message_id: firstMessage.message_id,
-    event: "read",
-  }, { idempotencyKey: receiptOperation.id });
-}
-
-await robono.endpointConnections.update({
-  connection,
-  external_user_id: user.id,
-  external_profile: currentProfile,
-}, { idempotencyKey: profileUpdate.operationId });
-
-await robono.endpointConnections.disconnect({
-  connection,
-  external_user_id: user.id,
-}, { idempotencyKey: disconnectOperation.id });
-```
-
-Use `page.next_cursor` and `history.next_before` for older pages. Use `history.sync_cursor` as the next `after` value when checking only for newer messages.
-Create and persist each operation ID before its first request, then reuse that ID
-after a timeout, retry, or restart.
+The same normalized namespaces list, update, and disconnect connections; load message history; and mark messages delivered, read, or heard. See the [Server SDK reference](https://robono.com/sdk-reference/server/).
 
 ## Protect client operations
 
-Keep the API key on your server. Mount the adapter at `/robono/*` behind your existing authentication:
+Keep the API key on your server. Mount the app-facing route at `/robono/*` behind your existing authentication:
 
 ```ts
 const handleRobono = createRobonoBackendAdapter({
   robono,
   authenticate: async request =>
     (await yourAuth.findUser(request))?.id ?? null,
-  authorize: async ({ action, userId, input }) => {
-    const user = await accounts.findActiveUser(userId);
-    if (!user) return false;
-    if (action === "networks.list") return true;
-    if (action === "network_connections.respond") {
-      return guardianApprovals.mayRespond(user, input);
-    }
-    if (action.endsWith(".list")) return access.mayRead(user, input);
-    if (
-      action === "message_transforms.create" ||
-      action === "speech_transforms.create"
-    ) return processing.hasPermissionAndCredits(user, input);
-    if (
-      action.endsWith(".request") ||
-      action.endsWith(".create") ||
-      action.endsWith(".send") ||
-      action.endsWith(".mark") ||
-      action.endsWith(".update") ||
-      action.endsWith(".update_profile") ||
-      action.endsWith(".disconnect") ||
-      action === "push_diagnostics.report"
-    ) return access.mayChange(user, action, input);
-    return false;
-  },
+  authorize: context =>
+    yourPermissions.allowRobonoAction(context),
 });
 ```
 
-`authenticate` proves the user's identity. The required `authorize` callback decides whether that user may perform the exact operation. Enforce relationship state, account rules, guardian approval when applicable, messaging restrictions, and processing allowances. Missing or false decisions are denied.
-Return `null` or `undefined` for a normal missing or invalid session. If your
-authentication library must throw for that case, throw
-`RobonoAuthenticationError`; the adapter safely returns HTTP 401. Unexpected
-authentication-system failures remain sanitized HTTP 500 responses.
+`authenticate` proves identity. The required `authorize` callback checks the exact action against your account, relationship, guardian, safety, and processing rules. Missing or false decisions are denied. The route uses standard Web `Request` and `Response` objects, so it works with common Node, serverless, and Deno frameworks.
 
-The adapter uses standard Web `Request` and `Response` objects, so it can be mounted in Express, Fastify, Next.js, serverless functions, Supabase Edge Functions, or another compatible backend. Exact Express, Next.js, Supabase Edge, and Deno mounts are available in the website documentation.
-
-## Language and speech tools
-
-The typed transform methods cover transcription, translation, TTS, translated voice, and existing-message transforms:
-
-```ts
-const { languages } = await robono.languages();
-showAvailableTransformLanguages(languages);
-
-const result = await robono.transforms.speech({
-  input: {
-    type: "audio",
-    source_url: audioUrl,
-    mime_type: "audio/mp4",
-    language: "en",
-  },
-  outputs: ["transcript", "translated_voice"],
-  target_language: "es",
-}, { idempotencyKey: transformOperationId });
-
-console.log(result.status);             // "completed"
-console.log(result.artifacts);          // Typed transcript and generated voice
-console.log(result.billing.operations); // Exact transcription/translation/TTS steps
-```
-
-Transforms complete synchronously. SDK errors report request failures, while signed `transform.completed` and `transform.failed` webhooks provide an auditable server event. Generated media URLs include `source_url_expires_at` and currently expire after ten minutes. Reuse the same idempotency key when retrying the same operation; cached message artifacts are not charged again.
-
-## Verify webhooks
+## Verify signed events
 
 Verify the signature against the exact raw request body before parsing JSON:
 
 ```ts
-import {
-  toClientPushPayload,
-  verifyRobonoWebhook,
-} from "@robono/server";
+import { verifyRobonoWebhook } from "@robono/server";
 
 const webhookSecret = process.env.ROBONO_WEBHOOK_SECRET;
 if (!webhookSecret) throw new Error("ROBONO_WEBHOOK_SECRET is required");
@@ -229,80 +121,10 @@ await webhookInbox.insertPendingIfAbsent({
   rawBody,
   event: verified.event,
 });
-
-// Return any HTTP 2xx within 10 seconds; 202 is recommended here.
-// Timeouts, network failures, redirects, and non-2xx responses receive up to
-// five retries with increasing delay capped at 15 minutes. Duplicate event IDs
-// must also return 2xx. A worker polls durable pending rows and runs:
-async function processPendingWebhook(pending: typeof verified) {
-  switch (pending.event.event) {
-    case "bridge.connection_requested":
-      await pendingRequests.store(pending.event);
-      break;
-    case "connection.status_changed":
-    case "bridge.connection_status_changed":
-      await existingMessagingSystem.updateConnection(pending.event);
-      break;
-    case "message.created":
-      await existingMessagingSystem.storeMessage(pending.event);
-      break;
-    case "bridge.message_created":
-      await existingMessagingSystem.storeMessage(pending.event.message);
-      break;
-    case "transform.completed":
-    case "transform.failed":
-      await existingMessagingSystem.updateTransform(pending.event);
-      break;
-  }
-
-  const externalUserId =
-    await existingMessagingSystem.recipientFor(pending.event);
-  if (externalUserId) {
-    await yourPushProvider.send(externalUserId, {
-      data: toClientPushPayload(pending.event),
-    });
-  }
-  await webhookInbox.markComplete(pending.eventId);
-}
+return new Response("accepted", { status: 202 });
 ```
 
-`verified.event` is a runtime-validated, discriminated `RobonoWebhookEvent` union covering connection, message, receipt, guardian, transform, failure, and diagnostic events. The durable inbox must enforce a unique event ID and keep failed work pending; receiving a duplicate must never cause unfinished work to be marked complete.
-Message-created webhooks contain the complete message: direct-endpoint content is
-on the event itself and app-to-app content is in `event.message`. Client push
-data contains routing IDs only; the authenticated client fetches current state.
-
-For `bridge.connection_requested`, resolve `event.target.identifier` on your
-backend, store the request pending any required guardian approval, and call
-`networkConnections.respond()` only from an authorized server action. Use a
-generic requester-facing result for `not_found`, rejection, and unauthorized
-lookups so account existence cannot be tested.
-
-## Automate user data requests
-
-Create exports and deletions only after your backend authenticates and
-authorizes the privacy request:
-
-```ts
-const request = await robono.dataRequests.deleteUser({
-  external_user_id: user.id,
-  external_request_id: privacyCase.id,
-}, { idempotencyKey: privacyCase.operationId });
-
-const status = await robono.dataRequests.status({
-  data_request_id: request.data_request.id,
-});
-
-if (status.export) {
-  await yourPrivacySystem.storeCompletedExport(status.export);
-}
-```
-
-Deletion requires a stable idempotency key. Signed `data.export_*` and
-`data.deletion_*` events report completion or failure; status lookup remains
-available if a webhook is delayed. A completed JSON export remains available
-from status responses until `result_expires_at`. Use a `data:read` or
-`data:write` API key when the operation should not share the integration's
-broader credential.
+Store each event once by event ID, return HTTP 2xx within 10 seconds, and process it asynchronously. Duplicate events must not create duplicate work. Connection requests must be resolved and approved only by an authorized server action.
 
 ## Run the sandbox lifecycle
 
@@ -313,9 +135,7 @@ ROBONO_SANDBOX_NETWORK_B_ID=... \
 npx --package @robono/server robono-sandbox-test
 ```
 
-The test runs the stateful network-to-network lifecycle, then validates the same unified connection and send methods against the test-only Robono endpoint. The Robono endpoint check cannot reach real users, SMS, billing, or production delivery.
-
-The lifecycle runner tests Robono's sandbox API, not your authentication, CORS, or deployed adapter. Test those separately:
+The lifecycle runner tests Robono's isolated Sandbox. Test your own authentication, authorization, and CORS separately:
 
 ```bash
 ROBONO_ADAPTER_URL=https://your-backend.example/robono \
@@ -328,18 +148,14 @@ npx --package @robono/server robono-adapter-test
 
 All packages are currently early-access `0.x` releases. Patch releases contain
 compatible fixes. Before `1.0`, a minor release may contain a breaking change;
-read the packaged `CHANGELOG.md` before upgrading. The latest minor line is the
-supported line, and public API versions receive at least 90 days' notice before
-retirement.
-
-The exact package and API compatibility matrix is published at
-[robono.com/docs#test](https://robono.com/docs#test). Production credentials
-start at 300 requests per rolling minute; Sandbox credentials start at 600.
-There is no separate published concurrency quota. Honor `Retry-After` on rate
-limits and retryable temporary failures.
+read the packaged `CHANGELOG.md` before upgrading. Each minor package line
+receives critical security and Bridge compatibility fixes for at least 12
+months after its successor is published. Public API versions receive at least
+12 months' notice before retirement unless continued support would create an
+active security risk.
 
 Report SDK problems at [robono.com/contact?topic=sdk](https://robono.com/contact?topic=sdk).
 Include the package version, runtime, safe reproduction steps, and request ID;
 never include credentials or private message content.
 
-See the complete build flow, REST reference, platform support, capabilities, delivery behavior, and testing guide at [robono.com/docs](https://robono.com/docs).
+See the complete build flow, optional language and privacy operations, platform support, and testing guide at [robono.com/docs](https://robono.com/docs).

package/SBOM.spdx.json

@@ -2,22 +2,22 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@robono/server@0.8.0",
-  "documentNamespace": "http://spdx.org/spdxdocs/@robono%2fserver-0.8.0-d581d2ee-66b5-4ca6-82e1-b207f45d0a67",
+  "name": "@robono/server@0.8.1",
+  "documentNamespace": "http://spdx.org/spdxdocs/@robono%2fserver-0.8.1-5363c57b-f29a-4d3f-bcb9-1e07d0a950d0",
   "creationInfo": {
-    "created": "2026-07-29T22:21:34.416Z",
+    "created": "2026-07-30T22:37:53.518Z",
     "creators": [
       "Tool: npm/cli-12.0.2"
     ]
   },
   "documentDescribes": [
-    "SPDXRef-Package-robono.server-0.8.0"
+    "SPDXRef-Package-robono.server-0.8.1"
   ],
   "packages": [
     {
       "name": "@robono/server",
-      "SPDXID": "SPDXRef-Package-robono.server-0.8.0",
-      "versionInfo": "0.8.0",
+      "SPDXID": "SPDXRef-Package-robono.server-0.8.1",
+      "versionInfo": "0.8.1",
       "packageFileName": "",
       "description": "Provider-neutral server SDK for the Robono Bridge API.",
       "primaryPackagePurpose": "LIBRARY",
@@ -29,7 +29,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40robono/server@0.8.0"
+          "referenceLocator": "pkg:npm/%40robono/server@0.8.1"
         }
       ]
     }
@@ -37,7 +37,7 @@
   "relationships": [
     {
       "spdxElementId": "SPDXRef-DOCUMENT",
-      "relatedSpdxElement": "SPDXRef-Package-robono.server-0.8.0",
+      "relatedSpdxElement": "SPDXRef-Package-robono.server-0.8.1",
       "relationshipType": "DESCRIBES"
     }
   ]

package/dist/client.js

@@ -45,7 +45,7 @@ export class RobonoServer {
                 code: "fetch_required",
             });
         }
-        this.userAgent = options.userAgent ?? "@robono/server/0.8.0";
+        this.userAgent = options.userAgent ?? "@robono/server/0.8.1";
         this.apiVersion = options.apiVersion?.trim() || DEFAULT_API_VERSION;
         this.directory = {
             list: (input = {}, requestOptions) => this.request("/networks", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robono/server",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Provider-neutral server SDK for the Robono Bridge API.",
   "keywords": [
     "robono",