@ekodb/ekodb-client 0.16.0 → 0.18.0

package/dist/functions.js

@@ -4,6 +4,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Stage = exports.ChatMessage = void 0;
+exports.parameterRef = parameterRef;
 exports.ChatMessage = {
     system: (content) => ({
         role: "system",
@@ -18,8 +19,17 @@ exports.ChatMessage = {
         content: content,
     }),
 };
+function parameterRef(name) {
+    return { type: "Parameter", name };
+}
 // Stage builder functions
 exports.Stage = {
+    /**
+     * Shorthand for `parameterRef(name)` — builds the structural placeholder
+     * `{"type": "Parameter", "name": name}`. See `parameterRef` for the full
+     * explanation and example.
+     */
+    param: (name) => parameterRef(name),
     findAll: (collection) => ({
         type: "FindAll",
         collection,
@@ -258,4 +268,306 @@ exports.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, output_field, cost) => ({
+        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, hash_field, output_field) => ({
+        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, output_field, encoding) => ({
+        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, 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.
+     *
+     * @param tryFunctions - Functions to attempt.
+     * @param catchFunctions - Functions to execute on failure.
+     * @param outputErrorField - Field name to store error details (default: "error").
+     */
+    tryCatch: (tryFunctions, catchFunctions, outputErrorField) => ({
+        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, waitForAll = true) => ({
+        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) => ({
+        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, statusCode) => ({
+        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, dataField, onError) => ({
+        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, 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,
+    }),
 };

package/dist/functions.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Unit tests for the stored-function builder helpers (Stage + parameterRef).
+ *
+ * These tests cover the pure-data construction helpers and the structural
+ * parameter placeholder. They don't hit a running ekoDB — server-side
+ * behavior is covered by the Rust integration tests in
+ * `ekodb/ekodb_server/tests/function_parameters_tests.rs`.
+ */
+export {};