@sst-community/sst 0.0.0-placeholder.0 → 4.17.2

package/dist/aws/workflow.d.ts

@@ -0,0 +1,324 @@
+import * as durable from "@aws/durable-execution-sdk-js";
+import { type AwsOptions } from "./client.js";
+/**
+ * The `workflow` SDK is a thin wrapper around the
+ * [`@aws/durable-execution-sdk-js`](https://www.npmjs.com/package/@aws/durable-execution-sdk-js)
+ * package and the AWS Lambda durable execution APIs.
+ *
+ * SST also adds a few helpers on top, including `ctx.stepWithRollback()`,
+ * `ctx.rollbackAll()`, and `ctx.waitUntil()`.
+ *
+ * @example
+ * ```ts title="src/workflow.ts"
+ * import { workflow } from "sst/aws/workflow";
+ * ```
+ *
+ * @example
+ * Use `stepWithRollback()` and `rollbackAll()` to register compensating actions.
+ *
+ * ```ts title="src/workflow.ts"
+ * import { workflow } from "sst/aws/workflow";
+ *
+ * export const handler = workflow.handler(async (_event, ctx) => {
+ *   try {
+ *     const order = await ctx.stepWithRollback("create-order", {
+ *       run: async () => ({ orderId: "order_123" }),
+ *       undo: async (error, result) => {
+ *         await fetch(`https://example.com/orders/${result.orderId}`, {
+ *           method: "DELETE",
+ *         });
+ *       },
+ *     });
+ *
+ *     await ctx.step("charge-card", async () => {
+ *       throw new Error("Card declined");
+ *     });
+ *
+ *     return order;
+ *   } catch (error) {
+ *     await ctx.rollbackAll(error);
+ *     throw error;
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * Use `waitUntil()` when you already know the exact time the workflow should resume.
+ *
+ * ```ts title="src/workflow.ts"
+ * import { workflow } from "sst/aws/workflow";
+ *
+ * export const handler = workflow.handler(
+ *   async (_event, ctx) => {
+ *     const resumeAt = new Date();
+ *     resumeAt.setMinutes(resumeAt.getMinutes() + 10);
+ *
+ *     await ctx.waitUntil("wait-for-follow-up", resumeAt);
+ *
+ *     return ctx.step("send-follow-up", async () => {
+ *       return { delivered: true };
+ *     });
+ *   },
+ * );
+ * ```
+ */
+export declare namespace workflow {
+    interface Context<TLogger extends durable.DurableLogger = durable.DurableLogger> extends durable.DurableContext<TLogger> {
+        /**
+         * Execute a durable step and register a compensating rollback step if it succeeds.
+         * If `run` throws, nothing is added to the rollback stack for that step.
+         */
+        stepWithRollback<TOutput>(name: string, handler: StepWithRollbackHandler<TOutput, TLogger>, config?: StepConfig<TOutput>): durable.DurablePromise<TOutput>;
+        /**
+         * Wait until the provided time. Delays are rounded up to the nearest second.
+         */
+        waitUntil(name: string, until: Date): durable.DurablePromise<void>;
+        /**
+         * Execute all registered rollback steps in reverse order.
+         */
+        rollbackAll(error: unknown): Promise<void>;
+    }
+    type Handler<TEvent = any, TResult = any, TLogger extends durable.DurableLogger = durable.DurableLogger> = (event: TEvent, context: Context<TLogger>) => Promise<TResult>;
+    type Config = durable.DurableExecutionConfig;
+    type Duration = durable.Duration;
+    type StepConfig<TOutput = any> = durable.StepConfig<TOutput>;
+    type ExecutionStatus = "RUNNING" | "SUCCEEDED" | "FAILED" | "TIMED_OUT" | "STOPPED";
+    interface Resource {
+        /**
+         * The name of the workflow function.
+         */
+        name: string;
+        /**
+         * The version or alias qualifier to invoke.
+         *
+         * Linked `sst.aws.Workflow` resources include this automatically.
+         */
+        qualifier: string;
+    }
+    interface Options {
+        /**
+         * Configure the options for the [aws4fetch](https://github.com/mhart/aws4fetch)
+         * [`AWSClient`](https://github.com/mhart/aws4fetch?tab=readme-ov-file#new-awsclientoptions) used internally by the SDK.
+         */
+        aws?: AwsOptions;
+    }
+    interface StartResponse {
+        /**
+         * The ARN of the durable execution.
+         */
+        arn?: string;
+        /**
+         * The HTTP status code from Lambda.
+         */
+        statusCode: number;
+        /**
+         * The function version that was executed.
+         */
+        version?: string;
+    }
+    interface Execution {
+        /**
+         * The ARN of the durable execution.
+         */
+        arn: string;
+        /**
+         * The durable execution name.
+         */
+        name: string;
+        /**
+         * The ARN of the workflow function.
+         */
+        functionArn: string;
+        /**
+         * The current execution status.
+         */
+        status: ExecutionStatus;
+        /**
+         * When the execution started.
+         */
+        createdAt: Date;
+        /**
+         * When the execution ended, if it has finished.
+         */
+        endedAt?: Date;
+    }
+    interface ListResponse {
+        /**
+         * The matching executions.
+         */
+        executions: Execution[];
+    }
+    interface DescribeResponse extends Execution {
+        /**
+         * The version that started the execution.
+         */
+        version?: string;
+    }
+    interface StopResponse {
+        /**
+         * The ARN of the durable execution.
+         */
+        arn: string;
+        /**
+         * The execution status after the stop call.
+         */
+        status: "STOPPED";
+        /**
+         * When the execution was stopped.
+         */
+        stoppedAt?: Date;
+    }
+    /**
+     * Create a durable workflow handler.
+     *
+     * @example
+     * ```ts title="src/workflow.ts"
+     * import { workflow } from "sst/aws/workflow";
+     *
+     * export const handler = workflow.handler(
+     *   async (_event, ctx) => {
+     *     const user = await ctx.step("load-user", async () => {
+     *       return { id: "user_123", email: "alice@example.com" };
+     *     });
+     *
+     *     await ctx.wait("pause-before-email", "1 minute");
+     *
+     *     return ctx.step("send-email", async () => {
+     *       return { sent: true, userId: user.id };
+     *     });
+     *   },
+     * );
+     * ```
+     */
+    function handler<TEvent = any, TResult = any, TLogger extends durable.DurableLogger = durable.DurableLogger>(input: Handler<TEvent, TResult, TLogger>, config?: Config): durable.DurableLambdaHandler;
+    /**
+     * Start a new workflow execution.
+     *
+     * This is the equivalent to calling
+     * [`Invoke`](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html)
+     * for a durable Lambda function, using the durable invocation flow described in
+     * [Invoking durable Lambda functions](https://docs.aws.amazon.com/lambda/latest/dg/durable-invoking.html).
+     */
+    function start<TPayload = unknown>(resource: Resource, input: StartInput<TPayload>, options?: Options): Promise<StartResponse>;
+    /**
+     * List workflow executions.
+     *
+     * The SDK returns only the first page of results.
+     */
+    function list(resource: Resource, query: ListQuery, options?: Options): Promise<ListResponse>;
+    /**
+     * Get the details for a single workflow execution.
+     */
+    function describe(arn: string, options?: Options): Promise<DescribeResponse>;
+    /**
+     * Stop a running workflow execution.
+     */
+    function stop(arn: string, input?: StopInput, options?: Options): Promise<StopResponse>;
+    /**
+     * Send a successful result for a pending workflow callback.
+     *
+     * This is the equivalent to calling
+     * [`SendDurableExecutionCallbackSuccess`](https://docs.aws.amazon.com/lambda/latest/api/API_SendDurableExecutionCallbackSuccess.html).
+     */
+    function succeed<TPayload = unknown>(token: string, input?: SucceedInput<TPayload>, options?: Options): Promise<void>;
+    /**
+     * Send a failure result for a pending workflow callback.
+     *
+     * This is the equivalent to calling
+     * [`SendDurableExecutionCallbackFailure`](https://docs.aws.amazon.com/lambda/latest/api/API_SendDurableExecutionCallbackFailure.html).
+     */
+    function fail(token: string, input: FailInput, options?: Options): Promise<void>;
+    /**
+     * Send a heartbeat for a pending workflow callback.
+     *
+     * This is useful when the external system handling the callback is still doing
+     * work and needs to prevent the callback from timing out.
+     *
+     * This is the equivalent to calling
+     * [`SendDurableExecutionCallbackHeartbeat`](https://docs.aws.amazon.com/lambda/latest/api/API_SendDurableExecutionCallbackHeartbeat.html).
+     */
+    function heartbeat(token: string, options?: Options): Promise<void>;
+    class StartError extends Error {
+        readonly response: Response;
+        constructor(response: Response);
+    }
+    class ListError extends Error {
+        readonly response: Response;
+        constructor(response: Response);
+    }
+    class DescribeError extends Error {
+        readonly response: Response;
+        constructor(response: Response);
+    }
+    class StopError extends Error {
+        readonly response: Response;
+        constructor(response: Response);
+    }
+    class SucceedError extends Error {
+        readonly response: Response;
+        constructor(response: Response);
+    }
+    class FailError extends Error {
+        readonly response: Response;
+        constructor(response: Response);
+    }
+    class HeartbeatError extends Error {
+        readonly response: Response;
+        constructor(response: Response);
+    }
+    class RollbackError extends Error {
+        readonly stepName: string;
+        readonly originalError: unknown;
+        readonly undoError: unknown;
+        constructor(stepName: string, originalError: unknown, undoError: unknown);
+    }
+}
+interface StepWithRollbackHandler<TOutput = any, TLogger extends durable.DurableLogger = durable.DurableLogger> {
+    /**
+     * The durable step to execute.
+     */
+    run: durable.StepFunc<TOutput, TLogger>;
+    /**
+     * Called during rollback with the original error, the step result, and step context.
+     */
+    undo: (error: unknown, value: TOutput, context: Parameters<durable.StepFunc<void, TLogger>>[0]) => Promise<void>;
+}
+interface StartInput<TPayload = unknown> {
+    /**
+     * The unique name for this workflow execution.
+     */
+    name: string;
+    /**
+     * The event payload passed to the workflow handler.
+     */
+    payload?: TPayload;
+}
+interface SucceedInput<TPayload = unknown> {
+    /**
+     * The payload to resolve the callback with.
+     */
+    payload?: TPayload;
+}
+interface FailInput {
+    /**
+     * The error to reject the callback with. Supports an `Error`, a string,
+     * or an object with camelCase fields like `message`, `type`, `data`, and `stack`.
+     */
+    error: unknown;
+}
+interface StopInput {
+    /**
+     * The error to reject the callback with. Supports an `Error`, a string,
+     * or an object with camelCase fields like `message`, `type`, `data`, and `stack`.
+     */
+    error?: unknown;
+}
+interface ListQuery {
+    status?: workflow.ExecutionStatus;
+    createdAt?: {
+        from?: Date;
+        to?: Date;
+        order?: "asc" | "desc";
+    };
+}
+export {};