@abloatai/ablo 0.3.0

package/dist/source/index.js

@@ -0,0 +1,320 @@
+/**
+ * HTTP headers used on signed source requests. Conforms to the
+ * Standard Webhooks specification (https://www.standardwebhooks.com/)
+ * so customer code can verify our signatures with any of the official
+ * libraries (svix, standardwebhooks, hookdeck, etc.) — no Ablo-
+ * specific verifier required.
+ */
+export const ABLO_SOURCE_HEADERS = {
+    signature: 'webhook-signature',
+    timestamp: 'webhook-timestamp',
+    id: 'webhook-id',
+    idempotencyKey: 'Idempotency-Key',
+};
+export class SourceSignatureError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'SourceSignatureError';
+        this.code = code;
+    }
+}
+const DEFAULT_SIGNATURE_TOLERANCE_MS = 5 * 60 * 1000;
+function json(data, status = 200) {
+    return new Response(JSON.stringify(data), {
+        status,
+        headers: { 'Content-Type': 'application/json' },
+    });
+}
+async function readBody(request) {
+    if (typeof request.text === 'function') {
+        const rawBody = await request.text();
+        return { rawBody, body: JSON.parse(rawBody) };
+    }
+    const body = (await request.json());
+    return { rawBody: JSON.stringify(body), body };
+}
+function getHeader(request, name) {
+    const headers = request.headers;
+    if (!headers)
+        return null;
+    if (typeof headers.get === 'function') {
+        return headers.get(name);
+    }
+    const record = headers;
+    return record[name] ?? record[name.toLowerCase()] ?? null;
+}
+/**
+ * Parse a `webhook-signature` header per the Standard Webhooks spec.
+ * Values are space-delimited `<scheme>,<base64>` pairs (e.g.
+ * `v1,abc== v1,def==` during a key rotation window). Returns the set
+ * of `v1` signatures so the verifier can accept any of them.
+ */
+function parseSignatureHeader(raw) {
+    if (!raw)
+        return [];
+    const out = [];
+    for (const part of raw.split(/\s+/)) {
+        const trimmed = part.trim();
+        if (!trimmed)
+            continue;
+        const commaAt = trimmed.indexOf(',');
+        if (commaAt === -1)
+            continue;
+        const scheme = trimmed.slice(0, commaAt);
+        const value = trimmed.slice(commaAt + 1);
+        if (scheme === 'v1' && value.length > 0) {
+            out.push(value);
+        }
+    }
+    return out;
+}
+function bufferToBase64(buffer) {
+    // Node + browsers both expose `btoa` on the global; we feed it
+    // a binary string built from the byte view.
+    let binary = '';
+    const bytes = new Uint8Array(buffer);
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
+async function hmacSha256Base64(secret, payload) {
+    const crypto = globalThis.crypto?.subtle;
+    if (!crypto) {
+        throw new SourceSignatureError('source_signature_invalid', 'WebCrypto HMAC support is unavailable in this runtime');
+    }
+    const encoder = new TextEncoder();
+    const key = await crypto.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    return bufferToBase64(await crypto.sign('HMAC', key, encoder.encode(payload)));
+}
+/**
+ * Constant-time string equality. Used over `===` so a malicious
+ * signature can't be probed byte-by-byte via timing differences.
+ */
+function timingSafeEqual(expected, actual) {
+    const max = Math.max(expected.length, actual.length);
+    let diff = expected.length ^ actual.length;
+    for (let i = 0; i < max; i++) {
+        diff |= (expected.charCodeAt(i) || 0) ^ (actual.charCodeAt(i) || 0);
+    }
+    return diff === 0;
+}
+export async function signAbloSourceRequest(options) {
+    const signedAt = options.timestamp ?? Date.now();
+    // Standard Webhooks signing input: `${msg_id}.${timestamp}.${payload}`
+    // Timestamps are seconds-since-epoch in the spec; we keep millis on
+    // the wire for backwards compatibility with our existing tolerance
+    // window — the receiver compares them millis-to-millis.
+    const signature = await hmacSha256Base64(options.secret, `${options.messageId}.${signedAt}.${options.body}`);
+    return {
+        signedAt,
+        signature,
+        headers: {
+            [ABLO_SOURCE_HEADERS.id]: options.messageId,
+            [ABLO_SOURCE_HEADERS.timestamp]: String(signedAt),
+            [ABLO_SOURCE_HEADERS.signature]: `v1,${signature}`,
+        },
+    };
+}
+export async function verifyAbloSourceRequest(options) {
+    const messageId = getHeader(options.request, ABLO_SOURCE_HEADERS.id);
+    if (!messageId) {
+        throw new SourceSignatureError('source_id_missing', 'Missing webhook-id header');
+    }
+    const rawTimestamp = getHeader(options.request, ABLO_SOURCE_HEADERS.timestamp);
+    if (!rawTimestamp) {
+        throw new SourceSignatureError('source_timestamp_missing', 'Missing webhook-timestamp header');
+    }
+    const signedAt = Number(rawTimestamp);
+    if (!Number.isFinite(signedAt)) {
+        throw new SourceSignatureError('source_timestamp_invalid', 'Invalid webhook-timestamp header');
+    }
+    const toleranceMs = options.toleranceMs ?? DEFAULT_SIGNATURE_TOLERANCE_MS;
+    if (Math.abs(Date.now() - signedAt) > toleranceMs) {
+        throw new SourceSignatureError('source_timestamp_expired', 'webhook-timestamp is outside the allowed clock-skew window');
+    }
+    const presented = parseSignatureHeader(getHeader(options.request, ABLO_SOURCE_HEADERS.signature));
+    if (presented.length === 0) {
+        throw new SourceSignatureError('source_signature_missing', 'Missing webhook-signature header');
+    }
+    const expected = await hmacSha256Base64(options.secret, `${messageId}.${signedAt}.${options.body}`);
+    // Accept any presented signature that matches — supports key
+    // rotation per the Standard Webhooks spec.
+    const ok = presented.some((sig) => timingSafeEqual(expected, sig));
+    if (!ok) {
+        throw new SourceSignatureError('source_signature_invalid', 'Invalid webhook-signature');
+    }
+    return { messageId, signedAt };
+}
+async function resolveSecret(secret, context) {
+    if (!secret)
+        return null;
+    return typeof secret === 'function' ? secret(context) : secret;
+}
+/**
+ * Map a wire request to its scope tag. Each request type corresponds
+ * to one scope, so the function is total and exhaustive — adding a
+ * new request type forces a new scope tag, which is the right design
+ * pressure for keeping the scope vocabulary in sync with the wire.
+ */
+function scopeFor(body) {
+    switch (body.type) {
+        case 'load':
+            return 'load';
+        case 'list':
+            return 'list';
+        case 'commit':
+            return 'commit';
+        case 'events':
+            return 'events';
+    }
+}
+function normalizeListResult(result) {
+    if (Array.isArray(result)) {
+        return { rows: result };
+    }
+    const page = result;
+    return page.nextCursor !== undefined
+        ? { rows: page.rows, nextCursor: page.nextCursor }
+        : { rows: page.rows };
+}
+function getModelHandlers(options, model) {
+    const grouped = options.models?.[model];
+    if (grouped)
+        return grouped;
+    const direct = options[model];
+    return direct;
+}
+function sameModel(operations) {
+    const first = operations[0]?.model;
+    if (!first)
+        return null;
+    return operations.every((op) => op.model === first) ? first : null;
+}
+export function abloSource(options) {
+    return async function handleAbloSource(request) {
+        if (request.method !== 'POST') {
+            return json({ error: 'method_not_allowed' }, 405);
+        }
+        let body;
+        let rawBody;
+        try {
+            const parsed = await readBody(request);
+            body = parsed.body;
+            rawBody = parsed.rawBody;
+        }
+        catch {
+            return json({ error: 'invalid_json' }, 400);
+        }
+        let signature = null;
+        try {
+            const secret = await resolveSecret(options.signingSecret ?? options.secret, {
+                request,
+                body,
+                rawBody,
+            });
+            if (secret) {
+                signature = await verifyAbloSourceRequest({
+                    request,
+                    body: rawBody,
+                    secret,
+                    toleranceMs: options.signatureToleranceMs,
+                });
+            }
+        }
+        catch (err) {
+            if (err instanceof SourceSignatureError) {
+                return json({ error: err.code, message: err.message }, 401);
+            }
+            throw err;
+        }
+        const auth = options.authorize
+            ? await options.authorize({ request, body, rawBody })
+            : undefined;
+        // Per-key permission scope check. When `resolveScopes` is set,
+        // the customer returns the operation set this key is allowed to
+        // invoke; we enforce before any model handler runs.
+        if (options.resolveScopes) {
+            const required = scopeFor(body);
+            const granted = await options.resolveScopes({ auth, request, body });
+            const grantedSet = granted instanceof Set ? granted : new Set(granted);
+            if (!grantedSet.has(required)) {
+                return json({
+                    error: 'source_forbidden',
+                    required,
+                    granted: Array.from(grantedSet),
+                }, 403);
+            }
+        }
+        const context = {
+            auth,
+            request,
+            messageId: signature?.messageId,
+            signedAt: signature?.signedAt,
+            ...(body.scope ? { scope: body.scope } : {}),
+        };
+        if (body.type === 'load') {
+            const handlers = getModelHandlers(options, body.model);
+            if (!handlers?.load) {
+                return json({ error: 'source_load_not_configured', model: body.model }, 404);
+            }
+            const row = await handlers.load({ id: body.id, context });
+            return json({ row });
+        }
+        if (body.type === 'list') {
+            const handlers = getModelHandlers(options, body.model);
+            if (!handlers?.list) {
+                return json({ error: 'source_list_not_configured', model: body.model }, 404);
+            }
+            const result = await handlers.list({ query: body.query ?? {}, context });
+            const normalized = normalizeListResult(result);
+            return json(normalized);
+        }
+        if (body.type === 'commit') {
+            if (options.commit) {
+                const result = await options.commit({
+                    operations: body.operations,
+                    clientTxId: body.clientTxId,
+                    context,
+                });
+                return json(result);
+            }
+            const model = body.model ?? sameModel(body.operations);
+            if (!model) {
+                return json({ error: 'source_commit_requires_single_model' }, 400);
+            }
+            const handlers = getModelHandlers(options, model);
+            if (!handlers?.commit) {
+                return json({ error: 'source_commit_not_configured', model }, 404);
+            }
+            const result = await handlers.commit({
+                operations: body.operations,
+                clientTxId: body.clientTxId,
+                context,
+            });
+            return json(result);
+        }
+        if (body.type === 'events') {
+            if (!options.events) {
+                return json({ error: 'source_events_not_configured' }, 404);
+            }
+            const result = await options.events({
+                cursor: body.cursor,
+                limit: body.limit,
+                context,
+            });
+            return json({
+                events: result.events,
+                ...(result.nextCursor !== undefined
+                    ? { nextCursor: result.nextCursor }
+                    : {}),
+            });
+        }
+        return json({ error: 'unknown_source_request' }, 400);
+    };
+}
+export function dataSource(options) {
+    return abloSource(options);
+}
+export { createPushQueue, InMemoryPushQueueStorage, STANDARD_WEBHOOKS_RETRY_SCHEDULE, } from './pushQueue.js';

package/dist/source/pushQueue.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Customer-side push retry queue.
+ *
+ * The push path (`POST /api/source/events` on Ablo Cloud) acks
+ * synchronously. If the customer's app crashes mid-call, the network
+ * drops, or Ablo returns 5xx, those events would otherwise be lost
+ * — the poll path is the durability backstop, but it's higher
+ * latency.
+ *
+ * `PushQueue` lives in the customer's process and gives them a
+ * queue+worker pattern matching Stripe / Svix semantics:
+ *
+ *   - `enqueue(events)` returns immediately after persisting
+ *   - background worker delivers and retries per the Standard
+ *     Webhooks schedule (0, 5s, 5m, 30m, 2h, 5h, 10h, 14h, 20h, 24h
+ *     — ~3 days total)
+ *   - exhausted items move to DLQ for customer-owned monitoring
+ *
+ * Persistence is pluggable — `InMemoryPushQueueStorage` for single-
+ * process customers, a SQL implementation against the customer's own
+ * outbox table for production.
+ */
+import { type SourceEvent } from './index.js';
+export interface PushQueueItem {
+    readonly id: string;
+    readonly events: readonly SourceEvent[];
+    readonly attempts: number;
+    /** Timestamp (ms) of the next attempt. Workers skip earlier items. */
+    readonly nextAttemptAt: number;
+    /** Most recent error message, when any attempt has failed. */
+    readonly lastError?: string;
+    /** `dlq` once retries exhausted. */
+    readonly status: 'pending' | 'delivered' | 'dlq';
+}
+export interface PushQueueStorage {
+    /**
+     * Append a new item; returns the persisted record. Implementations
+     * generate a stable id (used as the `webhook-id`) and set
+     * `nextAttemptAt = now`.
+     */
+    enqueue(events: readonly SourceEvent[]): Promise<PushQueueItem>;
+    /** Items whose `nextAttemptAt <= now` and `status === 'pending'`. */
+    due(now: number, limit: number): Promise<readonly PushQueueItem[]>;
+    /** Bump attempt count + reschedule. */
+    reschedule(id: string, nextAttemptAt: number, lastError: string): Promise<void>;
+    /** Mark the item delivered (no further attempts). */
+    markDelivered(id: string): Promise<void>;
+    /** Mark the item DLQ (retries exhausted). */
+    markDlq(id: string, lastError: string): Promise<void>;
+    /** Read DLQ contents — customer monitors this. */
+    listDlq(): Promise<readonly PushQueueItem[]>;
+}
+/**
+ * Standard Webhooks retry schedule. Index = attempt number; value =
+ * delay-ms after the previous attempt. After the last entry, items
+ * move to DLQ.
+ *
+ * Source: https://www.standardwebhooks.com/
+ */
+export declare const STANDARD_WEBHOOKS_RETRY_SCHEDULE: readonly number[];
+export interface PushQueueOptions {
+    readonly endpoint: string;
+    readonly secret: string;
+    readonly storage: PushQueueStorage;
+    /**
+     * Override the retry delays. Default: Standard Webhooks schedule.
+     * The number of attempts equals the array length; the i-th entry
+     * is the delay after attempt `i` failed.
+     */
+    readonly retrySchedule?: readonly number[];
+    /** Worker poll interval. Default 1000ms. */
+    readonly tickIntervalMs?: number;
+    /** Max items pulled per tick. Default 50. */
+    readonly batchSize?: number;
+    /** Pluggable for tests / non-Node fetch impls. */
+    readonly fetch?: typeof fetch;
+    /** Pluggable for tests. */
+    readonly now?: () => number;
+    /** Random jitter on retry delays. Default ±10%. Set to 0 to disable. */
+    readonly jitter?: number;
+    readonly onError?: (item: PushQueueItem, err: unknown) => void;
+}
+export interface PushQueue {
+    enqueue(events: readonly SourceEvent[]): Promise<PushQueueItem>;
+    /** Run the worker loop until `signal` aborts. */
+    run(signal: AbortSignal): Promise<void>;
+    /** Drain the DLQ by re-enqueueing — customer-triggered redrive. */
+    redriveDlq(): Promise<number>;
+}
+export declare function createPushQueue(options: PushQueueOptions): PushQueue;
+export declare class InMemoryPushQueueStorage implements PushQueueStorage {
+    /**
+     * Real implementation, not a mock. Suitable for low-volume single-
+     * process customers; not durable across restarts (in-flight items
+     * are lost). Production customers should swap in a SQL-backed
+     * storage that writes to their existing outbox table.
+     */
+    private items;
+    private nextId;
+    private readonly now;
+    constructor(options?: {
+        now?: () => number;
+    });
+    enqueue(events: readonly SourceEvent[]): Promise<PushQueueItem>;
+    due(now: number, limit: number): Promise<readonly PushQueueItem[]>;
+    reschedule(id: string, nextAttemptAt: number, lastError: string): Promise<void>;
+    markDelivered(id: string): Promise<void>;
+    markDlq(id: string, lastError: string): Promise<void>;
+    listDlq(): Promise<readonly PushQueueItem[]>;
+    /** Test helper — read all items regardless of status. */
+    snapshot(): readonly PushQueueItem[];
+}

package/dist/source/pushQueue.js

@@ -0,0 +1,249 @@
+/**
+ * Customer-side push retry queue.
+ *
+ * The push path (`POST /api/source/events` on Ablo Cloud) acks
+ * synchronously. If the customer's app crashes mid-call, the network
+ * drops, or Ablo returns 5xx, those events would otherwise be lost
+ * — the poll path is the durability backstop, but it's higher
+ * latency.
+ *
+ * `PushQueue` lives in the customer's process and gives them a
+ * queue+worker pattern matching Stripe / Svix semantics:
+ *
+ *   - `enqueue(events)` returns immediately after persisting
+ *   - background worker delivers and retries per the Standard
+ *     Webhooks schedule (0, 5s, 5m, 30m, 2h, 5h, 10h, 14h, 20h, 24h
+ *     — ~3 days total)
+ *   - exhausted items move to DLQ for customer-owned monitoring
+ *
+ * Persistence is pluggable — `InMemoryPushQueueStorage` for single-
+ * process customers, a SQL implementation against the customer's own
+ * outbox table for production.
+ */
+import { ABLO_SOURCE_HEADERS, signAbloSourceRequest, } from './index.js';
+/**
+ * Standard Webhooks retry schedule. Index = attempt number; value =
+ * delay-ms after the previous attempt. After the last entry, items
+ * move to DLQ.
+ *
+ * Source: https://www.standardwebhooks.com/
+ */
+export const STANDARD_WEBHOOKS_RETRY_SCHEDULE = [
+    0, // immediate
+    5_000, // 5s
+    5 * 60_000, // 5m
+    30 * 60_000, // 30m
+    2 * 60 * 60_000, // 2h
+    5 * 60 * 60_000, // 5h
+    10 * 60 * 60_000, // 10h
+    14 * 60 * 60_000, // 14h
+    20 * 60 * 60_000, // 20h
+    24 * 60 * 60_000, // 24h
+];
+export function createPushQueue(options) {
+    const tickIntervalMs = options.tickIntervalMs ?? 1000;
+    const batchSize = options.batchSize ?? 50;
+    const fetchImpl = options.fetch ?? fetch;
+    const now = options.now ?? Date.now;
+    const schedule = options.retrySchedule ?? STANDARD_WEBHOOKS_RETRY_SCHEDULE;
+    const jitter = options.jitter ?? 0.1;
+    return {
+        async enqueue(events) {
+            return options.storage.enqueue(events);
+        },
+        async run(signal) {
+            while (!signal.aborted) {
+                try {
+                    const due = await options.storage.due(now(), batchSize);
+                    for (const item of due) {
+                        if (signal.aborted)
+                            return;
+                        await deliver(item);
+                    }
+                }
+                catch (err) {
+                    // Storage failures shouldn't kill the loop; surface and
+                    // back off the tick interval.
+                    options.onError?.({ id: 'storage', events: [], attempts: 0, nextAttemptAt: 0, status: 'pending' }, err);
+                }
+                await sleep(tickIntervalMs, signal);
+            }
+        },
+        async redriveDlq() {
+            const items = await options.storage.listDlq();
+            let redriven = 0;
+            for (const item of items) {
+                await options.storage.enqueue(item.events);
+                redriven++;
+            }
+            return redriven;
+        },
+    };
+    async function deliver(item) {
+        const rawBody = JSON.stringify({ events: item.events });
+        let signed;
+        try {
+            signed = await signAbloSourceRequest({
+                secret: options.secret,
+                body: rawBody,
+                timestamp: now(),
+                // Reuse the queue id as the webhook-id across all retry
+                // attempts so the receiver can dedupe replays per spec.
+                messageId: item.id,
+            });
+        }
+        catch (err) {
+            // Signing should not fail in practice (no network, just HMAC).
+            // If it does, treat as a permanent failure.
+            await options.storage.markDlq(item.id, formatError(err));
+            options.onError?.(item, err);
+            return;
+        }
+        let response;
+        try {
+            response = await fetchImpl(options.endpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...signed.headers,
+                    [ABLO_SOURCE_HEADERS.idempotencyKey]: item.id,
+                },
+                body: rawBody,
+            });
+        }
+        catch (err) {
+            await reschedule(item, formatError(err));
+            return;
+        }
+        if (response.ok) {
+            await options.storage.markDelivered(item.id);
+            return;
+        }
+        // 4xx other than 408/429 are unrecoverable — don't retry. Move
+        // straight to DLQ so the customer's monitoring catches the bad
+        // request shape early instead of waiting 3 days for retries.
+        if (response.status >= 400 &&
+            response.status < 500 &&
+            response.status !== 408 &&
+            response.status !== 429) {
+            await options.storage.markDlq(item.id, `HTTP ${response.status}`);
+            return;
+        }
+        await reschedule(item, `HTTP ${response.status}`);
+    }
+    async function reschedule(item, error) {
+        const nextAttempt = item.attempts + 1;
+        if (nextAttempt >= schedule.length) {
+            await options.storage.markDlq(item.id, error);
+            options.onError?.(item, new Error(error));
+            return;
+        }
+        const delay = applyJitter(schedule[nextAttempt], jitter);
+        await options.storage.reschedule(item.id, now() + delay, error);
+    }
+}
+export class InMemoryPushQueueStorage {
+    /**
+     * Real implementation, not a mock. Suitable for low-volume single-
+     * process customers; not durable across restarts (in-flight items
+     * are lost). Production customers should swap in a SQL-backed
+     * storage that writes to their existing outbox table.
+     */
+    items = new Map();
+    nextId = 0;
+    now;
+    constructor(options = {}) {
+        this.now = options.now ?? Date.now;
+    }
+    async enqueue(events) {
+        const id = `q_${(++this.nextId).toString(36)}_${Math.random()
+            .toString(36)
+            .slice(2, 8)}`;
+        const item = {
+            id,
+            events,
+            attempts: 0,
+            nextAttemptAt: this.now(),
+            status: 'pending',
+        };
+        this.items.set(id, item);
+        return item;
+    }
+    async due(now, limit) {
+        const out = [];
+        for (const item of this.items.values()) {
+            if (out.length >= limit)
+                break;
+            if (item.status !== 'pending')
+                continue;
+            if (item.nextAttemptAt > now)
+                continue;
+            out.push(item);
+        }
+        return out;
+    }
+    async reschedule(id, nextAttemptAt, lastError) {
+        const item = this.items.get(id);
+        if (!item)
+            return;
+        this.items.set(id, {
+            ...item,
+            attempts: item.attempts + 1,
+            nextAttemptAt,
+            lastError,
+        });
+    }
+    async markDelivered(id) {
+        const item = this.items.get(id);
+        if (!item)
+            return;
+        this.items.set(id, { ...item, status: 'delivered' });
+    }
+    async markDlq(id, lastError) {
+        const item = this.items.get(id);
+        if (!item)
+            return;
+        this.items.set(id, {
+            ...item,
+            attempts: item.attempts + 1,
+            status: 'dlq',
+            lastError,
+        });
+    }
+    async listDlq() {
+        return Array.from(this.items.values()).filter((i) => i.status === 'dlq');
+    }
+    /** Test helper — read all items regardless of status. */
+    snapshot() {
+        return Array.from(this.items.values());
+    }
+}
+function applyJitter(delayMs, factor) {
+    if (factor <= 0 || delayMs === 0)
+        return delayMs;
+    const swing = delayMs * factor;
+    return Math.max(0, delayMs + (Math.random() * 2 - 1) * swing);
+}
+function formatError(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}