@ekodb/ekodb-client 0.17.0 → 0.18.0

package/dist/functions.d.ts

@@ -15,6 +15,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 {
     required: boolean;
@@ -235,6 +248,167 @@ export type FunctionStageConfig = {
     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.
@@ -483,6 +657,48 @@ export declare const Stage: {
      * @param encoding - `"hex"` (default) | `"base64"` | `"base64url"`.
      */
     randomToken: (bytes: number, output_field: string, encoding?: "hex" | "base64" | "base64url") => FunctionStageConfig;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
     /**
      * Try/Catch error handling for graceful failure recovery.
      * Executes tryFunctions, and if any fail, executes catchFunctions.
@@ -522,4 +738,63 @@ export declare const Stage: {
      * @param onError - Functions to execute on validation failure.
      */
     validate: (schema: Record<string, any>, dataField: string, onError?: FunctionStageConfig[]) => FunctionStageConfig;
+    /**
+     * 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;
+    /** 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;
+    /** AES-256-GCM encrypt; writes `{ciphertext, nonce}` envelope. */
+    aesEncrypt: (plaintext: string, key: string, output_field: string, key_encoding?: "hex" | "base64" | "base64url") => FunctionStageConfig;
+    /** AES-256-GCM decrypt; reads envelope from `ciphertext_field`. */
+    aesDecrypt: (ciphertext_field: string, key: string, output_field: string, key_encoding?: "hex" | "base64" | "base64url") => FunctionStageConfig;
+    /** Generate a v4 UUID into `output_field`. */
+    uuidGenerate: (output_field: string) => FunctionStageConfig;
+    /** TOTP code generation (RFC 6238). */
+    totpGenerate: (secret: string, output_field: string, options?: {
+        digits?: 6 | 8;
+        period?: number;
+        algorithm?: "sha1" | "sha256" | "sha512";
+    }) => FunctionStageConfig;
+    /** 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;
+    /** Base64 encode (`url_safe = true` for URL-safe / no-pad). */
+    base64Encode: (input: string, output_field: string, url_safe?: boolean) => FunctionStageConfig;
+    /** Base64 decode → UTF-8 string. Fail-closed. */
+    base64Decode: (input: string, output_field: string, url_safe?: boolean) => FunctionStageConfig;
+    /** Hex encode (lowercase). */
+    hexEncode: (input: string, output_field: string) => FunctionStageConfig;
+    /** Hex decode → UTF-8 string. Fail-closed. */
+    hexDecode: (input: string, output_field: string) => FunctionStageConfig;
+    /** URL-friendly slug. */
+    slugify: (input: string, output_field: string) => FunctionStageConfig;
+    /**
+     * 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;
+    /**
+     * 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;
+    /** Distributed-lock acquire (token-fenced). */
+    lockAcquire: (key: string, ttl_secs: number, output_field: string) => FunctionStageConfig;
+    /** Distributed-lock release; only releases on token match. */
+    lockRelease: (key: string, token: string, output_field: string) => FunctionStageConfig;
 };

package/dist/functions.js

@@ -315,6 +315,67 @@ exports.Stage = {
         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, secret, output_field, expires_in_secs, algorithm) => ({
+        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, secret, output_field, algorithm) => ({
+        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, subject, body, from, api_key, options) => ({
+        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.
@@ -375,4 +436,138 @@ exports.Stage = {
         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, secret, output_field, options) => ({
+        type: "HmacSign",
+        input,
+        secret,
+        algorithm: options?.algorithm,
+        output_field,
+        encoding: options?.encoding,
+    }),
+    /** HMAC verify (constant-time). Writes a boolean. */
+    hmacVerify: (input, provided_mac, secret, output_field, options) => ({
+        type: "HmacVerify",
+        input,
+        provided_mac,
+        secret,
+        algorithm: options?.algorithm,
+        encoding: options?.encoding,
+        output_field,
+    }),
+    /** AES-256-GCM encrypt; writes `{ciphertext, nonce}` envelope. */
+    aesEncrypt: (plaintext, key, output_field, key_encoding) => ({
+        type: "AesEncrypt",
+        plaintext,
+        key,
+        key_encoding,
+        output_field,
+    }),
+    /** AES-256-GCM decrypt; reads envelope from `ciphertext_field`. */
+    aesDecrypt: (ciphertext_field, key, output_field, key_encoding) => ({
+        type: "AesDecrypt",
+        ciphertext_field,
+        key,
+        key_encoding,
+        output_field,
+    }),
+    /** Generate a v4 UUID into `output_field`. */
+    uuidGenerate: (output_field) => ({
+        type: "UuidGenerate",
+        output_field,
+    }),
+    /** TOTP code generation (RFC 6238). */
+    totpGenerate: (secret, output_field, options) => ({
+        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, secret, output_field, options) => ({
+        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, output_field, url_safe) => ({
+        type: "Base64Encode",
+        input,
+        url_safe,
+        output_field,
+    }),
+    /** Base64 decode → UTF-8 string. Fail-closed. */
+    base64Decode: (input, output_field, url_safe) => ({
+        type: "Base64Decode",
+        input,
+        url_safe,
+        output_field,
+    }),
+    /** Hex encode (lowercase). */
+    hexEncode: (input, output_field) => ({
+        type: "HexEncode",
+        input,
+        output_field,
+    }),
+    /** Hex decode → UTF-8 string. Fail-closed. */
+    hexDecode: (input, output_field) => ({
+        type: "HexDecode",
+        input,
+        output_field,
+    }),
+    /** URL-friendly slug. */
+    slugify: (input, output_field) => ({
+        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, ttl_secs, output_field) => ({
+        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, limit, window_secs, output_field, on_exceed) => ({
+        type: "RateLimit",
+        key,
+        limit,
+        window_secs,
+        on_exceed,
+        output_field,
+    }),
+    /** Distributed-lock acquire (token-fenced). */
+    lockAcquire: (key, ttl_secs, output_field) => ({
+        type: "LockAcquire",
+        key,
+        ttl_secs,
+        output_field,
+    }),
+    /** Distributed-lock release; only releases on token match. */
+    lockRelease: (key, token, output_field) => ({
+        type: "LockRelease",
+        key,
+        token,
+        output_field,
+    }),
 };