@robono/server 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.7.0
+
+- Added authenticated guardian messaging to the protected backend adapter.
+- Added machine-readable directory identifier rules and aligned public pending-status handling.
+- Added credential-free CLI help and contract checks for the corrected OpenAPI profile fields.
+- Expanded the receiving-app, fail-closed authorization, capabilities, media, receipt, and reaction documentation.
+
+## 0.6.0
+
+- Fixed `health()` to use the production `GET /health` contract.
+- Added normalized connection peers and complete endpoint-neutral connection and message namespaces.
+- Added app-to-app profile propagation, delta message cursors, push diagnostics through the adapter, and an adapter smoke-test command.
+- Added atomic webhook event claims, stronger webhook validation, paginated receipt authorization, and sanitized server errors.
+- Corrected the generated OpenAPI contract and removed misleading package source links.
+
 ## 0.5.0
 
 - Added typed message and standalone speech transform contracts, operation-level billing details, generated-media URL expiration, and typed webhook event unions.

package/README.md

@@ -2,6 +2,10 @@
 
 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.
 
+## License in plain English
+
+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.
+
 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.
 
 ## Install
@@ -16,7 +20,7 @@ The package is ESM-only and supports Node.js 18+ and Deno 2.x through npm compat
 import {
   createRobonoBackendAdapter,
   RobonoServer,
-} from "npm:@robono/server@0.5.0";
+} from "npm:@robono/server@0.7.0";
 ```
 
 ## Discover endpoints
@@ -39,6 +43,9 @@ for (const endpoint of directory) {
 ```
 
 Show the returned endpoints in your app and ask for the identifier described by the selected endpoint. Do not hard-code Robono as a separate integration path.
+Each `accepted_identifier` also includes `input_type`, `pattern`, length,
+normalization, and case rules so the same value can be validated consistently
+before lookup.
 
 Use the same methods after any endpoint is selected:
 
@@ -53,7 +60,11 @@ const connection = await robono.connections.connect({
   external_user_id: user.id,
   external_display_name: user.displayName,
   target_identifier: identifierEnteredByUser,
-  capabilities: yourRules.forConnection(user.id),
+  capabilities: {
+    allowed_outbound_message_kinds: ["text"],
+    allowed_inbound_message_kinds: ["text"],
+    text: { max_characters: 1000 },
+  },
 });
 
 const result = await robono.messages.send({
@@ -69,6 +80,41 @@ The normalized `connection.connection_id` is valid for SDK state and subsequent
 
 The unified send validates negotiated message type, text length, media size, duration, and MIME type before making the API request. Validate capabilities before uploading media so unsupported work fails early.
 
+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,
+});
+
+await robono.endpointMessages.mark({
+  connection,
+  external_user_id: user.id,
+  message_id: history.messages[0].message_id,
+  event: "read",
+});
+
+await robono.endpointConnections.update({
+  connection,
+  external_user_id: user.id,
+  external_profile: currentProfile,
+});
+
+await robono.endpointConnections.disconnect({
+  connection,
+  external_user_id: user.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.
+
 ## Protect client operations
 
 Keep the API key on your server. Mount the adapter at `/robono/*` behind your existing authentication:
@@ -77,12 +123,30 @@ Keep the API key on your server. Mount the adapter at `/robono/*` behind your ex
 const handleRobono = createRobonoBackendAdapter({
   robono,
   authenticate: request => yourAuth.requireUser(request).id,
-  authorize: ({ action, userId, input }) =>
-    yourPolicy.authorizeRobonoOperation({
-      action,
-      userId,
-      input,
-    }),
+  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;
+  },
 });
 ```
 
@@ -124,11 +188,14 @@ const verified = await verifyRobonoWebhook(
   rawBody,
   request.headers,
   process.env.ROBONO_WEBHOOK_SECRET!,
-  { hasProcessedEvent: eventId => events.has(eventId) },
+  { claimEvent: eventId => eventStore.insertIfAbsent(eventId) },
 );
 
 if (!verified.duplicate) {
   switch (verified.event.event) {
+    case "bridge.connection_requested":
+      await pendingRequests.store(verified.event);
+      break;
     case "connection.status_changed":
     case "bridge.connection_status_changed":
       await existingMessagingSystem.updateConnection(verified.event);
@@ -145,7 +212,13 @@ if (!verified.duplicate) {
 }
 ```
 
-`verified.event` is a discriminated `RobonoWebhookEvent` union covering connection, message, receipt, guardian, transform, failure, and diagnostic events. Store processed event IDs so repeated delivery is harmless.
+`verified.event` is a discriminated `RobonoWebhookEvent` union covering connection, message, receipt, guardian, transform, failure, and diagnostic events. `claimEvent` must atomically return `true` only for the first delivery so concurrent retries cannot process the same event twice.
+
+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.
 
 ## Run the sandbox lifecycle
 
@@ -158,4 +231,13 @@ 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:
+
+```bash
+ROBONO_ADAPTER_URL=https://your-backend.example \
+ROBONO_ADAPTER_ACCESS_TOKEN=your_test_user_token \
+ROBONO_ADAPTER_EXPECTED_ORIGIN=https://your-app.example \
+npx --package @robono/server robono-adapter-test
+```
+
 See the complete build flow, REST reference, platform support, capabilities, delivery behavior, and testing guide at [robono.com/docs](https://robono.com/docs).

package/dist/adapter-smoke-test.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=adapter-smoke-test.d.ts.map

package/dist/adapter-smoke-test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-smoke-test.d.ts","sourceRoot":"","sources":["../src/adapter-smoke-test.ts"],"names":[],"mappings":""}

package/dist/adapter-smoke-test.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+    console.log(`Usage: robono-adapter-test
+
+Checks authentication, directory access, and optional CORS on your deployed
+protected adapter.
+
+Required environment variables:
+  ROBONO_ADAPTER_URL
+  ROBONO_ADAPTER_ACCESS_TOKEN
+
+Optional:
+  ROBONO_ADAPTER_EXPECTED_ORIGIN`);
+    process.exit(0);
+}
+const baseUrl = requiredEnvironment("ROBONO_ADAPTER_URL").replace(/\/+$/, "");
+const accessToken = requiredEnvironment("ROBONO_ADAPTER_ACCESS_TOKEN");
+const expectedOrigin = process.env.ROBONO_ADAPTER_EXPECTED_ORIGIN?.trim();
+const route = `${baseUrl}/robono/networks`;
+await check("Unauthenticated requests are rejected", async () => {
+    const response = await request(route, {});
+    if (response.status !== 401) {
+        throw new Error(`expected HTTP 401, received ${response.status}`);
+    }
+});
+await check("Authenticated directory request succeeds", async () => {
+    const response = await request(route, {
+        authorization: `Bearer ${accessToken}`,
+    });
+    const payload = await response.json().catch(() => ({}));
+    if (!response.ok) {
+        throw new Error(payload.error?.message ?? `received HTTP ${response.status}`);
+    }
+    if (!Array.isArray(payload.directory)) {
+        throw new Error("response does not contain a directory");
+    }
+});
+if (expectedOrigin) {
+    await check("Configured browser origin is allowed", async () => {
+        const response = await fetchWithTimeout(route, {
+            method: "OPTIONS",
+            headers: {
+                origin: expectedOrigin,
+                "access-control-request-method": "POST",
+                "access-control-request-headers": "authorization,content-type",
+            },
+        });
+        const allowed = response.headers.get("access-control-allow-origin");
+        if (allowed !== expectedOrigin) {
+            throw new Error(`expected Access-Control-Allow-Origin ${expectedOrigin}, received ${allowed ?? "no header"}`);
+        }
+    });
+}
+console.log("Robono adapter smoke test passed.");
+async function request(url, headers) {
+    return fetchWithTimeout(url, {
+        method: "POST",
+        headers: { "content-type": "application/json", ...headers },
+        body: "{}",
+    });
+}
+async function fetchWithTimeout(url, init) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 15_000);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function check(label, operation) {
+    try {
+        await operation();
+        console.log(`PASS ${label}`);
+    }
+    catch (error) {
+        console.error(`FAIL ${label}: ${error instanceof Error ? error.message : "unknown error"}`);
+        process.exitCode = 1;
+        throw error;
+    }
+}
+function requiredEnvironment(name) {
+    const value = process.env[name]?.trim();
+    if (!value) {
+        console.error(`${name} is required.`);
+        process.exit(1);
+    }
+    return value;
+}
+export {};
+//# sourceMappingURL=adapter-smoke-test.js.map

package/dist/adapter-smoke-test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-smoke-test.js","sourceRoot":"","sources":["../src/adapter-smoke-test.ts"],"names":[],"mappings":"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"}

package/dist/adapter.d.ts

@@ -1,6 +1,6 @@
 import type { RobonoServer } from "./client.js";
 import type { JsonObject } from "./types.js";
-export type RobonoAuthorizationAction = "networks.list" | "network_connections.request" | "network_connections.respond" | "network_connections.list" | "network_connections.disconnect" | "network_connections.update" | "robono_connections.create" | "robono_connections.list" | "robono_connections.update_profile" | "robono_connections.disconnect" | "network_messages.send" | "network_messages.list" | "network_messages.mark" | "robono_messages.send" | "robono_messages.list" | "robono_messages.mark" | "message_transforms.create" | "speech_transforms.create";
+export type RobonoAuthorizationAction = "networks.list" | "network_connections.request" | "network_connections.respond" | "network_connections.list" | "network_connections.disconnect" | "network_connections.update" | "robono_connections.create" | "robono_connections.list" | "robono_connections.update_profile" | "robono_connections.disconnect" | "network_messages.send" | "network_messages.list" | "network_messages.mark" | "robono_messages.send" | "robono_messages.list" | "robono_messages.mark" | "guardian_messages.send" | "guardian_messages.list" | "guardian_messages.mark" | "message_transforms.create" | "speech_transforms.create" | "push_diagnostics.report";
 export interface RobonoAuthorizationContext {
     action: RobonoAuthorizationAction;
     userId: string;

package/dist/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,MAAM,yBAAyB,GACjC,eAAe,GACf,6BAA6B,GAC7B,6BAA6B,GAC7B,0BAA0B,GAC1B,gCAAgC,GAChC,4BAA4B,GAC5B,2BAA2B,GAC3B,yBAAyB,GACzB,mCAAmC,GACnC,+BAA+B,GAC/B,uBAAuB,GACvB,uBAAuB,GACvB,uBAAuB,GACvB,sBAAsB,GACtB,sBAAsB,GACtB,sBAAsB,GACtB,2BAA2B,GAC3B,0BAA0B,CAAC;AAE/B,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,yBAAyB,CAAC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,YAAY,CAAC;IACrB,YAAY,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7D,SAAS,EAAE,CACT,OAAO,EAAE,0BAA0B,KAChC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAuBD,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,2BAA2B,IAIP,SAAS,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC,CA2TlE"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,MAAM,yBAAyB,GACjC,eAAe,GACf,6BAA6B,GAC7B,6BAA6B,GAC7B,0BAA0B,GAC1B,gCAAgC,GAChC,4BAA4B,GAC5B,2BAA2B,GAC3B,yBAAyB,GACzB,mCAAmC,GACnC,+BAA+B,GAC/B,uBAAuB,GACvB,uBAAuB,GACvB,uBAAuB,GACvB,sBAAsB,GACtB,sBAAsB,GACtB,sBAAsB,GACtB,wBAAwB,GACxB,wBAAwB,GACxB,wBAAwB,GACxB,2BAA2B,GAC3B,0BAA0B,GAC1B,yBAAyB,CAAC;AAE9B,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,yBAAyB,CAAC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,YAAY,CAAC;IACrB,YAAY,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7D,SAAS,EAAE,CACT,OAAO,EAAE,0BAA0B,KAChC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AA2BD,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,2BAA2B,IAIP,SAAS,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC,CAsalE"}

package/dist/adapter.js

@@ -16,8 +16,12 @@ const authorizationActions = {
     "/messages": "robono_messages.send",
     "/messages/list": "robono_messages.list",
     "/message-events": "robono_messages.mark",
+    "/guardian-messages": "guardian_messages.send",
+    "/guardian-messages/list": "guardian_messages.list",
+    "/guardian-messages/events": "guardian_messages.mark",
     "/transforms/message": "message_transforms.create",
     "/transforms/speech": "speech_transforms.create",
+    "/push-diagnostics/events": "push_diagnostics.report",
 };
 export function createRobonoBackendAdapter(options) {
     const maxRequestBytes = positiveInteger(options.maxRequestBytes, 1_000_000);
@@ -48,7 +52,11 @@ export function createRobonoBackendAdapter(options) {
             if (!authorized) {
                 return responseError(403, "operation_not_authorized", "The child app did not authorize this operation for the signed-in user.", requestId);
             }
-            const requestOptions = { requestId };
+            const idempotencyKey = optionalIdempotencyKey(request.headers.get("idempotency-key"));
+            const requestOptions = {
+                requestId,
+                ...(idempotencyKey ? { idempotencyKey } : {}),
+            };
             if (path === "/networks") {
                 return responseJson(await options.robono.directory.list({}, requestOptions));
             }
@@ -72,11 +80,15 @@ export function createRobonoBackendAdapter(options) {
                 const status = optionalString(body.status);
                 const limit = optionalNumber(body.limit);
                 const before = optionalString(body.before);
+                const bridgeConnectionId = optionalString(body.bridge_connection_id);
                 return responseJson(await options.robono.networkConnections.list({
                     external_user_id: externalUserId,
                     ...(status ? { status } : {}),
                     ...(limit ? { limit } : {}),
                     ...(before ? { before } : {}),
+                    ...(bridgeConnectionId
+                        ? { bridge_connection_id: bridgeConnectionId }
+                        : {}),
                 }, requestOptions));
             }
             if (path === "/network-connections/disconnect") {
@@ -106,11 +118,13 @@ export function createRobonoBackendAdapter(options) {
                 const status = optionalString(body.status);
                 const limit = optionalNumber(body.limit);
                 const before = optionalString(body.before);
+                const connectionId = optionalString(body.connection_id);
                 return responseJson(await options.robono.connections.list({
                     external_user_id: externalUserId,
                     ...(status ? { status } : {}),
                     ...(limit ? { limit } : {}),
                     ...(before ? { before } : {}),
+                    ...(connectionId ? { connection_id: connectionId } : {}),
                 }, requestOptions));
             }
             if (path === "/connections/profile") {
@@ -139,21 +153,25 @@ export function createRobonoBackendAdapter(options) {
             if (path === "/messages/list") {
                 const limit = optionalNumber(body.limit);
                 const before = optionalString(body.before);
+                const after = optionalString(body.after);
                 return responseJson(await options.robono.messages.listFromRobono({
                     connection_id: requiredString(body.connection_id, "connection_id"),
                     external_user_id: externalUserId,
                     ...(limit ? { limit } : {}),
                     ...(before ? { before } : {}),
+                    ...(after ? { after } : {}),
                 }, requestOptions));
             }
             if (path === "/network-messages/list") {
                 const limit = optionalNumber(body.limit);
                 const before = optionalString(body.before);
+                const after = optionalString(body.after);
                 return responseJson(await options.robono.messages.list({
                     bridge_connection_id: requiredString(body.bridge_connection_id, "bridge_connection_id"),
                     external_user_id: externalUserId,
                     ...(limit ? { limit } : {}),
                     ...(before ? { before } : {}),
+                    ...(after ? { after } : {}),
                 }, requestOptions));
             }
             if (path === "/network-messages/events") {
@@ -185,25 +203,78 @@ export function createRobonoBackendAdapter(options) {
                     ...(occurredAt ? { occurred_at: occurredAt } : {}),
                 }, requestOptions));
             }
+            if (path === "/guardian-messages") {
+                return responseJson(await options.robono.messages.sendGuardian({
+                    bridge_connection_id: requiredString(body.bridge_connection_id, "bridge_connection_id"),
+                    external_guardian_id: externalUserId,
+                    external_message_id: requiredString(body.external_message_id, "external_message_id"),
+                    text_body: requiredString(body.text_body, "text_body"),
+                    message_kind: "text",
+                }, requestOptions));
+            }
+            if (path === "/guardian-messages/list") {
+                const limit = optionalNumber(body.limit);
+                const before = optionalString(body.before);
+                return responseJson(await options.robono.messages.listGuardian({
+                    bridge_connection_id: requiredString(body.bridge_connection_id, "bridge_connection_id"),
+                    ...(limit ? { limit } : {}),
+                    ...(before ? { before } : {}),
+                }, requestOptions));
+            }
+            if (path === "/guardian-messages/events") {
+                const occurredAt = optionalString(body.occurred_at);
+                return responseJson(await options.robono.messages.markGuardian({
+                    bridge_connection_id: requiredString(body.bridge_connection_id, "bridge_connection_id"),
+                    guardian_message_id: requiredString(body.guardian_message_id, "guardian_message_id"),
+                    event: requiredGuardianEvent(body.event),
+                    ...(occurredAt ? { occurred_at: occurredAt } : {}),
+                }, requestOptions));
+            }
             if (path === "/transforms/speech") {
                 return responseJson(await options.robono.transforms.speech(body, requestOptions));
             }
             if (path === "/transforms/message") {
                 return responseJson(await options.robono.transforms.message(body, requestOptions));
             }
-            throw new Error("Authorized adapter route has no handler.");
+            if (path === "/push-diagnostics/events") {
+                const failureStage = optionalString(body.failure_stage);
+                const failureReason = optionalString(body.failure_reason);
+                const platform = optionalString(body.platform);
+                const provider = optionalString(body.provider);
+                const appVersion = optionalString(body.app_version);
+                const detail = optionalString(body.detail);
+                return responseJson(await options.robono.diagnostics.reportPush({
+                    diagnostic_id: requiredString(body.diagnostic_id, "diagnostic_id"),
+                    diagnostic_token: requiredString(body.diagnostic_token, "diagnostic_token"),
+                    stage: requiredPushDiagnosticStage(body.stage),
+                    ...(failureStage ? { failure_stage: failureStage } : {}),
+                    ...(failureReason ? { failure_reason: failureReason } : {}),
+                    ...(platform ? { platform } : {}),
+                    ...(provider ? { provider } : {}),
+                    ...(appVersion ? { app_version: appVersion } : {}),
+                    ...(detail ? { detail } : {}),
+                }, requestOptions));
+            }
+            throw new AdapterRequestError(500, "adapter_handler_missing", "Authorized adapter route has no handler.");
         }
         catch (error) {
+            if (error instanceof AdapterRequestError) {
+                return responseError(error.status, error.code, error.message, requestId);
+            }
             if (error instanceof RobonoError) {
+                const status = error.status ??
+                    (error.code === "request_timeout" ? 504 : 502);
                 return responseJson({
                     error: { code: error.code, message: error.message },
                     request_id: error.requestId ?? requestId,
                     ...(error.fields ? { fields: error.fields } : {}),
-                }, error.status ?? 400);
+                }, status);
             }
-            return responseError(400, "adapter_request_failed", error instanceof Error
-                ? error.message
-                : "Robono adapter request failed.", requestId);
+            console.error("Unexpected Robono adapter failure", {
+                request_id: requestId,
+                error,
+            });
+            return responseError(500, "adapter_internal_error", "The Robono adapter could not complete the request.", requestId);
         }
     };
 }
@@ -227,38 +298,57 @@ function inputWithAuthenticatedUser(action, input, userId) {
         action === "robono_messages.send"
         || action === "robono_messages.list"
         || action === "robono_messages.mark"
-        || action === "message_transforms.create") {
-        return { ...input, external_user_id: userId };
+        || action === "guardian_messages.send"
+        || action === "guardian_messages.list"
+        || action === "guardian_messages.mark"
+        || action === "message_transforms.create"
+        || action === "push_diagnostics.report") {
+        return action.startsWith("guardian_messages.")
+            ? { ...input, external_guardian_id: userId }
+            : { ...input, external_user_id: userId };
     }
     return { ...input };
 }
 async function assertConnectionBelongsToUser(robono, connectionId, externalUserId, requestId) {
-    const result = await robono.networkConnections.list({
-        external_user_id: externalUserId,
-        limit: 100,
-    }, { requestId });
-    if (!result.connections.some((item) => item.bridge_connection_id === connectionId)) {
-        throw new RobonoError("Connection was not found for this child app user.", {
-            code: "connection_not_found",
-            status: 404,
-            requestId,
-        });
+    let before;
+    for (let page = 0; page < 1_000; page += 1) {
+        const result = await robono.networkConnections.list({
+            external_user_id: externalUserId,
+            limit: 100,
+            ...(before ? { before } : {}),
+        }, { requestId });
+        if (result.connections.some((item) => item.bridge_connection_id === connectionId))
+            return;
+        if (!result.has_more || !result.next_before)
+            break;
+        before = result.next_before;
     }
+    throw new RobonoError("Connection was not found for this child app user.", {
+        code: "connection_not_found",
+        status: 404,
+        requestId,
+    });
 }
 async function readBody(request, maxRequestBytes) {
     const length = Number(request.headers.get("content-length") ?? "0");
     if (Number.isFinite(length) && length > maxRequestBytes) {
-        throw new Error("Request body is too large.");
+        throw new AdapterRequestError(413, "request_body_too_large", "Request body is too large.");
     }
     const text = await request.text();
     if (new TextEncoder().encode(text).byteLength > maxRequestBytes) {
-        throw new Error("Request body is too large.");
+        throw new AdapterRequestError(413, "request_body_too_large", "Request body is too large.");
     }
     if (!text.trim())
         return {};
-    const parsed = JSON.parse(text);
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new AdapterRequestError(400, "invalid_json", "Request body must contain valid JSON.");
+    }
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new Error("Request body must be a JSON object.");
+        throw new AdapterRequestError(400, "invalid_request_body", "Request body must be a JSON object.");
     }
     return parsed;
 }
@@ -270,13 +360,23 @@ function normalizedAdapterPath(pathname) {
 }
 function requiredString(value, field) {
     const normalized = optionalString(value);
-    if (!normalized)
-        throw new Error(`${field} is required.`);
+    if (!normalized) {
+        throw new AdapterRequestError(422, "required_field_missing", `${field} is required.`);
+    }
     return normalized;
 }
 function optionalString(value) {
     return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
+function optionalIdempotencyKey(value) {
+    if (!value)
+        return undefined;
+    const key = value.trim();
+    if (key.length < 8 || key.length > 200) {
+        throw new AdapterRequestError(422, "idempotency_key_invalid", "Idempotency-Key must contain 8 to 200 characters.");
+    }
+    return key;
+}
 function optionalNumber(value) {
     return typeof value === "number" && Number.isFinite(value)
         ? value
@@ -286,13 +386,35 @@ function requiredEvent(value) {
     if (value === "delivered" || value === "read" || value === "heard") {
         return value;
     }
-    throw new Error("event must be delivered, read, or heard.");
+    throw new AdapterRequestError(422, "event_invalid", "event must be delivered, read, or heard.");
+}
+function requiredGuardianEvent(value) {
+    if (value === "delivered" || value === "read")
+        return value;
+    throw new AdapterRequestError(422, "event_invalid", "event must be delivered or read.");
 }
 function requiredConnectionResponseStatus(value) {
     if (value === "accepted" || value === "rejected" || value === "not_found") {
         return value;
     }
-    throw new Error("status must be accepted, rejected, or not_found.");
+    throw new AdapterRequestError(422, "connection_status_invalid", "status must be accepted, rejected, or not_found.");
+}
+function requiredPushDiagnosticStage(value) {
+    if (value === "provider_accepted" || value === "device_received" ||
+        value === "content_fetched" || value === "rendered" ||
+        value === "polling_recovered" || value === "failed")
+        return value;
+    throw new AdapterRequestError(422, "push_diagnostic_stage_invalid", "stage is not a supported push diagnostic stage.");
+}
+class AdapterRequestError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "AdapterRequestError";
+    }
 }
 function positiveInteger(value, fallback) {
     return typeof value === "number" && Number.isFinite(value) && value > 0