@ekodb/ekodb-client 0.16.0 → 0.18.0

package/src/functions.ts

@@ -14,6 +14,19 @@ export interface UserFunction {
   tags?: string[];
   created_at?: string;
   updated_at?: string;
+  /**
+   * REST method this function answers — `"GET"`, `"POST"`, etc.
+   * Pair with `http_path` to expose the function under the
+   * path-routed dispatcher at `/api/route/{path}`.
+   * Requires ekoDB >= 0.42.0.
+   */
+  http_method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  /**
+   * REST path pattern (e.g. `"/users/:id"`). Path segments
+   * starting with `:` are extracted into the function's params
+   * map at call time. Requires ekoDB >= 0.42.0.
+   */
+  http_path?: string;
 }
 
 export interface ParameterDefinition {
@@ -226,6 +239,260 @@ export type FunctionStageConfig =
       timeout_seconds?: number;
       output_field?: string;
       collection?: string;
+    }
+  | {
+      /**
+       * Bcrypt-hash a plaintext value and add the result to every record in
+       * the working data as `output_field`. Requires ekoDB >= 0.41.0.
+       */
+      type: "BcryptHash";
+      plain: string;
+      cost?: number;
+      output_field: string;
+    }
+  | {
+      /**
+       * Verify a plaintext against a bcrypt hash stored on the first record
+       * in the working data and write a boolean result into `output_field`.
+       * Pair with an `If` stage for login flows. Requires ekoDB >= 0.41.0.
+       */
+      type: "BcryptVerify";
+      plain: string;
+      hash_field: string;
+      output_field: string;
+    }
+  | {
+      /**
+       * Generate a cryptographically-random token and add it to every
+       * record in the working data. Requires ekoDB >= 0.41.0.
+       */
+      type: "RandomToken";
+      bytes: number;
+      encoding?: "hex" | "base64" | "base64url";
+      output_field: string;
+    }
+  | {
+      /**
+       * Sign a JWT and write the resulting token to every working
+       * record. Pair with `BcryptVerify` to issue a session token
+       * after login. Use `"{{env.JWT_SECRET}}"` for `secret` so the
+       * LLM never sees the operator-owned signing key. `iat` and
+       * `exp` are auto-stamped when `expires_in_secs` is set.
+       * Requires ekoDB >= 0.42.0.
+       */
+      type: "JwtSign";
+      claims: Record<string, unknown>;
+      secret: string;
+      algorithm?: "HS256" | "HS384" | "HS512";
+      expires_in_secs?: number;
+      output_field: string;
+    }
+  | {
+      /**
+       * Verify a JWT held in `token_field` on the first working
+       * record. On success, writes the decoded claims object into
+       * `output_field`. On failure, writes `null` so callers can
+       * branch with `If { FieldEquals { value: null } }` to reject.
+       * Requires ekoDB >= 0.42.0.
+       */
+      type: "JwtVerify";
+      token_field: string;
+      secret: string;
+      algorithm?: "HS256" | "HS384" | "HS512";
+      output_field: string;
+    }
+  | {
+      /**
+       * Send a transactional email through a provider's REST API.
+       * Today only `provider = "sendgrid"` is supported. Pull the
+       * API key from `"{{env.SENDGRID_API_KEY}}"` so the LLM never
+       * sees the operator-owned secret. Result envelope
+       * `{provider_status, provider_message, provider}` is written
+       * to `output_field` (defaults to `"email_send"`).
+       * Requires ekoDB >= 0.42.0.
+       */
+      type: "EmailSend";
+      to: string;
+      subject: string;
+      body: string;
+      from: string;
+      reply_to?: string;
+      api_key: string;
+      provider?: "sendgrid";
+      html?: boolean;
+      output_field?: string;
+    }
+  | {
+      /** HMAC-SHA256/384/512 sign. Requires ekoDB >= 0.42.0. */
+      type: "HmacSign";
+      input: string;
+      secret: string;
+      algorithm?: "sha256" | "sha384" | "sha512";
+      output_field: string;
+      encoding?: "hex" | "base64";
+    }
+  | {
+      /** HMAC verify (constant-time). Writes a boolean. */
+      type: "HmacVerify";
+      input: string;
+      provided_mac: string;
+      secret: string;
+      algorithm?: "sha256" | "sha384" | "sha512";
+      encoding?: "hex" | "base64";
+      output_field: string;
+    }
+  | {
+      /** AES-256-GCM authenticated encryption. */
+      type: "AesEncrypt";
+      plaintext: string;
+      key: string;
+      key_encoding?: "hex" | "base64" | "base64url";
+      output_field: string;
+    }
+  | {
+      /** AES-256-GCM decrypt. Reads `{ciphertext, nonce}` envelope from `ciphertext_field`. */
+      type: "AesDecrypt";
+      ciphertext_field: string;
+      key: string;
+      key_encoding?: "hex" | "base64" | "base64url";
+      output_field: string;
+    }
+  | {
+      /** Generate a v4 UUID into `output_field`. */
+      type: "UuidGenerate";
+      output_field: string;
+    }
+  | {
+      /** TOTP code generation (RFC 6238). */
+      type: "TotpGenerate";
+      secret: string;
+      digits?: 6 | 8;
+      period?: number;
+      algorithm?: "sha1" | "sha256" | "sha512";
+      output_field: string;
+    }
+  | {
+      /** TOTP verify; tolerates `skew` time-steps either side. */
+      type: "TotpVerify";
+      code: string;
+      secret: string;
+      digits?: 6 | 8;
+      period?: number;
+      algorithm?: "sha1" | "sha256" | "sha512";
+      skew?: number;
+      output_field: string;
+    }
+  | {
+      /** Base64 encode (`url_safe = true` for URL-safe / no-pad). */
+      type: "Base64Encode";
+      input: string;
+      url_safe?: boolean;
+      output_field: string;
+    }
+  | {
+      /** Base64 decode → UTF-8 string. Fail-closed. */
+      type: "Base64Decode";
+      input: string;
+      url_safe?: boolean;
+      output_field: string;
+    }
+  | {
+      /** Hex encode (lowercase). */
+      type: "HexEncode";
+      input: string;
+      output_field: string;
+    }
+  | {
+      /** Hex decode → UTF-8 string. Fail-closed. */
+      type: "HexDecode";
+      input: string;
+      output_field: string;
+    }
+  | {
+      /** URL-friendly slug. */
+      type: "Slugify";
+      input: string;
+      output_field: string;
+    }
+  | {
+      /**
+       * Idempotency-key claim (KV SETNX with TTL). Writes
+       * `{claimed: true, key}` on first call, `{claimed: false, key,
+       * response}` on replay. Requires ekoDB >= 0.42.0.
+       */
+      type: "IdempotencyClaim";
+      key: string;
+      ttl_secs: number;
+      output_field: string;
+    }
+  | {
+      /**
+       * Fixed-window rate-limit gate. `on_exceed` either errors
+       * (`"fail"`, default) or writes `allowed: false` (`"skip"`).
+       */
+      type: "RateLimit";
+      key: string;
+      limit: number;
+      window_secs: number;
+      on_exceed?: "fail" | "skip";
+      output_field: string;
+    }
+  | {
+      /** Distributed-lock acquire (token-fenced). */
+      type: "LockAcquire";
+      key: string;
+      ttl_secs: number;
+      output_field: string;
+    }
+  | {
+      /** Distributed-lock release; token-fenced (no foreign release). */
+      type: "LockRelease";
+      key: string;
+      token: string;
+      output_field: string;
+    }
+  | {
+      /**
+       * Try/Catch error handling for graceful failure recovery.
+       * Executes try_functions, and if any fail, executes catch_functions.
+       */
+      type: "TryCatch";
+      try_functions: FunctionStageConfig[];
+      catch_functions: FunctionStageConfig[];
+      output_error_field?: string;
+    }
+  | {
+      /**
+       * Execute multiple functions in parallel (concurrently).
+       * All functions run simultaneously, results are merged.
+       */
+      type: "Parallel";
+      functions: FunctionStageConfig[];
+      wait_for_all: boolean;
+    }
+  | {
+      /** Sleep/delay execution for rate limiting or timing control. */
+      type: "Sleep";
+      duration_ms: string | number;
+    }
+  | {
+      /**
+       * Return a shaped response (final output formatting).
+       * Constructs the final response object from current execution context.
+       */
+      type: "Return";
+      fields: Record<string, any>;
+      status_code?: number;
+    }
+  | {
+      /**
+       * Validate data against a JSON schema before processing.
+       * Prevents invalid data from corrupting database or causing errors downstream.
+       */
+      type: "Validate";
+      schema: Record<string, any>;
+      data_field: string;
+      on_error?: FunctionStageConfig[];
     };
 
 export interface ChatMessage {
@@ -300,8 +567,54 @@ export interface StageStats {
   execution_time_ms: number;
 }
 
+/**
+ * Reference a call-time function parameter inside a stored-function stage
+ * body (Insert.record, Update.updates, UpdateById.updates,
+ * FindOneAndUpdate.updates, BatchInsert.records, or any nested JSON value).
+ *
+ * Returns the structural placeholder `{"type": "Parameter", "name": "<name>"}`.
+ * ekoDB's `resolve_json_parameters` recognizes this shape and substitutes the
+ * actual parameter value at execution time, preserving the original FieldType
+ * (Binary, DateTime, UUID, Decimal, Duration, Number, Set, Vector) via the
+ * `{type,value}` wrapped form. Safe to use for any type.
+ *
+ * This is the structural alternative to the text-level `"{{name}}"` form;
+ * both are accepted but structural placeholders are preferred when the
+ * parameter is a whole-object Record or a value whose type would be lost in
+ * raw JSON.
+ *
+ * @example
+ * ```ts
+ * const createUser: UserFunction = {
+ *   label: "users_create",
+ *   name: "Create user",
+ *   parameters: {
+ *     record: { required: true },
+ *   },
+ *   functions: [
+ *     Stage.insert("users", Stage.param("record")),
+ *   ],
+ * };
+ * ```
+ */
+export interface ParameterRef {
+  type: "Parameter";
+  name: string;
+}
+
+export function parameterRef(name: string): ParameterRef {
+  return { type: "Parameter", name };
+}
+
 // Stage builder functions
 export const Stage = {
+  /**
+   * Shorthand for `parameterRef(name)` — builds the structural placeholder
+   * `{"type": "Parameter", "name": name}`. See `parameterRef` for the full
+   * explanation and example.
+   */
+  param: (name: string): ParameterRef => parameterRef(name),
+
   findAll: (collection: string): FunctionStageConfig => ({
     type: "FindAll",
     collection,
@@ -344,7 +657,7 @@ export const Stage = {
 
   insert: (
     collection: string,
-    record: Record<string, any>,
+    record: Record<string, any> | ParameterRef,
     bypassRipple = false,
     ttl?: number,
   ): FunctionStageConfig => ({
@@ -358,7 +671,7 @@ export const Stage = {
   update: (
     collection: string,
     filter: Record<string, any>,
-    updates: Record<string, any>,
+    updates: Record<string, any> | ParameterRef,
     bypassRipple = false,
     ttl?: number,
   ): FunctionStageConfig => ({
@@ -373,7 +686,7 @@ export const Stage = {
   updateById: (
     collection: string,
     record_id: string,
-    updates: Record<string, any>,
+    updates: Record<string, any> | ParameterRef,
     bypassRipple = false,
     ttl?: number,
   ): FunctionStageConfig => ({
@@ -570,7 +883,7 @@ export const Stage = {
   findOneAndUpdate: (
     collection: string,
     record_id: string,
-    updates: Record<string, any>,
+    updates: Record<string, any> | ParameterRef,
     bypassRipple = false,
     ttl?: number,
   ): FunctionStageConfig => ({
@@ -684,4 +997,453 @@ export const Stage = {
     output_field,
     collection,
   }),
+
+  /**
+   * Bcrypt-hash a plaintext value and write the result into every record
+   * in the working data as `output_field`. Requires ekoDB >= 0.41.0.
+   *
+   * @param plain - Plaintext to hash. Typically a `"{{password}}"`
+   *   placeholder that the substituter replaces with the call-time param
+   *   before this stage runs.
+   * @param output_field - Field name to write the bcrypt hash into.
+   * @param cost - bcrypt cost factor (4..=31). Defaults to 12 when undefined.
+   */
+  bcryptHash: (
+    plain: string,
+    output_field: string,
+    cost?: number,
+  ): FunctionStageConfig => ({
+    type: "BcryptHash",
+    plain,
+    cost,
+    output_field,
+  }),
+
+  /**
+   * Verify a plaintext against a bcrypt hash stored on the first record in
+   * the working data. Writes a boolean into `output_field` on every
+   * working record. Pair with `Stage.if` to branch on success / failure.
+   * Requires ekoDB >= 0.41.0.
+   *
+   * @param plain - Plaintext to verify (typically `"{{password}}"`).
+   * @param hash_field - Name of the field on the current record that
+   *   holds the stored bcrypt hash (e.g. `"password_hash"`).
+   * @param output_field - Field name to write the boolean result into.
+   */
+  bcryptVerify: (
+    plain: string,
+    hash_field: string,
+    output_field: string,
+  ): FunctionStageConfig => ({
+    type: "BcryptVerify",
+    plain,
+    hash_field,
+    output_field,
+  }),
+
+  /**
+   * Generate a cryptographically-random token and add it to every record
+   * in the working data. Requires ekoDB >= 0.41.0.
+   *
+   * @param bytes - Number of random bytes to draw (1..=1024).
+   * @param output_field - Field name to write the encoded token into.
+   * @param encoding - `"hex"` (default) | `"base64"` | `"base64url"`.
+   */
+  randomToken: (
+    bytes: number,
+    output_field: string,
+    encoding?: "hex" | "base64" | "base64url",
+  ): FunctionStageConfig => ({
+    type: "RandomToken",
+    bytes,
+    encoding,
+    output_field,
+  }),
+
+  /**
+   * Sign a JWT and write the resulting token to every working
+   * record. Pair with `Stage.bcryptVerify` to issue a session
+   * token after login. Use `"{{env.JWT_SECRET}}"` for `secret` so
+   * the LLM never sees the operator-owned signing key. `iat` and
+   * `exp` are auto-stamped when `expires_in_secs` is set.
+   * Requires ekoDB >= 0.42.0.
+   *
+   * @param claims - JWT payload claims.
+   * @param secret - Signing secret (typically `"{{env.JWT_SECRET}}"`).
+   * @param output_field - Field name to write the signed JWT into.
+   * @param expires_in_secs - Lifetime in seconds (auto-stamps `iat` + `exp`).
+   * @param algorithm - `"HS256"` (default) | `"HS384"` | `"HS512"`.
+   */
+  jwtSign: (
+    claims: Record<string, unknown>,
+    secret: string,
+    output_field: string,
+    expires_in_secs?: number,
+    algorithm?: "HS256" | "HS384" | "HS512",
+  ): FunctionStageConfig => ({
+    type: "JwtSign",
+    claims,
+    secret,
+    algorithm,
+    expires_in_secs,
+    output_field,
+  }),
+
+  /**
+   * Verify a JWT held in `token_field` on the first working record.
+   * On success writes the decoded claims object into `output_field`;
+   * on failure writes `null`. Branch with `Stage.if` matching
+   * `output_field == null` to reject. Requires ekoDB >= 0.42.0.
+   *
+   * @param token_field - Field on the working record holding the JWT.
+   * @param secret - Verification secret (must match the signing secret).
+   * @param output_field - Field name to write decoded claims into.
+   * @param algorithm - Expected algorithm (default `"HS256"`).
+   */
+  jwtVerify: (
+    token_field: string,
+    secret: string,
+    output_field: string,
+    algorithm?: "HS256" | "HS384" | "HS512",
+  ): FunctionStageConfig => ({
+    type: "JwtVerify",
+    token_field,
+    secret,
+    algorithm,
+    output_field,
+  }),
+
+  /**
+   * Send a transactional email. Today only the `"sendgrid"`
+   * provider is supported. Use `"{{env.SENDGRID_API_KEY}}"` for
+   * `api_key` so the LLM never sees the operator-owned secret.
+   * Set `html: true` to send `text/html`. The result envelope
+   * (`{provider_status, provider_message, provider}`) is written
+   * to `output_field` (default `"email_send"`).
+   * Requires ekoDB >= 0.42.0.
+   */
+  emailSend: (
+    to: string,
+    subject: string,
+    body: string,
+    from: string,
+    api_key: string,
+    options?: {
+      reply_to?: string;
+      provider?: "sendgrid";
+      html?: boolean;
+      output_field?: string;
+    },
+  ): FunctionStageConfig => ({
+    type: "EmailSend",
+    to,
+    subject,
+    body,
+    from,
+    reply_to: options?.reply_to,
+    api_key,
+    provider: options?.provider,
+    html: options?.html,
+    output_field: options?.output_field,
+  }),
+
+  /**
+   * Try/Catch error handling for graceful failure recovery.
+   * Executes tryFunctions, and if any fail, executes catchFunctions.
+   *
+   * @param tryFunctions - Functions to attempt.
+   * @param catchFunctions - Functions to execute on failure.
+   * @param outputErrorField - Field name to store error details (default: "error").
+   */
+  tryCatch: (
+    tryFunctions: FunctionStageConfig[],
+    catchFunctions: FunctionStageConfig[],
+    outputErrorField?: string,
+  ): FunctionStageConfig => ({
+    type: "TryCatch",
+    try_functions: tryFunctions,
+    catch_functions: catchFunctions,
+    output_error_field: outputErrorField,
+  }),
+
+  /**
+   * Execute multiple functions in parallel (concurrently).
+   * All functions run simultaneously, results are merged.
+   *
+   * @param functions - Functions to execute concurrently.
+   * @param waitForAll - true = wait for all to complete, false = return on first completion.
+   */
+  parallel: (
+    functions: FunctionStageConfig[],
+    waitForAll = true,
+  ): FunctionStageConfig => ({
+    type: "Parallel",
+    functions,
+    wait_for_all: waitForAll,
+  }),
+
+  /**
+   * Sleep/delay execution for rate limiting or timing control.
+   *
+   * @param durationMs - Duration in milliseconds: `1000` or `"{{delay_param}}"`.
+   */
+  sleep: (durationMs: string | number): FunctionStageConfig => ({
+    type: "Sleep",
+    duration_ms: durationMs,
+  }),
+
+  /**
+   * Return a shaped response (final output formatting).
+   * Constructs the final response object from current execution context.
+   *
+   * @param fields - Fields to include in response with `{{param}}` substitution.
+   * @param statusCode - HTTP status code (default: 200).
+   */
+  returnResponse: (
+    fields: Record<string, any>,
+    statusCode?: number,
+  ): FunctionStageConfig => ({
+    type: "Return",
+    fields,
+    status_code: statusCode,
+  }),
+
+  /**
+   * Validate data against a JSON schema before processing.
+   *
+   * @param schema - JSON Schema to validate against.
+   * @param dataField - Field containing data to validate.
+   * @param onError - Functions to execute on validation failure.
+   */
+  validate: (
+    schema: Record<string, any>,
+    dataField: string,
+    onError?: FunctionStageConfig[],
+  ): FunctionStageConfig => ({
+    type: "Validate",
+    schema,
+    data_field: dataField,
+    on_error: onError,
+  }),
+
+  /**
+   * HMAC-SHA256/384/512 sign. Use for outbound webhook signing or
+   * pre-signed URL generation. Requires ekoDB >= 0.42.0.
+   */
+  hmacSign: (
+    input: string,
+    secret: string,
+    output_field: string,
+    options?: {
+      algorithm?: "sha256" | "sha384" | "sha512";
+      encoding?: "hex" | "base64";
+    },
+  ): FunctionStageConfig => ({
+    type: "HmacSign",
+    input,
+    secret,
+    algorithm: options?.algorithm,
+    output_field,
+    encoding: options?.encoding,
+  }),
+
+  /** HMAC verify (constant-time). Writes a boolean. */
+  hmacVerify: (
+    input: string,
+    provided_mac: string,
+    secret: string,
+    output_field: string,
+    options?: {
+      algorithm?: "sha256" | "sha384" | "sha512";
+      encoding?: "hex" | "base64";
+    },
+  ): FunctionStageConfig => ({
+    type: "HmacVerify",
+    input,
+    provided_mac,
+    secret,
+    algorithm: options?.algorithm,
+    encoding: options?.encoding,
+    output_field,
+  }),
+
+  /** AES-256-GCM encrypt; writes `{ciphertext, nonce}` envelope. */
+  aesEncrypt: (
+    plaintext: string,
+    key: string,
+    output_field: string,
+    key_encoding?: "hex" | "base64" | "base64url",
+  ): FunctionStageConfig => ({
+    type: "AesEncrypt",
+    plaintext,
+    key,
+    key_encoding,
+    output_field,
+  }),
+
+  /** AES-256-GCM decrypt; reads envelope from `ciphertext_field`. */
+  aesDecrypt: (
+    ciphertext_field: string,
+    key: string,
+    output_field: string,
+    key_encoding?: "hex" | "base64" | "base64url",
+  ): FunctionStageConfig => ({
+    type: "AesDecrypt",
+    ciphertext_field,
+    key,
+    key_encoding,
+    output_field,
+  }),
+
+  /** Generate a v4 UUID into `output_field`. */
+  uuidGenerate: (output_field: string): FunctionStageConfig => ({
+    type: "UuidGenerate",
+    output_field,
+  }),
+
+  /** TOTP code generation (RFC 6238). */
+  totpGenerate: (
+    secret: string,
+    output_field: string,
+    options?: {
+      digits?: 6 | 8;
+      period?: number;
+      algorithm?: "sha1" | "sha256" | "sha512";
+    },
+  ): FunctionStageConfig => ({
+    type: "TotpGenerate",
+    secret,
+    digits: options?.digits,
+    period: options?.period,
+    algorithm: options?.algorithm,
+    output_field,
+  }),
+
+  /** TOTP verify; tolerates `skew` time-steps either side (default 1). */
+  totpVerify: (
+    code: string,
+    secret: string,
+    output_field: string,
+    options?: {
+      digits?: 6 | 8;
+      period?: number;
+      algorithm?: "sha1" | "sha256" | "sha512";
+      skew?: number;
+    },
+  ): FunctionStageConfig => ({
+    type: "TotpVerify",
+    code,
+    secret,
+    digits: options?.digits,
+    period: options?.period,
+    algorithm: options?.algorithm,
+    skew: options?.skew,
+    output_field,
+  }),
+
+  /** Base64 encode (`url_safe = true` for URL-safe / no-pad). */
+  base64Encode: (
+    input: string,
+    output_field: string,
+    url_safe?: boolean,
+  ): FunctionStageConfig => ({
+    type: "Base64Encode",
+    input,
+    url_safe,
+    output_field,
+  }),
+
+  /** Base64 decode → UTF-8 string. Fail-closed. */
+  base64Decode: (
+    input: string,
+    output_field: string,
+    url_safe?: boolean,
+  ): FunctionStageConfig => ({
+    type: "Base64Decode",
+    input,
+    url_safe,
+    output_field,
+  }),
+
+  /** Hex encode (lowercase). */
+  hexEncode: (input: string, output_field: string): FunctionStageConfig => ({
+    type: "HexEncode",
+    input,
+    output_field,
+  }),
+
+  /** Hex decode → UTF-8 string. Fail-closed. */
+  hexDecode: (input: string, output_field: string): FunctionStageConfig => ({
+    type: "HexDecode",
+    input,
+    output_field,
+  }),
+
+  /** URL-friendly slug. */
+  slugify: (input: string, output_field: string): FunctionStageConfig => ({
+    type: "Slugify",
+    input,
+    output_field,
+  }),
+
+  /**
+   * Idempotency-key claim (KV SETNX with TTL). Pass an idempotency
+   * key (typically `"{{idempotency_key}}"`) and a TTL; first call
+   * writes `{claimed: true, key}`, subsequent calls within the TTL
+   * write `{claimed: false, key, response}` so the caller can
+   * short-circuit. Requires ekoDB >= 0.42.0.
+   */
+  idempotencyClaim: (
+    key: string,
+    ttl_secs: number,
+    output_field: string,
+  ): FunctionStageConfig => ({
+    type: "IdempotencyClaim",
+    key,
+    ttl_secs,
+    output_field,
+  }),
+
+  /**
+   * Fixed-window rate-limit gate. `on_exceed` either errors
+   * (`"fail"`, default) or writes `allowed: false` (`"skip"`).
+   */
+  rateLimit: (
+    key: string,
+    limit: number,
+    window_secs: number,
+    output_field: string,
+    on_exceed?: "fail" | "skip",
+  ): FunctionStageConfig => ({
+    type: "RateLimit",
+    key,
+    limit,
+    window_secs,
+    on_exceed,
+    output_field,
+  }),
+
+  /** Distributed-lock acquire (token-fenced). */
+  lockAcquire: (
+    key: string,
+    ttl_secs: number,
+    output_field: string,
+  ): FunctionStageConfig => ({
+    type: "LockAcquire",
+    key,
+    ttl_secs,
+    output_field,
+  }),
+
+  /** Distributed-lock release; only releases on token match. */
+  lockRelease: (
+    key: string,
+    token: string,
+    output_field: string,
+  ): FunctionStageConfig => ({
+    type: "LockRelease",
+    key,
+    token,
+    output_field,
+  }),
 };