@todoist/automations-sdk 0.0.0 → 1.0.0

package/dist/base-client.d.ts

@@ -0,0 +1,2 @@
+import { a as BaseClient, i as createClientContext, o as ClientContext, t as ClientApiOptions } from "./context-DsrXdqq8.js";
+export { BaseClient, type ClientApiOptions, type ClientContext, createClientContext };

package/dist/base-client.js

@@ -0,0 +1 @@
+export { i as BaseClient, r as createClientContext } from "./context-CxEkwuyE.js";

package/dist/chat-turn.d.ts

@@ -0,0 +1,314 @@
+import { A as ConnectionsClient, Ct as ChatStreamRequestErrorResponse, Nt as getChatBillingRefusal, St as ChatMessageDto, bt as ConnectionSetupDto, t as AutomationsApi, yt as ConnectionDto } from "./automations-api-CLcJvEjY.js";
+import { s as RequestOptions } from "./context-DsrXdqq8.js";
+import { n as ConnectionSelection } from "./connection-selection-C9yMkCvL.js";
+import { z } from "zod";
+import { UIMessage } from "ai";
+//#region ../core/dist/types/chat-tools/prompt-enable-push.d.ts
+declare const PromptEnablePushOutputSchema: z.ZodObject<{
+  enabled: z.ZodBoolean;
+  deviceCount: z.ZodNumber;
+  message: z.ZodString;
+}, z.core.$strip>;
+type PromptEnablePushOutput = z.infer<typeof PromptEnablePushOutputSchema>;
+//#endregion
+//#region ../core/dist/types/chat-tools/select-connections.d.ts
+declare const ConnectionItemSchema: z.ZodObject<{
+  connectorId: z.ZodString;
+  serviceName: z.ZodString;
+  connectionType: z.ZodEnum<{
+    mcp: "mcp";
+    trigger: "trigger";
+  }>;
+}, z.core.$strip>;
+declare const SelectConnectionsOutputSchema: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+  type: z.ZodLiteral<"success">;
+  connectionId: z.ZodString;
+  connectorId: z.ZodString;
+  connectionType: z.ZodEnum<{
+    mcp: "mcp";
+    trigger: "trigger";
+  }>;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodLiteral<"error">;
+  message: z.ZodString;
+  connectorId: z.ZodString;
+  connectionType: z.ZodEnum<{
+    mcp: "mcp";
+    trigger: "trigger";
+  }>;
+}, z.core.$strip>]>>;
+type ConnectionItem = z.infer<typeof ConnectionItemSchema>;
+type SelectConnectionsOutput = z.infer<typeof SelectConnectionsOutputSchema>;
+//#endregion
+//#region src/chat-turn/types.d.ts
+/** Terminal outcomes of one server turn. */
+type TurnOutcome = 'awaiting_input' | 'action_required' | 'published';
+/** A client-owned tool action on an assistant message that must be resolved before the agent can continue. */
+type PendingClientAction = {
+  kind: 'select_connections';
+  message: UIMessage;
+  toolCallId: string;
+  draftId: string;
+  connections: ConnectionItem[];
+} | {
+  kind: 'enable_push';
+  message: UIMessage;
+  toolCallId: string;
+  draftId?: string;
+};
+/** A tool call the agent made during a turn, reported once per state change. */
+type ToolActivity = {
+  tool: string;
+  toolCallId: string;
+  state: string;
+};
+type AvailableConnection = {
+  id: string;
+  label: string;
+};
+/** One service the agent needs a connection for, with the authorised connections that could satisfy it. */
+type ConnectionRequirement = ConnectionItem & {
+  availableConnections: AvailableConnection[];
+};
+/** A connection whose setup the user has to complete before it can be used. */
+type ConnectionSetupStart = {
+  connectionId: string;
+  setup: ConnectionSetupDto | null;
+  /** True when an existing pending connection was picked up rather than a new one created. */
+  resumed: boolean;
+};
+/** The pending action a turn ended on, without the message it was read from. */
+type PendingActionSummary = {
+  kind: 'select_connections';
+  toolCallId: string;
+  draftId: string;
+  requirements: Array<ConnectionRequirement & {
+    /** Present when a connection was created for the user to authorise. */
+    setup?: ConnectionSetupStart;
+  }>;
+} | {
+  kind: 'enable_push';
+  toolCallId: string;
+  draftId?: string;
+};
+type TurnResult = {
+  conversationId: string;
+  outcome: TurnOutcome;
+  assistantText: string;
+  /** Set when the outcome is `published`. */
+  automationId?: string;
+  /** Whether archiving the published conversation succeeded. */
+  conversationArchived?: boolean;
+  /** Why archiving failed, when it did. Publication itself succeeded. */
+  conversationArchiveError?: string;
+  /** Set when the outcome is `action_required`. */
+  pendingAction?: PendingActionSummary;
+};
+/**
+ * What the turn sends. A message starts or continues the conversation;
+ * selections answer a pending `select_connections` action, and an empty list
+ * lets the runner resolve it on its own.
+ */
+type TurnInput = {
+  message: string;
+} | {
+  selections: readonly ConnectionSelection[];
+};
+/** Why a turn could not be started from the given input. */
+type ChatTurnInputErrorCode = 'awaiting_selection' | 'awaiting_push' | 'not_awaiting_selection' | 'input_required' | 'ambiguous_selection' | 'unknown_connection' |
+/** A required connector needs a tenant or server URL, so it cannot be set up automatically. */
+'connection_input_required';
+export declare class ChatTurnInputError extends Error {
+  readonly code: ChatTurnInputErrorCode;
+  constructor(code: ChatTurnInputErrorCode, message: string);
+}
+//#endregion
+//#region src/chat-turn/transport.d.ts
+type ChatTurnTransportOptions = {
+  token: string;
+  baseUrl: string;
+  headers?: Record<string, string>;
+  fetch?: typeof fetch;
+};
+/**
+ * Adapts the AI SDK message stream to the Automations chat request contract.
+ *
+ * A turn on a workspace conversation goes to that workspace's chat route, so the
+ * access guard revalidates membership per turn; the scope is chosen per turn because
+ * a caller resuming a conversation only learns it once the conversation has been fetched.
+ */
+export declare class ChatTurnTransport {
+  private readonly transport;
+  constructor({ token, baseUrl, headers, fetch }: ChatTurnTransportOptions);
+  /** Streams one server turn, reporting incremental text and deduplicated tool state changes. */
+  streamTurn({ conversationId, workspaceId, message, signal, onText, onToolActivity }: {
+    conversationId: string;
+    /** The workspace the conversation lives in; null is the personal space. */
+    workspaceId?: string | null;
+    message: UIMessage;
+    signal?: AbortSignal;
+    onText?: (delta: string) => void;
+    onToolActivity?: (activity: ToolActivity) => void;
+  }): Promise<UIMessage>;
+}
+//#endregion
+//#region src/chat-turn/run-conversation-turn.d.ts
+type TurnApi = Pick<AutomationsApi, 'chat' | 'connections' | 'automationDraftConnections' | 'workspaceAutomationDraftConnections' | 'notifications'>;
+type TurnOptions = {
+  /** REST calls: messages, draft connections, connection lookup and creation. */
+  api: TurnApi;
+  /** The chat stream. Separate from `api` because the API object does not expose the credentials the transport needs. */
+  transport: Pick<ChatTurnTransport, 'streamTurn'>;
+  conversationId: string;
+  /** The workspace the conversation lives in; null or absent is the personal space. */
+  workspaceId?: string | null;
+  input: TurnInput;
+  /**
+   * The persisted pending action, when the caller has already read it. Absent means the
+   * runner reads it; null means there is none, which a freshly created conversation can assert.
+   */
+  pendingAction?: PendingClientAction | null;
+  onText?: (delta: string) => void;
+  onToolActivity?: (activity: ToolActivity) => void;
+  /** Called once the agent has published an automation, before the conversation is archived. */
+  onPublished?: (automationId: string) => void;
+  /**
+   * Several authorised connections satisfy a requirement. Return the chosen id, or undefined
+   * to end the turn as `action_required` listing them. Absent: the turn ends as `action_required`.
+   */
+  chooseConnection?: (requirement: ConnectionRequirement) => Promise<string | undefined>;
+  /**
+   * No authorised connection exists. Return the id of one the caller has just had authorised,
+   * or undefined to end the turn as `action_required` without creating anything. Absent: a
+   * connection is created and the turn ends as `action_required` carrying its setup.
+   */
+  authorizeConnection?: (requirement: ConnectionRequirement) => Promise<string | undefined>;
+  signal?: AbortSignal;
+};
+/**
+ * Runs one server turn on a persisted conversation until it reaches a terminal outcome.
+ *
+ * A turn may span several server round trips: when the agent asks for connections and every
+ * requirement can be satisfied without the user, the answer is fed straight back in.
+ */
+export declare function runConversationTurn(options: TurnOptions): Promise<TurnResult>;
+//#endregion
+//#region src/chat-turn/errors.d.ts
+/**
+ * How far a failed turn got. A `request` failure was refused or lost before the
+ * reply began. A `stream` failure ended a reply partway; the server keeps what
+ * it had said by then.
+ */
+type ChatTurnFailureStage = 'request' | 'stream';
+/**
+ * A chat turn that failed once it was sent. `requestId` is the `X-Request-Id`
+ * the request carried, which the backend logs the turn under.
+ */
+export declare class ChatTurnError extends Error {
+  readonly conversationId: string;
+  readonly requestId: string;
+  readonly stage: ChatTurnFailureStage;
+  /** The API's error body, when it refused the request with one. */
+  readonly response: ChatStreamRequestErrorResponse | undefined;
+  constructor({ conversationId, requestId, stage, cause }: {
+    conversationId: string;
+    requestId: string;
+    stage: ChatTurnFailureStage;
+    cause: unknown;
+  });
+  get httpStatus(): number | undefined;
+}
+/**
+ * Reads the API's error body out of the error a refused chat request throws,
+ * which carries the response body as its message.
+ */
+export declare function parseChatStreamRequestError(error: unknown): ChatStreamRequestErrorResponse | undefined;
+/**
+ * The usage billing refusal a failed turn carries. A refused request's own error,
+ * whose message is the response body, is the cause of the ChatTurnError wrapping it.
+ */
+export declare function getChatTurnBillingRefusal(error: unknown): ReturnType<typeof getChatBillingRefusal>;
+/** The request id and HTTP status a failed turn, or a request made during it, carries. */
+export declare function readFailedRequest(error: unknown): {
+  requestId?: string;
+  httpStatus?: number;
+};
+/**
+ * Whether a turn broke on the way (a server error, a lost connection, a reply
+ * cut off) and is worth retrying, was refused as sent (a 4xx), or failed for a
+ * reason that is not the API's at all.
+ */
+export declare function classifyChatTurnFailure(error: unknown): 'broken' | 'refused' | 'other';
+//#endregion
+//#region src/chat-turn/messages.d.ts
+type ChatTextPart = Extract<UIMessage['parts'][number], {
+  type: 'text';
+}>;
+type ChatStepStartPart = Extract<UIMessage['parts'][number], {
+  type: 'step-start';
+}>;
+type ChatReasoningPart = Extract<UIMessage['parts'][number], {
+  type: 'reasoning';
+}>;
+export declare function createUserMessage(text: string): UIMessage;
+export declare function toUiMessage(message: ChatMessageDto): UIMessage;
+/** Filters saved parts by their minimal replay shape, preserving accepted objects and metadata. */
+export declare function normalizePersistedMessageParts(parts: readonly unknown[]): UIMessage['parts'];
+export declare function isTextPart(part: unknown): part is ChatTextPart;
+export declare function isStepStartPart(part: unknown): part is ChatStepStartPart;
+export declare function isReasoningPart(part: unknown): part is ChatReasoningPart;
+export declare function getVisibleText(message: UIMessage): string;
+/** Finds the latest tool action that must be performed by the client. */
+export declare function getPendingClientAction(message: UIMessage): PendingClientAction | null;
+/** The pending client action on the last persisted message, if that message is the assistant's. */
+export declare function getPendingActionFromMessages(messages: readonly ChatMessageDto[]): PendingClientAction | null;
+export declare function getPublishedAutomationId(message: UIMessage): string | undefined;
+/** Reconstructs the assistant tool-call message expected when answering the push notification prompt. */
+export declare function createEnablePushContinuation(action: Extract<PendingClientAction, {
+  kind: 'enable_push';
+}>, output: PromptEnablePushOutput): UIMessage;
+/** Reconstructs the assistant tool-call message expected when returning connection selections. */
+export declare function createSelectConnectionsContinuation(action: Extract<PendingClientAction, {
+  kind: 'select_connections';
+}>, output: SelectConnectionsOutput): UIMessage;
+//#endregion
+//#region src/chat-turn/connection-requirements.d.ts
+/** Removes repeated connector and connection-type requirements, preserving their first occurrence. */
+export declare function deduplicateConnectionRequirements(requirements: readonly ConnectionItem[]): ConnectionItem[];
+/** Looks up the authorised connections that could satisfy each distinct requirement. */
+export declare function loadConnectionRequirements(connections: Pick<ConnectionsClient, 'list'>, requirements: readonly ConnectionItem[], options?: RequestOptions): Promise<ConnectionRequirement[]>;
+//#endregion
+//#region src/chat-turn/connection-setup.d.ts
+type StartConnectionSetupRequest = {
+  connectorId: string;
+  capability: 'mcp' | 'trigger';
+  /** Automations to move onto the new connection once it is authorised, when replacing a broken one. */
+  automationIds?: readonly string[];
+  /** The slug for a connector whose MCP server URL is a `{tenant}` template, e.g. `acme`. */
+  tenant?: string;
+  /** A full MCP server URL, for a self-hosted server or to reuse a connection's own URL. */
+  serverUrl?: string;
+};
+/** Creates a connection and returns what the user has to complete to authorise it. */
+export declare function startConnectionSetup(connections: Pick<ConnectionsClient, 'create'>, request: StartConnectionSetupRequest, options?: RequestOptions): Promise<ConnectionSetupStart>;
+/**
+ * The backend's sentence when a connection could not be created because its
+ * connector needs a tenant name or server URL, otherwise undefined.
+ */
+export declare function getConnectionInputRequiredMessage(error: unknown): string | undefined;
+/** Picks up the setup of a connection that is still waiting on the user. */
+export declare function resumeConnectionSetup(connection: Pick<ConnectionDto, 'id' | 'setup'>): ConnectionSetupStart;
+/** The pieces of a setup a client can show or open, flattened so callers need not switch on `kind`. */
+type ConnectionSetupSummary = {
+  setupKind: 'oauth' | 'managed' | 'none';
+  authorizationUrl?: string;
+  instructions?: string;
+  code?: string;
+  deepLinkUrl?: string | null;
+  expiresAt?: string;
+};
+export declare function summarizeConnectionSetup(setup: ConnectionSetupDto | null): ConnectionSetupSummary;
+/** The URL a client can open to let the user complete setup, when the setup has one. */
+export declare function getConnectionSetupUrl(setup: ConnectionSetupDto | null): string | null;
+//#endregion
+export type { AvailableConnection, ChatReasoningPart, ChatStepStartPart, ChatTextPart, ChatTurnFailureStage, ChatTurnInputErrorCode, ChatTurnTransportOptions, ConnectionRequirement, ConnectionSelection, ConnectionSetupStart, ConnectionSetupSummary, PendingActionSummary, PendingClientAction, StartConnectionSetupRequest, ToolActivity, TurnInput, TurnOptions, TurnOutcome, TurnResult };