@coji/durably 0.10.0 → 0.12.0

package/README.md

@@ -12,7 +12,7 @@ Step-oriented resumable batch execution for Node.js and browsers using SQLite.
 npm install @coji/durably kysely zod better-sqlite3
 ```
 
-See the [Getting Started Guide](https://coji.github.io/durably/guide/getting-started) for other SQLite backends (libsql, SQLocal for browsers).
+See the [Quick Start](https://coji.github.io/durably/guide/quick-start) for other SQLite backends (libsql, SQLocal for browsers).
 
 ## Quick Start
 
@@ -30,7 +30,7 @@ const myJob = defineJob({
   },
 })
 
-const durably = createDurably({ dialect }).register({ myJob })
+const durably = createDurably({ dialect, jobs: { myJob } })
 
 await durably.init() // migrate + start
 await durably.jobs.myJob.trigger({ id: '123' })

package/dist/{index-BjlCb0gP.d.ts → index-hM7-oiyj.d.ts}

@@ -70,13 +70,12 @@ interface RunDeleteEvent extends BaseEvent {
     labels: Record<string, string>;
 }
 /**
- * Run retry event (emitted when a failed run is retried)
+ * Progress data reported by step.progress()
  */
-interface RunRetryEvent extends BaseEvent {
-    type: 'run:retry';
-    runId: string;
-    jobName: string;
-    labels: Record<string, string>;
+interface ProgressData {
+    current: number;
+    total?: number;
+    message?: string;
 }
 /**
  * Run progress event
@@ -85,11 +84,7 @@ interface RunProgressEvent extends BaseEvent {
     type: 'run:progress';
     runId: string;
     jobName: string;
-    progress: {
-        current: number;
-        total?: number;
-        message?: string;
-    };
+    progress: ProgressData;
     labels: Record<string, string>;
 }
 /**
@@ -136,17 +131,24 @@ interface StepCancelEvent extends BaseEvent {
     stepIndex: number;
     labels: Record<string, string>;
 }
+/**
+ * Log data reported by step.log
+ */
+interface LogData {
+    level: 'info' | 'warn' | 'error';
+    message: string;
+    data?: unknown;
+    stepName?: string | null;
+}
 /**
  * Log write event
  */
-interface LogWriteEvent extends BaseEvent {
+interface LogWriteEvent extends BaseEvent, LogData {
     type: 'log:write';
     runId: string;
     jobName: string;
     labels: Record<string, string>;
     stepName: string | null;
-    level: 'info' | 'warn' | 'error';
-    message: string;
     data: unknown;
 }
 /**
@@ -161,7 +163,7 @@ interface WorkerErrorEvent extends BaseEvent {
 /**
  * All event types as discriminated union
  */
-type DurablyEvent = RunTriggerEvent | RunStartEvent | RunCompleteEvent | RunFailEvent | RunCancelEvent | RunDeleteEvent | RunRetryEvent | RunProgressEvent | StepStartEvent | StepCompleteEvent | StepFailEvent | StepCancelEvent | LogWriteEvent | WorkerErrorEvent;
+type DurablyEvent = RunTriggerEvent | RunStartEvent | RunCompleteEvent | RunFailEvent | RunCancelEvent | RunDeleteEvent | RunProgressEvent | StepStartEvent | StepCompleteEvent | StepFailEvent | StepCancelEvent | LogWriteEvent | WorkerErrorEvent;
 /**
  * Event types for type-safe event names
  */
@@ -179,7 +181,7 @@ type EventInput<T extends EventType> = Omit<EventByType<T>, 'timestamp' | 'seque
 /**
  * All possible event inputs as a union (properly distributed)
  */
-type AnyEventInput = EventInput<'run:trigger'> | EventInput<'run:start'> | EventInput<'run:complete'> | EventInput<'run:fail'> | EventInput<'run:cancel'> | EventInput<'run:delete'> | EventInput<'run:retry'> | EventInput<'run:progress'> | EventInput<'step:start'> | EventInput<'step:complete'> | EventInput<'step:fail'> | EventInput<'step:cancel'> | EventInput<'log:write'> | EventInput<'worker:error'>;
+type AnyEventInput = EventInput<'run:trigger'> | EventInput<'run:start'> | EventInput<'run:complete'> | EventInput<'run:fail'> | EventInput<'run:cancel'> | EventInput<'run:delete'> | EventInput<'run:progress'> | EventInput<'step:start'> | EventInput<'step:complete'> | EventInput<'step:fail'> | EventInput<'step:cancel'> | EventInput<'log:write'> | EventInput<'worker:error'>;
 /**
  * Event listener function
  */
@@ -248,17 +250,17 @@ interface Database {
 /**
  * Run data for creating a new run
  */
-interface CreateRunInput {
+interface CreateRunInput<TLabels extends Record<string, string> = Record<string, string>> {
     jobName: string;
     input: unknown;
     idempotencyKey?: string;
     concurrencyKey?: string;
-    labels?: Record<string, string>;
+    labels?: TLabels;
 }
 /**
  * Run data returned from storage
  */
-interface Run {
+interface Run<TLabels extends Record<string, string> = Record<string, string>> {
     id: string;
     jobName: string;
     input: unknown;
@@ -274,7 +276,7 @@ interface Run {
     } | null;
     output: unknown | null;
     error: string | null;
-    labels: Record<string, string>;
+    labels: TLabels;
     heartbeatAt: string;
     startedAt: string | null;
     completedAt: string | null;
@@ -301,10 +303,14 @@ interface UpdateRunInput {
 /**
  * Run filter options
  */
-interface RunFilter$1 {
+interface RunFilter<TLabels extends Record<string, string> = Record<string, string>> {
     status?: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
-    jobName?: string;
-    labels?: Record<string, string>;
+    /** Filter by job name(s). Pass a string for one, or an array for multiple (OR). */
+    jobName?: string | string[];
+    /** Filter by labels (all specified labels must match) */
+    labels?: {
+        [K in keyof TLabels]?: TLabels[K];
+    };
     /** Maximum number of runs to return */
     limit?: number;
     /** Number of runs to skip (for pagination) */
@@ -362,11 +368,11 @@ interface Log {
  * A client-safe subset of Run, excluding internal fields like
  * heartbeatAt, idempotencyKey, concurrencyKey, and updatedAt.
  */
-type ClientRun = Omit<Run, 'idempotencyKey' | 'concurrencyKey' | 'heartbeatAt' | 'updatedAt'>;
+type ClientRun<TLabels extends Record<string, string> = Record<string, string>> = Omit<Run<TLabels>, 'idempotencyKey' | 'concurrencyKey' | 'heartbeatAt' | 'updatedAt'>;
 /**
  * Project a full Run to a ClientRun by stripping internal fields.
  */
-declare function toClientRun(run: Run): ClientRun;
+declare function toClientRun<TLabels extends Record<string, string> = Record<string, string>>(run: Run<TLabels>): ClientRun<TLabels>;
 /**
  * Storage interface for database operations
  */
@@ -376,9 +382,10 @@ interface Storage {
     updateRun(runId: string, data: UpdateRunInput): Promise<void>;
     deleteRun(runId: string): Promise<void>;
     getRun<T extends Run = Run>(runId: string): Promise<T | null>;
-    getRuns<T extends Run = Run>(filter?: RunFilter$1): Promise<T[]>;
+    getRuns<T extends Run = Run>(filter?: RunFilter): Promise<T[]>;
     claimNextPendingRun(excludeConcurrencyKeys: string[]): Promise<Run | null>;
     createStep(input: CreateStepInput): Promise<Step>;
+    deleteSteps(runId: string): Promise<void>;
     getSteps(runId: string): Promise<Step[]>;
     getCompletedStep(runId: string, name: string): Promise<Step | null>;
     createLog(input: CreateLogInput): Promise<Log>;
@@ -411,39 +418,36 @@ interface StepContext {
     };
 }
 /**
- * Trigger options
+ * Trigger options for trigger() and batchTrigger()
  */
-interface TriggerOptions {
+interface TriggerOptions<TLabels extends Record<string, string> = Record<string, string>> {
     idempotencyKey?: string;
     concurrencyKey?: string;
-    labels?: Record<string, string>;
-    /** Timeout in milliseconds for triggerAndWait() */
-    timeout?: number;
+    labels?: TLabels;
 }
 /**
- * Run filter options
+ * Options for triggerAndWait() (extends TriggerOptions with wait-specific options)
  */
-interface RunFilter {
-    status?: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
-    jobName?: string;
-    labels?: Record<string, string>;
-    /** Maximum number of runs to return */
-    limit?: number;
-    /** Number of runs to skip (for pagination) */
-    offset?: number;
+interface TriggerAndWaitOptions<TLabels extends Record<string, string> = Record<string, string>> extends TriggerOptions<TLabels> {
+    /** Timeout in milliseconds */
+    timeout?: number;
+    /** Called when step.progress() is invoked during execution */
+    onProgress?: (progress: ProgressData) => void | Promise<void>;
+    /** Called when step.log is invoked during execution */
+    onLog?: (log: LogData) => void | Promise<void>;
 }
 /**
  * Typed run with output type
  */
-interface TypedRun<TOutput> extends Omit<Run, 'output'> {
+interface TypedRun<TOutput, TLabels extends Record<string, string> = Record<string, string>> extends Omit<Run<TLabels>, 'output'> {
     output: TOutput | null;
 }
 /**
  * Batch trigger input - either just the input or input with options
  */
-type BatchTriggerInput<TInput> = TInput | {
+type BatchTriggerInput<TInput, TLabels extends Record<string, string> = Record<string, string>> = TInput | {
     input: TInput;
-    options?: TriggerOptions;
+    options?: TriggerOptions<TLabels>;
 };
 /**
  * Result of triggerAndWait
@@ -455,30 +459,30 @@ interface TriggerAndWaitResult<TOutput> {
 /**
  * Job handle returned by defineJob
  */
-interface JobHandle<TName extends string, TInput, TOutput> {
+interface JobHandle<TName extends string, TInput, TOutput, TLabels extends Record<string, string> = Record<string, string>> {
     readonly name: TName;
     /**
      * Trigger a new run
      */
-    trigger(input: TInput, options?: TriggerOptions): Promise<TypedRun<TOutput>>;
+    trigger(input: TInput, options?: TriggerOptions<TLabels>): Promise<TypedRun<TOutput, TLabels>>;
     /**
      * Trigger a new run and wait for completion
      * Returns the output directly, throws if the run fails
      */
-    triggerAndWait(input: TInput, options?: TriggerOptions): Promise<TriggerAndWaitResult<TOutput>>;
+    triggerAndWait(input: TInput, options?: TriggerAndWaitOptions<TLabels>): Promise<TriggerAndWaitResult<TOutput>>;
     /**
      * Trigger multiple runs in a batch
      * All inputs are validated before any runs are created
      */
-    batchTrigger(inputs: BatchTriggerInput<TInput>[]): Promise<TypedRun<TOutput>[]>;
+    batchTrigger(inputs: BatchTriggerInput<TInput, TLabels>[]): Promise<TypedRun<TOutput, TLabels>[]>;
     /**
      * Get a run by ID
      */
-    getRun(id: string): Promise<TypedRun<TOutput> | null>;
+    getRun(id: string): Promise<TypedRun<TOutput, TLabels> | null>;
     /**
      * Get runs with optional filter
      */
-    getRuns(filter?: Omit<RunFilter, 'jobName'>): Promise<TypedRun<TOutput>[]>;
+    getRuns(filter?: Omit<RunFilter<TLabels>, 'jobName'>): Promise<TypedRun<TOutput, TLabels>[]>;
 }
 
 /**
@@ -544,29 +548,47 @@ declare function defineJob<TName extends string, TInputSchema extends z.ZodType,
 /**
  * Options for creating a Durably instance
  */
-interface DurablyOptions {
+interface DurablyOptions<TLabels extends Record<string, string> = Record<string, string>, TJobs extends Record<string, JobDefinition<string, any, any>> = Record<string, never>> {
     dialect: Dialect;
     pollingInterval?: number;
     heartbeatInterval?: number;
     staleThreshold?: number;
+    cleanupSteps?: boolean;
+    /**
+     * Zod schema for labels. When provided:
+     * - Labels are type-checked at compile time
+     * - Labels are validated at runtime on trigger()
+     */
+    labels?: z.ZodType<TLabels>;
+    /**
+     * Job definitions to register. Shorthand for calling .register() after creation.
+     * @example
+     * ```ts
+     * const durably = createDurably({
+     *   dialect,
+     *   jobs: { importCsv: importCsvJob, syncUsers: syncUsersJob },
+     * })
+     * ```
+     */
+    jobs?: TJobs;
 }
 /**
  * Plugin interface for extending Durably
  */
 interface DurablyPlugin {
     name: string;
-    install(durably: Durably<any>): void;
+    install(durably: Durably<any, any>): void;
 }
 /**
  * Helper type to transform JobDefinition record to JobHandle record
  */
-type TransformToHandles<TJobs extends Record<string, JobDefinition<string, unknown, unknown>>> = {
-    [K in keyof TJobs]: TJobs[K] extends JobDefinition<infer TName, infer TInput, infer TOutput> ? JobHandle<TName & string, TInput, TOutput> : never;
+type TransformToHandles<TJobs extends Record<string, JobDefinition<string, unknown, unknown>>, TLabels extends Record<string, string> = Record<string, string>> = {
+    [K in keyof TJobs]: TJobs[K] extends JobDefinition<infer TName, infer TInput, infer TOutput> ? JobHandle<TName & string, TInput, TOutput, TLabels> : never;
 };
 /**
  * Durably instance with type-safe jobs
  */
-interface Durably<TJobs extends Record<string, JobHandle<string, unknown, unknown>> = Record<string, never>> {
+interface Durably<TJobs extends Record<string, JobHandle<string, unknown, unknown, Record<string, string>>> = Record<string, never>, TLabels extends Record<string, string> = Record<string, string>> {
     /**
      * Registered job handles (type-safe)
      */
@@ -622,7 +644,7 @@ interface Durably<TJobs extends Record<string, JobHandle<string, unknown, unknow
      * // Usage: durably.jobs.importCsv.trigger({ rows: [...] })
      * ```
      */
-    register<TNewJobs extends Record<string, JobDefinition<string, any, any>>>(jobDefs: TNewJobs): Durably<TJobs & TransformToHandles<TNewJobs>>;
+    register<TNewJobs extends Record<string, JobDefinition<string, any, any>>>(jobDefs: TNewJobs): Durably<TJobs & TransformToHandles<TNewJobs, TLabels>, TLabels>;
     /**
      * Start the worker polling loop
      */
@@ -632,10 +654,10 @@ interface Durably<TJobs extends Record<string, JobHandle<string, unknown, unknow
      */
     stop(): Promise<void>;
     /**
-     * Retry a failed run by resetting it to pending
-     * @throws Error if run is not in failed status
+     * Create a fresh run from a completed, failed, or cancelled run
+     * @throws Error if run is pending, running, or does not exist
      */
-    retry(runId: string): Promise<void>;
+    retrigger(runId: string): Promise<Run<TLabels>>;
     /**
      * Cancel a pending or running run
      * @throws Error if run is already completed, failed, or cancelled
@@ -658,7 +680,7 @@ interface Durably<TJobs extends Record<string, JobHandle<string, unknown, unknow
      * const typedRun = await durably.getRun<MyRun>(runId)
      * ```
      */
-    getRun<T extends Run = Run>(runId: string): Promise<T | null>;
+    getRun<T extends Run<TLabels> = Run<TLabels>>(runId: string): Promise<T | null>;
     /**
      * Get runs with optional filtering
      * @example
@@ -671,7 +693,7 @@ interface Durably<TJobs extends Record<string, JobHandle<string, unknown, unknow
      * const typedRuns = await durably.getRuns<MyRun>({ jobName: 'my-job' })
      * ```
      */
-    getRuns<T extends Run = Run>(filter?: RunFilter$1): Promise<T[]>;
+    getRuns<T extends Run<TLabels> = Run<TLabels>>(filter?: RunFilter<TLabels>): Promise<T[]>;
     /**
      * Register a plugin
      */
@@ -680,7 +702,7 @@ interface Durably<TJobs extends Record<string, JobHandle<string, unknown, unknow
      * Get a registered job handle by name
      * Returns undefined if job is not registered
      */
-    getJob<TName extends string = string>(name: TName): JobHandle<TName, Record<string, unknown>, unknown> | undefined;
+    getJob<TName extends string = string>(name: TName): JobHandle<TName, Record<string, unknown>, unknown, TLabels> | undefined;
     /**
      * Subscribe to events for a specific run
      * Returns a ReadableStream that can be used for SSE
@@ -690,11 +712,14 @@ interface Durably<TJobs extends Record<string, JobHandle<string, unknown, unknow
 /**
  * Create a Durably instance
  */
-declare function createDurably(options: DurablyOptions): Durably<Record<string, never>>;
+declare function createDurably<TLabels extends Record<string, string> = Record<string, string>, TJobs extends Record<string, JobDefinition<string, any, any>> = Record<string, never>>(options: DurablyOptions<TLabels, TJobs> & {
+    jobs: TJobs;
+}): Durably<TransformToHandles<TJobs, TLabels>, TLabels>;
+declare function createDurably<TLabels extends Record<string, string> = Record<string, string>>(options: DurablyOptions<TLabels>): Durably<Record<string, never>, TLabels>;
 
 /**
  * Plugin that persists log events to the database
  */
 declare function withLogPersistence(): DurablyPlugin;
 
-export { type StepsTable as A, createDurably as B, type ClientRun as C, type Durably as D, type ErrorHandler as E, defineJob as F, toClientRun as G, withLogPersistence as H, type JobDefinition as J, type Log as L, type Run as R, type SchemaVersionsTable as S, type TriggerAndWaitResult as T, type WorkerErrorEvent as W, type Database as a, type DurablyEvent as b, type DurablyOptions as c, type DurablyPlugin as d, type EventType as e, type JobHandle as f, type JobInput as g, type JobOutput as h, type LogWriteEvent as i, type LogsTable as j, type RunCancelEvent as k, type RunCompleteEvent as l, type RunDeleteEvent as m, type RunFailEvent as n, type RunFilter$1 as o, type RunProgressEvent as p, type RunRetryEvent as q, type RunStartEvent as r, type RunTriggerEvent as s, type RunsTable as t, type Step as u, type StepCancelEvent as v, type StepCompleteEvent as w, type StepContext as x, type StepFailEvent as y, type StepStartEvent as z };
+export { type StepsTable as A, type BatchTriggerInput as B, type ClientRun as C, type Durably as D, type ErrorHandler as E, type TriggerAndWaitResult as F, type TriggerOptions as G, createDurably as H, defineJob as I, type JobDefinition as J, toClientRun as K, type Log as L, withLogPersistence as M, type ProgressData as P, type Run as R, type SchemaVersionsTable as S, type TriggerAndWaitOptions as T, type WorkerErrorEvent as W, type RunFilter as a, type Database as b, type DurablyEvent as c, type DurablyOptions as d, type DurablyPlugin as e, type EventType as f, type JobHandle as g, type JobInput as h, type JobOutput as i, type LogData as j, type LogWriteEvent as k, type LogsTable as l, type RunCancelEvent as m, type RunCompleteEvent as n, type RunDeleteEvent as o, type RunFailEvent as p, type RunProgressEvent as q, type RunStartEvent as r, type RunTriggerEvent as s, type RunsTable as t, type Step as u, type StepCancelEvent as v, type StepCompleteEvent as w, type StepContext as x, type StepFailEvent as y, type StepStartEvent as z };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { D as Durably } from './index-BjlCb0gP.js';
-export { C as ClientRun, a as Database, b as DurablyEvent, c as DurablyOptions, d as DurablyPlugin, E as ErrorHandler, e as EventType, J as JobDefinition, f as JobHandle, g as JobInput, h as JobOutput, L as Log, i as LogWriteEvent, j as LogsTable, R as Run, k as RunCancelEvent, l as RunCompleteEvent, m as RunDeleteEvent, n as RunFailEvent, o as RunFilter, p as RunProgressEvent, q as RunRetryEvent, r as RunStartEvent, s as RunTriggerEvent, t as RunsTable, S as SchemaVersionsTable, u as Step, v as StepCancelEvent, w as StepCompleteEvent, x as StepContext, y as StepFailEvent, z as StepStartEvent, A as StepsTable, T as TriggerAndWaitResult, W as WorkerErrorEvent, B as createDurably, F as defineJob, G as toClientRun, H as withLogPersistence } from './index-BjlCb0gP.js';
+import { R as Run, a as RunFilter, D as Durably } from './index-hM7-oiyj.js';
+export { B as BatchTriggerInput, C as ClientRun, b as Database, c as DurablyEvent, d as DurablyOptions, e as DurablyPlugin, E as ErrorHandler, f as EventType, J as JobDefinition, g as JobHandle, h as JobInput, i as JobOutput, L as Log, j as LogData, k as LogWriteEvent, l as LogsTable, P as ProgressData, m as RunCancelEvent, n as RunCompleteEvent, o as RunDeleteEvent, p as RunFailEvent, q as RunProgressEvent, r as RunStartEvent, s as RunTriggerEvent, t as RunsTable, S as SchemaVersionsTable, u as Step, v as StepCancelEvent, w as StepCompleteEvent, x as StepContext, y as StepFailEvent, z as StepStartEvent, A as StepsTable, T as TriggerAndWaitOptions, F as TriggerAndWaitResult, G as TriggerOptions, W as WorkerErrorEvent, H as createDurably, I as defineJob, K as toClientRun, M as withLogPersistence } from './index-hM7-oiyj.js';
 import 'kysely';
 import 'zod';
 
@@ -12,15 +12,23 @@ declare class CancelledError extends Error {
     constructor(runId: string);
 }
 
+/**
+ * Run operation types for onRunAccess
+ */
+type RunOperation = 'read' | 'subscribe' | 'steps' | 'retrigger' | 'cancel' | 'delete';
+/**
+ * Subscription filter — only fields that SSE subscriptions actually support.
+ */
+type RunsSubscribeFilter<TLabels extends Record<string, string> = Record<string, string>> = Pick<RunFilter<TLabels>, 'jobName' | 'labels'>;
 /**
  * Request body for triggering a job
  */
-interface TriggerRequest {
+interface TriggerRequest<TLabels extends Record<string, string> = Record<string, string>> {
     jobName: string;
-    input: Record<string, unknown>;
+    input: unknown;
     idempotencyKey?: string;
     concurrencyKey?: string;
-    labels?: Record<string, string>;
+    labels?: TLabels;
 }
 /**
  * Response for trigger endpoint
@@ -28,127 +36,69 @@ interface TriggerRequest {
 interface TriggerResponse {
     runId: string;
 }
+/**
+ * Auth middleware configuration.
+ * When `auth` is set, `authenticate` is required.
+ * TContext is inferred from authenticate's return type.
+ * TLabels is inferred from the Durably instance.
+ */
+interface AuthConfig<TContext, TLabels extends Record<string, string> = Record<string, string>> {
+    /** Authenticate every request. Return context or throw Response to reject. */
+    authenticate: (request: Request) => Promise<TContext> | TContext;
+    /** Guard before trigger. Called after body validation and job resolution. */
+    onTrigger?: (ctx: TContext, trigger: TriggerRequest<TLabels>) => Promise<void> | void;
+    /** Guard before run-level operations. Run is pre-fetched. */
+    onRunAccess?: (ctx: TContext, run: Run<TLabels>, info: {
+        operation: RunOperation;
+    }) => Promise<void> | void;
+    /** Scope runs list queries (GET /runs). */
+    scopeRuns?: (ctx: TContext, filter: RunFilter<TLabels>) => RunFilter<TLabels> | Promise<RunFilter<TLabels>>;
+    /** Scope runs subscribe stream (GET /runs/subscribe). Falls back to scopeRuns if not set. */
+    scopeRunsSubscribe?: (ctx: TContext, filter: RunsSubscribeFilter<TLabels>) => RunsSubscribeFilter<TLabels> | Promise<RunsSubscribeFilter<TLabels>>;
+}
 /**
  * Handler interface for HTTP endpoints
  */
 interface DurablyHandler {
     /**
-     * Handle all Durably HTTP requests with automatic routing
+     * Handle all Durably HTTP requests with automatic routing + auth
      *
      * Routes:
      * - GET  {basePath}/subscribe?runId=xxx - SSE stream
      * - GET  {basePath}/runs - List runs
+     * - GET  {basePath}/runs/subscribe - SSE stream of run updates
      * - GET  {basePath}/run?runId=xxx - Get single run
+     * - GET  {basePath}/steps?runId=xxx - Get steps
      * - POST {basePath}/trigger - Trigger a job
-     * - POST {basePath}/retry?runId=xxx - Retry a failed run
+     * - POST {basePath}/retrigger?runId=xxx - Create a fresh run from a terminal run
      * - POST {basePath}/cancel?runId=xxx - Cancel a run
-     *
-     * @param request - The incoming HTTP request
-     * @param basePath - The base path to strip from the URL (e.g., '/api/durably')
-     * @returns Response or null if route not matched
-     *
-     * @example
-     * ```ts
-     * // React Router / Remix
-     * export async function loader({ request }) {
-     *   return durablyHandler.handle(request, '/api/durably')
-     * }
-     * export async function action({ request }) {
-     *   return durablyHandler.handle(request, '/api/durably')
-     * }
-     * ```
+     * - DELETE {basePath}/run?runId=xxx - Delete a run
      */
     handle(request: Request, basePath: string): Promise<Response>;
-    /**
-     * Handle job trigger request
-     * Expects POST with JSON body: { jobName, input, idempotencyKey?, concurrencyKey? }
-     * Returns JSON: { runId }
-     */
-    trigger(request: Request): Promise<Response>;
-    /**
-     * Handle subscription request
-     * Expects GET with query param: runId
-     * Returns SSE stream of events
-     */
-    subscribe(request: Request): Response;
-    /**
-     * Handle runs list request
-     * Expects GET with optional query params: jobName, status, limit, offset
-     * Returns JSON array of runs
-     */
-    runs(request: Request): Promise<Response>;
-    /**
-     * Handle single run request
-     * Expects GET with query param: runId
-     * Returns JSON run object or 404
-     */
-    run(request: Request): Promise<Response>;
-    /**
-     * Handle retry request
-     * Expects POST with query param: runId
-     * Returns JSON: { success: true }
-     */
-    retry(request: Request): Promise<Response>;
-    /**
-     * Handle cancel request
-     * Expects POST with query param: runId
-     * Returns JSON: { success: true }
-     */
-    cancel(request: Request): Promise<Response>;
-    /**
-     * Handle delete request
-     * Expects DELETE with query param: runId
-     * Returns JSON: { success: true }
-     */
-    delete(request: Request): Promise<Response>;
-    /**
-     * Handle steps request
-     * Expects GET with query param: runId
-     * Returns JSON array of steps
-     */
-    steps(request: Request): Promise<Response>;
-    /**
-     * Handle runs subscription request
-     * Expects GET with optional query param: jobName
-     * Returns SSE stream of run update notifications
-     */
-    runsSubscribe(request: Request): Response;
 }
 /**
  * Options for createDurablyHandler
  */
-interface CreateDurablyHandlerOptions {
+interface CreateDurablyHandlerOptions<TContext = undefined, TLabels extends Record<string, string> = Record<string, string>> {
     /**
-     * Called before handling each request.
+     * Called before handling each request (after authentication).
      * Use this to initialize Durably (migrate, start worker, etc.)
-     *
-     * @example
-     * ```ts
-     * const durablyHandler = createDurablyHandler(durably, {
-     *   onRequest: async () => {
-     *     await durably.migrate()
-     *     durably.start()
-     *   }
-     * })
-     * ```
      */
     onRequest?: () => Promise<void> | void;
     /**
      * Throttle interval in milliseconds for SSE progress events.
-     * When set, `run:progress` events are throttled per run so the client
-     * receives at most one progress update per throttle window.
-     * The first and last progress events are always delivered.
-     * Non-progress events are never throttled.
-     *
-     * Set to 0 to disable throttling.
      * @default 100
      */
     sseThrottleMs?: number;
+    /**
+     * Auth middleware. When set, authenticate is required and auth applies to ALL endpoints.
+     */
+    auth?: AuthConfig<TContext, TLabels>;
 }
 /**
  * Create HTTP handlers for Durably
  * Uses Web Standard Request/Response for framework-agnostic usage
  */
-declare function createDurablyHandler(durably: Durably, options?: CreateDurablyHandlerOptions): DurablyHandler;
+declare function createDurablyHandler<TContext = undefined, TLabels extends Record<string, string> = Record<string, string>>(durably: Durably<any, TLabels>, options?: CreateDurablyHandlerOptions<TContext, TLabels>): DurablyHandler;
 
-export { CancelledError, type CreateDurablyHandlerOptions, Durably, type DurablyHandler, type TriggerRequest, type TriggerResponse, createDurablyHandler };
+export { type AuthConfig, CancelledError, type CreateDurablyHandlerOptions, Durably, type DurablyHandler, Run, RunFilter, type RunOperation, type RunsSubscribeFilter, type TriggerRequest, type TriggerResponse, createDurablyHandler };