@lovable.dev/sdk 1.4.0 → 1.6.1

package/dist/workflows.d.ts

@@ -0,0 +1,233 @@
+//#region ../workflow-sdk/src/index.d.ts
+interface JournalEntry {
+  result?: unknown;
+  resultType?: "undefined" | "ref";
+  /** Payload pointer when resultType is "ref"; see docs/workflows/payload-offload.md. */
+  ref?: PayloadRef;
+  /** Marks an auto-offloaded ref that replays as its parsed value instead of a WorkflowFile. */
+  transparent?: boolean;
+  /** Ephemeral read grant the engine hydrates per invocation; never persisted. */
+  grant?: PayloadGrant;
+}
+type Journal = Record<string, JournalEntry>;
+type PayloadAeadScheme = "CHUNKED_AES_256_GCM_V1";
+interface PayloadRef {
+  bucket: string;
+  key: string;
+  /** Lowercase hex SHA-256 of the plaintext bytes. */
+  sha256: string;
+  sizeBytes: number;
+  contentType: string;
+  /** Base64 AES-256 DEK sealed by the workflows payload KEK. */
+  wrappedDek: string;
+  kekId: string;
+  scheme: PayloadAeadScheme;
+}
+interface PayloadGrant {
+  getUrl: string;
+  /** Base64 raw AES-256 DEK for this object. */
+  dek: string;
+}
+interface PayloadOffload {
+  /** Absolute URL of the runtime payload endpoint (POST /runtime/v1/payloads). */
+  endpoint: string;
+  /** Step results whose JSON serialization is <= threshold bytes stay inline. */
+  threshold: number;
+  /** Per-object plaintext byte cap. */
+  maxBytes: number;
+}
+/** Lazy handle over an offloaded payload; reads stream-decrypt on access. */
+interface WorkflowFile {
+  readonly sha256: string;
+  readonly sizeBytes: number;
+  readonly contentType: string;
+  stream(): ReadableStream<Uint8Array>;
+  arrayBuffer(): Promise<ArrayBuffer>;
+  text(): Promise<string>;
+  json(): Promise<unknown>;
+}
+interface WorkflowFilesApi {
+  /** Offloads `data` and returns a handle; stream inputs are buffered in memory (tranche 1). */
+  create(data: ReadableStream<Uint8Array> | ArrayBuffer | Uint8Array | string, options: {
+    contentType: string;
+  }): Promise<WorkflowFile>;
+}
+interface WorkerRequest<Input = unknown> {
+  input: Input;
+  journal: Journal;
+  /** Present when the engine enables large-payload offload for this run. */
+  payloadOffload?: PayloadOffload;
+}
+interface WorkerTaskRequest<Input = unknown> {
+  operation: "task";
+  task: string;
+  input: Input;
+  runName: string;
+  stepId: string;
+  attempt: number;
+  workflowTenant: string;
+  workflowApiUrl: string;
+}
+type ExecutionEnvironment = "cloudflare";
+interface StepDispatch {
+  id: string;
+  task: string;
+  environment: ExecutionEnvironment;
+  input: unknown;
+  maxConcurrency?: number;
+  /** Durable-promise park request (ctx.promise); the engine parks the run instead of executing. */
+  promise?: {
+    name: string;
+    timeoutSeconds?: number;
+  };
+}
+/** `completed` is this invocation's unpersisted delta, including on workflow failure. */
+type WorkerResponse<Output = unknown> = {
+  status: "done";
+  output: Output;
+  outputType?: never;
+  completed: Journal;
+} | {
+  status: "done";
+  output: null;
+  outputType: "undefined";
+  completed: Journal;
+} | {
+  status: "failed";
+  error: string;
+  failedStep?: string;
+  completed: Journal;
+} | {
+  status: "dispatch";
+  steps: StepDispatch[];
+  completed: Journal;
+};
+interface TaskDefinitionBase {
+  readonly name: string;
+  readonly environment: ExecutionEnvironment;
+  readonly maxConcurrency?: number;
+}
+type WorkflowLogLevel = "debug" | "info" | "warn" | "error";
+interface WorkflowLogEntry {
+  readonly level: WorkflowLogLevel;
+  readonly message: string;
+  readonly fields?: Record<string, unknown>;
+}
+type WorkflowLogEmitter = (entry: WorkflowLogEntry) => void;
+/**
+ * Fire-and-forget structured logging. Entries are scrubbed for
+ * credential-shaped values, capped in size and count, and not journaled;
+ * workflow-body entries are suppressed while journaled effects replay, so
+ * each entry is emitted once across engine round-trips.
+ */
+interface WorkflowLogger {
+  debug(message: string, fields?: Record<string, unknown>): void;
+  info(message: string, fields?: Record<string, unknown>): void;
+  warn(message: string, fields?: Record<string, unknown>): void;
+  error(message: string, fields?: Record<string, unknown>): void;
+}
+interface TaskContext {
+  readonly runName: string;
+  readonly stepId: string;
+  readonly attempt: number;
+  readonly workflows: WorkflowsApi;
+  readonly log: WorkflowLogger;
+}
+interface WorkflowRunRequest {
+  readonly workspaceId: string;
+  readonly projectId: string;
+  readonly workflowId: string;
+  readonly inputs?: unknown;
+  readonly invocationKey?: string;
+}
+interface WorkflowRun {
+  readonly id: string;
+  readonly state: string;
+  readonly error?: string;
+  readonly inputs?: unknown;
+  readonly outputs?: unknown;
+  readonly codeAttempt?: number;
+  readonly createTime?: string;
+  readonly startTime?: string;
+  readonly endTime?: string;
+}
+interface WorkflowsApi {
+  run(request: WorkflowRunRequest): Promise<WorkflowRun>;
+}
+interface CloudflareTaskDefinition<Input = unknown, Output = unknown> extends TaskDefinitionBase {
+  readonly environment: "cloudflare";
+  readonly run: (input: Input, context: TaskContext) => Promise<Output> | Output;
+}
+type TaskDefinition<Input = unknown, Output = unknown> = CloudflareTaskDefinition<Input, Output>;
+interface CloudflareTaskConfig<Input, Output> {
+  name: string;
+  environment: "cloudflare";
+  run: (input: Input, context: TaskContext) => Promise<Output> | Output;
+  maxConcurrency?: number;
+}
+interface StepRunOptions {
+  id?: string;
+}
+declare function defineTask<Input, Output>(config: CloudflareTaskConfig<Input, Output>): CloudflareTaskDefinition<Input, Output>;
+interface StepApi {
+  /** Replays a stable, unique name from the journal; effects must tolerate deliberate retries. */
+  run<T>(name: string, effect: () => Promise<T> | T): Promise<T>;
+  run<Input, Output>(task: TaskDefinition<Input, Output>, input: Input, options?: StepRunOptions): Promise<Output>;
+}
+interface WorkflowPromiseOptions {
+  /** Auto-reject deadline in seconds (1..86400); unset means bounded only by the run deadline. */
+  timeoutSeconds?: number;
+}
+/** A durable promise was rejected (explicitly or by its timeout sweep). Catchable to branch on rejection. */
+declare class PromiseRejectedError extends Error {
+  readonly promiseName: string;
+  readonly reason: string;
+  constructor(promiseName: string, reason: string);
+}
+interface WorkflowContext<Input = unknown> {
+  readonly input: Input;
+  readonly step: StepApi;
+  readonly files: WorkflowFilesApi;
+  readonly log: WorkflowLogger;
+  /** Journaled wall clock keyed by a stable name. */
+  now(name: string): Promise<number>;
+  /** Journaled random UUID keyed by a stable name. */
+  uuid(name: string): Promise<string>;
+  /** Parks until external resolution; replay returns the value or throws PromiseRejectedError. */
+  promise<T = unknown>(name: string, options?: WorkflowPromiseOptions): Promise<T>;
+}
+interface WorkflowDefinition<Input = unknown, Output = unknown> {
+  readonly name: string;
+  readonly handler: (ctx: WorkflowContext<Input>) => Promise<Output>;
+}
+declare function defineWorkflow<Input = unknown, Output = unknown>(name: string, handler: (ctx: WorkflowContext<Input>) => Promise<Output>): WorkflowDefinition<Input, Output>;
+type PayloadCryptoKey = Awaited<ReturnType<typeof crypto.subtle.importKey>>;
+/** Chunked AES-256-GCM encryptor emitting [payloadLen u32 BE][nonce 12][ciphertext||tag] frames. */
+declare function encryptPayloadStream(key: PayloadCryptoKey): TransformStream<Uint8Array, Uint8Array>;
+/** Decrypts CHUNKED_AES_256_GCM_V1; rejects truncation, reordering, splices, and digest or size mismatches. */
+declare function decryptPayloadStream(key: PayloadCryptoKey, expected: {
+  sha256: string;
+  sizeBytes: number;
+}): TransformStream<Uint8Array, Uint8Array>;
+interface InvokeOptions {
+  /** Receives each capped and scrubbed entry; defaults to JSON envelopes on the console. */
+  onLog?: WorkflowLogEmitter;
+}
+declare function invoke<Input, Output>(workflow: WorkflowDefinition<Input, Output>, request: WorkerRequest<Input>, options?: InvokeOptions): Promise<WorkerResponse<Output>>;
+interface WorkerOptions {
+  tasks?: unknown;
+}
+interface Worker {
+  fetch: (request: Request) => Promise<Response>;
+}
+declare function toWorker<Input, Output>(workflowValue: WorkflowDefinition<Input, Output>, options?: WorkerOptions): Worker;
+interface DriveOptions {
+  /** Total invocations before a failure is surfaced. Default 1 (no retry). */
+  maxAttempts?: number;
+  /** Receives each capped and scrubbed entry; defaults to JSON envelopes on the console. */
+  onLog?: WorkflowLogEmitter;
+}
+declare function driveToCompletion<Input, Output>(workflow: WorkflowDefinition<Input, Output>, input: Input, options?: DriveOptions): Promise<Output>;
+//#endregion
+export { CloudflareTaskConfig, CloudflareTaskDefinition, DriveOptions, ExecutionEnvironment, InvokeOptions, Journal, JournalEntry, PayloadAeadScheme, PayloadCryptoKey, PayloadGrant, PayloadOffload, PayloadRef, PromiseRejectedError, StepApi, StepDispatch, StepRunOptions, TaskContext, TaskDefinition, Worker, WorkerOptions, WorkerRequest, WorkerResponse, WorkerTaskRequest, WorkflowContext, WorkflowDefinition, WorkflowFile, WorkflowFilesApi, WorkflowLogEmitter, WorkflowLogEntry, WorkflowLogLevel, WorkflowLogger, WorkflowPromiseOptions, WorkflowRun, WorkflowRunRequest, WorkflowsApi, decryptPayloadStream, defineTask, defineWorkflow, driveToCompletion, encryptPayloadStream, invoke, toWorker };
+//# sourceMappingURL=workflows.d.ts.map