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

package/dist/index.d.ts

@@ -25,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;
 		};
 	};
@@ -36,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;
 		};
 	};
@@ -47,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;
 		};
 	};
@@ -58,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;
 		};
 	} | {
@@ -65,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;
 		};
 	};
@@ -76,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;
 		};
 	};
@@ -87,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;
 		};
 	};
@@ -98,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;
@@ -187,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";
 } | {
@@ -388,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;
@@ -406,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<{
@@ -446,34 +560,6 @@ interface DurableFileUpload {
 export type ExternalApplicationServiceOperationRequest = {
 	input: DurableFileUpload;
 	operationId: "files_upload";
-} | {
-	input: {
-		email: string;
-		name: 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";
 } | {
 	input: {
 		origin: string;
@@ -497,10 +583,6 @@ 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>;
@@ -672,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;
 }
@@ -682,7 +766,7 @@ 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<{
@@ -838,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
@@ -882,6 +951,11 @@ export interface ServerClient {
 	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>;
@@ -892,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<{
@@ -964,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,