eve 0.5.4 → 0.6.0-beta.3

package/dist/src/compiled/@workflow/errors/index.d.ts

@@ -0,0 +1,536 @@
+import type { StringValue } from './_ms.js';
+/**
+ * @internal
+ * All the slugs of the errors used for documentation links.
+ */
+export declare const ERROR_SLUGS: {
+    readonly NODE_JS_MODULE_IN_WORKFLOW: "node-js-module-in-workflow";
+    readonly START_INVALID_WORKFLOW_FUNCTION: "start-invalid-workflow-function";
+    readonly SERIALIZATION_FAILED: "serialization-failed";
+    readonly WEBHOOK_INVALID_RESPOND_WITH_VALUE: "webhook-invalid-respond-with-value";
+    readonly WEBHOOK_RESPONSE_NOT_SENT: "webhook-response-not-sent";
+    readonly FETCH_IN_WORKFLOW_FUNCTION: "fetch-in-workflow";
+    readonly TIMEOUT_FUNCTIONS_IN_WORKFLOW: "timeout-in-workflow";
+    readonly HOOK_CONFLICT: "hook-conflict";
+    readonly CORRUPTED_EVENT_LOG: "corrupted-event-log";
+    readonly REPLAY_DIVERGENCE: "replay-divergence";
+    readonly STEP_NOT_REGISTERED: "step-not-registered";
+    readonly WORKFLOW_NOT_REGISTERED: "workflow-not-registered";
+    readonly RUNTIME_DECRYPTION_FAILED: "runtime-decryption-failed";
+};
+type ErrorSlug = (typeof ERROR_SLUGS)[keyof typeof ERROR_SLUGS];
+interface WorkflowErrorOptions extends ErrorOptions {
+    /**
+     * The slug of the error. This will be used to generate a link to the error documentation.
+     */
+    slug?: ErrorSlug;
+}
+/**
+ * The base class for all Workflow-related errors.
+ *
+ * This error is thrown by the Workflow SDK when internal operations fail.
+ * You can use this class with `instanceof` to catch any Workflow SDK error.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await getRun(runId);
+ * } catch (error) {
+ *   if (error instanceof WorkflowError) {
+ *     console.error('Workflow SDK error:', error.message);
+ *   }
+ * }
+ * ```
+ */
+export declare class WorkflowError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, options?: WorkflowErrorOptions);
+    static is(value: unknown): value is WorkflowError;
+}
+/**
+ * Thrown when a world (storage backend) operation fails unexpectedly.
+ *
+ * This is the catch-all error for world implementations. Specific,
+ * well-known failure modes have dedicated error types (e.g.
+ * EntityConflictError, RunExpiredError, ThrottleError). This error
+ * covers everything else — validation failures, missing entities
+ * without a dedicated type, or unexpected HTTP errors from world-vercel.
+ */
+export declare class WorkflowWorldError extends WorkflowError {
+    status?: number;
+    code?: string;
+    url?: string;
+    /** Retry-After value in seconds, present on 429 and 425 responses */
+    retryAfter?: number;
+    constructor(message: string, options?: {
+        status?: number;
+        url?: string;
+        code?: string;
+        retryAfter?: number;
+        cause?: unknown;
+    });
+    static is(value: unknown): value is WorkflowWorldError;
+}
+/**
+ * Thrown when a workflow run fails during execution.
+ *
+ * This error indicates that the workflow encountered a fatal error and cannot
+ * continue. It is thrown when awaiting `run.returnValue` on a run whose status
+ * is `'failed'`. The `cause` property contains the underlying error with its
+ * message, stack trace, and optional error code.
+ *
+ * Use the static `WorkflowRunFailedError.is()` method for type-safe checking
+ * in catch blocks.
+ *
+ * @example
+ * ```ts
+ * import { WorkflowRunFailedError } from "workflow/internal/errors";
+ *
+ * try {
+ *   const result = await run.returnValue;
+ * } catch (error) {
+ *   if (WorkflowRunFailedError.is(error)) {
+ *     console.error(`Run ${error.runId} failed:`, error.cause.message);
+ *   }
+ * }
+ * ```
+ */
+export declare class WorkflowRunFailedError extends WorkflowError {
+    runId: string;
+    /**
+     * The high-level error category (e.g. USER_ERROR, RUNTIME_ERROR) for the
+     * failed run, from the run_failed event's `errorCode` field.
+     */
+    errorCode?: string;
+    /**
+     * The original thrown value from the failed workflow run, hydrated through
+     * the workflow serialization pipeline. Preserves the original type identity
+     * (Error subclasses, FatalError, custom classes with WORKFLOW_SERIALIZE, etc.)
+     * and custom properties (cause chains, etc.).
+     *
+     * Note: any JavaScript value can be thrown, so this is typed as `unknown`.
+     * Typical values are Error instances, but strings, objects, etc. are also
+     * possible.
+     */
+    cause: unknown;
+    constructor(runId: string, error: unknown, options?: {
+        errorCode?: string;
+    });
+    static is(value: unknown): value is WorkflowRunFailedError;
+}
+/**
+ * Thrown when attempting to get results from an incomplete workflow run.
+ *
+ * This error occurs when you try to access the result of a workflow
+ * that is still running or hasn't completed yet.
+ */
+export declare class WorkflowRunNotCompletedError extends WorkflowError {
+    runId: string;
+    status: string;
+    constructor(runId: string, status: string);
+    static is(value: unknown): value is WorkflowRunNotCompletedError;
+}
+/**
+ * Thrown when the Workflow runtime encounters an internal error.
+ *
+ * This error indicates an issue with workflow execution, such as
+ * serialization failures, starting an invalid workflow function, or
+ * other runtime problems.
+ */
+export declare class WorkflowRuntimeError extends WorkflowError {
+    constructor(message: string, options?: WorkflowErrorOptions);
+    static is(value: unknown): value is WorkflowRuntimeError;
+}
+/**
+ * Thrown when the persisted workflow event log cannot be replayed because it
+ * contains orphaned, duplicate, or mismatched events.
+ *
+ * This is a runtime/infrastructure failure rather than user code throwing.
+ * When this reaches run failure handling, it is recorded with the distinct
+ * `CORRUPTED_EVENT_LOG` code so worlds and backends can track it separately
+ * from generic runtime failures.
+ */
+export declare class CorruptedEventLogError extends WorkflowRuntimeError {
+    constructor(message: string, options?: ErrorOptions);
+    static is(value: unknown): value is CorruptedEventLogError;
+}
+/**
+ * Thrown when the current workflow replay cannot follow the path described by
+ * the recorded event log. A single divergence does not prove that the
+ * persisted history is invalid: a subsequent replay may observe or schedule
+ * work correctly, so the runtime may redeliver before declaring corruption.
+ */
+export declare class ReplayDivergenceError extends WorkflowRuntimeError {
+    readonly eventId: string;
+    constructor(message: string, options: ErrorOptions & {
+        eventId: string;
+    });
+    static is(value: unknown): value is ReplayDivergenceError;
+}
+/**
+ * Optional structured context attached to a {@link RuntimeDecryptionError},
+ * carried over from the underlying decrypt call site to help diagnose the
+ * failure without poking through stacks.
+ */
+export interface RuntimeDecryptionErrorContext {
+    /** The operation that failed — useful to tell encrypt vs decrypt apart. */
+    operation?: 'encrypt' | 'decrypt';
+    /** Byte length of the input payload at the time of the failure. */
+    byteLength?: number;
+    /**
+     * The first 4 bytes of the input payload, decoded as UTF-8 if printable.
+     * Useful for telling apart truncated-but-valid-looking encrypted payloads
+     * from completely unrelated corruption (e.g. an HTML error page surfaced
+     * as a 200 OK).
+     */
+    formatPrefix?: string;
+}
+/**
+ * Thrown when the SDK's built-in AES-GCM encryption layer fails to encrypt
+ * or decrypt a workflow payload.
+ *
+ * This is an internal SDK failure — user code never invokes the SDK's
+ * encryption primitives directly. Common causes:
+ *
+ * - A ciphertext / auth tag mismatch, typically surfaced as the native Web
+ *   Crypto `OperationError: The operation failed for an operation-specific
+ *   reason`. Usually caused by ciphertext mutation or truncation in transit
+ *   between storage and read (truncated HTTP response, edge-cache miss
+ *   returning a partial 200, proxy drop during streaming, etc.).
+ * - A key resolution mismatch (wrong deployment, missing key material).
+ * - A malformed encrypted envelope (too short to contain the GCM nonce
+ *   and tag).
+ *
+ * Extends {@link WorkflowRuntimeError} so the run-failure classifier
+ * routes it to `RUNTIME_ERROR`.
+ */
+export declare class RuntimeDecryptionError extends WorkflowRuntimeError {
+    /** Optional structured context about the failed encrypt/decrypt call. */
+    readonly context?: RuntimeDecryptionErrorContext;
+    constructor(message: string, options?: ErrorOptions & {
+        context?: RuntimeDecryptionErrorContext;
+    });
+    static is(value: unknown): value is RuntimeDecryptionError;
+}
+interface WorkflowBuildErrorOptions extends ErrorOptions {
+    /**
+     * An optional actionable hint appended to the main message, explaining how
+     * the user can resolve the failure. Shown after a blank line.
+     */
+    hint?: string;
+}
+/**
+ * Thrown when the workflow build pipeline (esbuild, SWC transform, file
+ * discovery, bundler integration) fails in a way the user can act on.
+ *
+ * This is distinct from `WorkflowRuntimeError` (which is raised at runtime
+ * by the workflow engine) — `WorkflowBuildError` fires during `pnpm build`,
+ * `next build`, or equivalent, before any workflow has started executing.
+ *
+ * Prefer attaching a short, actionable `hint` (e.g. `run \`pnpm install workflow\``)
+ * as plain text — the rendering layer is responsible for any styling or
+ * "hint:" label. Keeping `hint` plain keeps it useful in non-TTY contexts
+ * (CI logs, structured error serialization) where ANSI escapes are noise.
+ */
+export declare class WorkflowBuildError extends WorkflowError {
+    readonly hint?: string;
+    constructor(message: string, options?: WorkflowBuildErrorOptions);
+    static is(value: unknown): value is WorkflowBuildError;
+}
+interface SerializationErrorOptions extends ErrorOptions {
+    /**
+     * An optional actionable hint appended to the main message, explaining how
+     * the user can resolve the failure (e.g. "register the class with…" or
+     * "move this call inside a step").
+     */
+    hint?: string;
+}
+/**
+ * Thrown when a value cannot be serialized into or deserialized out of the
+ * workflow event log.
+ *
+ * This usually indicates a user-facing mistake: passing a non-serializable
+ * value (class without `WORKFLOW_SERIALIZE`, locked stream, direct workflow
+ * function reference) into a step boundary, or an unregistered class
+ * returning from a step.
+ *
+ * Internal invariants (corrupted buffers, unknown format bytes) should use
+ * `WorkflowRuntimeError` instead — this class is scoped to things the user
+ * can fix in their own code.
+ */
+export declare class SerializationError extends WorkflowError {
+    readonly hint?: string;
+    /**
+     * Serialization errors are deterministic — if a step returns a non-POJO,
+     * replaying the step will always produce the same non-serializable value.
+     * Retrying is guaranteed to fail, so these errors are surfaced as fatal
+     * and skip the step-retry loop. `FatalError.is()` recognizes any error
+     * with `fatal: true` (see `packages/errors/src/index.ts`), so no other
+     * wiring is required for user-thrown SerializationErrors.
+     */
+    readonly fatal = true;
+    constructor(message: string, options?: SerializationErrorOptions);
+    static is(value: unknown): value is SerializationError;
+}
+/**
+ * Thrown when a step function is not registered in the current deployment.
+ *
+ * This is an infrastructure error — not a user code error. It typically means
+ * something went wrong with the bundling/build tooling that caused the step
+ * to not get built correctly.
+ *
+ * When this happens, the step fails (like a FatalError) and control is passed back
+ * to the workflow function, which can optionally handle the failure gracefully.
+ */
+export declare class StepNotRegisteredError extends WorkflowRuntimeError {
+    stepName: string;
+    constructor(stepName: string);
+    static is(value: unknown): value is StepNotRegisteredError;
+}
+/**
+ * Thrown when a workflow function is not registered in the current deployment.
+ *
+ * This is an infrastructure error — not a user code error. It typically means:
+ * - A run was started against a deployment that does not have the workflow
+ *   (e.g., the workflow was renamed or moved and a new run targeted the latest deployment)
+ * - Something went wrong with the bundling/build tooling that caused the workflow
+ *   to not get built correctly
+ *
+ * When this happens, the run fails with a `RUNTIME_ERROR` error code.
+ */
+export declare class WorkflowNotRegisteredError extends WorkflowRuntimeError {
+    workflowName: string;
+    constructor(workflowName: string);
+    static is(value: unknown): value is WorkflowNotRegisteredError;
+}
+/**
+ * Thrown when performing operations on a workflow run that does not exist.
+ *
+ * This error occurs when you call methods on a run object (e.g. `run.status`,
+ * `run.cancel()`, `run.returnValue`) but the underlying run ID does not match
+ * any known workflow run. Note that `getRun(id)` itself is synchronous and will
+ * not throw — this error is raised when subsequent operations discover the run
+ * is missing.
+ *
+ * Use the static `WorkflowRunNotFoundError.is()` method for type-safe checking
+ * in catch blocks.
+ *
+ * @example
+ * ```ts
+ * import { WorkflowRunNotFoundError } from "workflow/internal/errors";
+ *
+ * try {
+ *   const status = await run.status;
+ * } catch (error) {
+ *   if (WorkflowRunNotFoundError.is(error)) {
+ *     console.error(`Run ${error.runId} does not exist`);
+ *   }
+ * }
+ * ```
+ */
+export declare class WorkflowRunNotFoundError extends WorkflowError {
+    runId: string;
+    constructor(runId: string);
+    static is(value: unknown): value is WorkflowRunNotFoundError;
+}
+/**
+ * Thrown when a hook token is already in use by another active workflow run.
+ *
+ * This is a user error — it means the same custom token was passed to
+ * `createHook` in two or more concurrent runs. Use a unique token per run
+ * (or omit the token to let the runtime generate one automatically).
+ */
+export declare class HookConflictError extends WorkflowError {
+    token: string;
+    conflictingRunId?: string;
+    constructor(token: string, conflictingRunId?: string);
+    static is(value: unknown): value is HookConflictError;
+}
+/**
+ * Thrown when calling `resumeHook()` or `resumeWebhook()` with a token that
+ * does not match any active hook.
+ *
+ * Common causes:
+ * - The hook has expired (past its TTL)
+ * - The hook was already disposed after being consumed
+ * - The workflow has not started yet, so the hook does not exist
+ *
+ * A common pattern is to catch this error and start a new workflow run when
+ * the hook does not exist yet (the "resume or start" pattern).
+ *
+ * Use the static `HookNotFoundError.is()` method for type-safe checking in
+ * catch blocks.
+ *
+ * @example
+ * ```ts
+ * import { HookNotFoundError } from "workflow/internal/errors";
+ *
+ * try {
+ *   await resumeHook(token, payload);
+ * } catch (error) {
+ *   if (HookNotFoundError.is(error)) {
+ *     // Hook doesn't exist — start a new workflow run instead
+ *     await startWorkflow("myWorkflow", payload);
+ *   }
+ * }
+ * ```
+ */
+export declare class HookNotFoundError extends WorkflowError {
+    token: string;
+    constructor(token: string);
+    static is(value: unknown): value is HookNotFoundError;
+}
+/**
+ * Thrown when an operation conflicts with the current state of an entity.
+ * This includes attempts to modify an entity already in a terminal state,
+ * create an entity that already exists, or any other 409-style conflict.
+ *
+ * The workflow runtime handles this error automatically. Users interacting
+ * with world storage backends directly may encounter it.
+ */
+export declare class EntityConflictError extends WorkflowWorldError {
+    constructor(message: string);
+    static is(value: unknown): value is EntityConflictError;
+}
+/**
+ * Thrown when a run is no longer available — either because it has been
+ * cleaned up, expired, or already reached a terminal state (completed/failed).
+ *
+ * The workflow runtime handles this error automatically. Users interacting
+ * with world storage backends directly may encounter it.
+ */
+export declare class RunExpiredError extends WorkflowWorldError {
+    constructor(message: string);
+    static is(value: unknown): value is RunExpiredError;
+}
+/**
+ * Thrown when an operation cannot proceed because a required timestamp
+ * (e.g. retryAfter) has not been reached yet.
+ *
+ * The workflow runtime handles this error automatically. Users interacting
+ * with world storage backends directly may encounter it.
+ *
+ * @property retryAfter - Delay in seconds before the operation can be retried.
+ */
+export declare class TooEarlyError extends WorkflowWorldError {
+    constructor(message: string, options?: {
+        retryAfter?: number;
+    });
+    static is(value: unknown): value is TooEarlyError;
+}
+/**
+ * Thrown when a request is rate limited by the workflow backend.
+ *
+ * The workflow runtime handles this error automatically with retry logic.
+ * Users interacting with world storage backends directly may encounter it
+ * if retries are exhausted.
+ *
+ * @property retryAfter - Delay in seconds before the request can be retried.
+ */
+export declare class ThrottleError extends WorkflowWorldError {
+    retryAfter?: number;
+    constructor(message: string, options?: {
+        retryAfter?: number;
+    });
+    static is(value: unknown): value is ThrottleError;
+}
+/**
+ * Thrown when awaiting `run.returnValue` on a workflow run that was cancelled.
+ *
+ * This error indicates that the workflow was explicitly cancelled (via
+ * `run.cancel()`) and will not produce a return value. You can check for
+ * cancellation before awaiting the return value by inspecting `run.status`.
+ *
+ * Use the static `WorkflowRunCancelledError.is()` method for type-safe
+ * checking in catch blocks.
+ *
+ * @example
+ * ```ts
+ * import { WorkflowRunCancelledError } from "workflow/internal/errors";
+ *
+ * try {
+ *   const result = await run.returnValue;
+ * } catch (error) {
+ *   if (WorkflowRunCancelledError.is(error)) {
+ *     console.log(`Run ${error.runId} was cancelled`);
+ *   }
+ * }
+ * ```
+ */
+export declare class WorkflowRunCancelledError extends WorkflowError {
+    runId: string;
+    constructor(runId: string);
+    static is(value: unknown): value is WorkflowRunCancelledError;
+}
+/**
+ * Thrown when attempting to operate on a workflow run that requires a newer World version.
+ *
+ * This error occurs when a run was created with a newer spec version than the
+ * current World implementation supports. To resolve this, upgrade your
+ * `workflow` packages to a version that supports the required spec version.
+ *
+ * Use the static `RunNotSupportedError.is()` method for type-safe checking in
+ * catch blocks.
+ *
+ * @example
+ * ```ts
+ * import { RunNotSupportedError } from "workflow/internal/errors";
+ *
+ * try {
+ *   const status = await run.status;
+ * } catch (error) {
+ *   if (RunNotSupportedError.is(error)) {
+ *     console.error(
+ *       `Run requires spec v${error.runSpecVersion}, ` +
+ *       `but world supports v${error.worldSpecVersion}`
+ *     );
+ *   }
+ * }
+ * ```
+ */
+export declare class RunNotSupportedError extends WorkflowError {
+    readonly runSpecVersion: number;
+    readonly worldSpecVersion: number;
+    constructor(runSpecVersion: number, worldSpecVersion: number);
+    static is(value: unknown): value is RunNotSupportedError;
+}
+/**
+ * A fatal error is an error that cannot be retried.
+ * It will cause the step to fail and the error will
+ * be bubbled up to the workflow logic.
+ *
+ * Any error can opt into the non-retry behavior by setting a `fatal: true`
+ * own property. This is how structured error classes that aren't direct
+ * `FatalError` subclasses (e.g. context-violation errors) signal to the
+ * step handler that retrying will never help — the user's code is calling
+ * a workflow-only API from the wrong context, or similar — and burning
+ * retry attempts just produces a wall of duplicated log output.
+ */
+export declare class FatalError extends Error {
+    fatal: boolean;
+    constructor(message: string);
+    static is(value: unknown): value is FatalError;
+}
+export interface RetryableErrorOptions {
+    /**
+     * The number of milliseconds to wait before retrying the step.
+     * Can also be a duration string (e.g., "5s", "2m") or a Date object.
+     * If not provided, the step will be retried after 1 second (1000 milliseconds).
+     */
+    retryAfter?: number | StringValue | Date;
+}
+/**
+ * An error that can happen during a step execution, allowing
+ * for configuration of the retry behavior.
+ */
+export declare class RetryableError extends Error {
+    /**
+     * The Date when the step should be retried.
+     */
+    retryAfter: Date;
+    constructor(message: string, options?: RetryableErrorOptions);
+    static is(value: unknown): value is RetryableError;
+}
+export declare const VERCEL_403_ERROR_MESSAGE = "Your current vercel account does not have access to this resource. Use `vercel login` or `vercel switch` to ensure you are linked to the right account.";
+export { RUN_ERROR_CODES, type RunErrorCode } from './error-codes.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/compiled/@workflow/errors/index.js

@@ -0,0 +1 @@
+import{C as e,E as t,S as n,T as r,_ as i,a,b as o,c as s,d as c,f as l,g as u,h as d,i as f,l as p,m,n as h,o as g,p as _,r as v,s as y,t as b,u as x,v as S,w as C,x as w,y as T}from"../../_chunks/workflow/dist-6a3viBXZ.js";export{b as CorruptedEventLogError,h as ERROR_SLUGS,v as EntityConflictError,f as FatalError,a as HookConflictError,g as HookNotFoundError,t as RUN_ERROR_CODES,y as ReplayDivergenceError,s as RetryableError,p as RunExpiredError,x as RunNotSupportedError,c as RuntimeDecryptionError,l as SerializationError,_ as StepNotRegisteredError,m as ThrottleError,d as TooEarlyError,u as VERCEL_403_ERROR_MESSAGE,i as WorkflowBuildError,S as WorkflowError,T as WorkflowNotRegisteredError,o as WorkflowRunCancelledError,w as WorkflowRunFailedError,n as WorkflowRunNotCompletedError,e as WorkflowRunNotFoundError,C as WorkflowRuntimeError,r as WorkflowWorldError};