@collective-intelligence/external-apps-client-sdk 0.1.8 → 0.1.10

package/README.md

@@ -31,14 +31,66 @@ plus slack) before throwing `Run did not finish`; pass `deadlineMs` to change
 it and `signal` to cancel. Polling starts every `idleMs` (50 ms) and backs off
 to at most one second while no new events arrive.
 
+## Workflow results and read recovery
+
+A successful Workflow with a declared output contract exposes its persisted
+result in the run returned by `runs.get`:
+
+```json
+{
+  "status": "succeeded",
+  "result": {
+    "nativeStatus": "completed",
+    "output": {
+      "activeSearch": {
+        "notionPageId": "notion-search-123",
+        "url": "https://notion.so/notion-search-123",
+        "name": "Senior engineer",
+        "status": "created"
+      },
+      "customer": { "created": false, "id": "customer-42", "name": "Acme" },
+      "requirements": { "role": "engineer", "seniority": "senior" }
+    }
+  }
+}
+```
+
+This is an excerpt of the run JSON in the successful SDK response's `value`.
+The Workflow selects and validates `output`; it is portable JSON, not a
+search-specific SDK type. Unmapped intermediate node fields are not public
+output. `runs.stream` returns an event page; its `completed` event's `data`
+equals the run's `result`. `runs.follow` also returns an event page and drains
+remaining pages after a terminal snapshot, so read the completion event's
+`data.output` there. It does not return a run snapshot.
+
+`runs.get` and `runs.stream` return a failed `CiResult` for an HTTP read failure;
+`runs.follow` propagates that failure as an error. Following has no automatic
+read retry, even for a retryable error. Retain the original `runId` and explicitly
+call `get`, `stream`, or `follow` again when retrying observation. Do not invoke
+the Workflow again to recover its result. A new `follow` starts reading the
+same run's events from the beginning; use `stream({ runId, afterCursor })` when
+the application owns a saved cursor.
+
+Native execution and result persistence continue after the browser disconnects.
+The first authorized `get` or `stream` after completion publishes the external
+terminal receipt; `follow` uses those same reads. Access remains scoped to the
+original owner, Organization, Application and audit subject. Historical terminal
+runs are not backfilled or adapted. A missing promised output is a technical
+invariant defect, not a successful empty or partial result.
+
+Analysis history and candidate results remain Knowledge reads. A matching
+completion notification must wait until those results are actually available in
+Knowledge; a completed command alone does not establish that readiness. See the
+[Workflow output contract and recovery guide](../../../docs/architecture/external-app-gateway.md#workflow-results-and-observation).
+
+## Common entity CRUD
+
 The `@collective-intelligence/external-apps-client-sdk/resources` entrypoint
 provides the portable resource contracts and `createResourceClient`. A resource
 client supports filtering, sorting, text search, page or cursor pagination,
 opaque IDs and revisions, optimistic concurrency, idempotency, soft deletion,
 restore, and hard deletion according to the resource's declared capabilities.
 
-## Common entity CRUD
-
 Use the explicit `protocol: "entity"` option for the common page-based CRUD API.
 Both the root and `/resources` entrypoints export these builders:
 
@@ -82,7 +134,8 @@ 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`, and `delete`.
+The common client exposes `list`, `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
 optional `{ signal }`. Mutations are independent of view unmount cancellation.
@@ -100,6 +153,61 @@ 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`.
 
+## File uploads
+
+A File field holds files of a CI entity. The browser sends the file bytes
+straight to storage; they never pass through CI or a BFF:
+
+1. `upload({ field, filename, mimeType })` requests a File upload for one
+   File field. The definition must declare `capabilities.upload: true`;
+   otherwise the call fails with `capability_not_supported` and sends nothing.
+2. PUT the bytes to the returned `url` with the returned `headers`.
+3. Write the entity with `{ upload: uploadId }` for that File field key.
+
+```ts
+const slot = await leads.upload(
+  { field: "resume", filename: file.name, mimeType: file.type },
+  { signal }
+)
+if (slot.ok) {
+  await fetch(slot.value.url, {
+    body: file,
+    headers: slot.value.headers,
+    method: slot.value.method
+  })
+  await leads.update({
+    expectedRevision: record.revision,
+    id: record.id,
+    idempotencyKey: crypto.randomUUID(),
+    value: { resume: { upload: slot.value.uploadId } }
+  })
+}
+```
+
+`EntityFileFieldWrite` types the write form of a File field key:
+
+- `{ upload: uploadId }` adds a File upload.
+- `{ id }` keeps a file. A File value read before also keeps it; its other keys
+  are ignored.
+- `null` removes every file of the field.
+- An ordered array sets the exact list of a multiple File field.
+- An absent key keeps the files unchanged.
+
+The definition's create and update schemas must accept this form for each
+File field key. Reads return `EntityFileValue` objects:
+`{ id, url, filename, mimeType, size, source }`, where `source` is `managed` or
+`external_url`. A single File field reads as one File value or `null`; a
+multiple one as an array.
+
+A File upload is single use: the first successful write consumes it, and CI
+deletes an unused one after a retention window. Request a new one to retry.
+`upload` fails with `upload_not_supported` when the Organization storage can
+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`.
+
 ## Workspace development
 
 The repository's [Effect demo](../../../demo/external-app-effect/README.md)

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { $ as CiErrorCode, A as ResourceIdentityField, B as ResourceRecord, C as ResourceCursor, Ct as FederatedAuthError, D as ResourceFilter, Dt as FederatedSessionIdentity, E as ResourceErrorCode, Et as FederatedAuthState, F as ResourceListRequest, G as ResourceSort, H as ResourceRequestOptions, I as ResourceListResult, J as ResourceUpdateRequest, K as ResourceTransport, L as ResourceMutationInput, M as ResourceLifecycleInput, N as ResourceLifecycleRequest, O as ResourceGetRequest, Ot as createFederatedAuth, P as ResourceListQuery, Q as CiError, R as ResourcePagination, S as ResourceCreateRequest, St as FederatedAuth, T as ResourceError, Tt as FederatedAuthOptions, U as ResourceResult, V as ResourceRecordId, W as ResourceRevision, X as ProxyTransportOptions, Y as ProxyAuthentication, Z as createProxyTransport, _ as IdempotencyKey, _t as KnowledgeQuery, a as createResourceClient, at as ClientOperationId, b as ResourceClient, bt as WorkflowInvokeTarget, c as EntityDeleteInput, ct as ClientOperationOutput, d as EntityOperationResult, dt as clientOperationIds, et as CiResult, f as EntityPage, ft as isClientOperationId, g as EntityUpdateInput, gt as JsonObject, h as EntityTransport, ht as ConversationHistory, i as createEntityProtocol, it as ClientOperationDefinition, j as ResourceJsonValue, k as ResourceId, l as EntityListQuery, lt as OperationExecutionOptions, m as EntityRequest, mt as ConversationContinueTarget, n as EntityHttpTransportOptions, nt as OperationRequest, o as EntityClient, ot as ClientOperationInput, p as EntityProtocol, pt as AgentInvokeTarget, q as ResourceTransportRequest, r as createEntityHttpTransport, rt as OperationSuccess, s as EntityCreateInput, st as ClientOperationMap, t as EntityHttpDestination, tt as JsonValue, u as EntityOperation, ut as TypedOperationExecutor, v as PortableResourceSchema, vt as QueryFilter, w as ResourceDefinition, wt as FederatedAuthErrorCode, x as ResourceCreateInput, xt as ClientFetch, y as ResourceCapabilities, yt as SearchQuery, z as ResourcePaginationMode } from "./resources-D95LlDMa.js";
+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-D0bzEPx3.js";
 type ServerSessionAuthOptions = Readonly<{
   basePath: string;
   fetch?: ClientFetch;
@@ -889,4 +889,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 EntityHttpDestination, type EntityHttpTransportOptions, type EntityListQuery, type EntityOperation, type EntityOperationResult, type EntityPage, type EntityProtocol, type EntityRequest, type EntityTransport, type EntityUpdateInput, 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 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 };

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-BYm1KWAZ.js";
+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-C0wYfzcV.js";
 const base64Url = (bytes) => {
 	let binary = "";
 	for (const byte of bytes) binary += String.fromCodePoint(byte);

package/dist/{resources-BYm1KWAZ.js → resources-C0wYfzcV.js}

@@ -7575,6 +7575,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 +7681,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 +7797,7 @@ const entityQuerySchema = (definition) => {
 	});
 	const query = objectSchema({
 		filter: { $ref: "#/$defs/filter" },
+		include: includeSchema,
 		pagination: page,
 		sort: {
 			items: objectSchema({
@@ -7734,10 +7818,16 @@ const operationKey = {
 	pattern: "^[\\w.-]{1,256}$",
 	type: "string"
 };
-const requestSchema = (definition, operation, properties) => ({
+const uploadText = {
+	maxLength: 255,
+	minLength: 1,
+	type: "string"
+};
+const requestSchema = (definition, operation, properties, optional = {}) => ({
 	additionalProperties: false,
 	properties: {
 		...properties,
+		...optional,
 		operation: { const: operation },
 		requestId: identifier,
 		resourceId: { const: definition.id }
@@ -7774,7 +7864,7 @@ const createEntityProtocol = (definition) => {
 		},
 		oneOf: [
 			requestSchema(definition, "list", { query }),
-			requestSchema(definition, "get", { id: identifier }),
+			requestSchema(definition, "get", { id: identifier }, { include: includeSchema }),
 			requestSchema(definition, "create", {
 				idempotencyKey: operationKey,
 				value: { $ref: "#/$defs/create" }
@@ -7792,6 +7882,11 @@ const createEntityProtocol = (definition) => {
 				expectedRevision: identifier,
 				id: identifier,
 				idempotencyKey: operationKey
+			}),
+			requestSchema(definition, "upload", {
+				field: uploadText,
+				filename: uploadText,
+				mimeType: uploadText
 			})
 		]
 	});
@@ -7801,7 +7896,12 @@ const createEntityProtocol = (definition) => {
 			type: "string"
 		},
 		id: identifier,
+		included: { type: "object" },
 		revision: identifier,
+		truncated: {
+			items: { type: "string" },
+			type: "array"
+		},
 		value: { $ref: "#/$defs/entity" }
 	}, [
 		"id",
@@ -7819,7 +7919,8 @@ const createEntityProtocol = (definition) => {
 			"rate_limited",
 			"transport_error",
 			"unauthenticated",
-			"unavailable"
+			"unavailable",
+			"upload_not_supported"
 		] },
 		details: { type: "object" },
 		message: { type: "string" },
@@ -7883,6 +7984,15 @@ const createEntityProtocol = (definition) => {
 		required: [...record.required, "deletedAt"]
 	}));
 	const validatePage = ajv.compile(resultSchema(page));
+	const validateUploadSlot = ajv.compile(resultSchema(objectSchema({
+		headers: {
+			additionalProperties: { type: "string" },
+			type: "object"
+		},
+		method: { const: "PUT" },
+		uploadId: identifier,
+		url: identifier
+	})));
 	const coherentPage = (input) => {
 		if (!validatePage(input)) return false;
 		if (!input.ok) return true;
@@ -7894,7 +8004,8 @@ const createEntityProtocol = (definition) => {
 		delete: validateDeleted,
 		get: validateRecord,
 		list: coherentPage,
-		update: validateRecord
+		update: validateRecord,
+		upload: validateUploadSlot
 	};
 	return {
 		decodeRequest: (input) => {
@@ -7967,7 +8078,8 @@ const createCommonEntityClient = (options) => {
 			delete: "delete",
 			get: "get",
 			list: "search",
-			update: "update"
+			update: "update",
+			upload: "upload"
 		}[input.operation]] !== true) return {
 			correlationId,
 			error: {
@@ -8022,7 +8134,11 @@ const createCommonEntityClient = (options) => {
 		update: (input) => execute({
 			...input,
 			operation: "update"
-		})
+		}),
+		upload: (input, requestOptions) => execute({
+			...input,
+			operation: "upload"
+		}, requestOptions)
 	};
 };
 const capabilityByOperation = {
@@ -8118,10 +8234,13 @@ const encode = (request) => {
 			method: "POST",
 			path: "/search"
 		};
-		case "get": return {
-			method: "GET",
-			path: `/records/${encodeURIComponent(request.id)}`
-		};
+		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,
@@ -8147,6 +8266,15 @@ const encode = (request) => {
 			method: "POST",
 			path: `/records/${encodeURIComponent(request.id)}/soft-delete`
 		};
+		case "upload": return {
+			body: JSON.stringify({
+				field: request.field,
+				filename: request.filename,
+				mimeType: request.mimeType
+			}),
+			method: "POST",
+			path: "/uploads"
+		};
 	}
 };
 const createEntityHttpTransport = (options) => {

package/dist/{resources-D95LlDMa.d.ts → resources-D0bzEPx3.d.ts}

@@ -376,7 +376,25 @@ interface MemberUserPage {
   pageSize: number;
   totalItems: number;
 }
+declare const storageFileIdBrand: unique symbol;
+/** A durable private file of the application's Organization. */
+type StorageFileId = string & Readonly<{
+  [storageFileIdBrand]: "StorageFileId";
+}>;
+/**
+ * One file of up to 10 MiB, base64-encoded. CI accepts the content types
+ * `application/pdf`, `image/jpeg` and `image/png`.
+ */
+interface DurableFileUpload {
+  contentBase64: string;
+  contentType: string;
+  fileName: string;
+  sizeBytes: number;
+}
 type ExternalApplicationServiceOperationRequest = {
+  input: DurableFileUpload;
+  operationId: "files_upload";
+} | {
   input: {
     email: string;
     name: string;
@@ -404,6 +422,11 @@ type ExternalApplicationServiceOperationRequest = {
     userId: string;
   };
   operationId: "members_remove";
+} | {
+  input: {
+    origin: string;
+  };
+  operationId: "origins_set_runtime";
 } | {
   input: {
     userId: string;
@@ -420,10 +443,14 @@ type ExternalApplicationServiceOperationRequest = {
 interface UserCompanyLinks {
   entityIds: string[];
 }
-type ExternalApplicationServiceOperationSuccess = EnvelopeSuccess<"members_create_or_get", MemberUser & {
+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;
@@ -516,6 +543,8 @@ type ResourceCapabilities = Readonly<{
   search: true;
   softDelete?: boolean;
   update?: boolean;
+  /** File uploads for the File fields of a common entity resource. */
+  upload?: boolean;
 }>;
 type ResourcePaginationMode = "cursor" | "page";
 type PortableResourceSchema = Readonly<Record<string, ResourceJsonValue>>;
@@ -550,13 +579,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";
@@ -579,6 +616,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[];
@@ -587,7 +629,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<{
@@ -602,7 +652,9 @@ type ResourceListResult<Entity> = Readonly<{
   totalItems: number;
   totalPages: number;
 }>;
-type ResourceErrorCode = "capability_not_supported" | "conflict" | "forbidden" | "internal" | "invalid_request" | "not_found" | "rate_limited" | "transport_error" | "unauthenticated" | "unavailable";
+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";
 type ResourceError = Readonly<{
   code: ResourceErrorCode;
   /** Client-observed dispatch outcome; uncertainty never proves rollback. */
@@ -694,7 +746,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";
+type EntityOperation = "list" | "get" | "create" | "update" | "delete" | "upload";
 type EntityListQuery = Omit<ResourceListQuery, "pagination" | "includeDeleted"> & Readonly<{
   pagination: Extract<ResourcePagination, {
     mode: "page";
@@ -710,6 +762,42 @@ type EntityUpdateInput<Patch> = ResourceMutationInput<Patch> & Readonly<{
 type EntityDeleteInput = ResourceLifecycleInput & Readonly<{
   idempotencyKey: IdempotencyKey;
 }>;
+/** A File upload request for one File field of the entity schema. */
+type EntityUploadInput = Readonly<{
+  field: string;
+  filename: string;
+  mimeType: string;
+}>;
+/** PUT the file bytes to `url` with `headers`; then write `{ upload: uploadId }`. */
+type EntityUploadSlot = Readonly<{
+  headers: Readonly<Record<string, string>>;
+  method: "PUT";
+  uploadId: string;
+  url: string;
+}>;
+/** The read-time value of one file of a File field. */
+type EntityFileValue = Readonly<{
+  id: string;
+  url: string;
+  filename: string;
+  mimeType: string | null;
+  size: number | null;
+  source: "managed" | "external_url";
+}>;
+/** `{ upload }` adds a File upload; `{ id }`, or a File value read before, keeps that file. */
+type EntityFileWrite = Readonly<{
+  upload: string;
+  id?: never;
+}> | Readonly<{
+  id: string;
+  upload?: never;
+}>;
+/**
+ * The write form of a File field key: one file or `null` for a single field,
+ * an ordered array for a multiple field, `null` removes every file. Omit the
+ * key to keep its files unchanged.
+ */
+type EntityFileFieldWrite = EntityFileWrite | readonly EntityFileWrite[] | null;
 type EntityRequestIdentity = Readonly<{
   requestId: string;
   resourceId: string;
@@ -720,14 +808,17 @@ type EntityRequest<Create = unknown, Patch = unknown> = EntityRequestIdentity &
 }> | Readonly<{
   operation: "get";
   id: ResourceRecordId;
+  include?: readonly string[];
 }> | (Readonly<{
   operation: "create";
 }> & EntityCreateInput<Create>) | (Readonly<{
   operation: "update";
 }> & EntityUpdateInput<Patch>) | (Readonly<{
   operation: "delete";
-}> & EntityDeleteInput));
-type EntityOperationResult<Value, Operation extends EntityOperation> = Operation extends "list" ? EntityPage<Value> : ResourceRecord<Value>;
+}> & EntityDeleteInput) | (Readonly<{
+  operation: "upload";
+}> & EntityUploadInput));
+type EntityOperationResult<Value, Operation extends EntityOperation> = 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>>;
@@ -742,10 +833,13 @@ interface EntityClient<Value, Create = Value, Patch = Partial<Value>> {
   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>>>;
   readonly delete: (input: EntityDeleteInput) => Promise<ResourceResult<ResourceRecord<Value>>>;
+  /** A single-use File upload slot; requires the `upload` capability. */
+  readonly upload: (input: EntityUploadInput, options?: ResourceRequestOptions) => Promise<ResourceResult<EntityUploadSlot>>;
 }
 type ClientOptions<Value, Create, Patch> = Readonly<{
   definition: ResourceDefinition<Value, Create, Patch>;
@@ -775,4 +869,4 @@ type EntityHttpTransportOptions = Readonly<{
   fetch?: ClientFetch;
 }>;
 declare const createEntityHttpTransport: (options: EntityHttpTransportOptions) => EntityTransport;
-export { CiErrorCode as $, ResourceIdentityField as A, ResourceRecord as B, ResourceCursor as C, FederatedAuthError as Ct, ResourceFilter as D, FederatedSessionIdentity as Dt, ResourceErrorCode as E, FederatedAuthState as Et, ResourceListRequest as F, ResourceSort as G, ResourceRequestOptions as H, ResourceListResult as I, ResourceUpdateRequest as J, ResourceTransport as K, ResourceMutationInput as L, ResourceLifecycleInput as M, ResourceLifecycleRequest as N, ResourceGetRequest as O, createFederatedAuth as Ot, ResourceListQuery as P, CiError as Q, ResourcePagination as R, ResourceCreateRequest as S, FederatedAuth as St, ResourceError as T, FederatedAuthOptions as Tt, ResourceResult as U, ResourceRecordId as V, ResourceRevision as W, ProxyTransportOptions as X, ProxyAuthentication as Y, createProxyTransport as Z, IdempotencyKey as _, KnowledgeQuery as _t, createResourceClient as a, ClientOperationId as at, ResourceClient as b, WorkflowInvokeTarget as bt, EntityDeleteInput as c, ClientOperationOutput as ct, EntityOperationResult as d, clientOperationIds as dt, CiResult as et, EntityPage as f, isClientOperationId as ft, EntityUpdateInput as g, JsonObject as gt, EntityTransport as h, ConversationHistory as ht, createEntityProtocol as i, ClientOperationDefinition as it, ResourceJsonValue as j, ResourceId as k, EntityListQuery as l, OperationExecutionOptions as lt, EntityRequest as m, ConversationContinueTarget as mt, EntityHttpTransportOptions as n, OperationRequest as nt, EntityClient as o, ClientOperationInput as ot, EntityProtocol as p, AgentInvokeTarget as pt, ResourceTransportRequest as q, createEntityHttpTransport as r, OperationSuccess as rt, EntityCreateInput as s, ClientOperationMap as st, EntityHttpDestination as t, JsonValue as tt, EntityOperation as u, TypedOperationExecutor as ut, PortableResourceSchema as v, QueryFilter as vt, ResourceDefinition as w, FederatedAuthErrorCode as wt, ResourceCreateInput as x, ClientFetch as xt, ResourceCapabilities as y, SearchQuery as yt, ResourcePaginationMode as z };
+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 };

package/dist/resources.d.ts

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

package/dist/resources.js

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

package/package.json

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