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

package/README.md

@@ -579,6 +579,79 @@ await ci.workflows.invoke({
 - It needs the `ai:attachments` scope. Only service credentials may call it: a
   delegated user token or an anonymous visitor gets `operation_not_allowed`.
 
+### Entity File fields
+
+A File field of an entity schema takes a different flow: the file becomes a
+File value of the entity, not a stored file a workflow reads.
+`resources.createUpload` asks CI for a single-use upload slot, the server PUTs
+the bytes straight to storage, and the entity write through CI's resources API
+names the slot's `uploadId` as `{ upload }` for that File field key:
+
+```ts
+const slot = await ci.resources.createUpload({
+  field: "memberLogo",
+  filename: "logo.png",
+  mimeType: "image/png",
+  organizationId,
+  schemaId: "apito.vetrina.schemas.member-company"
+})
+if (slot.ok) {
+  const { headers, method, uploadId, url } = slot.value.result
+  await fetch(url, { body: logo, headers, method })
+  // The entity write then sends { memberLogo: { upload: uploadId } }.
+}
+```
+
+- Two credentials can ask for a slot, as for entity writes: the member's
+  delegated token (`exchangeMemberSession`), writing as that member; or the
+  application's service credential, for schemas declared by the application's
+  own package only, writing as the Organization default service principal.
+  `schemaId` is the schema id or FQN.
+- A refusal resolves `{ ok: false, error }` with CI's `correlationId` and a
+  `code`; `upload_not_supported` means the Organization storage cannot presign
+  uploads. Only `retryable` failures are retried.
+- Each attempt, request and response body, is bounded by `timeoutMs`
+  (10 seconds by default); a CI that stops answering ends in a retryable
+  `unavailable`. `signal` cancels: a cancelled request rejects with the
+  signal's reason.
+- The PUT is the caller's: send exactly `headers` to `url` with `method`. No
+  file bytes pass through CI's API. A slot is single use: the first successful
+  write consumes it; request a new one to retry.
+- The write form of a File field key is `{ upload }` to add the uploaded file,
+  `{ id }` (or a File value read before) to keep a file, an ordered array for a
+  multiple field, or `null` to remove every file. Omit the key to keep its
+  files.
+- `/runtime/effect` exports the Effect schemas `EntityFileValue` (a File value
+  as CI reads return it), `EntityFileWrite` (one file of a write) and
+  `EntityFileFieldWrite` (the write form of a File field key). Their types
+  equal the client SDK types of the same name. They validate CI entity
+  values; a portable resource form has no File field, so
+  `projectResourceSchema` refuses them.
+
+## Runtime origin
+
+The browser origins of an Organization are the `allowedOrigins` that its
+installed applications declare, plus one runtime origin per application. A
+confidential application sets its runtime origin, for example the URL of each
+new deployment; CI keeps storage CORS in line with the Organization origins, so
+a browser on that origin can upload to a presigned storage URL.
+
+```ts
+await ci.origins.setRuntime({
+  organizationId,
+  origin: `https://${process.env.VERCEL_URL}`
+})
+// value.result: { origin }
+```
+
+- Each call replaces the application's previous runtime origin, so the list
+  does not grow; declare stable origins, such as the production site, in
+  `allowedOrigins`.
+- `origin` is an exact HTTPS origin (`https://host[:port]`, no path), or a
+  loopback HTTP origin with a port; other values get `invalid_request`.
+- It needs the `origins:write` scope. Only service credentials may call it: a
+  delegated user token or an anonymous visitor gets `operation_not_allowed`.
+
 ## Member company links
 
 An application links a member of its Organization to the Knowledge company

package/dist/admin.d.ts

@@ -325,15 +325,33 @@ declare const FeatureFlagRolloutMode: {
 	readonly DISABLED_FOR_ORGANIZATIONS: "disabled_for_organizations";
 };
 export type FeatureFlagRolloutMode = typeof FeatureFlagRolloutMode[keyof typeof FeatureFlagRolloutMode];
-export type EntityRelationField = {
-	cardinality: "many" | "one";
-	field: string;
-	id: string;
-	nullable: boolean;
-	reference: "external_id";
-	targetEntityId: string;
+export type KnowledgeRelationFieldEntry = {
+	autocomplete?: {
+		baseFilters?: Array<{
+			caseSensitive?: boolean;
+			field: string;
+			operator: "eq" | "ne" | "in" | "nin" | "contains" | "not_contains" | "starts_with" | "ends_with" | "gt" | "gte" | "lt" | "lte" | "exists" | "is_empty" | "is_not_empty";
+			value: Suspend;
+		}>;
+		fields?: Array<{
+			field: string;
+			scope: "data" | "entity";
+		}>;
+	};
+	cardinality: "one" | "many";
+	display?: {
+		fields: Array<{
+			field: string;
+			scope: "data" | "entity";
+		}>;
+	};
+	maxItems?: number;
+	onDelete?: "clear" | "restrict";
 	targetSchemaFqn: string;
 };
+export type Suspend = null | boolean | number | string | Array<Suspend> | {
+	[key: string]: Suspend;
+};
 declare const KnowledgeFileVisibility: {
 	readonly PUBLIC: "public";
 	readonly PROTECTED: "protected";
@@ -1917,6 +1935,7 @@ export type RelationSchemasUpdateData = {
 				unique?: boolean;
 				file?: unknown;
 				mediaVisibility?: unknown;
+				relation?: unknown;
 			};
 		};
 		fqn?: string;
@@ -2030,6 +2049,7 @@ export type RelationSchemasCreateData = {
 				unique?: boolean;
 				file?: unknown;
 				mediaVisibility?: unknown;
+				relation?: unknown;
 			};
 		};
 		fqn: string;
@@ -2280,6 +2300,7 @@ export type EntitySchemasUpdateData = {
 				unique?: boolean;
 				file?: KnowledgeFileFieldEntry;
 				mediaVisibility?: KnowledgeFileVisibility;
+				relation?: KnowledgeRelationFieldEntry;
 			};
 		};
 		fqn?: string;
@@ -2302,7 +2323,6 @@ export type EntitySchemasUpdateData = {
 		name?: string;
 		overviewInputMaxChars?: number | null;
 		persistFullFieldContributions?: boolean;
-		relationFields?: Array<EntityRelationField>;
 		richEnrichment?: boolean | null;
 		usableAsDocumentScope?: boolean;
 	};
@@ -2421,6 +2441,7 @@ export type EntitySchemasCreateData = {
 				unique?: boolean;
 				file?: KnowledgeFileFieldEntry;
 				mediaVisibility?: KnowledgeFileVisibility;
+				relation?: KnowledgeRelationFieldEntry;
 			};
 		};
 		fqn: string;
@@ -2437,7 +2458,6 @@ export type EntitySchemasCreateData = {
 		name: string;
 		overviewInputMaxChars?: number | null;
 		persistFullFieldContributions?: boolean;
-		relationFields?: Array<EntityRelationField>;
 		richEnrichment?: boolean | null;
 		usableAsDocumentScope?: boolean;
 	};
@@ -5302,6 +5322,85 @@ declare const createAdministrationApi: (client: Client$1) => {
 					op: "transform";
 					remote: string;
 					transformerId: string;
+				} | {
+					direction: "both" | "inbound" | "outbound";
+					local: string;
+					skipIfNull: boolean;
+					op: "reference";
+					remote: string;
+					target?: string;
+				} | {
+					direction: "both" | "inbound" | "outbound";
+					local: string;
+					skipIfNull: boolean;
+					fieldMap: Array<{
+						direction: "both" | "inbound" | "outbound";
+						local: string;
+						skipIfNull: boolean;
+						op: "path";
+						remote: string;
+					} | {
+						direction: "both" | "inbound" | "outbound";
+						local: string;
+						skipIfNull: boolean;
+						falseValues?: Array<string>;
+						op: "cast";
+						remote: string;
+						trueValues?: Array<string>;
+					} | {
+						direction: "both" | "inbound" | "outbound";
+						local: string;
+						skipIfNull: boolean;
+						op: "default";
+						remote?: string;
+						value: unknown;
+					} | {
+						direction: "both" | "inbound" | "outbound";
+						local: string;
+						skipIfNull: boolean;
+						op: "concat";
+						remote: Array<string>;
+						separator?: string;
+					} | {
+						direction: "both" | "inbound" | "outbound";
+						local: string;
+						skipIfNull: boolean;
+						discardEmpty?: boolean;
+						op: "split";
+						remote: string;
+						separators?: Array<string>;
+						trimItems?: boolean;
+						uniqueItems?: boolean;
+					} | {
+						direction: "both" | "inbound" | "outbound";
+						local: string;
+						skipIfNull: boolean;
+						latitudeKey?: string;
+						longitudeKey?: string;
+						op: "coordinates";
+						remote: [
+							string,
+							string
+						];
+					} | {
+						direction: "both" | "inbound" | "outbound";
+						local: string;
+						skipIfNull: boolean;
+						op: "transform";
+						remote: string;
+						transformerId: string;
+					} | {
+						direction: "both" | "inbound" | "outbound";
+						local: string;
+						skipIfNull: boolean;
+						op: "reference";
+						remote: string;
+						target?: string;
+					}>;
+					op: "embedded";
+					remote: string;
+					remoteId: string;
+					target?: string;
 				}>;
 				fqn: string;
 				outboundStrategy?: "local_first" | "remote_first";
@@ -5403,6 +5502,85 @@ declare const createAdministrationApi: (client: Client$1) => {
 					op: "transform";
 					remote: string;
 					transformerId: string;
+				} | {
+					direction: "both" | "inbound" | "outbound";
+					local: string;
+					skipIfNull: boolean;
+					op: "reference";
+					remote: string;
+					target?: string;
+				} | {
+					direction: "both" | "inbound" | "outbound";
+					local: string;
+					skipIfNull: boolean;
+					fieldMap: Array<{
+						direction: "both" | "inbound" | "outbound";
+						local: string;
+						skipIfNull: boolean;
+						op: "path";
+						remote: string;
+					} | {
+						direction: "both" | "inbound" | "outbound";
+						local: string;
+						skipIfNull: boolean;
+						falseValues?: Array<string>;
+						op: "cast";
+						remote: string;
+						trueValues?: Array<string>;
+					} | {
+						direction: "both" | "inbound" | "outbound";
+						local: string;
+						skipIfNull: boolean;
+						op: "default";
+						remote?: string;
+						value: unknown;
+					} | {
+						direction: "both" | "inbound" | "outbound";
+						local: string;
+						skipIfNull: boolean;
+						op: "concat";
+						remote: Array<string>;
+						separator?: string;
+					} | {
+						direction: "both" | "inbound" | "outbound";
+						local: string;
+						skipIfNull: boolean;
+						discardEmpty?: boolean;
+						op: "split";
+						remote: string;
+						separators?: Array<string>;
+						trimItems?: boolean;
+						uniqueItems?: boolean;
+					} | {
+						direction: "both" | "inbound" | "outbound";
+						local: string;
+						skipIfNull: boolean;
+						latitudeKey?: string;
+						longitudeKey?: string;
+						op: "coordinates";
+						remote: [
+							string,
+							string
+						];
+					} | {
+						direction: "both" | "inbound" | "outbound";
+						local: string;
+						skipIfNull: boolean;
+						op: "transform";
+						remote: string;
+						transformerId: string;
+					} | {
+						direction: "both" | "inbound" | "outbound";
+						local: string;
+						skipIfNull: boolean;
+						op: "reference";
+						remote: string;
+						target?: string;
+					}>;
+					op: "embedded";
+					remote: string;
+					remoteId: string;
+					target?: string;
 				}>;
 				fqn: string;
 				outboundStrategy?: "local_first" | "remote_first";
@@ -5771,6 +5949,85 @@ declare const createAdministrationApi: (client: Client$1) => {
 						op: "transform";
 						remote: string;
 						transformerId: string;
+					} | {
+						direction: "both" | "inbound" | "outbound";
+						local: string;
+						skipIfNull: boolean;
+						op: "reference";
+						remote: string;
+						target?: string;
+					} | {
+						direction: "both" | "inbound" | "outbound";
+						local: string;
+						skipIfNull: boolean;
+						fieldMap: Array<{
+							direction: "both" | "inbound" | "outbound";
+							local: string;
+							skipIfNull: boolean;
+							op: "path";
+							remote: string;
+						} | {
+							direction: "both" | "inbound" | "outbound";
+							local: string;
+							skipIfNull: boolean;
+							falseValues?: Array<string>;
+							op: "cast";
+							remote: string;
+							trueValues?: Array<string>;
+						} | {
+							direction: "both" | "inbound" | "outbound";
+							local: string;
+							skipIfNull: boolean;
+							op: "default";
+							remote?: string;
+							value: unknown;
+						} | {
+							direction: "both" | "inbound" | "outbound";
+							local: string;
+							skipIfNull: boolean;
+							op: "concat";
+							remote: Array<string>;
+							separator?: string;
+						} | {
+							direction: "both" | "inbound" | "outbound";
+							local: string;
+							skipIfNull: boolean;
+							discardEmpty?: boolean;
+							op: "split";
+							remote: string;
+							separators?: Array<string>;
+							trimItems?: boolean;
+							uniqueItems?: boolean;
+						} | {
+							direction: "both" | "inbound" | "outbound";
+							local: string;
+							skipIfNull: boolean;
+							latitudeKey?: string;
+							longitudeKey?: string;
+							op: "coordinates";
+							remote: [
+								string,
+								string
+							];
+						} | {
+							direction: "both" | "inbound" | "outbound";
+							local: string;
+							skipIfNull: boolean;
+							op: "transform";
+							remote: string;
+							transformerId: string;
+						} | {
+							direction: "both" | "inbound" | "outbound";
+							local: string;
+							skipIfNull: boolean;
+							op: "reference";
+							remote: string;
+							target?: string;
+						}>;
+						op: "embedded";
+						remote: string;
+						remoteId: string;
+						target?: string;
 					}>;
 					fqn: string;
 					outboundStrategy?: "local_first" | "remote_first";
@@ -5872,6 +6129,85 @@ declare const createAdministrationApi: (client: Client$1) => {
 						op: "transform";
 						remote: string;
 						transformerId: string;
+					} | {
+						direction: "both" | "inbound" | "outbound";
+						local: string;
+						skipIfNull: boolean;
+						op: "reference";
+						remote: string;
+						target?: string;
+					} | {
+						direction: "both" | "inbound" | "outbound";
+						local: string;
+						skipIfNull: boolean;
+						fieldMap: Array<{
+							direction: "both" | "inbound" | "outbound";
+							local: string;
+							skipIfNull: boolean;
+							op: "path";
+							remote: string;
+						} | {
+							direction: "both" | "inbound" | "outbound";
+							local: string;
+							skipIfNull: boolean;
+							falseValues?: Array<string>;
+							op: "cast";
+							remote: string;
+							trueValues?: Array<string>;
+						} | {
+							direction: "both" | "inbound" | "outbound";
+							local: string;
+							skipIfNull: boolean;
+							op: "default";
+							remote?: string;
+							value: unknown;
+						} | {
+							direction: "both" | "inbound" | "outbound";
+							local: string;
+							skipIfNull: boolean;
+							op: "concat";
+							remote: Array<string>;
+							separator?: string;
+						} | {
+							direction: "both" | "inbound" | "outbound";
+							local: string;
+							skipIfNull: boolean;
+							discardEmpty?: boolean;
+							op: "split";
+							remote: string;
+							separators?: Array<string>;
+							trimItems?: boolean;
+							uniqueItems?: boolean;
+						} | {
+							direction: "both" | "inbound" | "outbound";
+							local: string;
+							skipIfNull: boolean;
+							latitudeKey?: string;
+							longitudeKey?: string;
+							op: "coordinates";
+							remote: [
+								string,
+								string
+							];
+						} | {
+							direction: "both" | "inbound" | "outbound";
+							local: string;
+							skipIfNull: boolean;
+							op: "transform";
+							remote: string;
+							transformerId: string;
+						} | {
+							direction: "both" | "inbound" | "outbound";
+							local: string;
+							skipIfNull: boolean;
+							op: "reference";
+							remote: string;
+							target?: string;
+						}>;
+						op: "embedded";
+						remote: string;
+						remoteId: string;
+						target?: string;
 					}>;
 					fqn: string;
 					outboundStrategy?: "local_first" | "remote_first";
@@ -6413,6 +6749,7 @@ declare const createAdministrationApi: (client: Client$1) => {
 					unique?: boolean;
 					file?: KnowledgeFileFieldEntry;
 					mediaVisibility?: KnowledgeFileVisibility;
+					relation?: KnowledgeRelationFieldEntry;
 				};
 			};
 			fqn: string;
@@ -6431,7 +6768,6 @@ declare const createAdministrationApi: (client: Client$1) => {
 			name: string;
 			overviewInputMaxChars: number | null;
 			persistFullFieldContributions: boolean;
-			relationFields: Array<EntityRelationField>;
 			removedFields: Array<unknown>;
 			richEnrichment: boolean | null;
 			updatedAt: string | null;
@@ -6654,6 +6990,7 @@ declare const createAdministrationApi: (client: Client$1) => {
 					unique?: boolean;
 					file?: KnowledgeFileFieldEntry;
 					mediaVisibility?: KnowledgeFileVisibility;
+					relation?: KnowledgeRelationFieldEntry;
 				};
 			};
 			fqn: string;
@@ -6672,7 +7009,6 @@ declare const createAdministrationApi: (client: Client$1) => {
 			name: string;
 			overviewInputMaxChars: number | null;
 			persistFullFieldContributions: boolean;
-			relationFields: Array<EntityRelationField>;
 			removedFields: Array<unknown>;
 			richEnrichment: boolean | null;
 			updatedAt: string | null;
@@ -6890,6 +7226,7 @@ declare const createAdministrationApi: (client: Client$1) => {
 						unique?: boolean;
 						file?: KnowledgeFileFieldEntry;
 						mediaVisibility?: KnowledgeFileVisibility;
+						relation?: KnowledgeRelationFieldEntry;
 					};
 				};
 				fqn: string;
@@ -6908,7 +7245,6 @@ declare const createAdministrationApi: (client: Client$1) => {
 				name: string;
 				overviewInputMaxChars: number | null;
 				persistFullFieldContributions: boolean;
-				relationFields: Array<EntityRelationField>;
 				removedFields: Array<unknown>;
 				richEnrichment: boolean | null;
 				updatedAt: string | null;

package/dist/express.d.ts

@@ -426,13 +426,21 @@ export type ResourceDefinition<Entity, Create = Entity, Update = Partial<Entity>
 	}>;
 }>;
 export 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.
+ */
 export 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";
@@ -455,6 +463,11 @@ export type ResourcePagination = Readonly<{
 }>;
 export 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[];

package/dist/gateway/contracts.d.ts

@@ -393,13 +393,21 @@ export type ResourceDefinition<Entity, Create = Entity, Update = Partial<Entity>
 	}>;
 }>;
 export 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.
+ */
 export 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";
@@ -422,6 +430,11 @@ export type ResourcePagination = Readonly<{
 }>;
 export 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[];

package/dist/gateway.d.ts

@@ -434,13 +434,21 @@ export type ResourceDefinition<Entity, Create = Entity, Update = Partial<Entity>
 	}>;
 }>;
 export 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.
+ */
 export 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";
@@ -463,6 +471,11 @@ export type ResourcePagination = Readonly<{
 }>;
 export 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[];