@abloatai/ablo 0.25.0 → 0.27.0

package/dist/source/index.js

@@ -1,429 +1,25 @@
-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.
+ * The entry point for the Data Source API, re-exporting the pieces you need from
+ * their individual modules:
  *
- * 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.
+ *   - `types.ts`   — the shared wire and handler types, plus `sourceEventForOperation`
+ *   - `signing.ts` — request signing and verification
+ *   - `factory.ts` — the `abloSource()` / `dataSource()` endpoint factory
+ *
+ * Import from here; the sibling modules import one another directly.
  */
-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
-// Source `commit`/`load`/`list` from localhost or a locked-down VPC with no
-// public inbound URL — see `connector-protocol.ts`.
+// The reverse-channel connector — an outbound transport for the load, list, and
+// commit leg, and the dial-out counterpart to `createPushQueue`. It lets you serve
+// a Data Source from localhost or a private network that has no public inbound
+// URL. See `connectorProtocol.ts` for the frames it exchanges.
 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';
+export { SOURCE_CONNECTOR_PROTOCOL_VERSION, SOURCE_CONNECTOR_WS_PATH, WS_SOURCE_SUBPROTOCOL, sourceConnectorSubprotocols, encodeFrame, decodeFrame, ConnectorProtocolError, connectorFrameSchema, } from './connectorProtocol.js';
+// The Data Source adapter interface and its Zod contract, with per-ORM implementations.
+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/migrations.d.ts

@@ -1,14 +1,14 @@
 /**
- * The table-creation SQL every ORM adapter ships for its OWN infrastructure tables —
- * `ablo_idempotency` (dedupe by clientTxId) and `ablo_outbox` (transactional
- * outbox the `events()` feed reads). Defined ONCE here so the Prisma adapter, the
- * Drizzle adapter, and `ablo migrate` can never disagree on the shape (they used
- * to inline their own copies, which had already drifted in whitespace).
+ * The table-creation SQL every ORM adapter ships for its own infrastructure
+ * tables: `ablo_idempotency`, which dedupes commits by `clientTxId`, and
+ * `ablo_outbox`, the transactional outbox the `events()` feed reads. Defining it in
+ * one place keeps the Prisma adapter, the Drizzle adapter, and `ablo migrate` in
+ * agreement on the exact shape.
  *
- * These are NOT model tables and are NOT emitted by the hosted provisioner
- * (`generateProvisionPlan`) — the hosted path uses `sync_deltas` directly. They
- * exist only on a customer's own database in Data Source mode.
+ * These are infrastructure tables, not model tables, and they exist only on your
+ * own database when you run a Data Source. Ablo's hosted storage does not use them;
+ * it records changes in its own `sync_deltas` log instead.
  */
 import type { Migration } from './contract.js';
-/** Canonical adapter-owned table-creation SQL. Idempotent (`IF NOT EXISTS`). */
+/** Returns the adapter's table-creation migrations. The SQL is idempotent, guarded by `IF NOT EXISTS`. */
 export declare function adapterTableMigrations(): readonly Migration[];

package/dist/source/migrations.js

@@ -1,15 +1,15 @@
 /**
- * The table-creation SQL every ORM adapter ships for its OWN infrastructure tables —
- * `ablo_idempotency` (dedupe by clientTxId) and `ablo_outbox` (transactional
- * outbox the `events()` feed reads). Defined ONCE here so the Prisma adapter, the
- * Drizzle adapter, and `ablo migrate` can never disagree on the shape (they used
- * to inline their own copies, which had already drifted in whitespace).
+ * The table-creation SQL every ORM adapter ships for its own infrastructure
+ * tables: `ablo_idempotency`, which dedupes commits by `clientTxId`, and
+ * `ablo_outbox`, the transactional outbox the `events()` feed reads. Defining it in
+ * one place keeps the Prisma adapter, the Drizzle adapter, and `ablo migrate` in
+ * agreement on the exact shape.
  *
- * These are NOT model tables and are NOT emitted by the hosted provisioner
- * (`generateProvisionPlan`) — the hosted path uses `sync_deltas` directly. They
- * exist only on a customer's own database in Data Source mode.
+ * These are infrastructure tables, not model tables, and they exist only on your
+ * own database when you run a Data Source. Ablo's hosted storage does not use them;
+ * it records changes in its own `sync_deltas` log instead.
  */
-/** Canonical adapter-owned table-creation SQL. Idempotent (`IF NOT EXISTS`). */
+/** Returns the adapter's table-creation migrations. The SQL is idempotent, guarded by `IF NOT EXISTS`. */
 export function adapterTableMigrations() {
     return [
         {

package/dist/source/next.d.ts

@@ -1,8 +1,8 @@
 /**
- * Next.js App Router adapter for Data Source. The core `dataSource()` already
- * returns a Web-standard `(Request) => Promise<Response>`, which Next App Router
- * accepts directly — so this is pure ergonomics: wire an ORM `adapter` in via the
- * bridge and hand back a named `POST` so the customer's route file is the minimum:
+ * 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';
@@ -16,16 +16,15 @@
  *     adapter: prismaDataSource(prisma, schema),
  *   });
  *
- * Day-one scope: Next + the adapter form only. Hand-written handlers use the core
- * `dataSource()` directly; Hono/Express are the same one-liner and land on demand
- * — not pre-built.
+ * For hand-written handlers, or another framework, call the core `dataSource()`
+ * directly and export its result however that framework expects.
  */
 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
- * at the call site. Pass `{ schema, apiKey, adapter }`.
+ * 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>): {

package/dist/source/next.js

@@ -1,8 +1,8 @@
 /**
- * Next.js App Router adapter for Data Source. The core `dataSource()` already
- * returns a Web-standard `(Request) => Promise<Response>`, which Next App Router
- * accepts directly — so this is pure ergonomics: wire an ORM `adapter` in via the
- * bridge and hand back a named `POST` so the customer's route file is the minimum:
+ * 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';
@@ -16,11 +16,10 @@
  *     adapter: prismaDataSource(prisma, schema),
  *   });
  *
- * Day-one scope: Next + the adapter form only. Hand-written handlers use the core
- * `dataSource()` directly; Hono/Express are the same one-liner and land on demand
- * — not pre-built.
+ * For hand-written handlers, or another framework, call the core `dataSource()`
+ * directly and export its result however that framework expects.
  */
-import { dataSource } from './index.js';
+import { dataSource } from './factory.js';
 export function dataSourceNext(options) {
     return { POST: dataSource(options) };
 }