@collective-intelligence/external-apps-server-sdk 0.1.0 → 0.1.2

package/dist/index.d.ts

@@ -393,15 +393,88 @@ 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;
+}
+export type ExternalApplicationServiceOperationRequest = {
+	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: {
+		userId: string;
+	};
+	operationId: "users_list_company_links";
+} | {
+	input: {
+		entityIds: string[];
+		userId: string;
+	};
+	operationId: "users_link_companies";
+};
+/** A user's linked company entities, in entity id order. */
+export interface UserCompanyLinks {
+	entityIds: string[];
+}
+export type ExternalApplicationServiceOperationSuccess = 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<"users_list_company_links", UserCompanyLinks> | EnvelopeSuccess<"users_link_companies", UserCompanyLinks>;
+/** Every operation a confidential server client may invoke. */
+export type ExternalApplicationServerOperationRequest = ExternalApplicationOperationRequest | ExternalApplicationServiceOperationRequest;
 export type ExternalApplicationOperationFailure = ExternalApplicationsGetContextError;
-export type ExternalApplicationOperationId = ExternalApplicationOperationRequest["operationId"];
-export type ExternalApplicationOperationRequestFor<Id extends ExternalApplicationOperationId> = Extract<ExternalApplicationOperationRequest, {
+export type ExternalApplicationServerOperationId = ExternalApplicationServerOperationRequest["operationId"];
+export type ExternalApplicationOperationRequestFor<Id extends ExternalApplicationServerOperationId> = Extract<ExternalApplicationServerOperationRequest, {
 	operationId: Id;
 }>;
-export type ExternalApplicationOperationSuccessFor<Id extends ExternalApplicationOperationId> = Extract<ExternalApplicationOperationSuccess, {
+export type ExternalApplicationOperationSuccessFor<Id extends ExternalApplicationServerOperationId> = Extract<ExternalApplicationOperationSuccess | ExternalApplicationServiceOperationSuccess, {
 	operationId: Id;
 }>;
-export type ExternalApplicationOperationResult<Id extends ExternalApplicationOperationId> = Readonly<{
+export type ExternalApplicationOperationResult<Id extends ExternalApplicationServerOperationId> = Readonly<{
 	error: ExternalApplicationOperationFailure;
 	ok: false;
 }> | Readonly<{
@@ -458,15 +531,15 @@ export interface ServerInvocationContext {
 	readonly signal?: AbortSignal;
 	readonly traceparent?: string;
 }
-export type OperationInput<Id extends ExternalApplicationOperationId> = ExternalApplicationOperationRequestFor<Id>["input"];
+export type OperationInput<Id extends ExternalApplicationServerOperationId> = 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 ManagedOperationInput<Id extends ExternalApplicationServerOperationId> = ManagedInput<OperationInput<Id>>;
+export type ServerOperationRequest<Id extends ExternalApplicationServerOperationId> = ManagedOperationInput<Id> & ServerInvocationContext;
+export type ServerOperationMethod<Id extends ExternalApplicationServerOperationId> = (request: ServerOperationRequest<Id>) => Promise<ExternalApplicationOperationResult<Id>>;
 export type RunOperationId = "runs_cancel" | "runs_get" | "runs_stream";
 export type ServerRunStatus = "accepted" | "cancelled" | "failed" | "running" | "succeeded";
 /**
@@ -566,6 +639,21 @@ 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">;
+	}>;
 	readonly runs: Readonly<{
 		cancel: ServerRunOperationMethod<"runs_cancel", ServerRun>;
 		get: ServerRunOperationMethod<"runs_get", ServerRun>;
@@ -575,11 +663,63 @@ export interface ServerClient {
 		invoke: ServerOperationMethod<"skills_invoke">;
 		list: ServerOperationMethod<"skills_list">;
 	}>;
+	/**
+	 * Organization members' links to the company entities they act for.
+	 * Confidential service credentials only; the Organization is the caller's.
+	 */
+	readonly users: Readonly<{
+		/** Links `userId` to `entityIds`, keeping existing links; returns all of them. */
+		linkCompanies: ServerOperationMethod<"users_link_companies">;
+		listCompanyLinks: ServerOperationMethod<"users_list_company_links">;
+	}>;
 	readonly workflows: Readonly<{
 		invoke: ServerOperationMethod<"workflows_invoke">;
 		list: ServerOperationMethod<"workflows_list">;
 	}>;
 }
+declare const oauthErrorCodes: readonly [
+	"invalid_client",
+	"invalid_grant",
+	"invalid_request",
+	"invalid_scope",
+	"invalid_target",
+	"temporarily_unavailable",
+	"unauthorized_client",
+	"unsupported_grant_type"
+];
+/**
+ * `invalid_grant` means the member's CI session ended or the member cannot act
+ * in the Organization: sign the member in again. `invalid_response` means CI
+ * answered with neither a token nor an OAuth error. Other codes are CI's OAuth
+ * errors and point at the application's configuration or CI availability.
+ */
+export type MemberSessionExchangeErrorCode = (typeof oauthErrorCodes)[number] | "invalid_response";
+export interface MemberSessionExchangeRequest {
+	readonly credentials: ConfidentialCredentialProvider;
+	readonly fetch?: typeof globalThis.fetch;
+	/** The Organization the member acts in; the application must be allowed in it. */
+	readonly organizationId: string;
+	/** A subset of the application's scopes. */
+	readonly scopes: readonly string[];
+	/** The member's CI session token, for example from `POST /auth/otp/verify`. */
+	readonly sessionToken: string;
+	/** Cancels the exchange; a cancelled exchange rejects with the signal's reason. */
+	readonly signal?: AbortSignal;
+	readonly tenantUrl: string;
+	/** Bound on the request and its response body. Defaults to 10 seconds. */
+	readonly timeoutMs?: number;
+}
+export interface MemberAccessToken {
+	readonly accessToken: string;
+	/** When to exchange again: before CI's expiry, which is counted from signing. */
+	readonly expiresAt: Date;
+}
+declare class MemberSessionExchangeError extends Error {
+	readonly code: MemberSessionExchangeErrorCode;
+	/** The HTTP status CI answered with; absent when CI was unreachable. */
+	readonly status: number | undefined;
+	constructor(code: MemberSessionExchangeErrorCode, status: number | undefined, options?: ErrorOptions);
+}
 export type RunAsApplicationConfig = Readonly<{
 	auditSubject: ExternalApplicationExternalAuditSubject;
 	credentials: ConfidentialCredentials;
@@ -592,6 +732,14 @@ export type RunAsApplicationConfig = Readonly<{
 }>;
 export declare const createServerClient: (config: ServerClientConfig) => ServerClient, serverSdkRuntime: "node";
 export declare const runAsApplication: (config: RunAsApplicationConfig) => ServerClient;
+export declare const exchangeMemberSession: (request: MemberSessionExchangeRequest) => Promise<MemberAccessToken>, MemberSessionExchangeError$1: typeof MemberSessionExchangeError;
 export declare const uuidV7: () => string;
 
+export {
+	MemberSessionExchangeError$1 as MemberSessionExchangeError,
+	MemberUser as ServerMemberUser,
+	MemberUserPage as ServerMemberUserPage,
+	MemberUserResolution as ServerMemberUserResolution,
+};
+
 export {};