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

package/README.md

@@ -358,6 +358,34 @@ than waiting for a workflow in this bounded tool adapter. The
 shows distinct receipts and final results, independent resource authorization,
 and application-owned execution, recovery, failure, and duplicate protection.
 
+## Workflow results
+
+Workflow invocation returns `runId`. A successful declared-output Workflow run
+read through `runs.get` has `result: { nativeStatus: "completed", output }`;
+the `completed` event from `runs.stream` carries that same object in `data`.
+CI reads the validated, persisted Workflow output snapshot. The Gateway Tool's
+response becomes public only through the Workflow's explicit `outputContract`
+bindings and schema; selecting a Tool alone does not declare a Workflow result.
+See the [binding example and lifecycle](../../../docs/architecture/external-app-gateway.md#workflow-results-and-observation).
+
+The native worker finishes and persists output independently of the browser.
+External terminal publication stays lazy on the next authorized run read, with
+status, result and completion event committed together as an immutable receipt.
+Existing terminal results and cancellation decisions survive repeated reads.
+Owner-user/kind, Organization, Application and external audit-subject checks
+still apply to both snapshots and events.
+
+If reading fails, observe the original `runId` again; do not resubmit the
+business command to retrieve its result. The browser SDK's `runs.follow`
+returns an event page, propagates read failures, and does not retry them
+automatically. Missing promised output is a technical invariant defect, not a
+normal null-output or partial-success terminal result. There is no historical
+terminal-run backfill or compatibility mode for this contract.
+
+Keep analysis history and candidate results in Knowledge reads. Send a matching
+completion notification only after the matching results are actually available
+in Knowledge, even if the command run has already completed.
+
 ## Agent runs and conversations
 
 `agents.invoke({ agentId, input })` starts one Agent run and returns
@@ -517,6 +545,40 @@ const created = await ci.members.createOrGet({
 - Only `temporarily_unavailable` is retryable (the client retries it); a
   creation CI refuses is a non-retryable `internal_error`.
 
+## Durable files
+
+A confidential application stores a file that a workflow run reads later, such
+as the PDF of a signed form. The file is a private stored file of the
+Organization the credentials were authorized for, with no expiry.
+
+```ts
+const uploaded = await ci.files.upload({
+  contentBase64: pdf.toString("base64"),
+  contentType: "application/pdf",
+  fileName: "application.pdf",
+  organizationId,
+  sizeBytes: pdf.byteLength
+})
+// uploaded.value.result: { storageFileId }
+
+await ci.workflows.invoke({
+  input: { document: { storageFileId: uploaded.value.result.storageFileId } },
+  organizationId,
+  workflowFqn
+})
+```
+
+- `contentType` is `application/pdf`, `image/jpeg` or `image/png`, and the file
+  holds 1 byte to 10 MiB. `sizeBytes` must match the decoded content. Other
+  files are refused with `invalid_request`.
+- A workflow input can name the `storageFileId`; the nodes of a run of the same
+  Organization read the file through their stored file access. The file has no
+  public URL, and another Organization cannot read it.
+- `attachments.upload` is different: its file belongs to one run and expires
+  after 24 hours.
+- It needs the `ai:attachments` scope. Only service credentials may call it: a
+  delegated user token or an anonymous visitor gets `operation_not_allowed`.
+
 ## Member company links
 
 An application links a member of its Organization to the Knowledge company
@@ -1407,6 +1469,21 @@ The adapter never retries or follows redirects. Cancellation or a lost response
 after dispatch remains an uncertain outcome; retain the original action for
 explicit resubmission.
 
+#### File uploads through the BFF
+
+When the definition declares `capabilities.upload: true`, the handler also
+accepts `POST {basePath}/uploads` with `{ field, filename, mimeType }`. It calls
+`authorize` with the operation `upload`, then forwards the request with the
+verified grant to `/application/v1/resources/{schemaFqn}/uploads`. CI answers
+the File upload `{ uploadId, url, method: "PUT", headers }`; the browser PUTs
+the bytes straight to that storage URL, so no file bytes pass through the BFF.
+The entity write that names `{ upload: uploadId }` follows the normal update
+path. `upload_not_supported` (the Organization storage can not presign) maps to
+HTTP 400. Without the capability the request answers `capability_not_supported`
+and is not forwarded. A local `defineEntityResource` binding answers
+`capability_not_supported`, and a `defineCrudResource` handler answers 404 for
+this path. The client SDK README documents the write form.
+
 ## Optional local user authentication
 
 Import `createBetterAuth` only from

package/dist/admin.d.ts

@@ -334,6 +334,19 @@ export type EntityRelationField = {
 	targetEntityId: string;
 	targetSchemaFqn: string;
 };
+declare const KnowledgeFileVisibility: {
+	readonly PUBLIC: "public";
+	readonly PROTECTED: "protected";
+	readonly PRIVATE: "private";
+};
+export type KnowledgeFileVisibility = typeof KnowledgeFileVisibility[keyof typeof KnowledgeFileVisibility];
+export type KnowledgeFileFieldEntry = {
+	accepts: Array<string>;
+	multiple: boolean;
+};
+export type PackageOperationAccepted7 = {
+	operationId: string;
+};
 export type PackageOperationAccepted5 = {
 	operationId: string;
 };
@@ -1505,6 +1518,7 @@ export type ExtensionPackagesUninstallData = {
 	headers: {
 		authorization?: string;
 		"x-organization-id": string;
+		"idempotency-key": string;
 	};
 	path: {
 		fqn: string;
@@ -1892,12 +1906,17 @@ export type RelationSchemasUpdateData = {
 				defaultSearch?: boolean;
 				embedded?: boolean;
 				faceted?: boolean;
+				includeInItemEmbedding?: boolean;
 				indexContent?: boolean;
 				indexOverview?: boolean;
 				indexed?: boolean;
 				managedProjectionSource?: "organization_group" | "organization_user";
+				overviewInputMaxChars?: number | null;
 				queryGuidance?: string;
+				richEnrichment?: boolean | null;
 				unique?: boolean;
+				file?: unknown;
+				mediaVisibility?: unknown;
 			};
 		};
 		fqn?: string;
@@ -2000,12 +2019,17 @@ export type RelationSchemasCreateData = {
 				defaultSearch?: boolean;
 				embedded?: boolean;
 				faceted?: boolean;
+				includeInItemEmbedding?: boolean;
 				indexContent?: boolean;
 				indexOverview?: boolean;
 				indexed?: boolean;
 				managedProjectionSource?: "organization_group" | "organization_user";
+				overviewInputMaxChars?: number | null;
 				queryGuidance?: string;
+				richEnrichment?: boolean | null;
 				unique?: boolean;
+				file?: unknown;
+				mediaVisibility?: unknown;
 			};
 		};
 		fqn: string;
@@ -2245,12 +2269,17 @@ export type EntitySchemasUpdateData = {
 				defaultSearch?: boolean;
 				embedded?: boolean;
 				faceted?: boolean;
+				includeInItemEmbedding?: boolean;
 				indexContent?: boolean;
 				indexOverview?: boolean;
 				indexed?: boolean;
 				managedProjectionSource?: "organization_group" | "organization_user";
+				overviewInputMaxChars?: number | null;
 				queryGuidance?: string;
+				richEnrichment?: boolean | null;
 				unique?: boolean;
+				file?: KnowledgeFileFieldEntry;
+				mediaVisibility?: KnowledgeFileVisibility;
 			};
 		};
 		fqn?: string;
@@ -2271,8 +2300,10 @@ export type EntitySchemasUpdateData = {
 			source: "organization_group" | "organization_group_hierarchy" | "organization_group_membership" | "organization_user";
 		} | null;
 		name?: string;
+		overviewInputMaxChars?: number | null;
 		persistFullFieldContributions?: boolean;
 		relationFields?: Array<EntityRelationField>;
+		richEnrichment?: boolean | null;
 		usableAsDocumentScope?: boolean;
 	};
 	headers: {
@@ -2379,12 +2410,17 @@ export type EntitySchemasCreateData = {
 				defaultSearch?: boolean;
 				embedded?: boolean;
 				faceted?: boolean;
+				includeInItemEmbedding?: boolean;
 				indexContent?: boolean;
 				indexOverview?: boolean;
 				indexed?: boolean;
 				managedProjectionSource?: "organization_group" | "organization_user";
+				overviewInputMaxChars?: number | null;
 				queryGuidance?: string;
+				richEnrichment?: boolean | null;
 				unique?: boolean;
+				file?: KnowledgeFileFieldEntry;
+				mediaVisibility?: KnowledgeFileVisibility;
 			};
 		};
 		fqn: string;
@@ -2399,8 +2435,10 @@ export type EntitySchemasCreateData = {
 			source: "organization_group" | "organization_group_hierarchy" | "organization_group_membership" | "organization_user";
 		} | null;
 		name: string;
+		overviewInputMaxChars?: number | null;
 		persistFullFieldContributions?: boolean;
 		relationFields?: Array<EntityRelationField>;
+		richEnrichment?: boolean | null;
 		usableAsDocumentScope?: boolean;
 	};
 	headers: {
@@ -6364,12 +6402,17 @@ declare const createAdministrationApi: (client: Client$1) => {
 					defaultSearch?: boolean;
 					embedded?: boolean;
 					faceted?: boolean;
+					includeInItemEmbedding?: boolean;
 					indexContent?: boolean;
 					indexOverview?: boolean;
 					indexed?: boolean;
 					managedProjectionSource?: "organization_group" | "organization_user";
+					overviewInputMaxChars?: number | null;
 					queryGuidance?: string;
+					richEnrichment?: boolean | null;
 					unique?: boolean;
+					file?: KnowledgeFileFieldEntry;
+					mediaVisibility?: KnowledgeFileVisibility;
 				};
 			};
 			fqn: string;
@@ -6386,9 +6429,11 @@ declare const createAdministrationApi: (client: Client$1) => {
 				source: "organization_group" | "organization_group_hierarchy" | "organization_group_membership" | "organization_user";
 			} | null;
 			name: string;
+			overviewInputMaxChars: number | null;
 			persistFullFieldContributions: boolean;
 			relationFields: Array<EntityRelationField>;
 			removedFields: Array<unknown>;
+			richEnrichment: boolean | null;
 			updatedAt: string | null;
 			usableAsDocumentScope: boolean;
 		}>;
@@ -6469,11 +6514,14 @@ declare const createAdministrationApi: (client: Client$1) => {
 					defaultSearch?: boolean;
 					embedded?: boolean;
 					faceted?: boolean;
+					includeInItemEmbedding?: boolean;
 					indexContent?: boolean;
 					indexOverview?: boolean;
 					indexed?: boolean;
 					managedProjectionSource?: "organization_group" | "organization_user";
+					overviewInputMaxChars?: number | null;
 					queryGuidance?: string;
+					richEnrichment?: boolean | null;
 					unique?: boolean;
 				};
 			};
@@ -6595,12 +6643,17 @@ declare const createAdministrationApi: (client: Client$1) => {
 					defaultSearch?: boolean;
 					embedded?: boolean;
 					faceted?: boolean;
+					includeInItemEmbedding?: boolean;
 					indexContent?: boolean;
 					indexOverview?: boolean;
 					indexed?: boolean;
 					managedProjectionSource?: "organization_group" | "organization_user";
+					overviewInputMaxChars?: number | null;
 					queryGuidance?: string;
+					richEnrichment?: boolean | null;
 					unique?: boolean;
+					file?: KnowledgeFileFieldEntry;
+					mediaVisibility?: KnowledgeFileVisibility;
 				};
 			};
 			fqn: string;
@@ -6617,9 +6670,11 @@ declare const createAdministrationApi: (client: Client$1) => {
 				source: "organization_group" | "organization_group_hierarchy" | "organization_group_membership" | "organization_user";
 			} | null;
 			name: string;
+			overviewInputMaxChars: number | null;
 			persistFullFieldContributions: boolean;
 			relationFields: Array<EntityRelationField>;
 			removedFields: Array<unknown>;
+			richEnrichment: boolean | null;
 			updatedAt: string | null;
 			usableAsDocumentScope: boolean;
 		}>;
@@ -6700,11 +6755,14 @@ declare const createAdministrationApi: (client: Client$1) => {
 					defaultSearch?: boolean;
 					embedded?: boolean;
 					faceted?: boolean;
+					includeInItemEmbedding?: boolean;
 					indexContent?: boolean;
 					indexOverview?: boolean;
 					indexed?: boolean;
 					managedProjectionSource?: "organization_group" | "organization_user";
+					overviewInputMaxChars?: number | null;
 					queryGuidance?: string;
+					richEnrichment?: boolean | null;
 					unique?: boolean;
 				};
 			};
@@ -6821,12 +6879,17 @@ declare const createAdministrationApi: (client: Client$1) => {
 						defaultSearch?: boolean;
 						embedded?: boolean;
 						faceted?: boolean;
+						includeInItemEmbedding?: boolean;
 						indexContent?: boolean;
 						indexOverview?: boolean;
 						indexed?: boolean;
 						managedProjectionSource?: "organization_group" | "organization_user";
+						overviewInputMaxChars?: number | null;
 						queryGuidance?: string;
+						richEnrichment?: boolean | null;
 						unique?: boolean;
+						file?: KnowledgeFileFieldEntry;
+						mediaVisibility?: KnowledgeFileVisibility;
 					};
 				};
 				fqn: string;
@@ -6843,9 +6906,11 @@ declare const createAdministrationApi: (client: Client$1) => {
 					source: "organization_group" | "organization_group_hierarchy" | "organization_group_membership" | "organization_user";
 				} | null;
 				name: string;
+				overviewInputMaxChars: number | null;
 				persistFullFieldContributions: boolean;
 				relationFields: Array<EntityRelationField>;
 				removedFields: Array<unknown>;
+				richEnrichment: boolean | null;
 				updatedAt: string | null;
 				usableAsDocumentScope: boolean;
 			}>;
@@ -6934,11 +6999,14 @@ declare const createAdministrationApi: (client: Client$1) => {
 						defaultSearch?: boolean;
 						embedded?: boolean;
 						faceted?: boolean;
+						includeInItemEmbedding?: boolean;
 						indexContent?: boolean;
 						indexOverview?: boolean;
 						indexed?: boolean;
 						managedProjectionSource?: "organization_group" | "organization_user";
+						overviewInputMaxChars?: number | null;
 						queryGuidance?: string;
+						richEnrichment?: boolean | null;
 						unique?: boolean;
 					};
 				};
@@ -7113,9 +7181,7 @@ declare const createAdministrationApi: (client: Client$1) => {
 		}[]>;
 		promoteRelease: (options: Pick<Options$1<PackageReleasesPromoteData, true, unknown>, "query" | "body" | "headers" | "path">) => Promise<PackageOperationAccepted2>;
 		publishRelease: (options: Pick<Options$1<PackageReleasesPublishData, true, unknown>, "query" | "body" | "headers" | "path">) => Promise<PackageOperationAccepted1>;
-		uninstall: (options: Pick<Options$1<ExtensionPackagesUninstallData, true, unknown>, "query" | "body" | "headers" | "path">) => Promise<{
-			message: string;
-		}>;
+		uninstall: (options: Pick<Options$1<ExtensionPackagesUninstallData, true, unknown>, "query" | "body" | "headers" | "path">) => Promise<PackageOperationAccepted7>;
 		updateInstallation: (options: Pick<Options$1<PackageReleasesUpdateInstallationData, true, unknown>, "query" | "body" | "headers" | "path">) => Promise<PackageOperationAccepted3>;
 	};
 	reports: {
@@ -7276,8 +7342,10 @@ declare const createAdministrationApi: (client: Client$1) => {
 			layoutProps: unknown | null;
 			name: string;
 			organizationId: string;
+			packageOwned: boolean;
 			publishedDefinitionHash: string | null;
 			publishedVersionId: string | null;
+			readonly: boolean;
 			slug: string;
 			updatedAt: string | null;
 		}>;
@@ -7296,8 +7364,10 @@ declare const createAdministrationApi: (client: Client$1) => {
 			layoutProps: unknown | null;
 			name: string;
 			organizationId: string;
+			packageOwned: boolean;
 			publishedDefinitionHash: string | null;
 			publishedVersionId: string | null;
+			readonly: boolean;
 			slug: string;
 			updatedAt: string | null;
 		}>;
@@ -7314,8 +7384,10 @@ declare const createAdministrationApi: (client: Client$1) => {
 				layoutProps: unknown | null;
 				name: string;
 				organizationId: string;
+				packageOwned: boolean;
 				publishedDefinitionHash: string | null;
 				publishedVersionId: string | null;
+				readonly: boolean;
 				slug: string;
 				updatedAt: string | null;
 			}>;

package/dist/express.d.ts

@@ -387,6 +387,8 @@ export type ResourceCapabilities = Readonly<{
 	search: true;
 	softDelete?: boolean;
 	update?: boolean;
+	/** File uploads for the File fields of a common entity resource. */
+	upload?: boolean;
 }>;
 export type ResourcePaginationMode = "cursor" | "page";
 export type PortableResourceSchema = Readonly<Record<string, ResourceJsonValue>>;
@@ -458,7 +460,9 @@ export type ResourceListQuery = Readonly<{
 	sort?: readonly ResourceSort[];
 	textSearch?: string;
 }>;
-export type ResourceErrorCode = "capability_not_supported" | "conflict" | "forbidden" | "internal" | "invalid_request" | "not_found" | "rate_limited" | "transport_error" | "unauthenticated" | "unavailable";
+export 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";
 export type ResourceError = Readonly<{
 	code: ResourceErrorCode;
 	/** Client-observed dispatch outcome; uncertainty never proves rollback. */

package/dist/gateway/contracts.d.ts

@@ -354,6 +354,8 @@ export type ResourceCapabilities = Readonly<{
 	search: true;
 	softDelete?: boolean;
 	update?: boolean;
+	/** File uploads for the File fields of a common entity resource. */
+	upload?: boolean;
 }>;
 export type ResourcePaginationMode = "cursor" | "page";
 export type PortableResourceSchema = Readonly<Record<string, ResourceJsonValue>>;
@@ -425,7 +427,9 @@ export type ResourceListQuery = Readonly<{
 	sort?: readonly ResourceSort[];
 	textSearch?: string;
 }>;
-export type ResourceErrorCode = "capability_not_supported" | "conflict" | "forbidden" | "internal" | "invalid_request" | "not_found" | "rate_limited" | "transport_error" | "unauthenticated" | "unavailable";
+export 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";
 export type ResourceError = Readonly<{
 	code: ResourceErrorCode;
 	/** Client-observed dispatch outcome; uncertainty never proves rollback. */

package/dist/gateway.d.ts

@@ -395,6 +395,8 @@ export type ResourceCapabilities = Readonly<{
 	search: true;
 	softDelete?: boolean;
 	update?: boolean;
+	/** File uploads for the File fields of a common entity resource. */
+	upload?: boolean;
 }>;
 export type ResourcePaginationMode = "cursor" | "page";
 export type PortableResourceSchema = Readonly<Record<string, ResourceJsonValue>>;
@@ -466,7 +468,9 @@ export type ResourceListQuery = Readonly<{
 	sort?: readonly ResourceSort[];
 	textSearch?: string;
 }>;
-export type ResourceErrorCode = "capability_not_supported" | "conflict" | "forbidden" | "internal" | "invalid_request" | "not_found" | "rate_limited" | "transport_error" | "unauthenticated" | "unavailable";
+export 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";
 export type ResourceError = Readonly<{
 	code: ResourceErrorCode;
 	/** Client-observed dispatch outcome; uncertainty never proves rollback. */