@collective-intelligence/external-apps-server-sdk 0.1.17 → 0.1.19

package/README.md

@@ -651,53 +651,31 @@ await ci.origins.setRuntime({
 - It needs the `origins:write` scope. Only service credentials may call it: a
   delegated user token or an anonymous visitor gets `operation_not_allowed`.
 
-## Member company links
+## Records a user acts for
 
-An application links a member of its Organization to the Knowledge company
-entities the member acts for. A member can have several companies and a company
-several members.
+A schema declares its accounts field to name the users that act for each of its
+records (see the [Knowledge User fields](../../../docs/reference/knowledge-user-fields.md)
+reference). CI stores no other link between a user and a record, and offers no
+operation that lists or changes one: write the accounts field as an
+administrator, with the workflow account step or with the Default Server Role
+credential. A policy reads the field as `resource` path `["data", "accounts"]`
+and the caller as `subject` path `["user", "id"]`.
 
-```ts
-const linked = await ci.users.linkCompanies({
-  entityIds: [companyEntityId],
-  organizationId,
-  userId
-})
-// linked.value.result: { entityIds } — all of the user's links
-
-const links = await ci.users.listCompanyLinks({ organizationId, userId })
-```
-
-- Only confidential service credentials may call these operations: a delegated
-  user token or an anonymous visitor gets `operation_not_allowed`, and the
-  browser client and user proxy do not offer them.
-- The Organization is the caller's. A user without membership in it, or an
-  entity that is missing, deleted, or in another Organization, returns
-  `not_found`; a refused call links nothing.
-- Linking keeps existing links, so a retried call converges. Results list the
-  user's linked entities in entity id order.
-- `knowledge:write` gates `linkCompanies`; `knowledge:read` gates
-  `listCompanyLinks`.
-- CI accepts any entity of the Organization and does not check its schema; the
-  calling application decides which entities count as companies.
-- Entity deduplication moves links to the surviving entity; physically deleting
-  an entity removes its links.
 - A delegated user's `/application/v1/resources` and `knowledge_*` calls, and
-  the Agents, Skills and workflows the user runs, carry the user's links to
-  Knowledge policy as `subject.linkedCompanyIds`, and a policy reads the
-  entity id as `resource` path `["id"]`. CI also sets `subject.access`:
-  `"read"` for gets, lists, searches, facets, autocomplete, traversal and
-  retrieval, `"write"` for creates, updates, deletes and relation writes. The
-  operation sets it; a caller cannot. A policy that does not test `access`
-  applies to reads and writes alike.
+  the Agents, Skills and workflows the user runs, decide under the user's
+  Knowledge policy subject. CI sets `subject.access`: `"read"` for gets, lists,
+  searches, facets, autocomplete, traversal and retrieval, `"write"` for
+  creates, updates, deletes and relation writes. The operation sets it; a
+  caller cannot. A policy that does not test `access` applies to reads and
+  writes alike.
 - To let `member`-role users write only their own companies but read every
   company (for example through member-run Agents), declare a `deny` `filter`
   policy on the company schema: subject match `user.role` equals `member` and
-  `access` equals `write`, rule "entity id not in `linkedCompanyIds`". Updates
-  and deletes of any other company, and creates, then fail with `forbidden`;
-  gets, lists and searches still return it. Without the `access` clause the
-  same policy also hides other companies from reads. Other roles and service
-  credentials are unaffected.
+  `access` equals `write`, rule "`subject.user.id` not in
+  `resource.data.accounts`". Updates and deletes of any other company, and
+  creates, then fail with `forbidden`; gets, lists and searches still return it.
+  Without the `access` clause the same policy also hides other companies from
+  reads. Other roles and service credentials are unaffected.
 - The policy binds an execution only while it acts as the member. An Agent or
   Skill tool bound to a fixed user, or a workflow that runs as another user or
   a service principal, decides as that principal, not as the member who
@@ -1562,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