@collective-intelligence/external-apps-server-sdk 0.1.9 → 0.1.11

package/README.md

@@ -503,47 +503,41 @@ const sent = await ci.messages.send({
   reached its rate limit; it is retryable, and the client repeats it with the
   same key.
 
-## Member users
+## Application users and roles
 
-A confidential application administers the `member` users of its own
-Organization: people whose only role there is `member` (Organization identity
-and their own Knowledge; no CI Studio or dashboard). The Organization is the
-one the credentials were authorized for through `organizationId`; a request
-cannot reach another Organization.
+Use `ci.users` and `ci.roles` with a delegated user token or service
+credentials. CI checks the caller's current `users.create` and `assignRoles`
+permissions. These methods replace the former `ci.members` API.
 
 ```ts
-const ci = createServerClient({
-  authentication: { credentials, mode: "service" },
-  tenantUrl
-})
-
-const created = await ci.members.createOrGet({
+const created = await ci.users.createOrGet({
   email: "info@rossi.example",
   name: "Rossi Srl",
-  organizationId
+  organizationId,
+  roles: ["patient"],
+  serverRole: "onboarding" // Optional for service calls; omission uses the credential default.
 })
-// created.value.result: { userId, email, name, outcome }
+// On success: created.value.result = { userId, email, name, created, kind }
+// kind is "member" or "external_app_user".
 ```
 
-- `createOrGet` resolves an email to one member user. `outcome` is `created`
-  for a new CI user, `linked` when an existing CI user joined the Organization
-  as a member, and `existing` when the user already was one. The email is
-  matched ignoring letter case, and concurrent or retried calls return the
-  same `userId`. It never sends CI's activation invitation and never accepts
-  a pending Organization invitation for the email; the application owns
-  onboarding.
-- `get({ userId })`, `list({ page?, pageSize? })` (at most 100 per page),
-  `update({ userId, name })` and `remove({ userId })` act only on member users.
-  `update` changes the name only of a user who belongs to no other
-  Organization. `remove` ends the `member` membership and keeps the CI user.
-- A user who holds any other role in the Organization (an administrator, for
-  example) is refused with `conflict` by every operation. `get`, `update` and
-  `remove` answer `not_found` for a user who is not in the Organization.
-- Reads need the `members:read` scope and writes `members:write`. Only service
-  credentials may call them: a delegated user token or an anonymous visitor
-  gets `operation_not_allowed`.
-- Only `temporarily_unavailable` is retryable (the client retries it); a
-  creation CI refuses is a non-retryable `internal_error`.
+- `createOrGet` reuses the person's auth identity. A new app user has no
+  Organization membership. An existing member remains a member.
+- `get({ organizationId, userId })` and
+  `list({ organizationId, page?, pageSize? })` read users accessible to this
+  app. A list result contains `items`.
+- `deactivate({ organizationId, userId })` ends access to the calling app for
+  an app user it may deactivate; it does not remove Organization membership.
+- `roles.list({ organizationId })` returns `items` with role `id` and `key`.
+  `roles.assign({ organizationId, userId, roles })` and `roles.revoke(...)`
+  change this app's assignments within the caller's `assignRoles` permission.
+  They cannot write Organization Roles, Groups, or another app's roles.
+- Pass `serverRole` on a service request to select an allowed Server Role via
+  `x-external-server-role`. It applies only to that request; credentials and
+  subsequent calls retain their default. It does not impersonate a user.
+- Refusals preserve the structured error, including a reason such as
+  `role_not_assignable`. Non-retryable refusals are returned without retrying.
+  CI records the actual user, or application and Server Role, as the actor.
 
 ## Durable files
 
@@ -579,6 +573,79 @@ await ci.workflows.invoke({
 - It needs the `ai:attachments` scope. Only service credentials may call it: a
   delegated user token or an anonymous visitor gets `operation_not_allowed`.
 
+### Entity File fields
+
+A File field of an entity schema takes a different flow: the file becomes a
+File value of the entity, not a stored file a workflow reads.
+`resources.createUpload` asks CI for a single-use upload slot, the server PUTs
+the bytes straight to storage, and the entity write through CI's resources API
+names the slot's `uploadId` as `{ upload }` for that File field key:
+
+```ts
+const slot = await ci.resources.createUpload({
+  field: "memberLogo",
+  filename: "logo.png",
+  mimeType: "image/png",
+  organizationId,
+  schemaId: "apito.vetrina.schemas.member-company"
+})
+if (slot.ok) {
+  const { headers, method, uploadId, url } = slot.value.result
+  await fetch(url, { body: logo, headers, method })
+  // The entity write then sends { memberLogo: { upload: uploadId } }.
+}
+```
+
+- Two credentials can ask for a slot, as for entity writes: the member's
+  delegated token (`exchangeMemberSession`), writing as that member; or the
+  application's service credential, for schemas declared by the application's
+  own package only, writing as the Organization default service principal.
+  `schemaId` is the schema id or FQN.
+- A refusal resolves `{ ok: false, error }` with CI's `correlationId` and a
+  `code`; `upload_not_supported` means the Organization storage cannot presign
+  uploads. Only `retryable` failures are retried.
+- Each attempt, request and response body, is bounded by `timeoutMs`
+  (10 seconds by default); a CI that stops answering ends in a retryable
+  `unavailable`. `signal` cancels: a cancelled request rejects with the
+  signal's reason.
+- The PUT is the caller's: send exactly `headers` to `url` with `method`. No
+  file bytes pass through CI's API. A slot is single use: the first successful
+  write consumes it; request a new one to retry.
+- The write form of a File field key is `{ upload }` to add the uploaded file,
+  `{ id }` (or a File value read before) to keep a file, an ordered array for a
+  multiple field, or `null` to remove every file. Omit the key to keep its
+  files.
+- `/runtime/effect` exports the Effect schemas `EntityFileValue` (a File value
+  as CI reads return it), `EntityFileWrite` (one file of a write) and
+  `EntityFileFieldWrite` (the write form of a File field key). Their types
+  equal the client SDK types of the same name. They validate CI entity
+  values; a portable resource form has no File field, so
+  `projectResourceSchema` refuses them.
+
+## Runtime origin
+
+The browser origins of an Organization are the `allowedOrigins` that its
+installed applications declare, plus one runtime origin per application. A
+confidential application sets its runtime origin, for example the URL of each
+new deployment; CI keeps storage CORS in line with the Organization origins, so
+a browser on that origin can upload to a presigned storage URL.
+
+```ts
+await ci.origins.setRuntime({
+  organizationId,
+  origin: `https://${process.env.VERCEL_URL}`
+})
+// value.result: { origin }
+```
+
+- Each call replaces the application's previous runtime origin, so the list
+  does not grow; declare stable origins, such as the production site, in
+  `allowedOrigins`.
+- `origin` is an exact HTTPS origin (`https://host[:port]`, no path), or a
+  loopback HTTP origin with a port; other values get `invalid_request`.
+- 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
 
 An application links a member of its Organization to the Knowledge company
@@ -1146,8 +1213,12 @@ const handle = createResourceHttpHandler({
 
 `auth` is the existing `createFederatedAuth(...)` instance. Its server-only
 `getEntityContext` resolves current CI application, user, organization, scopes,
-roles and group IDs; browser session JSON remains identity and expiry only.
-Missing CI policy context denies entity access. Local Better Auth sessions do
+the user's effective app roles and App Permissions. CI never sends Group IDs or
+Platform Permissions. The browser session JSON at `<basePath>/session` carries
+`expiresAt` and an `identity` with `userId`, `organizationId`, `appId`, `kind`
+(`member` or `external_app_user`), `roles`, `appPermissions`, `email` and
+`name`; it never carries the Access token. A user without a role on the app has
+no session and no entity access. Local Better Auth sessions do
 not establish CI entity authority. Browser framework adapters require this
 verified context instead of boolean authorization. Machine gateway calls retain
 their separate caller policy.
@@ -1343,8 +1414,9 @@ A renewal applies the same admission rule as `/oauth/identity`:
 
 - the external Application is enabled;
 - the CI session is live;
-- the user is not banned and is still admitted to the Organization, which
-  today means the Organization membership of the user and its role;
+- the user is not banned, is a member or an active External App User of the
+  Organization, and holds at least one role on the app other than
+  `anonymous` (Direct Role Assignments replace the roles that Groups give);
 - the scopes of the sign-in are still allowed.
 
 A refusal ends nothing. When the condition is corrected, the same Renewal
@@ -1426,7 +1498,7 @@ const caller = await tokens.verify(bearerToken)
 // userId, organizationId, applicationId, clientId, scopes, sessionId, expiresAt
 
 const identity = await tokens.identity(bearerToken, { signal: request.signal })
-// the same fields, and user { id, email, name }, roles, groupIds
+// the same fields, and user { id, email, name }, kind, roles, appPermissions
 ```
 
 - `verify` is offline against the issuer key set: ES256 signature, issuer,
@@ -1434,7 +1506,8 @@ const identity = await tokens.identity(bearerToken, { signal: request.signal })
   It does not see a revocation before the token expires.
 - `identity` runs `verify`, then reads CI's current identity for the token and
   checks that it describes the same grant. Use it when the API needs the
-  user's roles or groups, or must stop at once when CI revokes the token. It
+  user's app roles or App Permissions, or must stop at once when CI revokes
+  the token or a role. It
   is one CI request for each call, with a 10-second limit; cache the result
   for as long as a role change may take to reach your API. Pass the `signal`
   of the request you serve: when it aborts, the CI request ends and the call
@@ -1562,3 +1635,22 @@ values use `soft_delete` and `hard_delete`, and gateway principal kinds use
 `detached_user` and `service_principal`. Public method and capability property
 names such as `softDelete` remain unchanged. External HTTP, OAuth, JSON Schema
 and provider values retain their required spelling at their adapter boundaries.
+
+### CI relation-member reads
+
+CI-backed resources created by `defineCiEntityResource` accept the common client
+`listMembers(parentId, field, query, { signal })` operation. The shared Fetch handler
+mounts `POST /records/:parentId/relation-members/search` below the resource base
+path and forwards `{ field, ...query }` to the bound CI schema route. Existing
+verified tenant, organization, resource and user-grant checks still apply;
+`authorizeWithUserAuth` classifies this operation under `readScope`.
+
+The page envelope and exact totals remain unchanged. Member records are JSON
+objects validated independently of the parent schema, as are member query field
+names; CI resolves and authorizes the actual member schema. Abort signals and
+correlation IDs pass through the proxy. All four typed read-limit metrics
+(`work`, `nodes`, `relation_ids`, `bytes`) retain `invalid_request` details
+`{ reason: "read_limit_exceeded", budget }` and rejected read outcomes. Local
+`defineEntityResource` repositories have no CI relation resolver and return
+`capability_not_supported`; the legacy CRUD facade does not expose this route.
+See the client SDK README for complete IDs, bounded includes and narrowing guidance.