@abloatai/ablo 0.25.0 → 0.26.0

package/dist/source/index.js

@@ -1,422 +1,18 @@
-import { AbloValidationError } from '../errors.js';
-import { changeSetSchema } from './contract.js';
 /**
- * Build the source-event marker customers should write to their outbox table in
- * the SAME transaction as their app-row mutation.
+ * `@abloatai/ablo/source` — the Data Source barrel.
  *
- * This helper does not persist anything. It only standardizes the marker shape
- * so Prisma/Drizzle/Kysely/raw-SQL adapters all emit the fields Ablo's
- * reconciler expects.
- */
-export function sourceEventForOperation(options) {
-    const entityId = options.entityId ?? options.operation.id;
-    if (typeof entityId !== 'string' || entityId.length === 0) {
-        throw new AbloValidationError('sourceEventForOperation requires operation.id or an explicit entityId', { code: 'source_event_invalid' });
-    }
-    const occurredAt = normalizeEventOccurredAt(options.occurredAt);
-    return {
-        id: options.eventId,
-        model: options.operation.model,
-        entityId,
-        type: options.operation.type,
-        ...(options.data !== undefined ? { data: options.data } : {}),
-        ...(options.organizationId ? { organizationId: options.organizationId } : {}),
-        ...(options.clientTxId ? { clientTxId: options.clientTxId } : {}),
-        ...(occurredAt !== undefined ? { occurredAt } : {}),
-    };
-}
-function normalizeEventOccurredAt(value) {
-    if (value === undefined)
-        return undefined;
-    const timestamp = value instanceof Date ? value.getTime() : value;
-    return Number.isFinite(timestamp) ? timestamp : undefined;
-}
-/**
- * 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' },
-    });
-}
-/**
- * Serve a request from an ORM `adapter`. Routes the four operations to the adapter
- * interface (`read`/`commit`/`events`) and shapes the wire response. The adapter is the
- * single point of dispatch — no per-model branching here.
- */
-async function handleViaAdapter(adapter, body, scope) {
-    if (body.type === 'load') {
-        const rows = await adapter.read({
-            kind: 'load',
-            model: body.model,
-            id: body.id,
-            ...(scope ? { scope } : {}),
-        });
-        return json({ row: rows[0] ?? null });
-    }
-    if (body.type === 'list') {
-        const rows = await adapter.read({
-            kind: 'list',
-            model: body.model,
-            ...(body.query ? { query: body.query } : {}),
-            ...(scope ? { scope } : {}),
-        });
-        return json({ rows });
-    }
-    if (body.type === 'commit') {
-        if (!body.clientTxId) {
-            return json({ error: 'source_commit_requires_client_tx_id', message: 'commit requires a clientTxId for idempotency' }, 400);
-        }
-        const parsed = changeSetSchema.safeParse({
-            operations: body.operations,
-            clientTxId: body.clientTxId,
-        });
-        if (!parsed.success) {
-            return json({ error: 'source_commit_invalid', message: parsed.error.message }, 400);
-        }
-        const result = await adapter.commit(parsed.data);
-        return json({ rows: result.rows });
-    }
-    if (body.type === 'events') {
-        const page = await adapter.events(body.cursor ?? null, body.limit ?? 100);
-        return json({
-            events: page.events.map((event) => ({
-                id: event.id,
-                model: event.model,
-                entityId: event.entityId,
-                type: event.type,
-                ...(event.data !== undefined && event.data !== null ? { data: event.data } : {}),
-                ...(event.organizationId ? { organizationId: event.organizationId } : {}),
-                ...(event.clientTxId ? { clientTxId: event.clientTxId } : {}),
-                ...(event.occurredAt !== undefined && event.occurredAt !== null
-                    ? { occurredAt: event.occurredAt }
-                    : {}),
-            })),
-            ...(page.nextCursor !== null ? { nextCursor: page.nextCursor } : {}),
-        });
-    }
-    return json({ error: 'unknown_source_request' }, 400);
-}
-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(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;
-}
-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}`,
-        },
-    };
-}
-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 };
-}
-async function resolveApiKey(apiKey, context) {
-    if (!apiKey)
-        return null;
-    return typeof apiKey === 'function' ? apiKey(context) : apiKey;
-}
-/**
- * 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.
+ * Pure re-exports only: the implementation lives in cohesive leaf modules so
+ * sibling source/* files (`pushQueue.ts`, `adapter.ts`, `contract.ts`, the ORM
+ * adapters) import the leaves directly instead of routing a runtime circular
+ * dependency through this barrel.
+ *
+ *   - `types.ts`   — shared wire/handler types + `sourceEventForOperation`
+ *   - `signing.ts` — Standard Webhooks request signing/verification
+ *   - `factory.ts` — the `abloSource()` / `dataSource()` endpoint factory
  */
-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 apiKey = await resolveApiKey(options.apiKey, {
-                request,
-                body,
-                rawBody,
-            });
-            if (!apiKey) {
-                return json({
-                    error: 'source_api_key_missing',
-                    message: 'Data Source apiKey is required',
-                }, 401);
-            }
-            signature = await verifyAbloSourceRequest({
-                request,
-                body: rawBody,
-                apiKey,
-                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 } : {}),
-        };
-        // Adapter path: when an ORM adapter is configured it serves every operation,
-        // consumed at this generic layer (rows are JSON on the wire), so no per-model
-        // handler lookup and no typed↔generic boundary.
-        if (options.adapter) {
-            return handleViaAdapter(options.adapter, body, context.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 { sourceEventForOperation, } from './types.js';
+export { ABLO_SOURCE_HEADERS, SourceSignatureError, signAbloSourceRequest, verifyAbloSourceRequest, } from './signing.js';
+export { abloSource, dataSource, } from './factory.js';
 export { createPushQueue, InMemoryPushQueueStorage, STANDARD_WEBHOOKS_RETRY_SCHEDULE, } from './pushQueue.js';
 // ── Reverse-channel connector (outbound transport for the commit/load/list leg) ──
 // The dial-out counterpart to `createPushQueue`. Lets a customer serve Data
@@ -424,6 +20,8 @@ export { createPushQueue, InMemoryPushQueueStorage, STANDARD_WEBHOOKS_RETRY_SCHE
 // public inbound URL — see `connector-protocol.ts`.
 export { createSourceConnector, DEFAULT_RECONNECT_SCHEDULE, } from './connector.js';
 export { SOURCE_CONNECTOR_PROTOCOL_VERSION, SOURCE_CONNECTOR_WS_PATH, WS_SOURCE_SUBPROTOCOL, sourceConnectorSubprotocols, encodeFrame, decodeFrame, ConnectorProtocolError, connectorFrameSchema, } from './connector-protocol.js';
+// ── Data Source adapter interface (Zod contract + one interface, per-ORM packages) ──
+export {} from './adapter.js';
 export { operationSchema, operationTypeSchema, changeSetSchema, outboxEventSchema, eventsPageSchema, migrationSchema, adapterCapabilitiesSchema, } from './contract.js';
 export { prismaDataSource } from './adapters/prisma.js';
 export { adapterTableMigrations } from './migrations.js';

package/dist/source/next.d.ts

@@ -21,7 +21,7 @@
  * — not pre-built.
  */
 import type { SchemaRecord } from '../schema/schema.js';
-import { type DataSourceOptions } from './index.js';
+import { type DataSourceOptions } from './factory.js';
 /**
  * Next options ARE the core options — the `adapter` field lives on the core
  * handler now, so there is no bridging, no cast, and no per-model-typed boundary

package/dist/source/next.js

@@ -20,7 +20,7 @@
  * `dataSource()` directly; Hono/Express are the same one-liner and land on demand
  * — not pre-built.
  */
-import { dataSource } from './index.js';
+import { dataSource } from './factory.js';
 export function dataSourceNext(options) {
     return { POST: dataSource(options) };
 }

package/dist/source/pushQueue.d.ts

@@ -20,7 +20,7 @@
  * process customers, a SQL implementation against the customer's own
  * outbox table for production.
  */
-import { type SourceEvent } from './index.js';
+import type { SourceEvent } from './types.js';
 export interface PushQueueItem {
     readonly id: string;
     readonly events: readonly SourceEvent[];

package/dist/source/pushQueue.js

@@ -20,7 +20,7 @@
  * process customers, a SQL implementation against the customer's own
  * outbox table for production.
  */
-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
@@ -133,12 +133,15 @@ export function createPushQueue(options) {
     }
     async function reschedule(item, error) {
         const nextAttempt = item.attempts + 1;
-        if (nextAttempt >= schedule.length) {
+        // Off the end of the backoff schedule (same check as the old
+        // `nextAttempt >= schedule.length`) — 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);
     }
 }

package/dist/source/signing.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Standard Webhooks request signing/verification for Data Source calls.
+ *
+ * Ablo signs every outbound source request with the customer's project API
+ * key; the customer's endpoint verifies before any handler runs. Both halves
+ * live in this leaf so `pushQueue.ts` (customer-side sender) and `factory.ts`
+ * (customer-side receiver) can import them directly without a runtime cycle
+ * through the `index.ts` barrel.
+ */
+export interface SourceSignatureOptions {
+    readonly apiKey: string;
+    readonly body: string;
+    /**
+     * Unique message id (`webhook-id` per the Standard Webhooks spec).
+     * Required: it goes into the HMAC input for replay defense, and
+     * receivers may dedupe by it.
+     */
+    readonly messageId: string;
+    /**
+     * Unix timestamp in seconds. Defaults to the current time.
+     */
+    readonly timestamp?: number;
+}
+export interface SourceSignatureVerificationOptions {
+    readonly request: Request;
+    readonly body: string;
+    readonly apiKey: string;
+    readonly toleranceMs?: number;
+}
+export interface SourceSignatureVerificationResult {
+    readonly messageId: string;
+    readonly signedAt: number;
+}
+/**
+ * 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 declare const ABLO_SOURCE_HEADERS: {
+    readonly signature: "webhook-signature";
+    readonly timestamp: "webhook-timestamp";
+    readonly id: "webhook-id";
+    readonly idempotencyKey: "Idempotency-Key";
+};
+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);
+}
+export declare function signAbloSourceRequest(options: SourceSignatureOptions): Promise<{
+    readonly headers: Record<string, string>;
+    readonly signedAt: number;
+    readonly signature: string;
+}>;
+export declare function verifyAbloSourceRequest(options: SourceSignatureVerificationOptions): Promise<SourceSignatureVerificationResult>;
+export type DataSourceSignatureOptions = SourceSignatureOptions;
+export type DataSourceSignatureVerificationOptions = SourceSignatureVerificationOptions;
+export type DataSourceSignatureVerificationResult = SourceSignatureVerificationResult;