@lightspeed-ai/sdk 0.4.0

package/src/generated/workflow-types.ts

@@ -0,0 +1,612 @@
+/*
+ * Generated by clients/typescript/scripts/generate.mjs.
+ * Do not edit by hand.
+ */
+
+/**
+ * Who created a resource or authored bytes. An actor is whatever a key
+ * allowed to assert one said; core compares it and never resolves it.
+ *
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "Attribution".
+ */
+export type Attribution =
+  | {
+      id: string;
+      kind: "actor";
+    }
+  | {
+      kind: "key";
+      prefix: string;
+    }
+  | {
+      kind: "local";
+    }
+  | {
+      cause: string;
+      component: string;
+      kind: "internal";
+    };
+/**
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "BotId".
+ */
+export type BotId = string;
+/**
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "BotTriggerId".
+ */
+export type BotTriggerId = string;
+/**
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "ChannelAccountId".
+ */
+export type ChannelAccountId = string;
+/**
+ * What a connector executes: provider message ids and their direction.
+ *
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "ChannelDeliveryOperation".
+ */
+export type ChannelDeliveryOperation =
+  | {
+      replyContext?: ReplyContext | null;
+      replyTo?: string | null;
+      text: string;
+      type: "send";
+    }
+  | {
+      messageId: string;
+      text: string;
+      type: "edit";
+    }
+  | {
+      emoji: string;
+      /**
+       * Whether the reacted-to message is the bot's own.
+       */
+      fromMe: boolean;
+      messageId: string;
+      type: "react";
+    };
+/**
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "ChannelProvider".
+ */
+export type ChannelProvider = string;
+/**
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "ChannelMediaKind".
+ */
+export type ChannelMediaKind = "image" | "audio" | "document";
+/**
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "ChatTurnAccess".
+ */
+export type ChatTurnAccess = "anyone" | "listed";
+/**
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "ChatGroupActivation".
+ */
+export type ChatGroupActivation = "mention" | "always";
+/**
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "ChatScope".
+ */
+export type ChatScope = "direct" | "group";
+/**
+ * Closed internal vocabulary carried by the shared delivery signal.
+ *
+ * Workflow-tool invocation bodies join this enum when the durable tool
+ * contracts land. This first slice folds the two existing transports.
+ *
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "EmissionBody".
+ */
+export type EmissionBody =
+  | {
+      failure_message_ref?: string | null;
+      kind: "run_terminal";
+      output?: ContentRef | null;
+      run_id: number;
+      status: RunStatus;
+      token: string;
+    }
+  | {
+      kind: "source_resolution";
+      promise_id: PromiseId;
+      resolution: PromiseResolution;
+    }
+  | {
+      /**
+       * Workflow id of the session that emitted the invocation — the
+       * endpoint a receiver signals its reply to. Supplied by the
+       * substrate adapter; the harness treats it as opaque.
+       */
+      holder_workflow_id: string;
+      invocation: WorkflowToolInvocation;
+      kind: "tool_invocation";
+    }
+  | {
+      completion_key: string;
+      invocation_id: WorkflowToolInvocationId;
+      kind: "invocation_cancellation";
+      promise_id: PromiseId;
+    };
+/**
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "RunStatus".
+ */
+export type RunStatus = "active" | "parked" | "cancelling" | "completed" | "failed" | "cancelled";
+/**
+ * Stable identifier for a promise: a session-scoped counter rendered as
+ * `promise_<n>`, the same convention as `run_<n>`, so the model copies a
+ * short handle rather than a digest. The harness hands every tool batch a
+ * base one past the session cursor (`ToolInvocationBatchRequest::
+ * promise_id_base`); the executor numbers the promises it creates from
+ * that base, and the reducer accepts a creation only at or above the
+ * batch's base and never twice. Producer correlation lives on
+ * `PromiseSource`, not in the id.
+ *
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "PromiseId".
+ */
+export type PromiseId = string;
+/**
+ * How a promise reached a terminal state. Used by `ResolvePromise`
+ * admission; all transports (push notifications, poll results, timers,
+ * cancellation) converge on this one funnel.
+ *
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "PromiseResolution".
+ */
+export type PromiseResolution =
+  | {
+      kind: "resolved";
+      payload_ref?: string | null;
+    }
+  | {
+      error_ref?: string | null;
+      kind: "failed";
+    }
+  | {
+      kind: "cancelled";
+    };
+/**
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "WorkflowToolInvocationId".
+ */
+export type WorkflowToolInvocationId = string;
+/**
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "SessionId".
+ */
+export type SessionId = string;
+/**
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "ToolCallId".
+ */
+export type ToolCallId = string;
+/**
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "WorkflowToolId".
+ */
+export type WorkflowToolId = string;
+/**
+ * Stable identity for one cross-workflow emission.
+ *
+ * Ids are deterministic digests over a domain-separated, length-prefixed
+ * producer/source identity. They are safe to recompute after activity retry,
+ * worker restart, or workflow continue-as-new.
+ *
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "EmissionId".
+ */
+export type EmissionId = string;
+/**
+ * Durable producer identity carried with every emission.
+ *
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "EmissionProducer".
+ */
+export type EmissionProducer =
+  | {
+      kind: "session";
+      log_seq: number;
+      session_id: SessionId;
+      universe_id: string;
+    }
+  | {
+      kind: "workflow";
+      universe_id: string;
+      workflow_id: string;
+    };
+/**
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "TranscriptionActivityResult".
+ */
+export type TranscriptionActivityResult =
+  | {
+      kind: "succeeded";
+      transcript_ref: string;
+    }
+  | {
+      failure: TranscriptionFailure;
+      kind: "failed";
+    };
+/**
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "TranscriptionFailureKind".
+ */
+export type TranscriptionFailureKind =
+  "invalidAudio" | "configuration" | "provider" | "timeout" | "internal";
+/**
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "TranscriptionStatus".
+ */
+export type TranscriptionStatus =
+  "pending" | "running" | "succeeded" | "failed" | "cancelled" | "expired";
+
+/**
+ * Envelope and start-on-call types of the fixed deliver_emission transport between sessions and receiver workflows.
+ */
+export interface LightspeedWorkflowContract {
+  [k: string]: unknown;
+}
+/**
+ * One connector activity call. `idempotency_key` is the invocation id, or
+ * `{invocation}:chunk:{i}/{n}` for a chunk of a split send.
+ *
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "ChannelDeliveryCommand".
+ */
+export interface ChannelDeliveryCommand {
+  idempotencyKey: string;
+  invocationId: string;
+  operation: ChannelDeliveryOperation;
+  route: ChannelRoute;
+  version: number;
+}
+/**
+ * The message a send replies to, for providers that quote it themselves.
+ *
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "ReplyContext".
+ */
+export interface ReplyContext {
+  senderId: string;
+  text: string;
+}
+/**
+ * Where a delivery goes: one account's chat, optionally a thread.
+ *
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "ChannelRoute".
+ */
+export interface ChannelRoute {
+  accountId: ChannelAccountId;
+  chatId: string;
+  provider: ChannelProvider;
+  threadId?: string | null;
+}
+/**
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "ChannelDeliveryResult".
+ */
+export interface ChannelDeliveryResult {
+  /**
+   * Every provider id the delivery produced (a chunked send has several;
+   * the first is the anchor).
+   */
+  messageIds: string[];
+  provider: ChannelProvider;
+  version: number;
+}
+/**
+ * A provider-owned attachment reference; never bytes. The connector
+ * downloads it when the conversation workflow asks (`prepare_channel_media`).
+ *
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "ChannelInboundMedia".
+ */
+export interface ChannelInboundMedia {
+  byteSize?: number | null;
+  /**
+   * Provider file handle (a Telegram file id, a sealed WhatsApp locator).
+   */
+  fileId: string;
+  kind: ChannelMediaKind;
+  mime: string;
+  name?: string | null;
+}
+/**
+ * Who may take a turn and who may issue control commands, by provider
+ * handle (Telegram user id, WhatsApp JID). Handle allowlists on the
+ * trigger replace any platform membership lookup.
+ *
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "ChatAccess".
+ */
+export interface ChatAccess {
+  /**
+   * Handles allowed to take a turn when `turn` is `listed`.
+   */
+  allowed?: string[];
+  /**
+   * Handles allowed to issue `/activation` and `/status`; empty denies
+   * control commands to everyone.
+   */
+  controllers?: string[];
+  turn?: ChatTurnAccess & string;
+}
+/**
+ * When the bot acts in a conversation.
+ *
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "ChatActivation".
+ */
+export interface ChatActivation {
+  group?: ChatGroupActivation | null;
+  mentionNames?: string[];
+  triggerPrefixes?: string[];
+}
+/**
+ * Durable content identity and encoding. The payload stays in CAS; consumers
+ * project it outside the harness rather than assuming every output is text.
+ *
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "ContentRef".
+ */
+export interface ContentRef {
+  content_ref: string;
+  media_type?: string | null;
+  provider_kind?: string | null;
+}
+/**
+ * The conversation a message belongs to: one account's chat, optionally
+ * a thread inside it.
+ *
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "ConversationRef".
+ */
+export interface ConversationRef {
+  accountId: ChannelAccountId;
+  chatId: string;
+  threadId?: string | null;
+}
+/**
+ * Secret-free durable input of one conversation workflow: the chat trigger
+ * it serves and the conversation it fronts. The workflow owns nothing on
+ * the core side: the bot controller creates and controls the session; the
+ * workflow is the source of the conversation's events and the receiver of
+ * its `message_*` tools.
+ *
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "ConversationStart".
+ */
+export interface ConversationStart {
+  access: ChatAccess;
+  accountId: ChannelAccountId;
+  activation: ChatActivation;
+  botId: BotId;
+  /**
+   * Task queue of the connector host serving the account.
+   */
+  connectorTaskQueue: string;
+  conversation: ConversationRef;
+  /**
+   * Human label of the conversation (routed session label, display name).
+   */
+  label: string;
+  provider: ChannelProvider;
+  scope: ChatScope;
+  triggerId: BotTriggerId;
+  universeId: string;
+}
+/**
+ * Bounded durable record of one successful workflow-tool tool call.
+ *
+ * The model arguments remain in CAS and are referenced by `arguments_ref`.
+ * Receiver-specific interpretation belongs to the receiving workflow.
+ *
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "WorkflowToolInvocation".
+ */
+export interface WorkflowToolInvocation {
+  arguments_ref: string;
+  binding_fingerprint: string;
+  /**
+   * Keyed promise set created atomically with this invocation; `None`
+   * for notify (`Accepted`) completion. Request/reply is the single
+   * reserved key `reply`.
+   */
+  completion_promises?: {
+    [k: string]: PromiseId;
+  } | null;
+  /**
+   * Opaque, runtime-supplied context for the receiving workflow. This is
+   * separate from model-authored arguments so runtime state can be pinned
+   * without changing the tool's declared argument schema.
+   */
+  execution_context_ref?: string | null;
+  invocation_id: WorkflowToolInvocationId;
+  run_id: number;
+  schema_revision: number;
+  semantic_type: string;
+  session_id: SessionId;
+  session_universe_id: string;
+  tool_batch_id: number;
+  tool_call_id: ToolCallId;
+  tool_id: WorkflowToolId;
+  turn_id: number;
+}
+/**
+ * Bounded cross-workflow fact delivered through the fixed
+ * `deliver_emission` signal.
+ *
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "EmissionEnvelope".
+ */
+export interface EmissionEnvelope {
+  body: EmissionBody;
+  emission_id: EmissionId;
+  producer: EmissionProducer;
+}
+/**
+ * `maintain_channel_typing`: keep the provider's typing indicator up for
+ * the conversation until the activity is cancelled.
+ *
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "MaintainChannelTypingInput".
+ */
+export interface MaintainChannelTypingInput {
+  route: ChannelRoute;
+}
+/**
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "ModelConfig".
+ */
+export interface ModelConfig {
+  apiKind: string;
+  model: string;
+  providerId: string;
+}
+/**
+ * `prepare_channel_media`: the connector downloads the provider file and
+ * stores it in the universe's CAS.
+ *
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "PrepareChannelMediaInput".
+ */
+export interface PrepareChannelMediaInput {
+  media: ChannelInboundMedia;
+  route: ChannelRoute;
+  universeId: string;
+}
+/**
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "PrepareChannelMediaResult".
+ */
+export interface PrepareChannelMediaResult {
+  item: PreparedMediaItem;
+}
+/**
+ * A prepared attachment: a CAS reference, never bytes.
+ *
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "PreparedMediaItem".
+ */
+export interface PreparedMediaItem {
+  blobRef: string;
+  kind: ChannelMediaKind;
+  mime: string;
+  name?: string | null;
+}
+/**
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "TranscriptionFailure".
+ */
+export interface TranscriptionFailure {
+  kind: TranscriptionFailureKind;
+  message: string;
+}
+/**
+ * Immutable audio input in this universe's content store.
+ *
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "TranscriptionAudio".
+ */
+export interface TranscriptionAudio {
+  blobRef: string;
+  mime: string;
+  name: string;
+}
+/**
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "TranscriptionSnapshot".
+ */
+export interface TranscriptionSnapshot {
+  request: TranscriptionStartParams;
+  view: TranscriptionView;
+}
+/**
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "TranscriptionStartParams".
+ */
+export interface TranscriptionStartParams {
+  audio: TranscriptionAudio;
+  /**
+   * Scoped to the requester. Matching retries rejoin the original job,
+   * including after defaults change; changed requests conflict. Identity is
+   * retained for the Temporal namespace's workflow-history retention period.
+   */
+  idempotencyKey: string;
+  language?: string | null;
+  model?: ModelConfig | null;
+  prompt?: string | null;
+}
+/**
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "TranscriptionView".
+ */
+export interface TranscriptionView {
+  audio: TranscriptionAudio;
+  createdAtMs: number;
+  createdBy: Attribution;
+  failure?: TranscriptionFailure | null;
+  model: ModelConfig;
+  status: TranscriptionStatus;
+  text?: string | null;
+  /**
+   * Plain UTF-8 transcript blob, usable as ordinary textRef input.
+   * Unsubmitted content can be swept after the ordinary CAS grace period.
+   */
+  transcriptRef?: string | null;
+  transcriptionId: string;
+}
+/**
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "TranscriptionWorkflowArgs".
+ */
+export interface TranscriptionWorkflowArgs {
+  createdAtMs: number;
+  createdBy: Attribution;
+  model: ModelConfig;
+  request: TranscriptionStartParams;
+  transcriptionId: string;
+  universeId: string;
+}
+/**
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "WorkflowToolRecipeV1".
+ */
+export interface WorkflowToolRecipeV1 {
+  taskQueue: string;
+  workflowType: string;
+}
+/**
+ * Result shape of [`WORKFLOW_TOOL_RECOVERY_QUERY`].
+ *
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "WorkflowToolRecoveryResult".
+ */
+export interface WorkflowToolRecoveryResult {
+  resolutions?: {
+    [k: string]: PromiseResolution;
+  };
+}
+/**
+ * Start arguments every start-on-call plugin workflow receives. The plugin
+ * resolves each keyed completion promise by emitting `SourceResolution`
+ * bodies to the holder workflow through the fixed `deliver_emission`
+ * signal, using its own execution id as the producer workflow id.
+ *
+ * This interface was referenced by `LightspeedWorkflowContract`'s JSON-Schema
+ * via the `definition` "WorkflowToolStartArgs".
+ */
+export interface WorkflowToolStartArgs {
+  execution_id: string;
+  holder_workflow_id: string;
+  invocation: WorkflowToolInvocation;
+  universe_id: string;
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+export { LightspeedRpcError, LightspeedTransportError, lightspeedRpcErrorKind } from "./errors.js";
+export type { LightspeedRpcErrorKind, JsonRpcErrorPayload } from "./errors.js";
+export {
+  LightspeedClient,
+  generateSubmissionId,
+} from "./client.js";
+export type {
+  AwaitRunOptions,
+  AwaitRunResult,
+  CallOptions,
+  LightspeedClientOptions,
+  ReadEventsOptions,
+  RequestId,
+  RunTerminalState,
+  StartRunOptions,
+} from "./client.js";
+export {
+  METHODS,
+  METHOD_INFO,
+  NOTIFICATIONS,
+  rpc,
+} from "./generated/methods.js";
+export type {
+  Method,
+  MethodMap,
+  MethodParams,
+  MethodResult,
+  NotificationMethod,
+  RpcCaller,
+} from "./generated/methods.js";
+export type * from "./generated/types.js";