@abloatai/ablo 0.36.0 → 0.37.0

package/dist/source/next.d.ts

@@ -1,32 +0,0 @@
-/**
- * A thin Next.js App Router wrapper for a Data Source. The core `dataSource()`
- * already returns a standard `(Request) => Promise<Response>`, which the App Router
- * accepts directly, so this helper adds only convenience: it names the handler
- * `POST` so your route file can export it in one line.
- *
- *   // app/api/ablo/source/route.ts
- *   import { dataSourceNext } from '@abloatai/ablo/source/next';
- *   import { prismaDataSource } from '@abloatai/ablo/source';
- *   import { schema } from '@/ablo/schema';
- *   import { prisma } from '@/lib/prisma';
- *
- *   export const { POST } = dataSourceNext({
- *     schema,
- *     apiKey: process.env.ABLO_API_KEY!,
- *     adapter: prismaDataSource(prisma, schema),
- *   });
- *
- * For hand-written handlers, or another framework, call the core `dataSource()`
- * directly and export its result however that framework expects.
- */
-import type { SchemaRecord } from '../transaction/schema/schema.js';
-import { type DataSourceOptions } from './factory.js';
-/**
- * The options for `dataSourceNext`, which are exactly the core
- * `DataSourceOptions`. Pass `{ schema, apiKey, adapter }`, the same shape
- * `dataSource()` takes.
- */
-export type DataSourceNextOptions<S extends SchemaRecord, TAuth = unknown> = DataSourceOptions<S, TAuth>;
-export declare function dataSourceNext<const S extends SchemaRecord, TAuth = unknown>(options: DataSourceNextOptions<S, TAuth>): {
-    readonly POST: (request: Request) => Promise<Response>;
-};

package/dist/source/next.js

@@ -1,25 +0,0 @@
-/**
- * A thin Next.js App Router wrapper for a Data Source. The core `dataSource()`
- * already returns a standard `(Request) => Promise<Response>`, which the App Router
- * accepts directly, so this helper adds only convenience: it names the handler
- * `POST` so your route file can export it in one line.
- *
- *   // app/api/ablo/source/route.ts
- *   import { dataSourceNext } from '@abloatai/ablo/source/next';
- *   import { prismaDataSource } from '@abloatai/ablo/source';
- *   import { schema } from '@/ablo/schema';
- *   import { prisma } from '@/lib/prisma';
- *
- *   export const { POST } = dataSourceNext({
- *     schema,
- *     apiKey: process.env.ABLO_API_KEY!,
- *     adapter: prismaDataSource(prisma, schema),
- *   });
- *
- * For hand-written handlers, or another framework, call the core `dataSource()`
- * directly and export its result however that framework expects.
- */
-import { dataSource } from './factory.js';
-export function dataSourceNext(options) {
-    return { POST: dataSource(options) };
-}

package/dist/source/pushQueue.d.ts

@@ -1,134 +0,0 @@
-/**
- * A durable retry queue for delivering source events to the server.
- *
- * 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.)
- *
- * The queue follows a familiar enqueue-and-worker shape:
- *
- *   - `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 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 './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;
-    /** When the next attempt is due, in epoch milliseconds. The worker skips items due later. */
-    readonly nextAttemptAt: number;
-    /** The most recent error message, set once an attempt has failed. */
-    readonly lastError?: string;
-    /** `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 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>;
-    /** Return pending items whose `nextAttemptAt` is at or before `now`, up to `limit`. */
-    due(now: number, limit: number): Promise<readonly PushQueueItem[]>;
-    /** 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 so no further attempts are made. */
-    markDelivered(id: string): Promise<void>;
-    /** Move the item to the dead-letter queue after its retries are exhausted. */
-    markDlq(id: string, lastError: string): Promise<void>;
-    /** Read the dead-letter queue. Your monitoring reads this to surface deliveries that never succeeded. */
-    listDlq(): Promise<readonly PushQueueItem[]>;
-}
-/**
- * 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.
- *
- * 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. 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[];
-    /** How often the worker checks for due items, in milliseconds. Defaults to 1000. */
-    readonly tickIntervalMs?: number;
-    /** The most items the worker delivers per tick. Defaults to 50. */
-    readonly batchSize?: number;
-    /** A custom fetch implementation, for tests or runtimes without a global `fetch`. */
-    readonly fetch?: typeof fetch;
-    /** A custom clock source, mainly for tests. Defaults to `Date.now`. */
-    readonly now?: () => number;
-    /** 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 delivery worker until `signal` aborts. */
-    run(signal: AbortSignal): Promise<void>;
-    /**
-     * 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 {
-    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

@@ -1,256 +0,0 @@
-/**
- * A durable retry queue for delivering source events to the server.
- *
- * 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.)
- *
- * The queue follows a familiar enqueue-and-worker shape:
- *
- *   - `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 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 './signing.js';
-/**
- * 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.
- *
- * See 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
-];
-/** Create a {@link PushQueue} from the given {@link PushQueueOptions}. */
-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({
-                apiKey: options.apiKey,
-                body: rawBody,
-                timestamp: Math.floor(now() / 1000),
-                // 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;
-        // 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(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 {
-    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 });
-    });
-}

package/dist/source/signing.d.ts

@@ -1,92 +0,0 @@
-/**
- * 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. Any
-     * request-shaped object works: a fetch `Request` (its `Headers` is read with
-     * `.get`), or a plain header record like Node's `req.headers` — matching
-     * what the runtime has always accepted.
-     */
-    readonly request: {
-        readonly headers?: Headers | Record<string, string | string[] | undefined>;
-    };
-    /** 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>;