@collective-intelligence/external-apps-server-sdk 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,597 @@
+// Generated by dts-bundle-generator v9.5.1
+
+export type ResourceJsonValue = null | boolean | number | string | readonly ResourceJsonValue[] | Readonly<{
+	[key: string]: ResourceJsonValue;
+}>;
+export type ExternalApplicationsGetContextErrors = {
+	/**
+	 * Error
+	 */
+	400: {
+		correlationId: string;
+		error: {
+			code: "invalid_request";
+			message: string;
+			retryable: false;
+		};
+	};
+	/**
+	 * Error
+	 */
+	401: {
+		correlationId: string;
+		error: {
+			code: "authentication_required";
+			message: string;
+			retryable: false;
+		};
+	};
+	/**
+	 * Error
+	 */
+	403: {
+		correlationId: string;
+		error: {
+			code: "authorization_denied";
+			message: string;
+			retryable: false;
+		};
+	};
+	/**
+	 * Error
+	 */
+	404: {
+		correlationId: string;
+		error: {
+			code: "operation_not_allowed";
+			message: string;
+			retryable: false;
+		};
+	} | {
+		correlationId: string;
+		error: {
+			code: "not_found";
+			message: string;
+			retryable: false;
+		};
+	};
+	/**
+	 * Error
+	 */
+	409: {
+		correlationId: string;
+		error: {
+			code: "conflict";
+			message: string;
+			retryable: false;
+		};
+	};
+	/**
+	 * Error
+	 */
+	500: {
+		correlationId: string;
+		error: {
+			code: "internal_error";
+			message: string;
+			retryable: false;
+		};
+	};
+	/**
+	 * Error
+	 */
+	503: {
+		correlationId: string;
+		error: {
+			code: "temporarily_unavailable";
+			message: string;
+			retryable: true;
+		};
+	};
+};
+export type ExternalApplicationsGetContextError = ExternalApplicationsGetContextErrors[keyof ExternalApplicationsGetContextErrors];
+export type JsonValue = boolean | null | number | readonly JsonValue[] | Readonly<{
+	readonly [key: string]: JsonValue;
+}> | string;
+export type JsonObject = Readonly<Record<string, JsonValue>>;
+export type WorkflowInvokeTarget = {
+	workflowId: string;
+	workflowFqn?: never;
+} | {
+	workflowFqn: string;
+	workflowId?: never;
+};
+/** Addresses an Agent by its UUID or its in-organization FQN. */
+export type AgentInvokeTarget = {
+	agentId: string;
+	agentFqn?: never;
+} | {
+	agentFqn: string;
+	agentId?: never;
+};
+/** Starts a conversation with an Agent, or continues an existing one. */
+export type ConversationContinueTarget = (AgentInvokeTarget & {
+	conversationId?: never;
+}) | {
+	agentFqn?: never;
+	agentId?: never;
+	conversationId: string;
+};
+export type ConversationTurnStatus = "accepted" | "cancelled" | "failed" | "running" | "succeeded";
+/**
+ * One conversation turn: the application's input, the Agent's final message
+ * once its run succeeded, and the Agent Output the run saved, if any.
+ * `runId` identifies the turn and its producing run.
+ */
+export interface ConversationTurn {
+	completedAt: string | null;
+	createdAt: string;
+	input: unknown;
+	message: string | null;
+	output?: unknown;
+	runId: string;
+	status: ConversationTurnStatus;
+}
+export interface ConversationHistory {
+	agentId: string;
+	conversationId: string;
+	createdAt: string;
+	turns: ConversationTurn[];
+}
+export interface QueryFilter {
+	caseSensitive?: boolean;
+	field: string;
+	op: "eq" | "neq" | "in" | "contains" | "gt" | "gte" | "lt" | "lte" | "exists";
+	value?: unknown;
+}
+export interface SearchQuery {
+	cursor?: string;
+	entitySchemaId: string;
+	fields?: string[];
+	filters?: QueryFilter[];
+	limit?: number;
+	text?: string;
+}
+export type KnowledgeQuery = {
+	entityId: string;
+	op: "get";
+} | {
+	anchorEntityId: string;
+	filters?: QueryFilter[];
+	limit?: number;
+	op: "related";
+	relationSchemaId: string;
+	text?: string;
+} | (SearchQuery & {
+	op: "search";
+}) | {
+	entitySchemaId: string;
+	fields: string[];
+	filters?: QueryFilter[];
+	op: "facets";
+	text?: string;
+} | (SearchQuery & {
+	op: "autocomplete";
+});
+export type ExternalApplicationOperationRequest = {
+	input: JsonObject | unknown[];
+	operationId: "context_get";
+} | {
+	input: {
+		query: KnowledgeQuery;
+	};
+	operationId: "knowledge_query";
+} | {
+	input: {
+		schemaId: string;
+	};
+	operationId: "knowledge_get_entity_schema_snapshot";
+} | {
+	input: SearchQuery;
+	operationId: "knowledge_search_entities";
+} | {
+	input: {
+		entitySchemaId: string;
+		fields: string[];
+		filters?: QueryFilter[];
+		text?: string;
+	};
+	operationId: "knowledge_facets";
+} | {
+	input: {
+		entitySchemaId: string;
+	};
+	operationId: "knowledge_get_schema_query_context";
+} | {
+	input: SearchQuery;
+	operationId: "knowledge_autocomplete";
+} | {
+	input: {
+		entityId: string;
+	};
+	operationId: "knowledge_get_entity";
+} | {
+	input: {
+		entity: {
+			data: JsonObject;
+			description?: string;
+			entitySchemaId: string;
+			name: string;
+		};
+		idempotencyKey: string;
+	};
+	operationId: "knowledge_create_entity";
+} | {
+	input: {
+		entity: {
+			data?: JsonObject;
+			description?: string;
+			name?: string;
+		};
+		entityId: string;
+		expectedVersion: number;
+		idempotencyKey: string;
+	};
+	operationId: "knowledge_update_entity";
+} | {
+	input: {
+		entity: {
+			data: JsonObject;
+			description?: string;
+			entitySchemaId: string;
+			name: string;
+		};
+		entitySchemaId: string;
+		externalIdentity: {
+			source: string;
+			value: string;
+		};
+		idempotencyKey: string;
+	};
+	operationId: "knowledge_upsert_entity";
+} | {
+	input: {
+		entityId: string;
+		expectedVersion: number;
+		idempotencyKey: string;
+	};
+	operationId: "knowledge_delete_entity";
+} | {
+	input: {
+		anchorEntityId: string;
+		direction?: "incoming" | "outgoing" | "both";
+		limit?: number;
+		maxDepth?: number;
+		relationSchemaId?: string;
+	};
+	operationId: "knowledge_traverse";
+} | {
+	input: {
+		idempotencyKey: string;
+		relation: {
+			data?: JsonObject;
+			relationSchemaId: string;
+			sourceId: string;
+			targetId: string;
+		};
+	};
+	operationId: "knowledge_create_relation";
+} | {
+	input: {
+		expectedVersion: number;
+		idempotencyKey: string;
+		relation: {
+			data?: JsonObject;
+		};
+		relationId: string;
+	};
+	operationId: "knowledge_update_relation";
+} | {
+	input: {
+		expectedVersion: number;
+		idempotencyKey: string;
+		relationId: string;
+	};
+	operationId: "knowledge_delete_relation";
+} | {
+	input: {
+		filter?: JsonObject;
+	};
+	operationId: "agents_list";
+} | {
+	input: {
+		idempotencyKey: string;
+		input: unknown;
+	} & AgentInvokeTarget;
+	operationId: "agents_invoke";
+} | {
+	input: {
+		filter?: JsonObject;
+	};
+	operationId: "skills_list";
+} | {
+	input: {
+		idempotencyKey: string;
+		input: unknown;
+		skillId: string;
+	};
+	operationId: "skills_invoke";
+} | {
+	input: {
+		filter?: JsonObject;
+	};
+	operationId: "workflows_list";
+} | {
+	input: {
+		idempotencyKey: string;
+		input: unknown;
+	} & WorkflowInvokeTarget;
+	operationId: "workflows_invoke";
+} | {
+	input: {
+		runId: string;
+	};
+	operationId: "runs_get";
+} | {
+	input: {
+		afterCursor?: string;
+		runId: string;
+	};
+	operationId: "runs_stream";
+} | {
+	input: {
+		runId: string;
+	};
+	operationId: "runs_cancel";
+} | {
+	input: {
+		contentBase64: string;
+		contentType: string;
+		fileName: string;
+		runId: string;
+		sizeBytes: number;
+	};
+	operationId: "attachments_upload";
+} | {
+	input: {
+		attachmentId: string;
+		runId: string;
+	};
+	operationId: "attachments_download_url";
+} | {
+	input: {
+		idempotencyKey: string;
+		input: unknown;
+	} & ConversationContinueTarget;
+	operationId: "conversations_continue";
+} | {
+	input: {
+		conversationId: string;
+	};
+	operationId: "conversations_history";
+};
+export interface EnvelopeSuccess<Id extends string, Result> {
+	correlationId: string;
+	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", {
+	runId: string;
+}> | EnvelopeSuccess<"skills_list", JsonObject> | EnvelopeSuccess<"skills_invoke", {
+	runId: string;
+}> | EnvelopeSuccess<"workflows_list", JsonObject> | EnvelopeSuccess<"workflows_invoke", {
+	runId: string;
+}> | EnvelopeSuccess<"runs_get", JsonObject> | EnvelopeSuccess<"runs_stream", {
+	events: JsonObject[];
+	nextCursor: string | null;
+}> | EnvelopeSuccess<"runs_cancel", JsonObject> | EnvelopeSuccess<"attachments_upload", {
+	attachmentId: string;
+}> | EnvelopeSuccess<"attachments_download_url", {
+	expiresAt: string;
+	url: string;
+}> | EnvelopeSuccess<"conversations_continue", {
+	conversationId: string;
+	runId: string;
+}> | EnvelopeSuccess<"conversations_history", ConversationHistory>;
+export type ExternalApplicationOperationFailure = ExternalApplicationsGetContextError;
+export type ExternalApplicationOperationId = ExternalApplicationOperationRequest["operationId"];
+export type ExternalApplicationOperationRequestFor<Id extends ExternalApplicationOperationId> = Extract<ExternalApplicationOperationRequest, {
+	operationId: Id;
+}>;
+export type ExternalApplicationOperationSuccessFor<Id extends ExternalApplicationOperationId> = Extract<ExternalApplicationOperationSuccess, {
+	operationId: Id;
+}>;
+export type ExternalApplicationOperationResult<Id extends ExternalApplicationOperationId> = Readonly<{
+	error: ExternalApplicationOperationFailure;
+	ok: false;
+}> | Readonly<{
+	ok: true;
+	value: ExternalApplicationOperationSuccessFor<Id>;
+}>;
+export interface ExternalApplicationExternalAuditSubject {
+	readonly issuer: string;
+	readonly mappedUserId?: string;
+	readonly subjectId: string;
+}
+export interface ConfidentialCredentials {
+	readonly clientId: string;
+	readonly clientSecret: string;
+}
+export interface RotatingConfidentialCredentialProvider {
+	readonly getCredentials: () => ConfidentialCredentials | Promise<ConfidentialCredentials>;
+}
+export type ConfidentialCredentialProvider = ConfidentialCredentials | RotatingConfidentialCredentialProvider;
+export interface ServerRetryPolicy {
+	readonly baseDelayMs?: number;
+	readonly maxAttempts?: number;
+	readonly maxDelayMs?: number;
+}
+export type DelegatedServerAuthentication = Readonly<{
+	getAccessToken: () => Promise<string> | string;
+	mode?: "delegated";
+}>;
+export type ServiceServerAuthentication = Readonly<{
+	credentials: ConfidentialCredentialProvider;
+	mode: "service";
+}>;
+export type ServerClientAuthentication = DelegatedServerAuthentication | ServiceServerAuthentication;
+export interface ServerClientConfig {
+	readonly auditSubject?: ExternalApplicationExternalAuditSubject;
+	readonly authentication: ServerClientAuthentication;
+	readonly createCorrelationId?: () => string;
+	readonly createIdempotencyKey?: () => string;
+	readonly fetch?: typeof globalThis.fetch;
+	readonly retry?: ServerRetryPolicy;
+	readonly sleep?: (milliseconds: number) => Promise<void>;
+	readonly tenantUrl: string;
+}
+export interface ServerInvocationContext {
+	readonly auditSubject?: ExternalApplicationExternalAuditSubject;
+	/**
+	 * `anonymous_visitor`: this service call is made for the anonymous visitor
+	 * `auditSubject` names, who must not map to a CI user. The visitor may only
+	 * converse with Agents that admit anonymous visitors of this application.
+	 */
+	readonly callerKind?: "anonymous_visitor";
+	readonly correlationId?: string;
+	readonly organizationId: string;
+	readonly signal?: AbortSignal;
+	readonly traceparent?: string;
+}
+export type OperationInput<Id extends ExternalApplicationOperationId> = ExternalApplicationOperationRequestFor<Id>["input"];
+export type ManagedInput<Input> = Input extends {
+	idempotencyKey: string;
+} ? Omit<Input, "idempotencyKey"> & {
+	readonly idempotencyKey?: string;
+} : Input;
+export type ManagedOperationInput<Id extends ExternalApplicationOperationId> = ManagedInput<OperationInput<Id>>;
+export type ServerOperationRequest<Id extends ExternalApplicationOperationId> = ManagedOperationInput<Id> & ServerInvocationContext;
+export type ServerOperationMethod<Id extends ExternalApplicationOperationId> = (request: ServerOperationRequest<Id>) => Promise<ExternalApplicationOperationResult<Id>>;
+export type RunOperationId = "runs_cancel" | "runs_get" | "runs_stream";
+export type ServerRunStatus = "accepted" | "cancelled" | "failed" | "running" | "succeeded";
+/**
+ * A succeeded Agent run's result: the normal final assistant `message` and,
+ * when the run saved one, its schema-valid structured Agent `output`.
+ */
+export type ServerAgentRunResult = Readonly<{
+	message: string;
+	output?: ResourceJsonValue;
+}>;
+/**
+ * Snapshot of one external run. `result` is set once the run finishes: a
+ * succeeded Agent run carries a `ServerAgentRunResult`, a failed one
+ * `{ nativeStatus, reason }`.
+ */
+export type ServerRun = Readonly<{
+	cancelRequested: boolean;
+	completedAt: string | null;
+	createdAt: string;
+	result: ResourceJsonValue;
+	runId: string;
+	status: ServerRunStatus;
+	updatedAt: string;
+}>;
+/**
+ * One run event. `accepted`, `completed`, `failed` and `cancelled` are
+ * lifecycle kinds; namespaced kinds such as `app.update` are application
+ * events published by the invoked Agent.
+ */
+export type ServerRunEvent = Readonly<{
+	createdAt: string;
+	cursor: string;
+	data: Readonly<Record<string, ResourceJsonValue>>;
+	kind: string;
+}>;
+export type ServerRunEventPage = Readonly<{
+	events: readonly ServerRunEvent[];
+	nextCursor: string | null;
+}>;
+/**
+ * A conversation's turns, oldest first. Each turn has the Agent's final
+ * `message` once its run succeeded and, when the run saved one, its Agent
+ * `output`.
+ */
+export type ServerConversationHistory = Extract<ExternalApplicationOperationResult<"conversations_history">, {
+	ok: true;
+}>["value"]["result"];
+export type ServerConversationTurn = ServerConversationHistory["turns"][number];
+export type RunOperationSuccess<Id extends RunOperationId> = Extract<ExternalApplicationOperationResult<Id>, {
+	ok: true;
+}>["value"];
+export type ServerRunOperationResult<Id extends RunOperationId, Result> = Extract<ExternalApplicationOperationResult<Id>, {
+	ok: false;
+}> | Readonly<{
+	ok: true;
+	value: Omit<RunOperationSuccess<Id>, "result"> & Readonly<{
+		result: Result;
+	}>;
+}>;
+export type ServerRunOperationMethod<Id extends RunOperationId, Result> = (request: ServerOperationRequest<Id>) => Promise<ServerRunOperationResult<Id, Result>>;
+export interface ServerClient {
+	readonly agents: Readonly<{
+		/** Starts an Agent run addressed by `agentId` or by its Organization `agentFqn`. */
+		invoke: ServerOperationMethod<"agents_invoke">;
+		list: ServerOperationMethod<"agents_list">;
+	}>;
+	readonly attachments: Readonly<{
+		downloadUrl: ServerOperationMethod<"attachments_download_url">;
+		upload: ServerOperationMethod<"attachments_upload">;
+	}>;
+	readonly context: Readonly<{
+		get: ServerOperationMethod<"context_get">;
+	}>;
+	/**
+	 * Multi-turn Agent conversations scoped to the caller's Audit subject.
+	 * `continue({ agentId | agentFqn, input })` starts one; `continue({ conversationId, input })`
+	 * adds a turn whose run sees the earlier turns. Both return `{ conversationId, runId }`.
+	 */
+	readonly conversations: Readonly<{
+		continue: ServerOperationMethod<"conversations_continue">;
+		history: ServerOperationMethod<"conversations_history">;
+	}>;
+	readonly knowledge: Readonly<{
+		autocomplete: ServerOperationMethod<"knowledge_autocomplete">;
+		createEntity: ServerOperationMethod<"knowledge_create_entity">;
+		createRelation: ServerOperationMethod<"knowledge_create_relation">;
+		deleteEntity: ServerOperationMethod<"knowledge_delete_entity">;
+		deleteRelation: ServerOperationMethod<"knowledge_delete_relation">;
+		facets: ServerOperationMethod<"knowledge_facets">;
+		getEntity: ServerOperationMethod<"knowledge_get_entity">;
+		getEntitySchemaSnapshot: ServerOperationMethod<"knowledge_get_entity_schema_snapshot">;
+		getSchemaQueryContext: ServerOperationMethod<"knowledge_get_schema_query_context">;
+		query: ServerOperationMethod<"knowledge_query">;
+		searchEntities: ServerOperationMethod<"knowledge_search_entities">;
+		traverse: ServerOperationMethod<"knowledge_traverse">;
+		updateEntity: ServerOperationMethod<"knowledge_update_entity">;
+		updateRelation: ServerOperationMethod<"knowledge_update_relation">;
+		upsertEntity: ServerOperationMethod<"knowledge_upsert_entity">;
+	}>;
+	readonly runs: Readonly<{
+		cancel: ServerRunOperationMethod<"runs_cancel", ServerRun>;
+		get: ServerRunOperationMethod<"runs_get", ServerRun>;
+		stream: ServerRunOperationMethod<"runs_stream", ServerRunEventPage>;
+	}>;
+	readonly skills: Readonly<{
+		invoke: ServerOperationMethod<"skills_invoke">;
+		list: ServerOperationMethod<"skills_list">;
+	}>;
+	readonly workflows: Readonly<{
+		invoke: ServerOperationMethod<"workflows_invoke">;
+		list: ServerOperationMethod<"workflows_list">;
+	}>;
+}
+export type RunAsApplicationConfig = Readonly<{
+	auditSubject: ExternalApplicationExternalAuditSubject;
+	credentials: ConfidentialCredentials;
+	createCorrelationId?: () => string;
+	createIdempotencyKey?: () => string;
+	fetch?: typeof globalThis.fetch;
+	retry?: ServerRetryPolicy;
+	sleep?: (milliseconds: number) => Promise<void>;
+	tenantUrl: string;
+}>;
+export declare const createServerClient: (config: ServerClientConfig) => ServerClient, serverSdkRuntime: "node";
+export declare const runAsApplication: (config: RunAsApplicationConfig) => ServerClient;
+export declare const uuidV7: () => string;
+
+export {};