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

package/README.md

@@ -5,6 +5,14 @@ The root entrypoint provides federated login, typed CI operations, and direct or
 same-origin proxy transports. It contains no confidential credentials or
 framework state.
 
+The typed transport `execute` method supports `users_create_or_get`, `users_get`,
+`users_list`, `users_deactivate`, `roles_list`, `roles_assign`, and `roles_revoke`
+through the dedicated Application HTTP routes. Supply `organizationId` in the
+execution options. Role assignment inputs use `{ userId, roles }`; an empty
+`roles` array is forwarded unchanged. The backend checks the signed-in user's
+current permissions. Server credentials and Server Role selection belong to the
+Server SDK.
+
 `createFederatedAuth` implements the public OAuth authorization-code flow with
 PKCE. It validates same-origin return targets, keeps the login transaction in
 session storage, exchanges the callback code, tracks token expiry, and supports
@@ -134,7 +142,7 @@ authorizes access. They are configuration, never mutation-body authority.
 including identity, login, logout, and `runs_follow`. `createFixedWorkflowClient`
 posts a Fixed workflow BFF route and returns `{ runId }`.
 
-The common client exposes `list`, `get`, `create`, `update`, `delete`, and
+The common client exposes `list`, `listMembers`, `get`, `create`, `update`, `delete`, and
 `upload` (see [File uploads](#file-uploads)).
 `delete` calls the explicit soft-delete route. Every mutation requires an operation
 key; update/delete also require the revision originally edited. Reads accept an
@@ -153,6 +161,53 @@ During migration, omitting `protocol` retains the distinct legacy resource facad
 including its optional update keys, cursor pagination and explicit lifecycle
 methods. Existing hard-delete behavior is never relabeled as common `delete`.
 
+### Relation members
+
+`resource.listMembers(parentId, field, query, { signal })` reads a forward or
+inverse relation as an ordinary entity page. `query` uses `EntityListQuery`
+filters, sorting, page pagination and includes on the resolved **member** schema.
+For example:
+
+```ts
+const members = await leads.listMembers("lead-1", "companies", {
+  filter: { field: "industry", operator: "eq", value: "Research" },
+  sort: [{ field: "industry", direction: "asc" }],
+  pagination: { mode: "page", page: 1, pageSize: 25 }
+})
+```
+
+CI transport sends `POST /application/v1/resources/:schemaFqn/records/:parentId/relation-members/search`
+with `{ field, ...query }`. The existing page envelope and exact totals describe
+the authorized filtered membership, including zero/one-member scalar relations.
+Without explicit sorting, forward members use stored position and inverse members
+use source ID order. CI authorizes the parent and members and validates the field.
+A forward field needs no inverse declaration.
+
+Member values are `EntityMemberValue` JSON objects, not the parent's generic type;
+the codec validates the entire page and JSON without applying the parent's entity
+schema or query field allowlist. Narrow member values using the member's own
+schema before treating them as a specific application type.
+
+Successful pages and root relation-ID values are complete. Included objects
+return complete relation values only for requested next-hop fields; leaf objects
+omit relation fields entirely rather than returning fabricated empty arrays or
+nulls. Ordinary data and File values remain projected. Includes keep the existing
+three-level depth and 100-readable-object per-field cap with explicit `truncated`
+markers; nested include pagination is unavailable. Overall exhaustion fails with
+`invalid_request` and details `{ reason: "read_limit_exceeded", budget }`, where
+`budget` is `work`, `nodes`, `relation_ids` or `bytes`. The `/resources` export
+`isEntityReadLimitError(error)` narrows to `EntityReadLimitDetails`. Narrow the
+query or includes before retrying; these failures expose no member IDs or counts.
+Current request-wide ceilings are 100,000 work units, 2,000 nested object
+occurrences, 50,000 relation-ID occurrences and 8,388,608 accounted bytes.
+Repeated serialized occurrences count even when target reads are deduplicated.
+These are workload ceilings, not a latency or process-memory guarantee. See the
+[limits and measured envelope](../../../docs/reference/knowledge-relation-fields.md#read-limits-and-measured-envelope)
+for scope, recovery and benchmark evidence.
+
+Cancellation and malformed responses retain read-only dispatch outcomes and
+correlation IDs.
+
 ## File uploads
 
 A File field holds files of a CI entity. The browser sends the file bytes
@@ -205,8 +260,8 @@ deletes an unused one after a retention window. Request a new one to retry.
 not presign, with `invalid_request` (`details.reason` `not_a_file_field` or
 `type_not_accepted`) for a field or MIME type the schema refuses, and with
 `not_found` for an unknown schema. A write that refuses its write form answers
-`invalid_request` with `details.field` and `details.reason`; a File field of a
-connector-owned entity answers `conflict`.
+`invalid_request` with `details.field` and `details.reason`; a File field a
+connector writes answers `conflict` with `details.field`.
 
 ## Workspace development
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { $ as ResourceUpdateRequest, A as ResourceError, At as FederatedAuthOptions, B as ResourceListRequest, C as PortableResourceSchema, Ct as QueryFilter, D as ResourceCreateRequest, Dt as FederatedAuth, E as ResourceCreateInput, Et as ClientFetch, F as ResourceIdentityField, G as ResourceRecord, H as ResourceMutationInput, I as ResourceJsonValue, J as ResourceResult, K as ResourceRecordId, L as ResourceLifecycleInput, M as ResourceFilter, Mt as FederatedSessionIdentity, N as ResourceGetRequest, Nt as createFederatedAuth, O as ResourceCursor, Ot as FederatedAuthError, P as ResourceId, Q as ResourceTransportRequest, R as ResourceLifecycleRequest, S as IdempotencyKey, St as KnowledgeQuery, T as ResourceClient, Tt as WorkflowInvokeTarget, U as ResourcePagination, V as ResourceListResult, W as ResourcePaginationMode, X as ResourceSort, Y as ResourceRevision, Z as ResourceTransport, _ as EntityRequest, _t as isClientOperationId, a as createResourceClient, at as CiResult, b as EntityUploadInput, bt as ConversationHistory, c as EntityDeleteInput, ct as OperationSuccess, d as EntityFileWrite, dt as ClientOperationInput, et as ProxyAuthentication, f as EntityListQuery, ft as ClientOperationMap, g as EntityProtocol, gt as clientOperationIds, h as EntityPage, ht as TypedOperationExecutor, i as createEntityProtocol, it as CiErrorCode, j as ResourceErrorCode, jt as FederatedAuthState, k as ResourceDefinition, kt as FederatedAuthErrorCode, l as EntityFileFieldWrite, lt as ClientOperationDefinition, m as EntityOperationResult, mt as OperationExecutionOptions, n as EntityHttpTransportOptions, nt as createProxyTransport, o as EntityClient, ot as JsonValue, p as EntityOperation, pt as ClientOperationOutput, q as ResourceRequestOptions, r as createEntityHttpTransport, rt as CiError, s as EntityCreateInput, st as OperationRequest, t as EntityHttpDestination, tt as ProxyTransportOptions, u as EntityFileValue, ut as ClientOperationId, v as EntityTransport, vt as AgentInvokeTarget, w as ResourceCapabilities, wt as SearchQuery, x as EntityUploadSlot, xt as JsonObject, y as EntityUpdateInput, yt as ConversationContinueTarget, z as ResourceListQuery } from "./resources-DxMBAy-Z.js";
+import { $ as ResourceSort, A as ResourceCreateRequest, At as ClientFetch, B as ResourceLifecycleInput, C as EntityUploadInput, Ct as ConversationContinueTarget, D as ResourceCapabilities, Dt as QueryFilter, E as PortableResourceSchema, Et as KnowledgeQuery, F as ResourceFilter, Ft as FederatedAuthState, G as ResourceMutationInput, H as ResourceListQuery, I as ResourceGetRequest, It as FederatedSessionIdentity, J as ResourceRecord, K as ResourcePagination, L as ResourceId, Lt as createFederatedAuth, M as ResourceDefinition, Mt as FederatedAuthError, N as ResourceError, Nt as FederatedAuthErrorCode, O as ResourceClient, Ot as SearchQuery, P as ResourceErrorCode, Pt as FederatedAuthOptions, Q as ResourceRevision, R as ResourceIdentityField, S as EntityUpdateInput, St as ApplicationRole, T as IdempotencyKey, Tt as JsonObject, U as ResourceListRequest, V as ResourceLifecycleRequest, W as ResourceListResult, X as ResourceRequestOptions, Y as ResourceRecordId, Z as ResourceResult, _ as EntityPage, _t as OperationExecutionOptions, a as isEntityReadLimitError, at as createProxyTransport, b as EntityRequest, bt as isClientOperationId, c as EntityCreateInput, ct as CiResult, d as EntityFileValue, dt as OperationSuccess, et as ResourceTransport, f as EntityFileWrite, ft as ClientOperationDefinition, g as EntityOperationResult, gt as ClientOperationOutput, h as EntityOperation, ht as ClientOperationMap, i as createEntityProtocol, it as ProxyTransportOptions, j as ResourceCursor, jt as FederatedAuth, k as ResourceCreateInput, kt as WorkflowInvokeTarget, l as EntityDeleteInput, lt as JsonValue, m as EntityMemberValue, mt as ClientOperationInput, n as EntityHttpTransportOptions, nt as ResourceUpdateRequest, o as createResourceClient, ot as CiError, p as EntityListQuery, pt as ClientOperationId, q as ResourcePaginationMode, r as createEntityHttpTransport, rt as ProxyAuthentication, s as EntityClient, st as CiErrorCode, t as EntityHttpDestination, tt as ResourceTransportRequest, u as EntityFileFieldWrite, ut as OperationRequest, v as EntityProtocol, vt as TypedOperationExecutor, w as EntityUploadSlot, wt as ConversationHistory, x as EntityTransport, xt as AgentInvokeTarget, y as EntityReadLimitDetails, yt as clientOperationIds, z as ResourceJsonValue } from "./resources-BDcYZzER.js";
 type ServerSessionAuthOptions = Readonly<{
   basePath: string;
   fetch?: ClientFetch;
@@ -158,6 +158,54 @@ declare const createDelegatedApplicationRuntime: (options: DelegatedApplicationR
     subscribe: (listener: (state: FederatedAuthState) => void) => () => void;
   }>;
   client: ClientSdkClient<Readonly<{
+    users_get: ClientOperationDefinition<{
+      userId: string;
+    }, {
+      email: string | null;
+      name: string | null;
+      userId: string;
+    }>;
+    users_list: ClientOperationDefinition<{
+      page?: number;
+      pageSize?: number;
+    }, {
+      items: Array<{
+        email: string | null;
+        name: string | null;
+        userId: string;
+      }>;
+    }>;
+    users_deactivate: ClientOperationDefinition<{
+      userId: string;
+    }, {
+      userId: string;
+    }>;
+    roles_list: ClientOperationDefinition<Record<string, never>, {
+      items: ApplicationRole[];
+    }>;
+    roles_assign: ClientOperationDefinition<{
+      userId: string;
+      roles: string[];
+    }, {
+      userId: string;
+    }>;
+    roles_revoke: ClientOperationDefinition<{
+      userId: string;
+      roles: string[];
+    }, {
+      userId: string;
+    }>;
+    users_create_or_get: ClientOperationDefinition<{
+      email: string;
+      name: string;
+      roles: Array<string>;
+    }, {
+      email: string | null;
+      name: string | null;
+      userId: string;
+      created: boolean;
+      kind: "member" | "external_app_user";
+    }>;
     context_get: ClientOperationDefinition<Readonly<Record<string, string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | /*elided*/ any | Readonly<{
       readonly [key: string]: string | number | boolean | /*elided*/ any | Readonly< /*elided*/ any> | null;
     }> | null)[] | Readonly<{
@@ -889,4 +937,4 @@ type DirectTransportOptions = Readonly<{
   tenantUrl: string;
 }>;
 declare const createDirectTransport: <Operations extends ClientOperationMap>(options: DirectTransportOptions) => TypedOperationExecutor<Operations>;
-export { type CiError, type CiErrorCode, type CiResult, type CiRunCancellation, type CiStreamEvent, type CiStreamPage, type ClientDomains, type ClientFetch, type ClientOperationDefinition, type ClientOperationId, type ClientOperationInput, type ClientOperationMap, type ClientOperationOutput, type ClientSdkClient, type ClientSdkEntrypoint, DEFAULT_FOLLOW_RUN_DEADLINE_MS, type DelegatedApplicationRuntime, type DelegatedApplicationRuntimeOptions, type DelegatedRuntimeState, type DirectTransportOptions, type EntityClient, type EntityCreateInput, type EntityDeleteInput, type EntityFileFieldWrite, type EntityFileValue, type EntityFileWrite, type EntityHttpDestination, type EntityHttpTransportOptions, type EntityListQuery, type EntityOperation, type EntityOperationResult, type EntityPage, type EntityProtocol, type EntityRequest, type EntityTransport, type EntityUpdateInput, type EntityUploadInput, type EntityUploadSlot, type FederatedAuth, FederatedAuthError, type FederatedAuthErrorCode, type FederatedAuthOptions, type FederatedAuthState, type FederatedSessionIdentity, type FixedWorkflowClient, type FixedWorkflowClientOptions, type FollowRunOptions, type FollowRunSource, type IdempotencyKey, type JsonObject, type JsonValue, type KnowledgeQuery, type OperationExecutionOptions, type OperationRequest, type OperationSuccess, type OrganizationClient, type PortableResourceSchema, type ProxyAuthentication, type ProxyTransportOptions, type QueryFilter, type ResourceCapabilities, type ResourceClient, type ResourceCreateInput, type ResourceCreateRequest, type ResourceCursor, type ResourceDefinition, type ResourceError, type ResourceErrorCode, type ResourceFilter, type ResourceGetRequest, type ResourceId, type ResourceIdentityField, type ResourceJsonValue, type ResourceLifecycleInput, type ResourceLifecycleRequest, type ResourceListQuery, type ResourceListRequest, type ResourceListResult, type ResourceMutationInput, type ResourcePagination, type ResourcePaginationMode, type ResourceRecord, type ResourceRecordId, type ResourceRequestOptions, type ResourceResult, type ResourceRevision, type ResourceSort, type ResourceTransport, type ResourceTransportRequest, type ResourceUpdateRequest, type SearchQuery, type ServerSessionAuthOptions, type TypedOperationExecutor, type WorkflowInvokeTarget, clientOperationIds, clientSdkProtocolVersion, createClient, createDelegatedApplicationRuntime, createDirectTransport, createEntityHttpTransport, createEntityProtocol, createFederatedAuth, createFixedWorkflowClient, createProxyTransport, createResourceClient, createServerSessionAuth, followRun, isClientOperationId, nextStreamCursor };
+export { type CiError, type CiErrorCode, type CiResult, type CiRunCancellation, type CiStreamEvent, type CiStreamPage, type ClientDomains, type ClientFetch, type ClientOperationDefinition, type ClientOperationId, type ClientOperationInput, type ClientOperationMap, type ClientOperationOutput, type ClientSdkClient, type ClientSdkEntrypoint, DEFAULT_FOLLOW_RUN_DEADLINE_MS, type DelegatedApplicationRuntime, type DelegatedApplicationRuntimeOptions, type DelegatedRuntimeState, type DirectTransportOptions, type EntityClient, type EntityCreateInput, type EntityDeleteInput, type EntityFileFieldWrite, type EntityFileValue, type EntityFileWrite, type EntityHttpDestination, type EntityHttpTransportOptions, type EntityListQuery, type EntityMemberValue, type EntityOperation, type EntityOperationResult, type EntityPage, type EntityProtocol, type EntityReadLimitDetails, type EntityRequest, type EntityTransport, type EntityUpdateInput, type EntityUploadInput, type EntityUploadSlot, type FederatedAuth, FederatedAuthError, type FederatedAuthErrorCode, type FederatedAuthOptions, type FederatedAuthState, type FederatedSessionIdentity, type FixedWorkflowClient, type FixedWorkflowClientOptions, type FollowRunOptions, type FollowRunSource, type IdempotencyKey, type JsonObject, type JsonValue, type KnowledgeQuery, type OperationExecutionOptions, type OperationRequest, type OperationSuccess, type OrganizationClient, type PortableResourceSchema, type ProxyAuthentication, type ProxyTransportOptions, type QueryFilter, type ResourceCapabilities, type ResourceClient, type ResourceCreateInput, type ResourceCreateRequest, type ResourceCursor, type ResourceDefinition, type ResourceError, type ResourceErrorCode, type ResourceFilter, type ResourceGetRequest, type ResourceId, type ResourceIdentityField, type ResourceJsonValue, type ResourceLifecycleInput, type ResourceLifecycleRequest, type ResourceListQuery, type ResourceListRequest, type ResourceListResult, type ResourceMutationInput, type ResourcePagination, type ResourcePaginationMode, type ResourceRecord, type ResourceRecordId, type ResourceRequestOptions, type ResourceResult, type ResourceRevision, type ResourceSort, type ResourceTransport, type ResourceTransportRequest, type ResourceUpdateRequest, type SearchQuery, type ServerSessionAuthOptions, type TypedOperationExecutor, type WorkflowInvokeTarget, clientOperationIds, clientSdkProtocolVersion, createClient, createDelegatedApplicationRuntime, createDirectTransport, createEntityHttpTransport, createEntityProtocol, createFederatedAuth, createFixedWorkflowClient, createProxyTransport, createResourceClient, createServerSessionAuth, followRun, isClientOperationId, isEntityReadLimitError, nextStreamCursor };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as parseMountPath, c as isClientOperationId, i as createHttpOperationTransport, n as createResourceClient, o as parseOriginUrl, r as createEntityProtocol, s as clientOperationIds, t as createEntityHttpTransport } from "./resources-BP_TaCP6.js";
+import { a as createHttpOperationTransport, c as clientOperationIds, i as isEntityReadLimitError, l as isClientOperationId, n as createResourceClient, o as parseMountPath, r as createEntityProtocol, s as parseOriginUrl, t as createEntityHttpTransport } from "./resources--kU5LiFu.js";
 const base64Url = (bytes) => {
 	let binary = "";
 	for (const byte of bytes) binary += String.fromCodePoint(byte);
@@ -250,18 +250,35 @@ const readString$1 = (record, key) => {
 	const candidate = record[key];
 	return typeof candidate === "string" ? candidate : null;
 };
+const readStrings = (record, key) => {
+	const candidate = record[key];
+	if (!Array.isArray(candidate)) return null;
+	const items = candidate;
+	return items.every((item) => typeof item === "string") ? items : null;
+};
+const readKind = (record) => {
+	const { kind } = record;
+	return kind === "member" || kind === "external_app_user" ? kind : null;
+};
 const parseIdentity = (value) => {
-	const payload = asRecord$2(value);
-	if (payload === null) return null;
-	const nested = asRecord$2(payload.identity) ?? payload;
-	const id = readString$1(nested, "id");
-	const organizationId = readString$1(nested, "organizationId") ?? readString$1(payload, "organizationId");
-	if (id === null || organizationId === null) return null;
+	const identity = asRecord$2(asRecord$2(value)?.identity);
+	if (identity === null) return null;
+	const appId = readString$1(identity, "appId");
+	const appPermissions = readStrings(identity, "appPermissions");
+	const kind = readKind(identity);
+	const organizationId = readString$1(identity, "organizationId");
+	const roles = readStrings(identity, "roles");
+	const userId = readString$1(identity, "userId");
+	if (appId === null || appPermissions === null || kind === null || organizationId === null || roles === null || userId === null) return null;
 	return {
-		email: readString$1(nested, "email"),
-		id,
-		name: readString$1(nested, "name"),
-		organizationId
+		appId,
+		appPermissions,
+		email: readString$1(identity, "email"),
+		kind,
+		name: readString$1(identity, "name"),
+		organizationId,
+		roles,
+		userId
 	};
 };
 /** Browser session client for a sealed-cookie BFF. The access token never leaves the server. */
@@ -722,4 +739,4 @@ const createDirectTransport = (options) => {
 		origin: tenantUrl
 	});
 };
-export { DEFAULT_FOLLOW_RUN_DEADLINE_MS, FederatedAuthError, clientOperationIds, clientSdkProtocolVersion, createClient, createDelegatedApplicationRuntime, createDirectTransport, createEntityHttpTransport, createEntityProtocol, createFederatedAuth, createFixedWorkflowClient, createProxyTransport, createResourceClient, createServerSessionAuth, followRun, isClientOperationId, nextStreamCursor };
+export { DEFAULT_FOLLOW_RUN_DEADLINE_MS, FederatedAuthError, clientOperationIds, clientSdkProtocolVersion, createClient, createDelegatedApplicationRuntime, createDirectTransport, createEntityHttpTransport, createEntityProtocol, createFederatedAuth, createFixedWorkflowClient, createProxyTransport, createResourceClient, createServerSessionAuth, followRun, isClientOperationId, isEntityReadLimitError, nextStreamCursor };

package/dist/{resources-BP_TaCP6.js → resources--kU5LiFu.js}

@@ -22,6 +22,13 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 const completeOperationRegistry = (ids) => ids;
 /** Generated, curated external-application operation authority. */
 const clientOperationIds = completeOperationRegistry([
+	"users_get",
+	"users_list",
+	"users_deactivate",
+	"roles_list",
+	"roles_assign",
+	"roles_revoke",
+	"users_create_or_get",
 	"context_get",
 	"knowledge_query",
 	"knowledge_get_entity_schema_snapshot",
@@ -234,6 +241,47 @@ const dedicatedHttpCall = (operationId, input) => {
 	if (removedEntityOperation.has(operationId)) return null;
 	const record = isRecord$1(input) ? input : {};
 	switch (operationId) {
+		case "users_create_or_get": return {
+			body: input,
+			method: "POST",
+			parse: "json",
+			pathname: "/users"
+		};
+		case "users_list": {
+			const query = {};
+			if (typeof record.page === "number") query.page = String(record.page);
+			if (typeof record.pageSize === "number") query.pageSize = String(record.pageSize);
+			return {
+				method: "GET",
+				parse: "json",
+				pathname: "/users",
+				query
+			};
+		}
+		case "roles_list": return {
+			method: "GET",
+			parse: "json",
+			pathname: "/roles"
+		};
+		case "users_get":
+		case "users_deactivate":
+		case "roles_assign":
+		case "roles_revoke": {
+			const userId = textField(record, "userId");
+			if (userId === void 0) return null;
+			const pathname = `/users/${encodeURIComponent(userId)}`;
+			if (operationId === "users_get" || operationId === "users_deactivate") return {
+				method: operationId === "users_get" ? "GET" : "DELETE",
+				parse: "json",
+				pathname
+			};
+			return {
+				body: { roles: record.roles },
+				method: operationId === "roles_assign" ? "POST" : "DELETE",
+				parse: "json",
+				pathname: `${pathname}/roles`
+			};
+		}
 		case "context_get": return {
 			method: "GET",
 			parse: "json",
@@ -7575,6 +7623,36 @@ const objectSchema = (properties, required = Object.keys(properties)) => ({
 	required,
 	type: "object"
 });
+/**
+* Include Paths: relation fields whose records a read returns in
+* `included`, such as `["company", "contacts.company"]`, at most three
+* levels deep. CI refuses a segment that names no relation field.
+*/
+const includeSchema = {
+	items: {
+		minLength: 1,
+		pattern: "^[^.]+(\\.[^.]+){0,2}$",
+		type: "string"
+	},
+	type: "array"
+};
+const escapePattern = (value) => value.replaceAll(/[$()*+.?[\\\]^{|}]/gu, "\\$&");
+/**
+* The Entity References a declared property holds: `one` uuid string, or
+* `many` as an array of uuid strings.
+*/
+const references = (property) => {
+	if (property === null || typeof property !== "object" || Array.isArray(property)) return;
+	if ("format" in property && property.format === "uuid") return "one";
+	const items = "items" in property ? property.items : void 0;
+	return items !== null && typeof items === "object" && !Array.isArray(items) && "format" in items && items.format === "uuid" ? "many" : void 0;
+};
+/**
+* A path through a field that holds Entity References, such as
+* `company.industry`: at most three relation fields and a field of the
+* last target, as CI resolves it.
+*/
+const relationPath = (field) => ({ pattern: `^${escapePattern(field)}(\\.[^.]+){1,3}$` });
 const pointerKey = (key) => key.replaceAll("~", "~0").replaceAll("/", "~1");
 const schemaMaps = /* @__PURE__ */ new Set([
 	"$defs",
@@ -7651,42 +7729,95 @@ const entityQuerySchema = (definition) => {
 		...definition.query.sortableFields,
 		...definition.query.textSearchFields ?? []
 	]) if (!Object.hasOwn(properties, field)) throw new TypeError(`Query field '${field}' has no declared entity property`);
-	const filter = { oneOf: [
-		...definition.query.filterableFields.flatMap((field) => {
-			const value = { $ref: `#/$defs/filterEntity/properties/${pointerKey(field)}` };
-			const nullable = { anyOf: [value, { type: "null" }] };
-			const predicate = (operators, valueSchema) => {
-				const predicateProperties = {
-					field: { const: field },
-					operator: { enum: operators }
-				};
-				if (valueSchema === void 0) return objectSchema(predicateProperties);
-				return objectSchema({
-					...predicateProperties,
-					value: valueSchema
-				});
+	const leaves = definition.query.filterableFields.flatMap((field) => {
+		const cardinality = references(properties[field]);
+		const value = { $ref: `#/$defs/filterEntity/properties/${pointerKey(field)}` };
+		const nullable = { anyOf: [cardinality === "many" ? {
+			format: "uuid",
+			type: "string"
+		} : value, { type: "null" }] };
+		const predicate = (operators, valueSchema) => {
+			const predicateProperties = {
+				field: { const: field },
+				operator: { enum: operators }
 			};
-			return [
-				predicate(["is_null", "is_not_null"]),
-				predicate(["eq", "ne"], nullable),
-				predicate([
-					"gt",
-					"gte",
-					"lt",
-					"lte"
-				], { allOf: [value, { type: ["number", "string"] }] }),
-				predicate([
-					"contains",
-					"starts_with",
-					"ends_with"
-				], { allOf: [value, { type: "string" }] }),
-				predicate(["in", "not_in"], {
-					items: nullable,
-					minItems: 1,
-					type: "array"
-				})
-			];
+			if (valueSchema === void 0) return objectSchema(predicateProperties);
+			return objectSchema({
+				...predicateProperties,
+				value: valueSchema
+			});
+		};
+		return [
+			predicate(cardinality === void 0 ? ["is_null", "is_not_null"] : [
+				"is_null",
+				"is_not_null",
+				"is_empty"
+			]),
+			...cardinality === "many" ? [predicate(["contains_any", "contains_all"], {
+				items: { $ref: `${value.$ref}/items` },
+				minItems: 1,
+				type: "array"
+			})] : [],
+			predicate(["eq", "ne"], nullable),
+			predicate([
+				"gt",
+				"gte",
+				"lt",
+				"lte"
+			], { allOf: [value, { type: ["number", "string"] }] }),
+			predicate([
+				"contains",
+				"starts_with",
+				"ends_with"
+			], { allOf: [value, { type: "string" }] }),
+			predicate(["in", "not_in"], {
+				items: nullable,
+				minItems: 1,
+				type: "array"
+			})
+		];
+	});
+	const relationPaths = definition.query.filterableFields.flatMap((field) => references(properties[field]) === void 0 ? [] : [
+		objectSchema({
+			field: relationPath(field),
+			operator: { enum: [
+				"contains",
+				"ends_with",
+				"eq",
+				"gt",
+				"gte",
+				"ne",
+				"lt",
+				"lte",
+				"starts_with"
+			] },
+			value: true
+		}),
+		objectSchema({
+			field: relationPath(field),
+			operator: { enum: [
+				"in",
+				"not_in",
+				"contains_any",
+				"contains_all"
+			] },
+			value: {
+				minItems: 1,
+				type: "array"
+			}
 		}),
+		objectSchema({
+			field: relationPath(field),
+			operator: { enum: [
+				"is_null",
+				"is_not_null",
+				"is_empty"
+			] }
+		})
+	]);
+	const filter = { oneOf: [
+		...leaves,
+		...relationPaths,
 		objectSchema({
 			filters: {
 				items: { $ref: "#/$defs/filter" },
@@ -7714,6 +7845,7 @@ const entityQuerySchema = (definition) => {
 	});
 	const query = objectSchema({
 		filter: { $ref: "#/$defs/filter" },
+		include: includeSchema,
 		pagination: page,
 		sort: {
 			items: objectSchema({
@@ -7730,6 +7862,94 @@ const entityQuerySchema = (definition) => {
 		query
 	};
 };
+/** Member query structure is portable; CI validates fields against the resolved member schema. */
+const memberQuerySchema = {
+	filter: { oneOf: [
+		objectSchema({
+			field: identifier,
+			operator: { enum: ["eq", "ne"] },
+			value: true
+		}),
+		objectSchema({
+			field: identifier,
+			operator: { enum: [
+				"gt",
+				"gte",
+				"lt",
+				"lte"
+			] },
+			value: { type: ["number", "string"] }
+		}),
+		objectSchema({
+			field: identifier,
+			operator: { enum: [
+				"contains",
+				"starts_with",
+				"ends_with"
+			] },
+			value: { type: "string" }
+		}),
+		objectSchema({
+			field: identifier,
+			operator: { enum: [
+				"in",
+				"not_in",
+				"contains_any",
+				"contains_all"
+			] },
+			value: {
+				minItems: 1,
+				type: "array"
+			}
+		}),
+		objectSchema({
+			field: identifier,
+			operator: { enum: [
+				"is_null",
+				"is_not_null",
+				"is_empty"
+			] }
+		}),
+		objectSchema({
+			filters: {
+				items: { $ref: "#/$defs/memberFilter" },
+				minItems: 1,
+				type: "array"
+			},
+			operator: { enum: ["and", "or"] }
+		}),
+		objectSchema({
+			filter: { $ref: "#/$defs/memberFilter" },
+			operator: { const: "not" }
+		})
+	] },
+	query: objectSchema({
+		filter: { $ref: "#/$defs/memberFilter" },
+		include: includeSchema,
+		pagination: objectSchema({
+			mode: { const: "page" },
+			page: {
+				minimum: 1,
+				type: "integer"
+			},
+			pageSize: {
+				maximum: 100,
+				minimum: 1,
+				type: "integer"
+			}
+		}),
+		sort: {
+			items: objectSchema({
+				direction: { enum: ["asc", "desc"] },
+				field: identifier
+			}),
+			type: "array"
+		},
+		textSearch: { type: "string" }
+	}, ["pagination"])
+};
+/** Narrow a decoded resource failure to its documented request-wide read limit. */
+const isEntityReadLimitError = (error) => error.code === "invalid_request" && error.details?.reason === "read_limit_exceeded" && (error.details.budget === "work" || error.details.budget === "nodes" || error.details.budget === "relation_ids" || error.details.budget === "bytes");
 const operationKey = {
 	pattern: "^[\\w.-]{1,256}$",
 	type: "string"
@@ -7739,10 +7959,11 @@ const uploadText = {
 	minLength: 1,
 	type: "string"
 };
-const requestSchema = (definition, operation, properties) => ({
+const requestSchema = (definition, operation, properties, optional = {}) => ({
 	additionalProperties: false,
 	properties: {
 		...properties,
+		...optional,
 		operation: { const: operation },
 		requestId: identifier,
 		resourceId: { const: definition.id }
@@ -7762,6 +7983,12 @@ const correlation = (input, key, fallback) => {
 	else if (key === "correlationId" && "correlationId" in input) value = input.correlationId;
 	return typeof value === "string" && value.length > 0 ? value : fallback;
 };
+const coherentPage = (validatePageEnvelope) => (input) => {
+	if (!validatePageEnvelope(input)) return false;
+	if (!input.ok) return true;
+	const { value } = input;
+	return value.totalPages === Math.ceil(value.totalItems / value.pageSize) && value.items.length <= value.pageSize && value.items.length <= value.totalItems && (value.page <= value.totalPages || value.items.length === 0);
+};
 /** Common entity wire codec; transport and persistence remain with their owners. */
 const createEntityProtocol = (definition) => {
 	const { filter, filterValues, query } = entityQuerySchema(definition);
@@ -7775,11 +8002,17 @@ const createEntityProtocol = (definition) => {
 			create: scopeSchema(definition.schemas.create ?? false, "#/$defs/create"),
 			filter,
 			filterEntity: scopeSchema(filterValues, "#/$defs/filterEntity"),
+			memberFilter: memberQuerySchema.filter,
 			update: scopeSchema(definition.schemas.update ?? false, "#/$defs/update")
 		},
 		oneOf: [
 			requestSchema(definition, "list", { query }),
-			requestSchema(definition, "get", { id: identifier }),
+			requestSchema(definition, "list_members", {
+				field: identifier,
+				parentId: identifier,
+				query: memberQuerySchema.query
+			}),
+			requestSchema(definition, "get", { id: identifier }, { include: includeSchema }),
 			requestSchema(definition, "create", {
 				idempotencyKey: operationKey,
 				value: { $ref: "#/$defs/create" }
@@ -7811,40 +8044,68 @@ const createEntityProtocol = (definition) => {
 			type: "string"
 		},
 		id: identifier,
+		included: { type: "object" },
 		revision: identifier,
+		truncated: {
+			items: { type: "string" },
+			type: "array"
+		},
 		value: { $ref: "#/$defs/entity" }
 	}, [
 		"id",
 		"revision",
 		"value"
 	]);
-	const error = objectSchema({
-		code: { enum: [
-			"capability_not_supported",
-			"conflict",
-			"forbidden",
-			"internal",
-			"invalid_request",
-			"not_found",
-			"rate_limited",
-			"transport_error",
-			"unauthenticated",
-			"unavailable",
-			"upload_not_supported"
-		] },
-		details: { type: "object" },
-		message: { type: "string" },
-		outcome: { enum: [
-			"not_dispatched",
-			"rejected",
-			"uncertain"
-		] },
-		retryable: { type: "boolean" }
-	}, [
-		"code",
-		"message",
-		"retryable"
-	]);
+	const error = {
+		...objectSchema({
+			code: { enum: [
+				"capability_not_supported",
+				"conflict",
+				"forbidden",
+				"internal",
+				"invalid_request",
+				"not_found",
+				"rate_limited",
+				"transport_error",
+				"unauthenticated",
+				"unavailable",
+				"upload_not_supported"
+			] },
+			details: { type: "object" },
+			message: { type: "string" },
+			outcome: { enum: [
+				"not_dispatched",
+				"rejected",
+				"uncertain"
+			] },
+			retryable: { type: "boolean" }
+		}, [
+			"code",
+			"message",
+			"retryable"
+		]),
+		allOf: [{
+			if: {
+				properties: { details: {
+					properties: { reason: { const: "read_limit_exceeded" } },
+					required: ["reason"]
+				} },
+				required: ["details"]
+			},
+			then: { properties: {
+				code: { const: "invalid_request" },
+				details: objectSchema({
+					budget: { enum: [
+						"work",
+						"nodes",
+						"relation_ids",
+						"bytes"
+					] },
+					reason: { const: "read_limit_exceeded" }
+				})
+			} }
+		}]
+	};
 	const liveRecord = {
 		...record,
 		properties: {
@@ -7903,17 +8164,28 @@ const createEntityProtocol = (definition) => {
 		uploadId: identifier,
 		url: identifier
 	})));
-	const coherentPage = (input) => {
-		if (!validatePage(input)) return false;
-		if (!input.ok) return true;
-		const { value } = input;
-		return value.totalPages === Math.ceil(value.totalItems / value.pageSize) && value.items.length <= value.pageSize && value.items.length <= value.totalItems && (value.page <= value.totalPages || value.items.length === 0);
-	};
+	const validateMemberPage = ajv.compile(resultSchema({
+		...page,
+		properties: {
+			...page.properties,
+			items: {
+				items: {
+					...liveRecord,
+					properties: {
+						...liveRecord.properties,
+						value: { type: "object" }
+					}
+				},
+				type: "array"
+			}
+		}
+	}));
 	const validateOperationResult = {
 		create: validateRecord,
 		delete: validateDeleted,
 		get: validateRecord,
-		list: coherentPage,
+		list: coherentPage(validatePage),
+		list_members: coherentPage(validateMemberPage),
 		update: validateRecord,
 		upload: validateUploadSlot
 	};
@@ -7988,6 +8260,7 @@ const createCommonEntityClient = (options) => {
 			delete: "delete",
 			get: "get",
 			list: "search",
+			list_members: "search",
 			update: "update",
 			upload: "upload"
 		}[input.operation]] !== true) return {
@@ -8007,7 +8280,7 @@ const createCommonEntityClient = (options) => {
 				...decoded,
 				error: {
 					...decoded.error,
-					outcome: input.operation === "list" || input.operation === "get" ? "rejected" : "uncertain"
+					outcome: input.operation === "list" || input.operation === "list_members" || input.operation === "get" ? "rejected" : "uncertain"
 				}
 			} : decoded;
 		} catch {
@@ -8016,7 +8289,7 @@ const createCommonEntityClient = (options) => {
 				error: {
 					code: "transport_error",
 					message: "The entity transport failed",
-					outcome: input.operation === "list" || input.operation === "get" ? "rejected" : "uncertain",
+					outcome: input.operation === "list" || input.operation === "list_members" || input.operation === "get" ? "rejected" : "uncertain",
 					retryable: false
 				},
 				ok: false
@@ -8041,6 +8314,12 @@ const createCommonEntityClient = (options) => {
 			operation: "list",
 			query
 		}, requestOptions),
+		listMembers: (parentId, field, query, requestOptions) => execute({
+			field,
+			operation: "list_members",
+			parentId,
+			query
+		}, requestOptions),
 		update: (input) => execute({
 			...input,
 			operation: "update"
@@ -8144,10 +8423,21 @@ const encode = (request) => {
 			method: "POST",
 			path: "/search"
 		};
-		case "get": return {
-			method: "GET",
-			path: `/records/${encodeURIComponent(request.id)}`
+		case "list_members": return {
+			body: JSON.stringify({
+				...request.query,
+				field: request.field
+			}),
+			method: "POST",
+			path: `/records/${encodeURIComponent(request.parentId)}/relation-members/search`
 		};
+		case "get": {
+			const query = request.include?.length ? `?include=${encodeURIComponent(request.include.join(","))}` : "";
+			return {
+				method: "GET",
+				path: `/records/${encodeURIComponent(request.id)}${query}`
+			};
+		}
 		case "create": return {
 			body: JSON.stringify({
 				idempotencyKey: request.idempotencyKey,
@@ -8245,10 +8535,10 @@ const createEntityHttpTransport = (options) => {
 			return failure({
 				code: "transport_error",
 				message: "The entity response could not be received",
-				outcome: request.operation === "get" || request.operation === "list" ? "rejected" : "uncertain",
+				outcome: request.operation === "get" || request.operation === "list" || request.operation === "list_members" ? "rejected" : "uncertain",
 				retryable: false
 			});
 		}
 	} };
 };
-export { parseMountPath as a, isClientOperationId as c, createHttpOperationTransport as i, createResourceClient as n, parseOriginUrl as o, createEntityProtocol as r, clientOperationIds as s, createEntityHttpTransport as t };
+export { createHttpOperationTransport as a, clientOperationIds as c, isEntityReadLimitError as i, isClientOperationId as l, createResourceClient as n, parseMountPath as o, createEntityProtocol as r, parseOriginUrl as s, createEntityHttpTransport as t };

package/dist/{resources-DxMBAy-Z.d.ts → resources-BDcYZzER.d.ts}

@@ -3,11 +3,22 @@ declare class FederatedAuthError extends Error {
   readonly code: FederatedAuthErrorCode;
   constructor(code: FederatedAuthErrorCode, message: string);
 }
+/**
+ * The signed-in CI user as the application's BFF reports it: the fields of
+ * CI's `/oauth/identity`, read live by the server, plus email and name.
+ */
 type FederatedSessionIdentity = Readonly<{
+  appId: string;
+  /** The App Permissions of the user's effective roles. */
+  appPermissions: readonly string[];
   email: string | null;
-  id: string;
+  /** A person is a member or an External App User of one Organization, never both. */
+  kind: "member" | "external_app_user";
   name: string | null;
   organizationId: string;
+  /** The user's effective roles on the app. */
+  roles: readonly string[];
+  userId: string;
 }>;
 type FederatedAuthState = Readonly<{
   status: "anonymous";
@@ -51,6 +62,87 @@ type FederatedAuthOptions = Readonly<{
   tenantUrl: string;
 }>;
 declare const createFederatedAuth: (options: FederatedAuthOptions) => FederatedAuth;
+type ExternalApplicationsListAppUsersResponses = {
+  /**
+   * Success
+   */
+  200: {
+    correlationId: string;
+    result: {
+      items: Array<{
+        email: string | null;
+        name: string | null;
+        userId: string;
+      }>;
+    };
+  };
+};
+type ExternalApplicationsListAppUsersResponse = ExternalApplicationsListAppUsersResponses[keyof ExternalApplicationsListAppUsersResponses];
+type ExternalApplicationsCreateOrGetAppUserData = {
+  body: {
+    email: string;
+    name: string;
+    roles: Array<string>;
+  };
+  headers: {
+    authorization?: string;
+    'x-organization-id': string;
+    'x-correlation-id'?: string;
+    'x-external-audit-issuer'?: string;
+    'x-external-audit-subject'?: string;
+    'x-external-caller-kind'?: 'anonymous_visitor';
+    'x-external-ci-user-id'?: string;
+    'x-external-server-role'?: string;
+  };
+  path?: never;
+  query?: never;
+  url: '/application/v1/users';
+};
+type ExternalApplicationsCreateOrGetAppUserResponses = {
+  /**
+   * Success
+   */
+  200: {
+    correlationId: string;
+    result: {
+      email: string | null;
+      name: string | null;
+      userId: string;
+      created: boolean;
+      kind: 'member' | 'external_app_user';
+    };
+  };
+};
+type ExternalApplicationsCreateOrGetAppUserResponse = ExternalApplicationsCreateOrGetAppUserResponses[keyof ExternalApplicationsCreateOrGetAppUserResponses];
+type ExternalApplicationsGetAppUserResponses = {
+  /**
+   * Success
+   */
+  200: {
+    correlationId: string;
+    result: {
+      email: string | null;
+      name: string | null;
+      userId: string;
+    };
+  };
+};
+type ExternalApplicationsGetAppUserResponse = ExternalApplicationsGetAppUserResponses[keyof ExternalApplicationsGetAppUserResponses];
+type ExternalApplicationsListAppRolesResponses = {
+  /**
+   * Success
+   */
+  200: {
+    correlationId: string;
+    result: {
+      items: Array<{
+        id: string;
+        key: string;
+      }>;
+    };
+  };
+};
+type ExternalApplicationsListAppRolesResponse = ExternalApplicationsListAppRolesResponses[keyof ExternalApplicationsListAppRolesResponses];
 type JsonValue$1 = boolean | null | number | readonly JsonValue$1[] | Readonly<{
   readonly [key: string]: JsonValue$1;
 }> | string;
@@ -135,6 +227,40 @@ type KnowledgeQuery = {
   op: "autocomplete";
 });
 type ExternalApplicationOperationRequest = {
+  input: {
+    userId: string;
+  };
+  operationId: "users_get";
+} | {
+  input: {
+    page?: number;
+    pageSize?: number;
+  };
+  operationId: "users_list";
+} | {
+  input: {
+    userId: string;
+  };
+  operationId: "users_deactivate";
+} | {
+  input: Record<string, never>;
+  operationId: "roles_list";
+} | {
+  input: {
+    userId: string;
+    roles: string[];
+  };
+  operationId: "roles_assign";
+} | {
+  input: {
+    userId: string;
+    roles: string[];
+  };
+  operationId: "roles_revoke";
+} | {
+  input: ExternalApplicationsCreateOrGetAppUserData["body"];
+  operationId: "users_create_or_get";
+} | {
   input: JsonObject | unknown[];
   operationId: "context_get";
 } | {
@@ -336,7 +462,15 @@ interface EnvelopeSuccess<Id extends string, Result> {
   operationId: Id;
   result: Result;
 }
-type ExternalApplicationOperationSuccess = EnvelopeSuccess<"context_get", JsonObject> | EnvelopeSuccess<"knowledge_query", JsonObject> | EnvelopeSuccess<"knowledge_get_entity_schema_snapshot", JsonObject> | EnvelopeSuccess<"knowledge_search_entities", JsonObject> | EnvelopeSuccess<"knowledge_facets", JsonObject> | EnvelopeSuccess<"knowledge_get_schema_query_context", JsonObject> | EnvelopeSuccess<"knowledge_autocomplete", JsonObject> | EnvelopeSuccess<"knowledge_get_entity", JsonObject> | EnvelopeSuccess<"knowledge_create_entity", JsonObject> | EnvelopeSuccess<"knowledge_update_entity", JsonObject> | EnvelopeSuccess<"knowledge_upsert_entity", JsonObject> | EnvelopeSuccess<"knowledge_delete_entity", JsonObject> | EnvelopeSuccess<"knowledge_traverse", JsonObject> | EnvelopeSuccess<"knowledge_create_relation", JsonObject> | EnvelopeSuccess<"knowledge_update_relation", JsonObject> | EnvelopeSuccess<"knowledge_delete_relation", JsonObject> | EnvelopeSuccess<"agents_list", JsonObject> | EnvelopeSuccess<"agents_invoke", {
+type ExternalApplicationOperationSuccess = EnvelopeSuccess<"users_get", ApplicationUser> | EnvelopeSuccess<"users_list", ApplicationUserPage> | EnvelopeSuccess<"users_deactivate", {
+  userId: string;
+}> | EnvelopeSuccess<"roles_list", {
+  items: ApplicationRole[];
+}> | EnvelopeSuccess<"roles_assign", {
+  userId: string;
+}> | EnvelopeSuccess<"roles_revoke", {
+  userId: string;
+}> | EnvelopeSuccess<"users_create_or_get", ApplicationUserResolution> | EnvelopeSuccess<"context_get", JsonObject> | EnvelopeSuccess<"knowledge_query", JsonObject> | EnvelopeSuccess<"knowledge_get_entity_schema_snapshot", JsonObject> | EnvelopeSuccess<"knowledge_search_entities", JsonObject> | EnvelopeSuccess<"knowledge_facets", JsonObject> | EnvelopeSuccess<"knowledge_get_schema_query_context", JsonObject> | EnvelopeSuccess<"knowledge_autocomplete", JsonObject> | EnvelopeSuccess<"knowledge_get_entity", JsonObject> | EnvelopeSuccess<"knowledge_create_entity", JsonObject> | EnvelopeSuccess<"knowledge_update_entity", JsonObject> | EnvelopeSuccess<"knowledge_upsert_entity", JsonObject> | EnvelopeSuccess<"knowledge_delete_entity", JsonObject> | EnvelopeSuccess<"knowledge_traverse", JsonObject> | EnvelopeSuccess<"knowledge_create_relation", JsonObject> | EnvelopeSuccess<"knowledge_update_relation", JsonObject> | EnvelopeSuccess<"knowledge_delete_relation", JsonObject> | EnvelopeSuccess<"agents_list", JsonObject> | EnvelopeSuccess<"agents_invoke", {
   runId: string;
 }> | EnvelopeSuccess<"skills_list", JsonObject> | EnvelopeSuccess<"skills_invoke", {
   runId: string;
@@ -354,28 +488,11 @@ type ExternalApplicationOperationSuccess = EnvelopeSuccess<"context_get", JsonOb
   conversationId: string;
   runId: string;
 }> | EnvelopeSuccess<"conversations_history", ConversationHistory>;
-/**
- * Operations only the confidential application itself may invoke. They stay
- * out of `externalApplicationOperationIds`, so browser clients and the user
- * proxy never offer them.
- */
-/** A person whose only role in the application's Organization is `member`. */
-interface MemberUser {
-  email: string | null;
-  name: string | null;
-  userId: string;
-}
-/**
- * How create-or-get resolved the email: a new user, an existing CI user who
- * joined the Organization as a member, or a user who already was one.
- */
-type MemberUserResolution = "created" | "existing" | "linked";
-interface MemberUserPage {
-  items: MemberUser[];
-  page: number;
-  pageSize: number;
-  totalItems: number;
-}
+/** User details returned by the application's user-management gateway. */
+type ApplicationUser = ExternalApplicationsGetAppUserResponse["result"];
+type ApplicationUserResolution = ExternalApplicationsCreateOrGetAppUserResponse["result"];
+type ApplicationUserPage = ExternalApplicationsListAppUsersResponse["result"];
+type ApplicationRole = ExternalApplicationsListAppRolesResponse["result"]["items"][number];
 declare const storageFileIdBrand: unique symbol;
 /** A durable private file of the application's Organization. */
 type StorageFileId = string & Readonly<{
@@ -396,32 +513,9 @@ type ExternalApplicationServiceOperationRequest = {
   operationId: "files_upload";
 } | {
   input: {
-    email: string;
-    name: string;
+    origin: string;
   };
-  operationId: "members_create_or_get";
-} | {
-  input: {
-    userId: string;
-  };
-  operationId: "members_get";
-} | {
-  input: {
-    page?: number;
-    pageSize?: number;
-  };
-  operationId: "members_list";
-} | {
-  input: {
-    name: string;
-    userId: string;
-  };
-  operationId: "members_update";
-} | {
-  input: {
-    userId: string;
-  };
-  operationId: "members_remove";
+  operationId: "origins_set_runtime";
 } | {
   input: {
     userId: string;
@@ -440,10 +534,8 @@ interface UserCompanyLinks {
 }
 type ExternalApplicationServiceOperationSuccess = EnvelopeSuccess<"files_upload", {
   storageFileId: StorageFileId;
-}> | EnvelopeSuccess<"members_create_or_get", MemberUser & {
-  outcome: MemberUserResolution;
-}> | EnvelopeSuccess<"members_get", MemberUser> | EnvelopeSuccess<"members_list", MemberUserPage> | EnvelopeSuccess<"members_update", MemberUser> | EnvelopeSuccess<"members_remove", {
-  userId: string;
+}> | EnvelopeSuccess<"origins_set_runtime", {
+  origin: string;
 }> | EnvelopeSuccess<"users_list_company_links", UserCompanyLinks> | EnvelopeSuccess<"users_link_companies", UserCompanyLinks>;
 /** Every operation a confidential server client may invoke. */
 type ExternalApplicationServerOperationRequest = ExternalApplicationOperationRequest | ExternalApplicationServiceOperationRequest;
@@ -456,7 +548,7 @@ type ExternalApplicationOperationSuccessFor<Id extends ExternalApplicationServer
   operationId: Id;
 }>;
 /** Generated, curated external-application operation authority. */
-declare const clientOperationIds: readonly ["context_get", "knowledge_query", "knowledge_get_entity_schema_snapshot", "knowledge_search_entities", "knowledge_facets", "knowledge_get_schema_query_context", "knowledge_autocomplete", "knowledge_get_entity", "knowledge_create_entity", "knowledge_update_entity", "knowledge_upsert_entity", "knowledge_delete_entity", "knowledge_traverse", "knowledge_create_relation", "knowledge_update_relation", "knowledge_delete_relation", "agents_list", "agents_invoke", "skills_list", "skills_invoke", "workflows_list", "workflows_invoke", "runs_get", "runs_stream", "runs_cancel", "attachments_upload", "attachments_download_url", "conversations_continue", "conversations_history"];
+declare const clientOperationIds: readonly ["users_get", "users_list", "users_deactivate", "roles_list", "roles_assign", "roles_revoke", "users_create_or_get", "context_get", "knowledge_query", "knowledge_get_entity_schema_snapshot", "knowledge_search_entities", "knowledge_facets", "knowledge_get_schema_query_context", "knowledge_autocomplete", "knowledge_get_entity", "knowledge_create_entity", "knowledge_update_entity", "knowledge_upsert_entity", "knowledge_delete_entity", "knowledge_traverse", "knowledge_create_relation", "knowledge_update_relation", "knowledge_delete_relation", "agents_list", "agents_invoke", "skills_list", "skills_invoke", "workflows_list", "workflows_invoke", "runs_get", "runs_stream", "runs_cancel", "attachments_upload", "attachments_download_url", "conversations_continue", "conversations_history"];
 type ClientOperationId = ExternalApplicationOperationId;
 declare const isClientOperationId: (value: string) => value is ClientOperationId;
 interface ClientOperationDefinition<Input, Output> {
@@ -572,13 +664,21 @@ type ResourceDefinition<Entity, Create = Entity, Update = Partial<Entity>> = Rea
   }>;
 }>;
 type FilterValue = ResourceJsonValue | readonly ResourceJsonValue[];
+/**
+ * A filter predicate. `field` names a declared filterable field, or a path
+ * through at most three fields that hold Entity References to a field of
+ * the last target, such as `company.industry` or
+ * `contacts.company.parent.industry`. On a field that holds Entity
+ * References, `is_empty` means no reference, and `contains_any` and
+ * `contains_all` compare the ids of a field that holds many.
+ */
 type ResourceFilter = Readonly<{
   field: string;
-  operator: "contains" | "ends_with" | "eq" | "gt" | "gte" | "in" | "lt" | "lte" | "ne" | "not_in" | "starts_with";
+  operator: "contains" | "contains_all" | "contains_any" | "ends_with" | "eq" | "gt" | "gte" | "in" | "lt" | "lte" | "ne" | "not_in" | "starts_with";
   value: FilterValue;
 }> | Readonly<{
   field: string;
-  operator: "is_not_null" | "is_null";
+  operator: "is_empty" | "is_not_null" | "is_null";
 }> | Readonly<{
   filters: readonly ResourceFilter[];
   operator: "and" | "or";
@@ -601,6 +701,11 @@ type ResourcePagination = Readonly<{
 }>;
 type ResourceListQuery = Readonly<{
   filter?: ResourceFilter;
+  /**
+   * Include Paths, such as `["company", "contacts.company"]`: relation
+   * fields whose records each item carries in `included`.
+   */
+  include?: readonly string[];
   includeDeleted?: boolean;
   pagination: ResourcePagination;
   sort?: readonly ResourceSort[];
@@ -609,7 +714,15 @@ type ResourceListQuery = Readonly<{
 type ResourceRecord<Entity> = Readonly<{
   deletedAt?: string;
   id: ResourceRecordId;
+  /**
+   * The records of the read's Include Paths by relation field key: one
+   * record, or the records of a `many` field in reference order. Untyped:
+   * the target schemas are CI's.
+   */
+  included?: Readonly<Record<string, ResourceJsonValue>>;
   revision: ResourceRevision;
+  /** The keys whose included records were cut to the first 100. */
+  truncated?: readonly string[];
   value: Entity;
 }>;
 type ResourceListResult<Entity> = Readonly<{
@@ -627,6 +740,11 @@ type ResourceListResult<Entity> = Readonly<{
 type ResourceErrorCode = "capability_not_supported" | "conflict" | "forbidden" | "internal" | "invalid_request" | "not_found" | "rate_limited" | "transport_error" | "unauthenticated" | "unavailable" |
 /** The CI Organization storage can not take a presigned File upload. */
 "upload_not_supported";
+/** Stable, content-free diagnostics for request-wide Knowledge read limits. */
+type EntityReadLimitDetails = Readonly<{
+  reason: "read_limit_exceeded";
+  budget: "work" | "nodes" | "relation_ids" | "bytes";
+}>;
 type ResourceError = Readonly<{
   code: ResourceErrorCode;
   /** Client-observed dispatch outcome; uncertainty never proves rollback. */
@@ -718,7 +836,7 @@ interface ResourceClient<Entity, Create = Entity, Update = Partial<Entity>> {
   readonly update: (input: ResourceMutationInput<Update>, options?: ResourceRequestOptions) => Promise<ResourceResult<ResourceRecord<Entity>>>;
 }
 /** Common entity operations. Generic resource lifecycle/cursor APIs remain separate. */
-type EntityOperation = "list" | "get" | "create" | "update" | "delete" | "upload";
+type EntityOperation = "list_members" | "list" | "get" | "create" | "update" | "delete" | "upload";
 type EntityListQuery = Omit<ResourceListQuery, "pagination" | "includeDeleted"> & Readonly<{
   pagination: Extract<ResourcePagination, {
     mode: "page";
@@ -727,6 +845,8 @@ type EntityListQuery = Omit<ResourceListQuery, "pagination" | "includeDeleted">
 type EntityPage<Value> = Extract<ResourceListResult<Value>, {
   pagination: "page";
 }>;
+/** Member schemas are resolved by CI, independently of the parent resource. */
+type EntityMemberValue = Readonly<Record<string, ResourceJsonValue>>;
 type EntityCreateInput<Value> = ResourceCreateInput<Value>;
 type EntityUpdateInput<Patch> = ResourceMutationInput<Patch> & Readonly<{
   idempotencyKey: IdempotencyKey;
@@ -777,9 +897,15 @@ type EntityRequestIdentity = Readonly<{
 type EntityRequest<Create = unknown, Patch = unknown> = EntityRequestIdentity & (Readonly<{
   operation: "list";
   query: EntityListQuery;
+}> | Readonly<{
+  operation: "list_members";
+  parentId: ResourceRecordId;
+  field: string;
+  query: EntityListQuery;
 }> | Readonly<{
   operation: "get";
   id: ResourceRecordId;
+  include?: readonly string[];
 }> | (Readonly<{
   operation: "create";
 }> & EntityCreateInput<Create>) | (Readonly<{
@@ -789,7 +915,7 @@ type EntityRequest<Create = unknown, Patch = unknown> = EntityRequestIdentity &
 }> & EntityDeleteInput) | (Readonly<{
   operation: "upload";
 }> & EntityUploadInput));
-type EntityOperationResult<Value, Operation extends EntityOperation> = Operation extends "list" ? EntityPage<Value> : Operation extends "upload" ? EntityUploadSlot : ResourceRecord<Value>;
+type EntityOperationResult<Value, Operation extends EntityOperation> = Operation extends "list_members" ? EntityPage<EntityMemberValue> : Operation extends "list" ? EntityPage<Value> : Operation extends "upload" ? EntityUploadSlot : ResourceRecord<Value>;
 /** Codecs return safe typed failures without coercing values or performing I/O. */
 type EntityProtocol<Value, Create = Value, Patch = Partial<Value>> = Readonly<{
   decodeRequest: (input: unknown) => ResourceResult<EntityRequest<Create, Patch>>;
@@ -800,10 +926,13 @@ interface EntityTransport {
 }
 /** A logical write retains its key, payload and edited revision on explicit resubmission. */
 interface EntityClient<Value, Create = Value, Patch = Partial<Value>> {
+  /** Filter, sort and page the resolved member schema; includes remain bounded. */
+  readonly listMembers: (parentId: ResourceRecordId, field: string, query: EntityListQuery, options?: ResourceRequestOptions) => Promise<ResourceResult<EntityPage<EntityMemberValue>>>;
   readonly definition: ResourceDefinition<Value, Create, Patch>;
   readonly list: (query: EntityListQuery, options?: ResourceRequestOptions) => Promise<ResourceResult<EntityPage<Value>>>;
   readonly get: (input: Readonly<{
     id: ResourceRecordId;
+    include?: readonly string[];
   }>, options?: ResourceRequestOptions) => Promise<ResourceResult<ResourceRecord<Value>>>;
   readonly create: (input: EntityCreateInput<Create>) => Promise<ResourceResult<ResourceRecord<Value>>>;
   readonly update: (input: EntityUpdateInput<Patch>) => Promise<ResourceResult<ResourceRecord<Value>>>;
@@ -822,6 +951,11 @@ declare function createResourceClient<Value, Create = Value, Patch = Partial<Val
 declare function createResourceClient<Value, Create = Value, Patch = Partial<Value>>(options: ClientOptions<Value, Create, Patch> & Readonly<{
   transport: ResourceTransport;
 }>): ResourceClient<Value, Create, Patch>;
+/** Narrow a decoded resource failure to its documented request-wide read limit. */
+declare const isEntityReadLimitError: (error: ResourceError) => error is ResourceError & Readonly<{
+  code: "invalid_request";
+  details: EntityReadLimitDetails;
+}>;
 /** Common entity wire codec; transport and persistence remain with their owners. */
 declare const createEntityProtocol: <Value, Create = Value, Patch = Partial<Value>>(definition: ResourceDefinition<Value, Create, Patch>) => EntityProtocol<Value, Create, Patch>;
 type EntityHttpDestination = Readonly<{
@@ -839,4 +973,4 @@ type EntityHttpTransportOptions = Readonly<{
   fetch?: ClientFetch;
 }>;
 declare const createEntityHttpTransport: (options: EntityHttpTransportOptions) => EntityTransport;
-export { ResourceUpdateRequest as $, ResourceError as A, FederatedAuthOptions as At, ResourceListRequest as B, PortableResourceSchema as C, QueryFilter as Ct, ResourceCreateRequest as D, FederatedAuth as Dt, ResourceCreateInput as E, ClientFetch as Et, ResourceIdentityField as F, ResourceRecord as G, ResourceMutationInput as H, ResourceJsonValue as I, ResourceResult as J, ResourceRecordId as K, ResourceLifecycleInput as L, ResourceFilter as M, FederatedSessionIdentity as Mt, ResourceGetRequest as N, createFederatedAuth as Nt, ResourceCursor as O, FederatedAuthError as Ot, ResourceId as P, ResourceTransportRequest as Q, ResourceLifecycleRequest as R, IdempotencyKey as S, KnowledgeQuery as St, ResourceClient as T, WorkflowInvokeTarget as Tt, ResourcePagination as U, ResourceListResult as V, ResourcePaginationMode as W, ResourceSort as X, ResourceRevision as Y, ResourceTransport as Z, EntityRequest as _, isClientOperationId as _t, createResourceClient as a, CiResult as at, EntityUploadInput as b, ConversationHistory as bt, EntityDeleteInput as c, OperationSuccess as ct, EntityFileWrite as d, ClientOperationInput as dt, ProxyAuthentication as et, EntityListQuery as f, ClientOperationMap as ft, EntityProtocol as g, clientOperationIds as gt, EntityPage as h, TypedOperationExecutor as ht, createEntityProtocol as i, CiErrorCode as it, ResourceErrorCode as j, FederatedAuthState as jt, ResourceDefinition as k, FederatedAuthErrorCode as kt, EntityFileFieldWrite as l, ClientOperationDefinition as lt, EntityOperationResult as m, OperationExecutionOptions as mt, EntityHttpTransportOptions as n, createProxyTransport as nt, EntityClient as o, JsonValue as ot, EntityOperation as p, ClientOperationOutput as pt, ResourceRequestOptions as q, createEntityHttpTransport as r, CiError as rt, EntityCreateInput as s, OperationRequest as st, EntityHttpDestination as t, ProxyTransportOptions as tt, EntityFileValue as u, ClientOperationId as ut, EntityTransport as v, AgentInvokeTarget as vt, ResourceCapabilities as w, SearchQuery as wt, EntityUploadSlot as x, JsonObject as xt, EntityUpdateInput as y, ConversationContinueTarget as yt, ResourceListQuery as z };
+export { ResourceSort as $, ResourceCreateRequest as A, ClientFetch as At, ResourceLifecycleInput as B, EntityUploadInput as C, ConversationContinueTarget as Ct, ResourceCapabilities as D, QueryFilter as Dt, PortableResourceSchema as E, KnowledgeQuery as Et, ResourceFilter as F, FederatedAuthState as Ft, ResourceMutationInput as G, ResourceListQuery as H, ResourceGetRequest as I, FederatedSessionIdentity as It, ResourceRecord as J, ResourcePagination as K, ResourceId as L, createFederatedAuth as Lt, ResourceDefinition as M, FederatedAuthError as Mt, ResourceError as N, FederatedAuthErrorCode as Nt, ResourceClient as O, SearchQuery as Ot, ResourceErrorCode as P, FederatedAuthOptions as Pt, ResourceRevision as Q, ResourceIdentityField as R, EntityUpdateInput as S, ApplicationRole as St, IdempotencyKey as T, JsonObject as Tt, ResourceListRequest as U, ResourceLifecycleRequest as V, ResourceListResult as W, ResourceRequestOptions as X, ResourceRecordId as Y, ResourceResult as Z, EntityPage as _, OperationExecutionOptions as _t, isEntityReadLimitError as a, createProxyTransport as at, EntityRequest as b, isClientOperationId as bt, EntityCreateInput as c, CiResult as ct, EntityFileValue as d, OperationSuccess as dt, ResourceTransport as et, EntityFileWrite as f, ClientOperationDefinition as ft, EntityOperationResult as g, ClientOperationOutput as gt, EntityOperation as h, ClientOperationMap as ht, createEntityProtocol as i, ProxyTransportOptions as it, ResourceCursor as j, FederatedAuth as jt, ResourceCreateInput as k, WorkflowInvokeTarget as kt, EntityDeleteInput as l, JsonValue as lt, EntityMemberValue as m, ClientOperationInput as mt, EntityHttpTransportOptions as n, ResourceUpdateRequest as nt, createResourceClient as o, CiError as ot, EntityListQuery as p, ClientOperationId as pt, ResourcePaginationMode as q, createEntityHttpTransport as r, ProxyAuthentication as rt, EntityClient as s, CiErrorCode as st, EntityHttpDestination as t, ResourceTransportRequest as tt, EntityFileFieldWrite as u, OperationRequest as ut, EntityProtocol as v, TypedOperationExecutor as vt, EntityUploadSlot as w, ConversationHistory as wt, EntityTransport as x, AgentInvokeTarget as xt, EntityReadLimitDetails as y, clientOperationIds as yt, ResourceJsonValue as z };

package/dist/resources.d.ts

@@ -1,2 +1,2 @@
-import { $ as ResourceUpdateRequest, A as ResourceError, B as ResourceListRequest, C as PortableResourceSchema, D as ResourceCreateRequest, E as ResourceCreateInput, F as ResourceIdentityField, G as ResourceRecord, H as ResourceMutationInput, I as ResourceJsonValue, J as ResourceResult, K as ResourceRecordId, L as ResourceLifecycleInput, M as ResourceFilter, N as ResourceGetRequest, O as ResourceCursor, P as ResourceId, Q as ResourceTransportRequest, R as ResourceLifecycleRequest, S as IdempotencyKey, T as ResourceClient, U as ResourcePagination, V as ResourceListResult, W as ResourcePaginationMode, X as ResourceSort, Y as ResourceRevision, Z as ResourceTransport, _ as EntityRequest, a as createResourceClient, b as EntityUploadInput, c as EntityDeleteInput, d as EntityFileWrite, f as EntityListQuery, g as EntityProtocol, h as EntityPage, i as createEntityProtocol, j as ResourceErrorCode, k as ResourceDefinition, l as EntityFileFieldWrite, m as EntityOperationResult, n as EntityHttpTransportOptions, o as EntityClient, p as EntityOperation, q as ResourceRequestOptions, r as createEntityHttpTransport, s as EntityCreateInput, t as EntityHttpDestination, u as EntityFileValue, v as EntityTransport, w as ResourceCapabilities, x as EntityUploadSlot, y as EntityUpdateInput, z as ResourceListQuery } from "./resources-DxMBAy-Z.js";
-export { type EntityClient, type EntityCreateInput, type EntityDeleteInput, type EntityFileFieldWrite, type EntityFileValue, type EntityFileWrite, type EntityHttpDestination, type EntityHttpTransportOptions, type EntityListQuery, type EntityOperation, type EntityOperationResult, type EntityPage, type EntityProtocol, type EntityRequest, type EntityTransport, type EntityUpdateInput, type EntityUploadInput, type EntityUploadSlot, type IdempotencyKey, type PortableResourceSchema, type ResourceCapabilities, type ResourceClient, type ResourceCreateInput, type ResourceCreateRequest, type ResourceCursor, type ResourceDefinition, type ResourceError, type ResourceErrorCode, type ResourceFilter, type ResourceGetRequest, type ResourceId, type ResourceIdentityField, type ResourceJsonValue, type ResourceLifecycleInput, type ResourceLifecycleRequest, type ResourceListQuery, type ResourceListRequest, type ResourceListResult, type ResourceMutationInput, type ResourcePagination, type ResourcePaginationMode, type ResourceRecord, type ResourceRecordId, type ResourceRequestOptions, type ResourceResult, type ResourceRevision, type ResourceSort, type ResourceTransport, type ResourceTransportRequest, type ResourceUpdateRequest, createEntityHttpTransport, createEntityProtocol, createResourceClient };
+import { $ as ResourceSort, A as ResourceCreateRequest, B as ResourceLifecycleInput, C as EntityUploadInput, D as ResourceCapabilities, E as PortableResourceSchema, F as ResourceFilter, G as ResourceMutationInput, H as ResourceListQuery, I as ResourceGetRequest, J as ResourceRecord, K as ResourcePagination, L as ResourceId, M as ResourceDefinition, N as ResourceError, O as ResourceClient, P as ResourceErrorCode, Q as ResourceRevision, R as ResourceIdentityField, S as EntityUpdateInput, T as IdempotencyKey, U as ResourceListRequest, V as ResourceLifecycleRequest, W as ResourceListResult, X as ResourceRequestOptions, Y as ResourceRecordId, Z as ResourceResult, _ as EntityPage, a as isEntityReadLimitError, b as EntityRequest, c as EntityCreateInput, d as EntityFileValue, et as ResourceTransport, f as EntityFileWrite, g as EntityOperationResult, h as EntityOperation, i as createEntityProtocol, j as ResourceCursor, k as ResourceCreateInput, l as EntityDeleteInput, m as EntityMemberValue, n as EntityHttpTransportOptions, nt as ResourceUpdateRequest, o as createResourceClient, p as EntityListQuery, q as ResourcePaginationMode, r as createEntityHttpTransport, s as EntityClient, t as EntityHttpDestination, tt as ResourceTransportRequest, u as EntityFileFieldWrite, v as EntityProtocol, w as EntityUploadSlot, x as EntityTransport, y as EntityReadLimitDetails, z as ResourceJsonValue } from "./resources-BDcYZzER.js";
+export { type EntityClient, type EntityCreateInput, type EntityDeleteInput, type EntityFileFieldWrite, type EntityFileValue, type EntityFileWrite, type EntityHttpDestination, type EntityHttpTransportOptions, type EntityListQuery, type EntityMemberValue, type EntityOperation, type EntityOperationResult, type EntityPage, type EntityProtocol, type EntityReadLimitDetails, type EntityRequest, type EntityTransport, type EntityUpdateInput, type EntityUploadInput, type EntityUploadSlot, type IdempotencyKey, type PortableResourceSchema, type ResourceCapabilities, type ResourceClient, type ResourceCreateInput, type ResourceCreateRequest, type ResourceCursor, type ResourceDefinition, type ResourceError, type ResourceErrorCode, type ResourceFilter, type ResourceGetRequest, type ResourceId, type ResourceIdentityField, type ResourceJsonValue, type ResourceLifecycleInput, type ResourceLifecycleRequest, type ResourceListQuery, type ResourceListRequest, type ResourceListResult, type ResourceMutationInput, type ResourcePagination, type ResourcePaginationMode, type ResourceRecord, type ResourceRecordId, type ResourceRequestOptions, type ResourceResult, type ResourceRevision, type ResourceSort, type ResourceTransport, type ResourceTransportRequest, type ResourceUpdateRequest, createEntityHttpTransport, createEntityProtocol, createResourceClient, isEntityReadLimitError };

package/dist/resources.js

@@ -1,2 +1,2 @@
-import { n as createResourceClient, r as createEntityProtocol, t as createEntityHttpTransport } from "./resources-BP_TaCP6.js";
-export { createEntityHttpTransport, createEntityProtocol, createResourceClient };
+import { i as isEntityReadLimitError, n as createResourceClient, r as createEntityProtocol, t as createEntityHttpTransport } from "./resources--kU5LiFu.js";
+export { createEntityHttpTransport, createEntityProtocol, createResourceClient, isEntityReadLimitError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@collective-intelligence/external-apps-client-sdk",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Framework-neutral client for Collective Intelligence external applications.",
   "type": "module",
   "sideEffects": false,