rowbound 1.0.2

package/dist/core/http-client.js

@@ -0,0 +1,161 @@
+import { validateUrl } from "./url-guard.js";
+/** Thrown when onError config specifies "stop_provider" */
+export class StopProviderError extends Error {
+    constructor(message = "Provider stopped due to error") {
+        super(message);
+        this.name = "StopProviderError";
+    }
+}
+/**
+ * Check if a status code is retryable (429 or 5xx).
+ */
+function isRetryable(status) {
+    return status === 429 || (status >= 500 && status <= 599);
+}
+/**
+ * Resolve the onError action for a given status code.
+ * Checks the specific status first, then falls back to "default".
+ */
+function resolveErrorAction(onError, status) {
+    if (!onError)
+        return undefined;
+    const statusKey = String(status);
+    if (statusKey in onError) {
+        return onError[statusKey];
+    }
+    if ("default" in onError) {
+        return onError.default;
+    }
+    return undefined;
+}
+/**
+ * Apply the resolved error action, returning an HttpResponse or throwing.
+ */
+function applyErrorAction(action, status) {
+    if (action === undefined) {
+        // No error handler — throw a generic error
+        throw new Error(`HTTP request failed with status ${status}`);
+    }
+    if (action === "skip") {
+        return null;
+    }
+    if (action === "stop_provider") {
+        throw new StopProviderError(`Provider stopped: HTTP ${status}`);
+    }
+    if (typeof action === "object" && "write" in action) {
+        return { status, data: action.write };
+    }
+    // Unknown action — treat as skip
+    return null;
+}
+/**
+ * Make an HTTP request with retry, rate limiting, and structured error handling.
+ *
+ * - Acquires a rate limiter token before each request attempt
+ * - Retries on 429/5xx with exponential backoff
+ * - Applies onError config for non-retryable errors or exhausted retries
+ * - Respects AbortSignal for cancellation
+ */
+export async function httpRequest(options) {
+    const { method, url, headers, body, retryAttempts = 0, retryBackoff, onError, rateLimiter, signal, } = options;
+    // Validate URL to prevent SSRF
+    validateUrl(url);
+    const maxAttempts = retryAttempts + 1;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        // Check abort before each attempt
+        if (signal?.aborted) {
+            throw new Error("Request aborted");
+        }
+        // Acquire rate limiter token
+        if (rateLimiter) {
+            await rateLimiter.acquire(signal);
+        }
+        let finalHeaders = headers;
+        if (body !== undefined) {
+            const hasContentType = headers &&
+                Object.keys(headers).some((k) => k.toLowerCase() === "content-type");
+            if (!hasContentType) {
+                finalHeaders = { ...headers, "Content-Type": "application/json" };
+            }
+        }
+        let response;
+        try {
+            response = await fetch(url, {
+                method,
+                headers: finalHeaders,
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                signal,
+            });
+        }
+        catch (_err) {
+            // Network error or abort
+            if (signal?.aborted) {
+                throw new Error("Request aborted");
+            }
+            if (attempt < maxAttempts - 1) {
+                await backoff(attempt, retryBackoff, signal);
+                continue;
+            }
+            const action = resolveErrorAction(onError, 0);
+            return applyErrorAction(action, 0);
+        }
+        // Success
+        if (response.ok) {
+            const data = await parseResponseBody(response);
+            return { status: response.status, data };
+        }
+        // Retryable error
+        if (isRetryable(response.status) && attempt < maxAttempts - 1) {
+            await backoff(attempt, retryBackoff, signal);
+            continue;
+        }
+        // Non-retryable error, or retries exhausted
+        const action = resolveErrorAction(onError, response.status);
+        return applyErrorAction(action, response.status);
+    }
+    // Should not be reached, but handle gracefully
+    throw new Error("HTTP request failed: no attempts made");
+}
+/**
+ * Backoff delay between retries. Respects AbortSignal to allow early exit.
+ *
+ * Strategies:
+ * - "exponential" (default): 2^attempt * 100ms (100, 200, 400, 800, ...)
+ * - "linear": (attempt + 1) * 200ms (200, 400, 600, ...)
+ * - "fixed": constant 1000ms
+ */
+async function backoff(attempt, strategy, signal) {
+    let delayMs;
+    switch (strategy) {
+        case "linear":
+            delayMs = (attempt + 1) * 200;
+            break;
+        case "fixed":
+            delayMs = 1000;
+            break;
+        default:
+            delayMs = 2 ** attempt * 100;
+            break;
+    }
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(resolve, delayMs);
+        signal?.addEventListener("abort", () => {
+            clearTimeout(timer);
+            resolve();
+        }, { once: true });
+    });
+}
+/**
+ * Parse response body as JSON, falling back to text.
+ */
+async function parseResponseBody(response) {
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.includes("json")) {
+        return response.json();
+    }
+    return response.text();
+}

package/dist/core/rate-limiter.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Token bucket rate limiter.
+ *
+ * Refills tokens based on elapsed time, with max capacity equal to
+ * tokensPerSecond. Used globally across all HTTP requests.
+ */
+export declare class RateLimiter {
+    private readonly tokensPerSecond;
+    private tokens;
+    private readonly maxTokens;
+    private lastRefill;
+    private queue;
+    constructor(tokensPerSecond: number);
+    /**
+     * Acquire a single token. Resolves immediately if a token is available,
+     * otherwise waits until one is refilled. Respects AbortSignal for early exit.
+     *
+     * Serialized via a promise chain to prevent race conditions when
+     * multiple callers invoke acquire() concurrently.
+     */
+    acquire(signal?: AbortSignal): Promise<void>;
+    private _acquire;
+    private refill;
+    private sleep;
+}

package/dist/core/rate-limiter.js

@@ -0,0 +1,64 @@
+/**
+ * Token bucket rate limiter.
+ *
+ * Refills tokens based on elapsed time, with max capacity equal to
+ * tokensPerSecond. Used globally across all HTTP requests.
+ */
+export class RateLimiter {
+    tokensPerSecond;
+    tokens;
+    maxTokens;
+    lastRefill;
+    queue = Promise.resolve();
+    constructor(tokensPerSecond) {
+        this.tokensPerSecond = tokensPerSecond;
+        this.maxTokens = tokensPerSecond;
+        this.tokens = tokensPerSecond;
+        this.lastRefill = Date.now();
+    }
+    /**
+     * Acquire a single token. Resolves immediately if a token is available,
+     * otherwise waits until one is refilled. Respects AbortSignal for early exit.
+     *
+     * Serialized via a promise chain to prevent race conditions when
+     * multiple callers invoke acquire() concurrently.
+     */
+    async acquire(signal) {
+        this.queue = this.queue.then(() => this._acquire(signal));
+        return this.queue;
+    }
+    async _acquire(signal) {
+        if (signal?.aborted)
+            return;
+        this.refill();
+        if (this.tokens >= 1) {
+            this.tokens -= 1;
+            return;
+        }
+        // Calculate wait time until at least one token is available
+        const deficit = 1 - this.tokens;
+        const waitMs = (deficit / this.tokensPerSecond) * 1000;
+        await this.sleep(waitMs, signal);
+        this.refill();
+        this.tokens -= 1;
+    }
+    refill() {
+        const now = Date.now();
+        const elapsed = (now - this.lastRefill) / 1000;
+        this.tokens = Math.min(this.maxTokens, this.tokens + elapsed * this.tokensPerSecond);
+        this.lastRefill = now;
+    }
+    sleep(ms, signal) {
+        return new Promise((resolve) => {
+            if (signal?.aborted) {
+                resolve();
+                return;
+            }
+            const timer = setTimeout(resolve, ms);
+            signal?.addEventListener("abort", () => {
+                clearTimeout(timer);
+                resolve();
+            }, { once: true });
+        });
+    }
+}

package/dist/core/reconcile.d.ts

@@ -0,0 +1,24 @@
+import type { SheetsAdapter } from "../adapters/sheets/sheets-adapter.js";
+import type { PipelineConfig, SheetRef, TabConfig } from "./types.js";
+export interface ReconcileResult {
+    /** Updated config — always v2 format */
+    config: PipelineConfig;
+    /** The GID of the tab being operated on */
+    tabGid: string;
+    /** The specific tab's config (convenience) */
+    tabConfig: TabConfig;
+    /** User-facing messages about detected changes */
+    messages: string[];
+    /** Whether the config was modified and needs re-saving */
+    configChanged: boolean;
+}
+/**
+ * Reconcile a pipeline config with the current sheet state.
+ *
+ * This function handles:
+ * 1. v1 → v2 migration (wraps top-level actions/columns under the resolved GID)
+ * 2. Tab name reconciliation (detects renamed tabs by GID)
+ * 3. Column reconciliation for the target tab (named ranges, renames, new columns)
+ * 4. Action target migration from column names to IDs
+ */
+export declare function reconcile(adapter: SheetsAdapter, ref: SheetRef, config: PipelineConfig): Promise<ReconcileResult>;

package/dist/core/reconcile.js

@@ -0,0 +1,192 @@
+import { randomBytes } from "node:crypto";
+/**
+ * Reconcile a pipeline config with the current sheet state.
+ *
+ * This function handles:
+ * 1. v1 → v2 migration (wraps top-level actions/columns under the resolved GID)
+ * 2. Tab name reconciliation (detects renamed tabs by GID)
+ * 3. Column reconciliation for the target tab (named ranges, renames, new columns)
+ * 4. Action target migration from column names to IDs
+ */
+export async function reconcile(adapter, ref, config) {
+    const messages = [];
+    let configChanged = false;
+    // --- Action 1: Get all tabs from the spreadsheet ---
+    const sheets = await adapter.listSheets(ref.spreadsheetId);
+    const targetName = ref.sheetName || "Sheet1";
+    const targetSheet = sheets.find((s) => s.name === targetName);
+    if (!targetSheet) {
+        throw new Error(`Tab "${targetName}" not found in spreadsheet ${ref.spreadsheetId}`);
+    }
+    const tabGid = String(targetSheet.gid);
+    // --- Action 2: Migrate v1 → v2 if needed ---
+    let tabs;
+    if (!config.tabs) {
+        // v1 config — migrate to v2
+        const v1Columns = config.columns ?? {};
+        const v1Actions = config.actions ?? [];
+        tabs = {
+            [tabGid]: {
+                name: targetName,
+                columns: { ...v1Columns },
+                actions: [...v1Actions],
+            },
+        };
+        configChanged = true;
+        messages.push(`Migrated v1 config to v2 multi-tab format (tab GID: ${tabGid})`);
+    }
+    else {
+        // Already v2 — deep clone tabs
+        tabs = {};
+        for (const [gid, tab] of Object.entries(config.tabs)) {
+            tabs[gid] = {
+                name: tab.name,
+                columns: { ...tab.columns },
+                actions: [...tab.actions],
+            };
+        }
+    }
+    // Ensure the target tab exists in config
+    if (!tabs[tabGid]) {
+        tabs[tabGid] = {
+            name: targetName,
+            columns: {},
+            actions: [],
+        };
+        configChanged = true;
+    }
+    // --- Action 3: Reconcile tab names ---
+    for (const [gid, tab] of Object.entries(tabs)) {
+        const sheet = sheets.find((s) => String(s.gid) === gid);
+        if (sheet && sheet.name !== tab.name) {
+            messages.push(`Tab ${gid}: renamed "${tab.name}" → "${sheet.name}"`);
+            tab.name = sheet.name;
+            configChanged = true;
+        }
+    }
+    // --- Action 4: Reconcile columns for the target tab ---
+    const tabConfig = tabs[tabGid];
+    const headers = await adapter.getHeaders(ref);
+    const sheetRanges = await adapter.readColumnRanges(ref, targetSheet.gid);
+    let oldColumns = tabConfig.columns;
+    const newColumns = {};
+    if (Object.keys(oldColumns).length === 0 && !config.tabs) {
+        // First time — configChanged already set from migration
+    }
+    // Detect old {name: id} format and flip to new {id: name} format.
+    const isOldFormat = Object.keys(oldColumns).length > 0 &&
+        Object.values(oldColumns).some((v) => sheetRanges.has(v));
+    if (isOldFormat) {
+        const flipped = {};
+        for (const [name, id] of Object.entries(oldColumns)) {
+            flipped[id] = name;
+        }
+        oldColumns = flipped;
+        tabConfig.columns = flipped;
+        configChanged = true;
+    }
+    // Track which header indices are covered by existing ranges
+    const coveredIndices = new Set();
+    // --- Pass 1: Process all named ranges found in the sheet ---
+    for (const [rangeId, colIndex] of sheetRanges) {
+        const currentHeader = headers[colIndex];
+        if (!currentHeader) {
+            // Range points beyond current headers → column was deleted
+            const oldName = oldColumns[rangeId];
+            if (oldName) {
+                messages.push(`✗ "${oldName}" (${rangeId}) → deleted, removing`);
+                configChanged = true;
+            }
+            continue;
+        }
+        coveredIndices.add(colIndex);
+        const oldName = oldColumns[rangeId];
+        if (oldName && oldName !== currentHeader) {
+            // Header name changed — just update the label
+            newColumns[rangeId] = currentHeader;
+            messages.push(`✓ "${oldName}" → renamed to "${currentHeader}" (${rangeId})`);
+            configChanged = true;
+        }
+        else if (oldName) {
+            // No change
+            newColumns[rangeId] = currentHeader;
+        }
+        else {
+            // Range exists in sheet but not in our config (migration from action-based ranges)
+            newColumns[rangeId] = currentHeader;
+            configChanged = true;
+        }
+    }
+    // --- Pass 2: Create ranges for untracked headers ---
+    const trackedNames = new Set(Object.values(newColumns));
+    for (let i = 0; i < headers.length; i++) {
+        if (coveredIndices.has(i))
+            continue;
+        const header = headers[i];
+        if (!header || trackedNames.has(header))
+            continue;
+        const rangeId = randomBytes(4).toString("hex");
+        try {
+            await adapter.createColumnRange(ref, rangeId, i);
+            newColumns[rangeId] = header;
+            messages.push(`✓ "${header}" → new column (${rangeId})`);
+            configChanged = true;
+        }
+        catch {
+            // Non-fatal — column just won't have tracking
+        }
+    }
+    // --- Pass 3: Migrate action targets from column names to IDs ---
+    const nameToId = new Map();
+    for (const [id, name] of Object.entries(newColumns)) {
+        nameToId.set(name, id);
+    }
+    const actions = tabConfig.actions.map((action) => {
+        // Target is already an ID (exists as key in columns)
+        if (newColumns[action.target] !== undefined) {
+            return action;
+        }
+        // Target is a column name — migrate to ID
+        const id = nameToId.get(action.target);
+        if (id) {
+            messages.push(`✓ action "${action.id}": target "${action.target}" → ${id} (migrated to ID)`);
+            return { ...action, target: id };
+        }
+        // Legacy migration: action.id was used as the range name in the old system
+        const legacyColIndex = sheetRanges.get(action.id);
+        if (legacyColIndex !== undefined) {
+            const currentHeader = headers[legacyColIndex];
+            if (currentHeader) {
+                const resolvedId = nameToId.get(currentHeader);
+                if (resolvedId) {
+                    messages.push(`✓ action "${action.id}": target "${action.target}" → ${resolvedId} (legacy migration)`);
+                    return { ...action, target: resolvedId };
+                }
+            }
+        }
+        return action;
+    });
+    if (actions.some((s, i) => s !== tabConfig.actions[i])) {
+        configChanged = true;
+    }
+    // Update tab config
+    tabConfig.columns = newColumns;
+    tabConfig.actions = actions;
+    // Build the final v2 config
+    const updatedConfig = {
+        ...config,
+        version: "2",
+        tabs,
+        // Clear v1 top-level fields after migration
+        columns: undefined,
+        actions: [],
+        settings: config.settings,
+    };
+    return {
+        config: updatedConfig,
+        tabGid,
+        tabConfig,
+        messages,
+        configChanged,
+    };
+}

package/dist/core/run-format.d.ts

@@ -0,0 +1,39 @@
+import type { RunState } from "./run-state.js";
+/**
+ * Format milliseconds as a human-readable duration.
+ * Examples: "12s", "1m30s", "2h5m"
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * Format an ISO date as a relative "age" string.
+ * Examples: "just now", "5m ago", "2h ago", "3d ago", or "running" if status is running.
+ */
+export declare function formatAge(isoDate: string, status?: string): string;
+/**
+ * Format a list of runs as a compact table.
+ *
+ * ```
+ * STATUS  RUN       SHEET        ROWS      UPDATES  ERRORS  DURATION  AGE
+ * ✓       a1b2c3    EliteCart    30/30     28       0       12s       5m ago
+ * ```
+ */
+export declare function formatRunList(runs: RunState[]): string;
+/**
+ * Format a detailed view of a single run.
+ *
+ * ```
+ * ✗ Run d4e5f6 · LeadList
+ *   Sheet: 1xABC...def · Started: 2h ago · Duration: 45s
+ *
+ * ACTIONS
+ *   extract_domain    ✓ 150/150
+ *   enrich_company    ✗ 147/150 (3 errors)
+ *   find_email        ⚠ 120/147 (27 skipped)
+ *
+ * ERRORS (3)
+ *   Row 45   enrich_company   429 Too Many Requests (retries exhausted)
+ *   Row 89   enrich_company   timeout after 30s
+ *   Row 102  enrich_company   404 → wrote "not_found"
+ * ```
+ */
+export declare function formatRunDetail(run: RunState, errorsOnly?: boolean): string;