@abloatai/ablo 0.25.0 → 0.27.0

package/dist/source/pushQueue.d.ts

@@ -1,100 +1,122 @@
 /**
- * Customer-side push retry queue.
+ * A durable retry queue for delivering source events to the server.
  *
- * 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.
+ * When your application changes a row, it can push the resulting event to
+ * the server, which acknowledges delivery synchronously. If your process
+ * crashes mid-call, the network drops, or the server returns a 5xx, that
+ * event would be lost without a safety net. This queue is the safety net:
+ * it persists each event first, then delivers it from a background worker
+ * with automatic retries. (Polling the change feed is the slower fallback
+ * for anything the queue never manages to deliver.)
  *
- * `PushQueue` lives in the customer's process and gives them a
- * queue+worker pattern matching Stripe / Svix semantics:
+ * The queue follows a familiar enqueue-and-worker shape:
  *
- *   - `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
+ *   - `enqueue(events)` returns as soon as the events are persisted.
+ *   - A background worker delivers them and retries on failure, following
+ *     the Standard Webhooks schedule (0, 5s, 5m, 30m, 2h, 5h, 10h, 14h,
+ *     20h, 24h — roughly three days in total).
+ *   - Items that exhaust every retry move to a dead-letter queue you can
+ *     monitor.
  *
- * Persistence is pluggable — `InMemoryPushQueueStorage` for single-
- * process customers, a SQL implementation against the customer's own
- * outbox table for production.
+ * Persistence is pluggable through {@link PushQueueStorage}. Use
+ * {@link InMemoryPushQueueStorage} for a single process, or implement that
+ * interface against your own outbox table for production durability.
  */
-import { type SourceEvent } from './index.js';
+import type { SourceEvent } from './types.js';
+/** One queued delivery: a batch of source events plus its retry bookkeeping. */
 export interface PushQueueItem {
     readonly id: string;
     readonly events: readonly SourceEvent[];
     readonly attempts: number;
-    /** Timestamp (ms) of the next attempt. Workers skip earlier items. */
+    /** When the next attempt is due, in epoch milliseconds. The worker skips items due later. */
     readonly nextAttemptAt: number;
-    /** Most recent error message, when any attempt has failed. */
+    /** The most recent error message, set once an attempt has failed. */
     readonly lastError?: string;
-    /** `dlq` once retries exhausted. */
+    /** `pending` while awaiting delivery, `delivered` on success, `dlq` once retries are exhausted. */
     readonly status: 'pending' | 'delivered' | 'dlq';
 }
+/**
+ * The persistence behind a {@link PushQueue}. Implement it against your own
+ * durable table (or use {@link InMemoryPushQueueStorage}) so queued events
+ * survive a process restart. The queue calls these methods; you decide where
+ * the rows actually live.
+ */
 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`.
+     * Append a new item and return the persisted record. Generate a stable id
+     * — it doubles as the `webhook-id` on the delivered request — and set
+     * `nextAttemptAt` to the current time so the item is due immediately.
      */
     enqueue(events: readonly SourceEvent[]): Promise<PushQueueItem>;
-    /** Items whose `nextAttemptAt <= now` and `status === 'pending'`. */
+    /** Return pending items whose `nextAttemptAt` is at or before `now`, up to `limit`. */
     due(now: number, limit: number): Promise<readonly PushQueueItem[]>;
-    /** Bump attempt count + reschedule. */
+    /** Increase the attempt count and set the next attempt time after a failed delivery. */
     reschedule(id: string, nextAttemptAt: number, lastError: string): Promise<void>;
-    /** Mark the item delivered (no further attempts). */
+    /** Mark the item delivered so no further attempts are made. */
     markDelivered(id: string): Promise<void>;
-    /** Mark the item DLQ (retries exhausted). */
+    /** Move the item to the dead-letter queue after its retries are exhausted. */
     markDlq(id: string, lastError: string): Promise<void>;
-    /** Read DLQ contents — customer monitors this. */
+    /** Read the dead-letter queue. Your monitoring reads this to surface deliveries that never succeeded. */
     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.
+ * The default retry schedule, taken from the Standard Webhooks
+ * specification. The index is the attempt number and the value is the delay
+ * in milliseconds after the previous attempt failed. Once an item runs off
+ * the end of this array, it moves to the dead-letter queue.
  *
- * Source: https://www.standardwebhooks.com/
+ * See https://www.standardwebhooks.com/.
  */
 export declare const STANDARD_WEBHOOKS_RETRY_SCHEDULE: readonly number[];
+/** Configuration for {@link createPushQueue}. */
 export interface PushQueueOptions {
+    /** The URL the worker delivers events to. */
     readonly endpoint: string;
+    /** The API key used to sign each delivery. */
     readonly apiKey: string;
+    /** Where queued items are persisted. */
     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.
+     * Override the retry delays. Defaults to {@link STANDARD_WEBHOOKS_RETRY_SCHEDULE}.
+     * The number of attempts equals the array length, and the i-th entry is the
+     * delay after attempt `i` failed.
      */
     readonly retrySchedule?: readonly number[];
-    /** Worker poll interval. Default 1000ms. */
+    /** How often the worker checks for due items, in milliseconds. Defaults to 1000. */
     readonly tickIntervalMs?: number;
-    /** Max items pulled per tick. Default 50. */
+    /** The most items the worker delivers per tick. Defaults to 50. */
     readonly batchSize?: number;
-    /** Pluggable for tests / non-Node fetch impls. */
+    /** A custom fetch implementation, for tests or runtimes without a global `fetch`. */
     readonly fetch?: typeof fetch;
-    /** Pluggable for tests. */
+    /** A custom clock source, mainly for tests. Defaults to `Date.now`. */
     readonly now?: () => number;
-    /** Random jitter on retry delays. Default ±10%. Set to 0 to disable. */
+    /** Random jitter applied to each retry delay, as a fraction. Defaults to ±10%; set 0 to disable. */
     readonly jitter?: number;
+    /** Called when an item is dead-lettered or the worker loop hits an error. */
     readonly onError?: (item: PushQueueItem, err: unknown) => void;
 }
+/** A running push queue: persist events, deliver them, and recover dead-lettered ones. */
 export interface PushQueue {
+    /** Persist a batch of events for delivery and return the queued item. */
     enqueue(events: readonly SourceEvent[]): Promise<PushQueueItem>;
-    /** Run the worker loop until `signal` aborts. */
+    /** Run the delivery worker until `signal` aborts. */
     run(signal: AbortSignal): Promise<void>;
-    /** Drain the DLQ by re-enqueueing — customer-triggered redrive. */
+    /**
+     * Re-enqueue every dead-lettered item for another round of delivery. Call
+     * this yourself once you have fixed whatever caused the failures. Returns
+     * the number of items re-enqueued.
+     */
     redriveDlq(): Promise<number>;
 }
+/** Create a {@link PushQueue} from the given {@link PushQueueOptions}. */
 export declare function createPushQueue(options: PushQueueOptions): PushQueue;
+/**
+ * A {@link PushQueueStorage} that keeps items in memory. It is not durable —
+ * items are lost when the process restarts — so it suits development and
+ * low-volume use. For production, implement {@link PushQueueStorage} against
+ * your own table.
+ */
 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;

package/dist/source/pushQueue.js

@@ -1,32 +1,35 @@
 /**
- * Customer-side push retry queue.
+ * A durable retry queue for delivering source events to the server.
  *
- * 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.
+ * When your application changes a row, it can push the resulting event to
+ * the server, which acknowledges delivery synchronously. If your process
+ * crashes mid-call, the network drops, or the server returns a 5xx, that
+ * event would be lost without a safety net. This queue is the safety net:
+ * it persists each event first, then delivers it from a background worker
+ * with automatic retries. (Polling the change feed is the slower fallback
+ * for anything the queue never manages to deliver.)
  *
- * `PushQueue` lives in the customer's process and gives them a
- * queue+worker pattern matching Stripe / Svix semantics:
+ * The queue follows a familiar enqueue-and-worker shape:
  *
- *   - `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
+ *   - `enqueue(events)` returns as soon as the events are persisted.
+ *   - A background worker delivers them and retries on failure, following
+ *     the Standard Webhooks schedule (0, 5s, 5m, 30m, 2h, 5h, 10h, 14h,
+ *     20h, 24h — roughly three days in total).
+ *   - Items that exhaust every retry move to a dead-letter queue you can
+ *     monitor.
  *
- * Persistence is pluggable — `InMemoryPushQueueStorage` for single-
- * process customers, a SQL implementation against the customer's own
- * outbox table for production.
+ * Persistence is pluggable through {@link PushQueueStorage}. Use
+ * {@link InMemoryPushQueueStorage} for a single process, or implement that
+ * interface against your own outbox table for production durability.
  */
-import { ABLO_SOURCE_HEADERS, signAbloSourceRequest, } from './index.js';
+import { ABLO_SOURCE_HEADERS, signAbloSourceRequest } from './signing.js';
 /**
- * Standard Webhooks retry schedule. Index = attempt number; value =
- * delay-ms after the previous attempt. After the last entry, items
- * move to DLQ.
+ * The default retry schedule, taken from the Standard Webhooks
+ * specification. The index is the attempt number and the value is the delay
+ * in milliseconds after the previous attempt failed. Once an item runs off
+ * the end of this array, it moves to the dead-letter queue.
  *
- * Source: https://www.standardwebhooks.com/
+ * See https://www.standardwebhooks.com/.
  */
 export const STANDARD_WEBHOOKS_RETRY_SCHEDULE = [
     0, // immediate
@@ -40,6 +43,7 @@ export const STANDARD_WEBHOOKS_RETRY_SCHEDULE = [
     20 * 60 * 60_000, // 20h
     24 * 60 * 60_000, // 24h
 ];
+/** Create a {@link PushQueue} from the given {@link PushQueueOptions}. */
 export function createPushQueue(options) {
     const tickIntervalMs = options.tickIntervalMs ?? 1000;
     const batchSize = options.batchSize ?? 50;
@@ -133,22 +137,25 @@ export function createPushQueue(options) {
     }
     async function reschedule(item, error) {
         const nextAttempt = item.attempts + 1;
-        if (nextAttempt >= schedule.length) {
+        // Past the end of the backoff schedule: no attempts left, so dead-letter
+        // the item.
+        const backoff = schedule[nextAttempt];
+        if (backoff === undefined) {
             await options.storage.markDlq(item.id, error);
             options.onError?.(item, new Error(error));
             return;
         }
-        const delay = applyJitter(schedule[nextAttempt], jitter);
+        const delay = applyJitter(backoff, jitter);
         await options.storage.reschedule(item.id, now() + delay, error);
     }
 }
+/**
+ * A {@link PushQueueStorage} that keeps items in memory. It is not durable —
+ * items are lost when the process restarts — so it suits development and
+ * low-volume use. For production, implement {@link PushQueueStorage} against
+ * your own table.
+ */
 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;

package/dist/source/signing.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Signs and verifies source requests using the Standard Webhooks scheme.
+ *
+ * Every request Ablo sends to a data source is signed with that source's API
+ * key, and the receiving endpoint verifies the signature before any handler
+ * runs. This module provides both halves: {@link signAbloSourceRequest} for
+ * the sender and {@link verifyAbloSourceRequest} for the receiver. Because the
+ * signature format follows the Standard Webhooks specification, you can verify
+ * it with any compatible library instead of these functions if you prefer.
+ */
+/** Inputs to {@link signAbloSourceRequest}. */
+export interface SourceSignatureOptions {
+    /** The API key to sign with; the receiver verifies against the same key. */
+    readonly apiKey: string;
+    /** The exact request body being signed. */
+    readonly body: string;
+    /**
+     * The unique message id, sent as the `webhook-id` header. It is folded into
+     * the signature to defend against replay, and receivers may deduplicate on
+     * it. Retries of the same request must reuse the same id.
+     */
+    readonly messageId: string;
+    /** The signing time as a Unix timestamp in seconds. Defaults to the current time. */
+    readonly timestamp?: number;
+}
+/** Inputs to {@link verifyAbloSourceRequest}. */
+export interface SourceSignatureVerificationOptions {
+    /** The incoming request, whose headers carry the signature to check. */
+    readonly request: Request;
+    /** The request body, which must match what was signed. */
+    readonly body: string;
+    /** The API key to verify against. */
+    readonly apiKey: string;
+    /**
+     * How far the request's timestamp may differ from the current clock, in
+     * milliseconds, before it is rejected as expired. Defaults to five minutes.
+     */
+    readonly toleranceMs?: number;
+}
+/** What {@link verifyAbloSourceRequest} returns once a signature checks out. */
+export interface SourceSignatureVerificationResult {
+    /** The verified `webhook-id` of the request. */
+    readonly messageId: string;
+    /** The time the request was signed, as a Unix timestamp in seconds. */
+    readonly signedAt: number;
+}
+/**
+ * The HTTP header names carried on a signed source request. They follow the
+ * Standard Webhooks specification (https://www.standardwebhooks.com/), so you
+ * can verify the signature with any compatible library rather than
+ * {@link verifyAbloSourceRequest} if you prefer.
+ */
+export declare const ABLO_SOURCE_HEADERS: {
+    readonly signature: "webhook-signature";
+    readonly timestamp: "webhook-timestamp";
+    readonly id: "webhook-id";
+    readonly idempotencyKey: "Idempotency-Key";
+};
+/**
+ * Thrown when a source request fails signature verification. The
+ * {@link SourceSignatureError.code} names the specific reason — a missing
+ * header, a malformed or expired timestamp, or a signature that does not
+ * match.
+ */
+export declare class SourceSignatureError extends Error {
+    readonly code: 'source_signature_missing' | 'source_id_missing' | 'source_timestamp_missing' | 'source_timestamp_invalid' | 'source_timestamp_expired' | 'source_signature_invalid' | 'source_forbidden';
+    constructor(code: SourceSignatureError['code'], message: string);
+}
+/**
+ * Sign a source request and return the headers to send with it. The signature
+ * covers the message id, the timestamp, and the body, so any change to those
+ * invalidates it. The receiver checks it with {@link verifyAbloSourceRequest}.
+ */
+export declare function signAbloSourceRequest(options: SourceSignatureOptions): Promise<{
+    readonly headers: Record<string, string>;
+    readonly signedAt: number;
+    readonly signature: string;
+}>;
+/**
+ * Verify a signed source request, throwing {@link SourceSignatureError} when
+ * the message id, timestamp, or signature is missing, malformed, or outside
+ * the allowed clock-skew window. On success it returns the request's message
+ * id and signing time. This is the counterpart to {@link signAbloSourceRequest}.
+ */
+export declare function verifyAbloSourceRequest(options: SourceSignatureVerificationOptions): Promise<SourceSignatureVerificationResult>;
+export type DataSourceSignatureOptions = SourceSignatureOptions;
+export type DataSourceSignatureVerificationOptions = SourceSignatureVerificationOptions;
+export type DataSourceSignatureVerificationResult = SourceSignatureVerificationResult;

package/dist/source/signing.js

@@ -0,0 +1,159 @@
+/**
+ * Signs and verifies source requests using the Standard Webhooks scheme.
+ *
+ * Every request Ablo sends to a data source is signed with that source's API
+ * key, and the receiving endpoint verifies the signature before any handler
+ * runs. This module provides both halves: {@link signAbloSourceRequest} for
+ * the sender and {@link verifyAbloSourceRequest} for the receiver. Because the
+ * signature format follows the Standard Webhooks specification, you can verify
+ * it with any compatible library instead of these functions if you prefer.
+ */
+/**
+ * The HTTP header names carried on a signed source request. They follow the
+ * Standard Webhooks specification (https://www.standardwebhooks.com/), so you
+ * can verify the signature with any compatible library rather than
+ * {@link verifyAbloSourceRequest} if you prefer.
+ */
+export const ABLO_SOURCE_HEADERS = {
+    signature: 'webhook-signature',
+    timestamp: 'webhook-timestamp',
+    id: 'webhook-id',
+    idempotencyKey: 'Idempotency-Key',
+};
+/**
+ * Thrown when a source request fails signature verification. The
+ * {@link SourceSignatureError.code} names the specific reason — a missing
+ * header, a malformed or expired timestamp, or a signature that does not
+ * match.
+ */
+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 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 = '';
+    for (const byte of new Uint8Array(buffer)) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+}
+async function hmacSha256Base64(apiKey, 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(apiKey), { 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;
+}
+/**
+ * Sign a source request and return the headers to send with it. The signature
+ * covers the message id, the timestamp, and the body, so any change to those
+ * invalidates it. The receiver checks it with {@link verifyAbloSourceRequest}.
+ */
+export async function signAbloSourceRequest(options) {
+    const signedAt = options.timestamp ?? Math.floor(Date.now() / 1000);
+    // Standard Webhooks signing input: `${msg_id}.${timestamp}.${payload}`
+    const signature = await hmacSha256Base64(options.apiKey, `${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}`,
+        },
+    };
+}
+/**
+ * Verify a signed source request, throwing {@link SourceSignatureError} when
+ * the message id, timestamp, or signature is missing, malformed, or outside
+ * the allowed clock-skew window. On success it returns the request's message
+ * id and signing time. This is the counterpart to {@link signAbloSourceRequest}.
+ */
+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;
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    const toleranceSeconds = Math.ceil(toleranceMs / 1000);
+    if (Math.abs(nowSeconds - signedAt) > toleranceSeconds) {
+        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.apiKey, `${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 };
+}