@collective-intelligence/external-apps-server-sdk 0.1.10 → 0.1.12

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
 
@@ -1219,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.
@@ -1416,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
@@ -1499,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,
@@ -1507,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
@@ -1635,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.