rowbound 1.0.2

package/dist/core/template.js

@@ -0,0 +1,82 @@
+/**
+ * Resolve template strings like {{row.email}} and {{env.API_KEY}}.
+ * Missing variables resolve to empty string.
+ *
+ * When `onMissing` is provided, it is called for every variable that
+ * resolves to `undefined` in the given context.
+ */
+export function resolveTemplate(template, context, onMissing) {
+    const TEMPLATE_REGEX = /\{\{(row|env)\.([^}]+)\}\}/g;
+    return template.replace(TEMPLATE_REGEX, (_match, source, key) => {
+        if (source === "row") {
+            const value = context.row[key];
+            if (value === undefined && onMissing) {
+                onMissing(source, key);
+            }
+            return value ?? "";
+        }
+        if (source === "env") {
+            const value = context.env[key];
+            if (value === undefined && onMissing) {
+                onMissing(source, key);
+            }
+            return value ?? "";
+        }
+        return "";
+    });
+}
+/**
+ * Resolve template strings with an escape function applied to each resolved value.
+ *
+ * Used for shell contexts where row/env values must be sanitized before
+ * interpolation (e.g., shell-escaping to prevent command injection).
+ * The escape function is applied to each resolved placeholder value,
+ * NOT to static parts of the template.
+ */
+export function resolveTemplateEscaped(template, context, escapeFn, onMissing) {
+    const TEMPLATE_REGEX = /\{\{(row|env)\.([^}]+)\}\}/g;
+    return template.replace(TEMPLATE_REGEX, (_match, source, key) => {
+        let value;
+        if (source === "row") {
+            value = context.row[key];
+        }
+        else if (source === "env") {
+            value = context.env[key];
+        }
+        if (value === undefined && onMissing) {
+            onMissing(source, key);
+        }
+        return escapeFn(value ?? "");
+    });
+}
+/** Maximum recursion depth for resolveObject to prevent stack overflow. */
+const MAX_RESOLVE_DEPTH = 20;
+/**
+ * Recursively resolve templates in an object/array/string.
+ * - Strings: resolve template placeholders
+ * - Arrays: resolve each element
+ * - Objects: resolve each value (keys are not resolved)
+ * - Other types: pass through unchanged
+ */
+export function resolveObject(obj, context, onMissing, depth = 0) {
+    if (depth > MAX_RESOLVE_DEPTH) {
+        throw new Error(`resolveObject exceeded maximum recursion depth of ${MAX_RESOLVE_DEPTH}`);
+    }
+    if (typeof obj === "string") {
+        return resolveTemplate(obj, context, onMissing);
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => resolveObject(item, context, onMissing, depth + 1));
+    }
+    if (obj !== null && typeof obj === "object") {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            if (key === "__proto__" || key === "constructor" || key === "prototype")
+                continue;
+            result[key] = resolveObject(value, context, onMissing, depth + 1);
+        }
+        return result;
+    }
+    // Numbers, booleans, null, undefined — pass through
+    return obj;
+}

package/dist/core/types.d.ts

@@ -0,0 +1,105 @@
+/** Reference to a Google Sheet */
+export interface SheetRef {
+    spreadsheetId: string;
+    sheetName?: string;
+}
+/** A row of data: header name -> cell value */
+export type Row = Record<string, string>;
+/** Shared context passed to condition evaluation and template resolution */
+export interface ExecutionContext {
+    row: Row;
+    env: Record<string, string>;
+    results?: Record<string, unknown>;
+}
+/** A single cell update to write back to the sheet */
+export interface CellUpdate {
+    row: number;
+    column: string;
+    value: string;
+}
+/** Error handling config: maps error codes to actions */
+export type OnErrorConfig = Record<string, string | {
+    write: string;
+}>;
+/** HTTP enrichment action */
+export interface HttpAction {
+    id: string;
+    type: "http";
+    target: string;
+    when?: string;
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    extract: string;
+    onError?: OnErrorConfig;
+}
+/** A single provider in a waterfall action */
+export interface WaterfallProvider {
+    name: string;
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    extract: string;
+    onError?: OnErrorConfig;
+}
+/** Waterfall action: tries providers in order until one succeeds */
+export interface WaterfallAction {
+    id: string;
+    type: "waterfall";
+    target: string;
+    when?: string;
+    providers: WaterfallProvider[];
+}
+/** Transform action: computes a value from existing data */
+export interface TransformAction {
+    id: string;
+    type: "transform";
+    target: string;
+    when?: string;
+    expression: string;
+}
+/** Exec action: runs a shell command and captures output */
+export interface ExecAction {
+    id: string;
+    type: "exec";
+    target: string;
+    when?: string;
+    command: string;
+    extract?: string;
+    timeout?: number;
+    onError?: OnErrorConfig;
+}
+/** Union of all action types */
+export type Action = HttpAction | WaterfallAction | TransformAction | ExecAction;
+/** Global pipeline execution settings */
+export interface PipelineSettings {
+    concurrency: number;
+    rateLimit: number;
+    retryAttempts: number;
+    retryBackoff: string;
+}
+/** Per-tab configuration (v2 multi-tab format) */
+export interface TabConfig {
+    name: string;
+    columns: Record<string, string>;
+    actions: Action[];
+}
+/** Top-level pipeline configuration */
+export interface PipelineConfig {
+    version: string;
+    tabs?: Record<string, TabConfig>;
+    columns?: Record<string, string>;
+    actions: Action[];
+    settings: PipelineSettings;
+}
+/** Adapter interface for reading/writing data (Google Sheets, future: Postgres, etc.) */
+export interface Adapter {
+    readRows(ref: SheetRef): Promise<Row[]>;
+    writeCell(ref: SheetRef, update: CellUpdate): Promise<void>;
+    writeBatch(ref: SheetRef, updates: CellUpdate[]): Promise<void>;
+    readConfig(ref: SheetRef): Promise<PipelineConfig | null>;
+    writeConfig(ref: SheetRef, config: PipelineConfig): Promise<void>;
+    getHeaders(ref: SheetRef): Promise<string[]>;
+}

package/dist/core/types.js

@@ -0,0 +1,2 @@
+// Rowbound Core Types
+export {};

package/dist/core/url-guard.d.ts

@@ -0,0 +1,21 @@
+/**
+ * URL validation guard to prevent SSRF (Server-Side Request Forgery).
+ *
+ * Blocks requests to private/internal networks and non-HTTPS URLs
+ * unless explicitly allowed.
+ *
+ * Known limitation: DNS rebinding attacks are NOT mitigated here. A hostname
+ * could resolve to a public IP at check time and then re-resolve to a private
+ * IP when the actual HTTP request is made. Mitigating this would require
+ * resolving DNS before the check and pinning the IP for the request, which
+ * adds latency and complexity. For now, this is accepted as a known gap.
+ */
+/**
+ * Validate a URL before making an HTTP request.
+ *
+ * - Blocks non-HTTPS URLs by default (http://localhost and http://127.0.0.1
+ *   are allowed for dev; set ROWBOUND_ALLOW_HTTP=true to allow all HTTP)
+ * - Blocks private IP ranges to prevent SSRF to internal services
+ * - Throws on invalid URLs
+ */
+export declare function validateUrl(url: string): void;

package/dist/core/url-guard.js

@@ -0,0 +1,184 @@
+/**
+ * URL validation guard to prevent SSRF (Server-Side Request Forgery).
+ *
+ * Blocks requests to private/internal networks and non-HTTPS URLs
+ * unless explicitly allowed.
+ *
+ * Known limitation: DNS rebinding attacks are NOT mitigated here. A hostname
+ * could resolve to a public IP at check time and then re-resolve to a private
+ * IP when the actual HTTP request is made. Mitigating this would require
+ * resolving DNS before the check and pinning the IP for the request, which
+ * adds latency and complexity. For now, this is accepted as a known gap.
+ */
+/**
+ * Check if a hostname is an IPv6 private/reserved address.
+ *
+ * Blocked ranges:
+ * - ::1              (loopback)
+ * - fe80::/10        (link-local)
+ * - fc00::/7         (unique local — fc00::/8 + fd00::/8)
+ * - ::ffff:x.x.x.x  (IPv4-mapped IPv6 — delegates to IPv4 private check)
+ */
+function isPrivateIpv6(ip) {
+    // Normalize: strip surrounding brackets (URLs use [::1] form)
+    const raw = ip.replace(/^\[|\]$/g, "");
+    const lower = raw.toLowerCase();
+    // ::1 loopback
+    if (lower === "::1")
+        return true;
+    // fe80::/10 link-local
+    if (lower.startsWith("fe80:") || lower.startsWith("fe80%"))
+        return true;
+    // fc00::/7 — matches fc and fd prefixes
+    if (lower.startsWith("fc") || lower.startsWith("fd"))
+        return true;
+    // ::ffff: IPv4-mapped IPv6 — two forms:
+    // 1. Dotted-quad: ::ffff:10.0.0.1
+    // 2. Hex-pair (URL-normalized): ::ffff:a00:1 (which is ::ffff:0a00:0001)
+    const v4MappedDotted = lower.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+    if (v4MappedDotted) {
+        return isPrivateIpv4(v4MappedDotted[1]);
+    }
+    // Hex-pair form: ::ffff:XXYY:ZZWW where XXYY and ZZWW are hex
+    const v4MappedHex = lower.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+    if (v4MappedHex) {
+        const hi = parseInt(v4MappedHex[1], 16);
+        const lo = parseInt(v4MappedHex[2], 16);
+        const a = (hi >>> 8) & 0xff;
+        const b = hi & 0xff;
+        const c = (lo >>> 8) & 0xff;
+        const d = lo & 0xff;
+        return isPrivateIpv4(`${a}.${b}.${c}.${d}`);
+    }
+    return false;
+}
+/**
+ * Check if a string is a numeric (decimal) IP representation.
+ * e.g. 2130706433 === 127.0.0.1, 0x7f000001, 0177.0.0.1
+ *
+ * Returns the dotted-quad string if it is, or null if not.
+ */
+function decodeNumericIp(hostname) {
+    // Decimal integer form: e.g. 2130706433
+    if (/^\d+$/.test(hostname)) {
+        const num = Number(hostname);
+        if (num >= 0 && num <= 0xffffffff) {
+            const a = (num >>> 24) & 0xff;
+            const b = (num >>> 16) & 0xff;
+            const c = (num >>> 8) & 0xff;
+            const d = num & 0xff;
+            return `${a}.${b}.${c}.${d}`;
+        }
+    }
+    // Hex form: 0x7f000001
+    if (/^0x[0-9a-fA-F]+$/.test(hostname)) {
+        const num = Number(hostname);
+        if (num >= 0 && num <= 0xffffffff) {
+            const a = (num >>> 24) & 0xff;
+            const b = (num >>> 16) & 0xff;
+            const c = (num >>> 8) & 0xff;
+            const d = num & 0xff;
+            return `${a}.${b}.${c}.${d}`;
+        }
+    }
+    // Octal dotted form: 0177.0.0.1
+    if (/^0\d*(\.\d+){0,3}$/.test(hostname)) {
+        const parts = hostname.split(".").map((p) => parseInt(p, 8));
+        if (parts.length === 4 &&
+            parts.every((p) => !Number.isNaN(p) && p >= 0 && p <= 255)) {
+            return parts.join(".");
+        }
+    }
+    return null;
+}
+/**
+ * Check if an IPv4 address falls within a private/reserved range.
+ *
+ * Blocked ranges:
+ * - 0.0.0.0           (unspecified)
+ * - 10.0.0.0/8        (private)
+ * - 127.0.0.0/8       (loopback)
+ * - 172.16.0.0/12     (private)
+ * - 192.168.0.0/16    (private)
+ * - 169.254.0.0/16    (link-local / cloud metadata)
+ */
+function isPrivateIpv4(ip) {
+    const parts = ip.split(".").map(Number);
+    if (parts.length !== 4 ||
+        parts.some((p) => Number.isNaN(p) || p < 0 || p > 255)) {
+        return false;
+    }
+    const [a, b] = parts;
+    // 0.0.0.0
+    if (a === 0 && parts[1] === 0 && parts[2] === 0 && parts[3] === 0)
+        return true;
+    // 10.0.0.0/8
+    if (a === 10)
+        return true;
+    // 127.0.0.0/8 (full loopback range)
+    if (a === 127)
+        return true;
+    // 172.16.0.0/12
+    if (a === 172 && b >= 16 && b <= 31)
+        return true;
+    // 192.168.0.0/16
+    if (a === 192 && b === 168)
+        return true;
+    // 169.254.0.0/16 (link-local, AWS metadata endpoint)
+    if (a === 169 && b === 254)
+        return true;
+    return false;
+}
+/**
+ * Check if a hostname resolves to a private/reserved IP.
+ * Handles IPv4, IPv6, numeric/octal representations.
+ */
+function isPrivateIp(hostname) {
+    // Check numeric/octal IP representations first
+    const decoded = decodeNumericIp(hostname);
+    if (decoded) {
+        return isPrivateIpv4(decoded);
+    }
+    // IPv6 check (URL class strips brackets, but handle both)
+    if (hostname.includes(":")) {
+        return isPrivateIpv6(hostname);
+    }
+    // Standard IPv4 dotted-quad
+    return isPrivateIpv4(hostname);
+}
+/**
+ * Validate a URL before making an HTTP request.
+ *
+ * - Blocks non-HTTPS URLs by default (http://localhost and http://127.0.0.1
+ *   are allowed for dev; set ROWBOUND_ALLOW_HTTP=true to allow all HTTP)
+ * - Blocks private IP ranges to prevent SSRF to internal services
+ * - Throws on invalid URLs
+ */
+export function validateUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`Invalid URL: ${url}`);
+    }
+    const allowHttp = process.env.ROWBOUND_ALLOW_HTTP === "true";
+    const hostname = parsed.hostname;
+    // Localhost dev exception: http://localhost and http://127.0.0.1 are allowed
+    const isLocalhostDev = hostname === "localhost" || hostname === "127.0.0.1";
+    // Protocol check
+    if (parsed.protocol === "http:") {
+        if (!isLocalhostDev && !allowHttp) {
+            throw new Error(`Non-HTTPS URL blocked: ${url}. Set ROWBOUND_ALLOW_HTTP=true to allow HTTP.`);
+        }
+    }
+    else if (parsed.protocol !== "https:") {
+        throw new Error(`Unsupported protocol: ${parsed.protocol}`);
+    }
+    // Private IP check — block even for HTTPS (DNS rebinding protection).
+    // Skip for explicit localhost dev addresses (127.0.0.1 / localhost) so
+    // local development still works.
+    if (!isLocalhostDev && isPrivateIp(hostname)) {
+        throw new Error(`URL blocked: ${hostname} is a private IP address.`);
+    }
+}

package/dist/core/validator.d.ts

@@ -0,0 +1,11 @@
+import type { PipelineConfig } from "./types.js";
+/** Result of validating a PipelineConfig. */
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Validate an entire PipelineConfig, returning errors and warnings.
+ */
+export declare function validateConfig(config: PipelineConfig): ValidationResult;

package/dist/core/validator.js

@@ -0,0 +1,261 @@
+import vm from "node:vm";
+import { JSONPath } from "jsonpath-plus";
+/** Maximum recommended config size in bytes (Developer Metadata limit is 30K). */
+const CONFIG_SIZE_WARN = 25_000;
+/** Allowed action types. */
+const VALID_ACTION_TYPES = new Set(["http", "waterfall", "transform", "exec"]);
+/** Known retry backoff strategies. */
+const KNOWN_BACKOFF = new Set(["exponential", "linear", "fixed"]);
+/** Standard HTTP methods. */
+const KNOWN_HTTP_METHODS = new Set([
+    "GET",
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE",
+    "HEAD",
+    "OPTIONS",
+]);
+/**
+ * Regex for valid template placeholders: {{row.xxx}} or {{env.XXX}}.
+ * Invalid patterns are anything inside {{ }} that does NOT match this form.
+ */
+const VALID_TEMPLATE_REGEX = /^\{\{(row|env)\.[^}]+\}\}$/;
+/**
+ * Finds all {{...}} patterns in a string and returns any that are invalid.
+ */
+function findInvalidTemplates(value) {
+    const TEMPLATE_REGEX = /\{\{[^}]*\}\}/g;
+    const invalid = [];
+    for (const match of value.matchAll(TEMPLATE_REGEX)) {
+        if (!VALID_TEMPLATE_REGEX.test(match[0])) {
+            invalid.push(match[0]);
+        }
+    }
+    return invalid;
+}
+/**
+ * Recursively collect all string values from a JSON-like structure.
+ */
+function collectStrings(obj) {
+    if (typeof obj === "string")
+        return [obj];
+    if (Array.isArray(obj))
+        return obj.flatMap(collectStrings);
+    if (obj !== null && typeof obj === "object") {
+        return Object.values(obj).flatMap(collectStrings);
+    }
+    return [];
+}
+/**
+ * Check whether a `when` expression can be parsed as valid JavaScript.
+ * Uses vm.compileFunction which only compiles (no callable Function object).
+ */
+function isParseableExpression(expression) {
+    try {
+        vm.compileFunction(`"use strict"; return (${expression});`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check whether a JSONPath expression is syntactically valid.
+ */
+function isValidJsonPath(expression) {
+    try {
+        JSONPath({ path: expression, json: {}, eval: false });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validate template strings in url, headers, and body of an action-like object.
+ */
+function validateTemplates(label, obj, errors) {
+    // Check url
+    if (obj.url) {
+        const invalid = findInvalidTemplates(obj.url);
+        for (const t of invalid) {
+            errors.push(`${label}: invalid template "${t}" in url — must be {{row.x}} or {{env.X}}`);
+        }
+    }
+    // Check header values
+    if (obj.headers) {
+        for (const [headerKey, headerVal] of Object.entries(obj.headers)) {
+            const invalid = findInvalidTemplates(headerVal);
+            for (const t of invalid) {
+                errors.push(`${label}: invalid template "${t}" in header "${headerKey}"`);
+            }
+        }
+    }
+    // Check body (recursively collect strings)
+    if (obj.body !== undefined) {
+        const bodyStrings = collectStrings(obj.body);
+        for (const s of bodyStrings) {
+            const invalid = findInvalidTemplates(s);
+            for (const t of invalid) {
+                errors.push(`${label}: invalid template "${t}" in body`);
+            }
+        }
+    }
+}
+/**
+ * Validate an entire PipelineConfig, returning errors and warnings.
+ */
+export function validateConfig(config) {
+    const errors = [];
+    const warnings = [];
+    // 1. Version check
+    if (config.version !== "1" && config.version !== "2") {
+        errors.push(`Invalid version "${config.version}" (expected "1" or "2")`);
+    }
+    // 2. Unique action IDs
+    const ids = config.actions.map((s) => s.id);
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const id of ids) {
+        if (seen.has(id)) {
+            duplicates.add(id);
+        }
+        seen.add(id);
+    }
+    if (duplicates.size > 0) {
+        errors.push(`Duplicate action IDs: ${[...duplicates].join(", ")}`);
+    }
+    // 3 & 4. Per-action validation
+    for (const action of config.actions) {
+        const label = `Action "${action.id}"`;
+        // Common required fields
+        if (!action.id) {
+            errors.push("An action is missing the 'id' field");
+        }
+        if (!action.type) {
+            errors.push(`${label}: missing 'type' field`);
+        }
+        if (!action.target) {
+            errors.push(`${label}: missing 'target' field`);
+        }
+        // Valid action type
+        if (action.type && !VALID_ACTION_TYPES.has(action.type)) {
+            errors.push(`${label}: invalid type "${action.type}"`);
+        }
+        // 6. Parseable conditions
+        if (action.when !== undefined) {
+            if (!isParseableExpression(action.when)) {
+                errors.push(`${label}: 'when' expression has invalid syntax: "${action.when}"`);
+            }
+        }
+        // Type-specific validation
+        if (action.type === "http") {
+            const httpAction = action;
+            if (!httpAction.method) {
+                errors.push(`${label}: http action missing 'method'`);
+            }
+            else if (!KNOWN_HTTP_METHODS.has(httpAction.method.toUpperCase())) {
+                warnings.push(`${label}: HTTP method "${httpAction.method}" is not a standard method (expected one of: ${[...KNOWN_HTTP_METHODS].join(", ")})`);
+            }
+            if (!httpAction.url) {
+                errors.push(`${label}: http action missing 'url'`);
+            }
+            if (!httpAction.extract) {
+                errors.push(`${label}: http action missing 'extract'`);
+            }
+            // 5. Template validation
+            validateTemplates(label, httpAction, errors);
+            // 7. JSONPath validation
+            if (httpAction.extract && !isValidJsonPath(httpAction.extract)) {
+                errors.push(`${label}: invalid JSONPath in 'extract': "${httpAction.extract}"`);
+            }
+        }
+        else if (action.type === "waterfall") {
+            const waterfallAction = action;
+            if (!waterfallAction.providers ||
+                !Array.isArray(waterfallAction.providers) ||
+                waterfallAction.providers.length === 0) {
+                errors.push(`${label}: waterfall action must have a non-empty 'providers' array`);
+            }
+            else {
+                for (let i = 0; i < waterfallAction.providers.length; i++) {
+                    const provider = waterfallAction.providers[i];
+                    const pLabel = `${label} provider[${i}]`;
+                    if (!provider.name) {
+                        errors.push(`${pLabel}: missing 'name'`);
+                    }
+                    if (!provider.method) {
+                        errors.push(`${pLabel}: missing 'method'`);
+                    }
+                    if (!provider.url) {
+                        errors.push(`${pLabel}: missing 'url'`);
+                    }
+                    if (!provider.extract) {
+                        errors.push(`${pLabel}: missing 'extract'`);
+                    }
+                    // Template validation on each provider
+                    validateTemplates(provider.name ? `${label} provider "${provider.name}"` : pLabel, provider, errors);
+                    // JSONPath validation on each provider
+                    if (provider.extract && !isValidJsonPath(provider.extract)) {
+                        errors.push(`${provider.name ? `${label} provider "${provider.name}"` : pLabel}: invalid JSONPath in 'extract': "${provider.extract}"`);
+                    }
+                }
+            }
+        }
+        else if (action.type === "transform") {
+            const transformAction = action;
+            if (!transformAction.expression) {
+                errors.push(`${label}: transform action missing 'expression'`);
+            }
+        }
+        else if (action.type === "exec") {
+            const execAction = action;
+            if (!execAction.command) {
+                errors.push(`${label}: exec action missing 'command'`);
+            }
+            // Template validation in command
+            if (execAction.command) {
+                const invalid = findInvalidTemplates(execAction.command);
+                for (const t of invalid) {
+                    errors.push(`${label}: invalid template "${t}" in command — must be {{row.x}} or {{env.X}}`);
+                }
+            }
+            // Validate timeout if present
+            if (execAction.timeout !== undefined &&
+                (typeof execAction.timeout !== "number" || execAction.timeout <= 0)) {
+                errors.push(`${label}: exec action 'timeout' must be a positive number (got ${JSON.stringify(execAction.timeout)})`);
+            }
+            // JSONPath validation on extract if present
+            if (execAction.extract && !isValidJsonPath(execAction.extract)) {
+                errors.push(`${label}: invalid JSONPath in 'extract': "${execAction.extract}"`);
+            }
+        }
+    }
+    // 8. Config size warning
+    const serialized = JSON.stringify(config);
+    if (serialized.length > CONFIG_SIZE_WARN) {
+        warnings.push(`Config size is ${serialized.length} bytes — approaching the 30K Developer Metadata limit`);
+    }
+    // 9. Settings validation
+    if (config.settings) {
+        const { concurrency, rateLimit, retryAttempts, retryBackoff } = config.settings;
+        if (typeof concurrency !== "number" || concurrency <= 0) {
+            errors.push(`settings.concurrency must be > 0 (got ${JSON.stringify(concurrency)})`);
+        }
+        if (typeof rateLimit !== "number" || rateLimit < 0) {
+            errors.push(`settings.rateLimit must be >= 0 (got ${JSON.stringify(rateLimit)})`);
+        }
+        if (typeof retryAttempts !== "number" || retryAttempts < 0) {
+            errors.push(`settings.retryAttempts must be >= 0 (got ${JSON.stringify(retryAttempts)})`);
+        }
+        if (typeof retryBackoff === "string" && !KNOWN_BACKOFF.has(retryBackoff)) {
+            warnings.push(`settings.retryBackoff "${retryBackoff}" is not a known strategy (known: ${[...KNOWN_BACKOFF].join(", ")})`);
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}