@collective-intelligence/external-apps-server-sdk 0.1.18 → 0.1.21

package/README.md

@@ -1540,6 +1540,37 @@ and is not forwarded. A local `defineEntityResource` binding answers
 `capability_not_supported`, and a `defineCrudResource` handler answers 404 for
 this path. The client SDK README documents the write form.
 
+### Realtime ticket route
+
+A browser opens the CI realtime stream with a single-use ticket, never with the
+user's token. Add `realtime` to the BFF; it mounts
+`POST {basePath}/realtime/ticket` (`basePath` defaults to `/api`) ahead of the
+dedicated Capability prefix:
+
+```ts
+createExternalApplicationBffNextHandlers({
+  auth,
+  publicOrigin: env.APP_ORIGIN,
+  realtime: {
+    organizationId: env.CI_ORGANIZATION_ID,
+    tenantUrl: env.CI_TENANT_URL,
+    // Optional: the origin the browser opens the stream on.
+    host: "https://realtime.example.com"
+  }
+})
+```
+
+The route accepts `{ topics }` as JSON from the application's own origin
+(cross-site requests answer 403), reads the signed-in user's server-held
+delegated token, and calls CI `POST /application/v1/realtime/tickets` with it.
+It answers `{ ticket, expiresAt, streamUrl }`; `streamUrl` is
+`{host}/application/v1/realtime/events?ticket=…`, and `host` defaults to
+`tenantUrl`. Without a session it answers 401 before calling CI. CI refusals
+keep their status, body, and `Retry-After`: 429 `too_many_connections` at the
+per-user connection cap, 503 `unavailable`. Use
+`createRealtimeTicketHandler` from `/runtime/web` or `/runtime/next` to mount
+the route yourself. The client SDK README documents the browser client.
+
 ## Optional local user authentication
 
 Import `createBetterAuth` only from