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

package/dist/index.d.ts

@@ -3,6 +3,19 @@
 export type ResourceJsonValue = null | boolean | number | string | readonly ResourceJsonValue[] | Readonly<{
 	[key: string]: ResourceJsonValue;
 }>;
+/** A File upload request for one File field of the entity schema. */
+export type EntityUploadInput = Readonly<{
+	field: string;
+	filename: string;
+	mimeType: string;
+}>;
+/** PUT the file bytes to `url` with `headers`; then write `{ upload: uploadId }`. */
+export type EntityUploadSlot = Readonly<{
+	headers: Readonly<Record<string, string>>;
+	method: "PUT";
+	uploadId: string;
+	url: string;
+}>;
 export type ExternalApplicationsGetContextErrors = {
 	/**
 	 * Error
@@ -12,6 +25,7 @@ export type ExternalApplicationsGetContextErrors = {
 		error: {
 			code: "invalid_request";
 			message: string;
+			reason?: "users_create_forbidden" | "role_not_assignable" | "user_unavailable" | "target_inactive" | "user_not_found" | "user_not_created_by_app" | "application_unavailable" | "actor_not_allowed";
 			retryable: false;
 		};
 	};
@@ -23,6 +37,7 @@ export type ExternalApplicationsGetContextErrors = {
 		error: {
 			code: "authentication_required";
 			message: string;
+			reason?: "users_create_forbidden" | "role_not_assignable" | "user_unavailable" | "target_inactive" | "user_not_found" | "user_not_created_by_app" | "application_unavailable" | "actor_not_allowed";
 			retryable: false;
 		};
 	};
@@ -34,6 +49,7 @@ export type ExternalApplicationsGetContextErrors = {
 		error: {
 			code: "authorization_denied";
 			message: string;
+			reason?: "users_create_forbidden" | "role_not_assignable" | "user_unavailable" | "target_inactive" | "user_not_found" | "user_not_created_by_app" | "application_unavailable" | "actor_not_allowed";
 			retryable: false;
 		};
 	};
@@ -45,6 +61,7 @@ export type ExternalApplicationsGetContextErrors = {
 		error: {
 			code: "operation_not_allowed";
 			message: string;
+			reason?: "users_create_forbidden" | "role_not_assignable" | "user_unavailable" | "target_inactive" | "user_not_found" | "user_not_created_by_app" | "application_unavailable" | "actor_not_allowed";
 			retryable: false;
 		};
 	} | {
@@ -52,6 +69,7 @@ export type ExternalApplicationsGetContextErrors = {
 		error: {
 			code: "not_found";
 			message: string;
+			reason?: "users_create_forbidden" | "role_not_assignable" | "user_unavailable" | "target_inactive" | "user_not_found" | "user_not_created_by_app" | "application_unavailable" | "actor_not_allowed";
 			retryable: false;
 		};
 	};
@@ -63,6 +81,7 @@ export type ExternalApplicationsGetContextErrors = {
 		error: {
 			code: "conflict";
 			message: string;
+			reason?: "users_create_forbidden" | "role_not_assignable" | "user_unavailable" | "target_inactive" | "user_not_found" | "user_not_created_by_app" | "application_unavailable" | "actor_not_allowed";
 			retryable: false;
 		};
 	};
@@ -74,6 +93,7 @@ export type ExternalApplicationsGetContextErrors = {
 		error: {
 			code: "internal_error";
 			message: string;
+			reason?: "users_create_forbidden" | "role_not_assignable" | "user_unavailable" | "target_inactive" | "user_not_found" | "user_not_created_by_app" | "application_unavailable" | "actor_not_allowed";
 			retryable: false;
 		};
 	};
@@ -85,11 +105,93 @@ export type ExternalApplicationsGetContextErrors = {
 		error: {
 			code: "temporarily_unavailable";
 			message: string;
+			reason?: "users_create_forbidden" | "role_not_assignable" | "user_unavailable" | "target_inactive" | "user_not_found" | "user_not_created_by_app" | "application_unavailable" | "actor_not_allowed";
 			retryable: true;
 		};
 	};
 };
 export type ExternalApplicationsGetContextError = ExternalApplicationsGetContextErrors[keyof ExternalApplicationsGetContextErrors];
+export type ExternalApplicationsListAppUsersResponses = {
+	/**
+	 * Success
+	 */
+	200: {
+		correlationId: string;
+		result: {
+			items: Array<{
+				email: string | null;
+				name: string | null;
+				userId: string;
+			}>;
+		};
+	};
+};
+export type ExternalApplicationsListAppUsersResponse = ExternalApplicationsListAppUsersResponses[keyof ExternalApplicationsListAppUsersResponses];
+export 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";
+};
+export type ExternalApplicationsCreateOrGetAppUserResponses = {
+	/**
+	 * Success
+	 */
+	200: {
+		correlationId: string;
+		result: {
+			email: string | null;
+			name: string | null;
+			userId: string;
+			created: boolean;
+			kind: "member" | "external_app_user";
+		};
+	};
+};
+export type ExternalApplicationsCreateOrGetAppUserResponse = ExternalApplicationsCreateOrGetAppUserResponses[keyof ExternalApplicationsCreateOrGetAppUserResponses];
+export type ExternalApplicationsGetAppUserResponses = {
+	/**
+	 * Success
+	 */
+	200: {
+		correlationId: string;
+		result: {
+			email: string | null;
+			name: string | null;
+			userId: string;
+		};
+	};
+};
+export type ExternalApplicationsGetAppUserResponse = ExternalApplicationsGetAppUserResponses[keyof ExternalApplicationsGetAppUserResponses];
+export type ExternalApplicationsListAppRolesResponses = {
+	/**
+	 * Success
+	 */
+	200: {
+		correlationId: string;
+		result: {
+			items: Array<{
+				id: string;
+				key: string;
+			}>;
+		};
+	};
+};
+export type ExternalApplicationsListAppRolesResponse = ExternalApplicationsListAppRolesResponses[keyof ExternalApplicationsListAppRolesResponses];
 export type JsonValue = boolean | null | number | readonly JsonValue[] | Readonly<{
 	readonly [key: string]: JsonValue;
 }> | string;
@@ -174,6 +276,40 @@ export type KnowledgeQuery = {
 	op: "autocomplete";
 });
 export 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";
 } | {
@@ -375,7 +511,15 @@ export interface EnvelopeSuccess<Id extends string, Result> {
 	operationId: Id;
 	result: Result;
 }
-export 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", {
+export 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;
@@ -393,28 +537,11 @@ export type ExternalApplicationOperationSuccess = EnvelopeSuccess<"context_get",
 	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<{
@@ -435,32 +562,9 @@ export 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;
@@ -479,10 +583,8 @@ export interface UserCompanyLinks {
 }
 export 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. */
 export type ExternalApplicationServerOperationRequest = ExternalApplicationOperationRequest | ExternalApplicationServiceOperationRequest;
@@ -652,6 +754,8 @@ export interface ServerInvocationContext {
 	readonly callerKind?: "anonymous_visitor";
 	readonly correlationId?: string;
 	readonly organizationId: string;
+	/** Selects a Server Role for this call; omission uses the credential default. */
+	readonly serverRole?: string;
 	readonly signal?: AbortSignal;
 	readonly traceparent?: string;
 }
@@ -662,13 +766,52 @@ export type ManagedInput<Input> = Input extends {
 	readonly idempotencyKey?: string;
 } : Input;
 export type ManagedOperationInput<Id extends ExternalApplicationServerOperationId> = ManagedInput<OperationInput<Id>>;
-export type ServerOperationRequest<Id extends ExternalApplicationServerOperationId> = ManagedOperationInput<Id> & ServerInvocationContext;
+export type ServerOperationRequest<Id extends ExternalApplicationServerOperationId> = OperationInput<Id> extends Readonly<Record<string, never>> ? ServerInvocationContext : ManagedOperationInput<Id> & ServerInvocationContext;
 export type ServerOperationMethod<Id extends ExternalApplicationServerOperationId> = (request: ServerOperationRequest<Id>) => Promise<ExternalApplicationOperationResult<Id>>;
 /** One message to send; `idempotencyKey` is generated when omitted. */
 export type ServerMessageSendRequest = Omit<MessageSendInput, "idempotencyKey"> & Readonly<{
 	idempotencyKey?: string;
 }> & ServerInvocationContext;
 export type ServerMessageSendMethod = (request: ServerMessageSendRequest) => Promise<MessageSendResult>;
+/** A File upload slot for one File field of an entity schema, named by id or FQN. */
+export type ServerResourceUploadRequest = EntityUploadInput & Readonly<{
+	schemaId: string;
+	/** Bound on each attempt's request and response body. Defaults to 10 seconds. */
+	timeoutMs?: number;
+}> & ServerInvocationContext;
+declare const resourceFailureCodes: readonly [
+	"conflict",
+	"forbidden",
+	"internal",
+	"invalid_request",
+	"not_found",
+	"unauthenticated",
+	"unavailable",
+	"upload_not_supported"
+];
+/** Why CI's resources API refused the request. */
+export type ServerResourceFailure = Readonly<{
+	correlationId: string;
+	error: Readonly<{
+		code: (typeof resourceFailureCodes)[number];
+		details?: Readonly<Record<string, ResourceJsonValue>>;
+		message: string;
+		retryable: boolean;
+	}>;
+}>;
+/** PUT the bytes to `result.url` with `result.headers`, then write `{ upload: uploadId }`. */
+export type ServerResourceUploadResult = Readonly<{
+	error: ServerResourceFailure;
+	ok: false;
+}> | Readonly<{
+	ok: true;
+	value: Readonly<{
+		correlationId: string;
+		operationId: "resources_create_upload";
+		result: EntityUploadSlot;
+	}>;
+}>;
+export type ServerResourceUploadMethod = (request: ServerResourceUploadRequest) => Promise<ServerResourceUploadResult>;
 export type RunOperationId = "runs_cancel" | "runs_get" | "runs_stream";
 export type ServerRunStatus = "accepted" | "cancelled" | "failed" | "running" | "succeeded";
 /**
@@ -779,21 +922,6 @@ export interface ServerClient {
 		updateRelation: ServerOperationMethod<"knowledge_update_relation">;
 		upsertEntity: ServerOperationMethod<"knowledge_upsert_entity">;
 	}>;
-	/**
-	 * Member users of the application's Organization: people whose only role
-	 * there is `member`. Needs `members:read` (get, list) or `members:write`
-	 * (createOrGet, update, remove) and confidential credentials; a user with
-	 * any other role is refused. `createOrGet` resolves an email to the same
-	 * user on every call and never sends CI's activation invitation. `remove`
-	 * ends the membership and keeps the CI user.
-	 */
-	readonly members: Readonly<{
-		createOrGet: ServerOperationMethod<"members_create_or_get">;
-		get: ServerOperationMethod<"members_get">;
-		list: ServerOperationMethod<"members_list">;
-		remove: ServerOperationMethod<"members_remove">;
-		update: ServerOperationMethod<"members_update">;
-	}>;
 	/**
 	 * Sends one message through a messaging connection that an administrator
 	 * granted to the application. Needs the `messaging:send` scope. A repeat
@@ -803,6 +931,31 @@ export interface ServerClient {
 	readonly messages: Readonly<{
 		send: ServerMessageSendMethod;
 	}>;
+	/**
+	 * The application's browser origins in its Organization. `setRuntime({ origin })`
+	 * replaces the application's one runtime origin, such as the URL of the
+	 * current deployment, beside the `allowedOrigins` its package declares.
+	 * Needs the `origins:write` scope and confidential credentials.
+	 */
+	readonly origins: Readonly<{
+		setRuntime: ServerOperationMethod<"origins_set_runtime">;
+	}>;
+	/**
+	 * CI's resources API. `createUpload` asks a single-use File upload slot for
+	 * one File field of an entity schema; the entity write then names its
+	 * `uploadId` as `{ upload }`. Slots follow entity writes: the member's
+	 * delegated token writes as that member; the service credential writes as
+	 * the Organization default service principal, only on schemas its own
+	 * package declares.
+	 */
+	readonly resources: Readonly<{
+		createUpload: ServerResourceUploadMethod;
+	}>;
+	readonly roles: Readonly<{
+		assign: ServerOperationMethod<"roles_assign">;
+		list: ServerOperationMethod<"roles_list">;
+		revoke: ServerOperationMethod<"roles_revoke">;
+	}>;
 	readonly runs: Readonly<{
 		cancel: ServerRunOperationMethod<"runs_cancel", ServerRun>;
 		get: ServerRunOperationMethod<"runs_get", ServerRun>;
@@ -813,12 +966,17 @@ export interface ServerClient {
 		list: ServerOperationMethod<"skills_list">;
 	}>;
 	/**
-	 * Organization members' links to the company entities they act for.
-	 * Confidential service credentials only; the Organization is the caller's.
+	 * Application users and their role-bounded lifecycle. User tokens and service
+	 * credentials are authorized by CI on each call. Company-link operations
+	 * remain limited to service credentials and Organization members.
 	 */
 	readonly users: Readonly<{
+		createOrGet: ServerOperationMethod<"users_create_or_get">;
+		deactivate: ServerOperationMethod<"users_deactivate">;
+		get: ServerOperationMethod<"users_get">;
 		/** Links `userId` to `entityIds`, keeping existing links; returns all of them. */
 		linkCompanies: ServerOperationMethod<"users_link_companies">;
+		list: ServerOperationMethod<"users_list">;
 		listCompanyLinks: ServerOperationMethod<"users_list_company_links">;
 	}>;
 	readonly workflows: Readonly<{
@@ -885,11 +1043,12 @@ export declare const exchangeMemberSession: (request: MemberSessionExchangeReque
 export declare const uuidV7: () => string;
 
 export {
+	ApplicationRole as ServerApplicationRole,
+	ApplicationUser as ServerApplicationUser,
+	ApplicationUserPage as ServerApplicationUserPage,
+	ApplicationUserResolution as ServerApplicationUserResolution,
 	DurableFileUpload as ServerDurableFileUpload,
 	MemberSessionExchangeError$1 as MemberSessionExchangeError,
-	MemberUser as ServerMemberUser,
-	MemberUserPage as ServerMemberUserPage,
-	MemberUserResolution as ServerMemberUserResolution,
 	MessageContent as ServerMessageContent,
 	MessageReceipt as ServerMessageReceipt,
 	MessageSendErrorCode as ServerMessageSendErrorCode,