@abloatai/transaction 0.37.0

package/dist/source/factory.js

@@ -0,0 +1,287 @@
+/**
+ * Builds the request handler returned by `dataSource()`. Given your options —
+ * the schema, the API key, and either
+ * per-model handlers or an ORM adapter — the handler verifies each signed request,
+ * enforces the per-key scopes, and routes the four wire operations (`load`,
+ * `list`, `commit`, and `events`) to whichever handlers you configured.
+ */
+import { changeSetSchema } from './contract.js';
+import { SourceSignatureError, verifyAbloSourceRequest, } from './signing.js';
+function json(data, status = 200) {
+    return new Response(JSON.stringify(data), {
+        status,
+        headers: { 'Content-Type': 'application/json' },
+    });
+}
+/**
+ * Serves one request from an ORM `adapter`, mapping each of the four operations to
+ * the adapter's `read`, `commit`, or `events` method and shaping the wire response.
+ * The adapter is the only dispatch point, so there is 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') {
+        const correlationId = body.correlationId ?? body.clientTxId;
+        if (!correlationId) {
+            return json({
+                error: 'source_commit_requires_correlation_id',
+                message: 'commit requires a scoped correlationId for idempotency',
+            }, 400);
+        }
+        const parsed = changeSetSchema.safeParse({
+            operations: body.operations,
+            correlationId,
+            intentHash: body.intentHash,
+            echo: body.echo,
+        });
+        if (!parsed.success) {
+            return json({ error: 'source_commit_invalid', message: parsed.error.message }, 400);
+        }
+        if (parsed.data.echo?.kind === 'postgres-wal' &&
+            adapter.capabilities.postgresWalEcho !== true) {
+            return json({
+                error: 'source_commit_echo_not_supported',
+                message: 'This adapter cannot emit the required Postgres WAL commit echo',
+            }, 409);
+        }
+        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.correlationId ? { correlationId: event.correlationId } : {}),
+                ...(event.transactionId ? { transactionId: event.transactionId } : {}),
+                ...(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 };
+}
+async function resolveApiKey(apiKey, context) {
+    if (!apiKey)
+        return null;
+    return typeof apiKey === 'function' ? apiKey(context) : apiKey;
+}
+/**
+ * Maps a wire request to the single scope it requires. The mapping is exhaustive,
+ * so a new request type must be given its own scope, keeping the scope vocabulary
+ * in step with the set of operations.
+ */
+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;
+}
+/**
+ * Creates a Data Source endpoint you host in front of your own database.
+ *
+ * Your application code still reads and writes through Ablo, as in
+ * `ablo.files.load`, `.list`, and `.update`. This helper is for keeping the
+ * canonical rows in your database: Ablo calls a narrow, signed endpoint you
+ * control rather than holding your database credentials.
+ */
+export function dataSource(options) {
+    return async function handleDataSource(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;
+        // Enforce the per-key scope. When `resolveScopes` is set, it returns the
+        // operations this key may invoke, and we check the request against that set
+        // 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 } : {}),
+        };
+        // When an ORM adapter is configured it serves every operation here, at the
+        // generic layer where rows are plain JSON, so there is no per-model handler
+        // lookup on this path.
+        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,
+                    correlationId: body.correlationId ?? body.clientTxId,
+                    clientTxId: body.clientTxId,
+                    intentHash: body.intentHash,
+                    echo: body.echo,
+                    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,
+                correlationId: body.correlationId ?? body.clientTxId,
+                clientTxId: body.clientTxId,
+                intentHash: body.intentHash,
+                echo: body.echo,
+                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);
+    };
+}
+//# sourceMappingURL=factory.js.map

package/dist/source/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/source/factory.ts"],"names":[],"mappings":"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"}

package/dist/source/idempotency.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Customer-side source idempotency helpers.
+ *
+ * Connected writes use a permanent, server-derived correlation key at the
+ * customer boundary. The matching intent hash must therefore also be
+ * permanent: replaying the key with a different request is a conflict, never a
+ * fresh execution. Ablo supplies the hash for signed source requests because
+ * it covers context/read guards that an adapter cannot reconstruct from the
+ * effective operation list alone. Direct adapter users get a canonical
+ * operations-only fallback.
+ */
+import { z } from 'zod';
+import type { ChangeSet, Operation } from './contract.js';
+/** Runtime shape recovered from the internal storage envelope. */
+export declare const sourceEchoTransactionIdSchema: z.ZodObject<{
+    correlationId: z.ZodString;
+    transactionId: z.ZodString;
+}, z.core.$strict>;
+export type SourceEchoTransactionId = z.infer<typeof sourceEchoTransactionIdSchema>;
+/**
+ * Store both source-batch identity and the originating optimistic-write id in
+ * the existing `sync_deltas.transaction_id` column. The database value is an
+ * internal envelope: the server unwraps it before broadcasting, so clients
+ * still receive the exact operation transaction id they authored.
+ *
+ * Keeping the opaque, authenticated-scope correlation in the stored value is
+ * load-bearing for crash recovery. A raw caller may choose or reuse an
+ * operation transaction id; that value alone must never be able to satisfy a
+ * different participant's queued receipt.
+ */
+export declare function encodeSourceEchoTransactionId(correlationId: string, transactionId: string): string;
+/** Decode a source-WAL transaction envelope, or return null for normal rows. */
+export declare function decodeSourceEchoTransactionId(value: string | null): SourceEchoTransactionId | null;
+/** Canonical operations-only fallback for direct adapter use. */
+export declare function sourceOperationsIntentHash(operations: readonly Operation[]): string;
+/** Resolve the hash every newly-written customer ledger row must persist. */
+export declare function sourceChangeIntentHash(change: ChangeSet): string;
+/** Fail closed for changed intent and legacy rows that lack hash evidence. */
+export declare function assertSourceIdempotencyIntent(cachedHash: unknown, requestHash: string): void;
+/**
+ * How long a ledger row stays replayable, as a Postgres interval. New rows are
+ * written with `expires_at = now() + this`, so the customer can prune anything
+ * past it — the writer can't (it holds no DELETE, by design), so pruning is a
+ * job for their own admin/cron: `DELETE FROM ablo_idempotency WHERE expires_at <
+ * now()`.
+ *
+ * This is an ops/UX window, not a safety one: {@link assertSourceIdempotencyRetention}
+ * already refuses to replay an expired key (fail-closed), so an expired row can
+ * never be safely re-applied whether or not it has been pruned. The window only
+ * governs how late a retry can still collect its cached response before it's
+ * told to start over. 30 days comfortably covers an offline client's queued
+ * commits while keeping the table bounded.
+ */
+export declare const SOURCE_IDEMPOTENCY_RETENTION = "30 days";
+/**
+ * Enforce the retention contract on replay. A row past its `expires_at` is
+ * refused (fail-closed) rather than re-applied, so pruning expired rows is
+ * always safe. Rows written before the column existed (`infinity`/null) are
+ * accepted — they predate bounded retention and never expire.
+ */
+export declare function assertSourceIdempotencyRetention(expiresAt: unknown, now?: number): void;
+//# sourceMappingURL=idempotency.d.ts.map

package/dist/source/idempotency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../../src/source/idempotency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAS1D,kEAAkE;AAClE,eAAO,MAAM,6BAA6B;;;kBAGxC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAOpF;;;;;;;;;;GAUG;AACH,wBAAgB,6BAA6B,CAC3C,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,MAAM,GACpB,MAAM,CAMR;AAED,gFAAgF;AAChF,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,MAAM,GAAG,IAAI,GACnB,uBAAuB,GAAG,IAAI,CAehC;AAoBD,iEAAiE;AACjE,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,SAAS,SAAS,EAAE,GAC/B,MAAM,CAIR;AAED,6EAA6E;AAC7E,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAQhE;AAED,8EAA8E;AAC9E,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,OAAO,EACnB,WAAW,EAAE,MAAM,GAClB,IAAI,CASN;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,4BAA4B,YAAY,CAAC;AAEtD;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAC9C,SAAS,EAAE,OAAO,EAClB,GAAG,SAAa,GACf,IAAI,CA4BN"}

package/dist/source/idempotency.js

@@ -0,0 +1,145 @@
+/**
+ * Customer-side source idempotency helpers.
+ *
+ * Connected writes use a permanent, server-derived correlation key at the
+ * customer boundary. The matching intent hash must therefore also be
+ * permanent: replaying the key with a different request is a conflict, never a
+ * fresh execution. Ablo supplies the hash for signed source requests because
+ * it covers context/read guards that an adapter cannot reconstruct from the
+ * effective operation list alone. Direct adapter users get a canonical
+ * operations-only fallback.
+ */
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { AbloValidationError } from '../errors.js';
+import { COMMIT_CORRELATION_ID_MAX_LENGTH, correlationIdSchema, } from '../wire/commit.js';
+const SOURCE_ECHO_TRANSACTION_ID_PREFIX = 'ablo_echo_tx_v1:';
+const sourceOperationTransactionIdSchema = z
+    .string()
+    .min(1)
+    .max(COMMIT_CORRELATION_ID_MAX_LENGTH);
+/** Runtime shape recovered from the internal storage envelope. */
+export const sourceEchoTransactionIdSchema = z.strictObject({
+    correlationId: correlationIdSchema,
+    transactionId: sourceOperationTransactionIdSchema,
+});
+const sourceEchoTransactionIdTupleSchema = z.tuple([
+    correlationIdSchema,
+    sourceOperationTransactionIdSchema,
+]);
+/**
+ * Store both source-batch identity and the originating optimistic-write id in
+ * the existing `sync_deltas.transaction_id` column. The database value is an
+ * internal envelope: the server unwraps it before broadcasting, so clients
+ * still receive the exact operation transaction id they authored.
+ *
+ * Keeping the opaque, authenticated-scope correlation in the stored value is
+ * load-bearing for crash recovery. A raw caller may choose or reuse an
+ * operation transaction id; that value alone must never be able to satisfy a
+ * different participant's queued receipt.
+ */
+export function encodeSourceEchoTransactionId(correlationId, transactionId) {
+    const tuple = sourceEchoTransactionIdTupleSchema.parse([
+        correlationId,
+        transactionId,
+    ]);
+    return `${SOURCE_ECHO_TRANSACTION_ID_PREFIX}${JSON.stringify(tuple)}`;
+}
+/** Decode a source-WAL transaction envelope, or return null for normal rows. */
+export function decodeSourceEchoTransactionId(value) {
+    if (!value?.startsWith(SOURCE_ECHO_TRANSACTION_ID_PREFIX))
+        return null;
+    try {
+        const parsed = JSON.parse(value.slice(SOURCE_ECHO_TRANSACTION_ID_PREFIX.length));
+        const tuple = sourceEchoTransactionIdTupleSchema.safeParse(parsed);
+        if (!tuple.success)
+            return null;
+        return sourceEchoTransactionIdSchema.parse({
+            correlationId: tuple.data[0],
+            transactionId: tuple.data[1],
+        });
+    }
+    catch {
+        return null;
+    }
+}
+function canonicalJson(value) {
+    if (value === null || typeof value !== 'object') {
+        const encoded = JSON.stringify(value);
+        return encoded ?? 'null';
+    }
+    if (Array.isArray(value)) {
+        return `[${value
+            .map((entry) => canonicalJson(entry === undefined ? null : entry))
+            .join(',')}]`;
+    }
+    const record = value;
+    return `{${Object.keys(record)
+        .filter((key) => record[key] !== undefined)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+        .join(',')}}`;
+}
+/** Canonical operations-only fallback for direct adapter use. */
+export function sourceOperationsIntentHash(operations) {
+    return createHash('sha256')
+        .update(canonicalJson(operations))
+        .digest('hex');
+}
+/** Resolve the hash every newly-written customer ledger row must persist. */
+export function sourceChangeIntentHash(change) {
+    if (change.echo && !change.intentHash) {
+        throw new AbloValidationError('A WAL-correlated source commit requires Ablo intentHash evidence', { code: 'idempotency_conflict' });
+    }
+    return change.intentHash ?? sourceOperationsIntentHash(change.operations);
+}
+/** Fail closed for changed intent and legacy rows that lack hash evidence. */
+export function assertSourceIdempotencyIntent(cachedHash, requestHash) {
+    if (cachedHash !== requestHash) {
+        throw new AbloValidationError(cachedHash == null
+            ? 'The source idempotency row predates intent hashing and cannot be replayed safely'
+            : 'The source idempotency key was already used with a different request intent', { code: 'idempotency_conflict' });
+    }
+}
+/**
+ * How long a ledger row stays replayable, as a Postgres interval. New rows are
+ * written with `expires_at = now() + this`, so the customer can prune anything
+ * past it — the writer can't (it holds no DELETE, by design), so pruning is a
+ * job for their own admin/cron: `DELETE FROM ablo_idempotency WHERE expires_at <
+ * now()`.
+ *
+ * This is an ops/UX window, not a safety one: {@link assertSourceIdempotencyRetention}
+ * already refuses to replay an expired key (fail-closed), so an expired row can
+ * never be safely re-applied whether or not it has been pruned. The window only
+ * governs how late a retry can still collect its cached response before it's
+ * told to start over. 30 days comfortably covers an offline client's queued
+ * commits while keeping the table bounded.
+ */
+export const SOURCE_IDEMPOTENCY_RETENTION = '30 days';
+/**
+ * Enforce the retention contract on replay. A row past its `expires_at` is
+ * refused (fail-closed) rather than re-applied, so pruning expired rows is
+ * always safe. Rows written before the column existed (`infinity`/null) are
+ * accepted — they predate bounded retention and never expire.
+ */
+export function assertSourceIdempotencyRetention(expiresAt, now = Date.now()) {
+    if (expiresAt == null ||
+        expiresAt === 'infinity' ||
+        expiresAt === Infinity) {
+        return;
+    }
+    const timestamp = expiresAt instanceof Date
+        ? expiresAt.getTime()
+        : typeof expiresAt === 'number'
+            ? expiresAt
+            : typeof expiresAt === 'string'
+                ? Date.parse(expiresAt)
+                : Number.NaN;
+    if (!Number.isFinite(timestamp)) {
+        throw new AbloValidationError('The source idempotency retention evidence is invalid', { code: 'idempotency_conflict' });
+    }
+    if (timestamp <= now) {
+        throw new AbloValidationError('The source idempotency key has expired and cannot be executed again safely', { code: 'idempotency_key_expired' });
+    }
+}
+//# sourceMappingURL=idempotency.js.map

package/dist/source/idempotency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.js","sourceRoot":"","sources":["../../src/source/idempotency.ts"],"names":[],"mappings":"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"}

package/dist/source/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The entry point for the Data Source API, re-exporting the pieces you need from
+ * their individual modules:
+ *
+ *   - `types.ts`   — the shared wire and handler types, plus `sourceEventForOperation`
+ *   - `signing.ts` — request signing and verification
+ *   - `factory.ts` — the `dataSource()` endpoint factory
+ *
+ * Import from here; the sibling modules import one another directly.
+ */
+export { sourceEventForOperation, ABLO_POSTGRES_COMMIT_ECHO_PREFIX, ABLO_SOURCE_CLIENT_TX_ID_MAX_LENGTH, ABLO_SOURCE_ECHO_MAX_OPERATIONS, ABLO_SOURCE_ECHO_MAX_PAYLOAD_BYTES, type SourcePrimitive, type SourceWhere, type SourceListQuery, type SourceListPage, type SourceListResult, type SourceRequestContext, type SourceOperation, type SourceDelta, type SourceEvent, type SourceEventForOperationOptions, type SourceCommitResult, type SourceCommitEcho, type SourceCommitEchoOperation, type SourceCommitEchoMarker, type SourceCommitParams, type SourceScope, type SourceEventsResult, type SourceEventsHandler, type SourceAuthorizeContext, type SourceHandlerContext, type SourceModelHandlers, type SourceCommitHandler, type SourceApiKey, type SourceLoadRequest, type SourceListRequest, type SourceCommitRequest, type SourceEventsRequest, type SourceRequest, type SourceResponse, } from './types.js';
+export { ABLO_SOURCE_HEADERS, SourceSignatureError, signAbloSourceRequest, verifyAbloSourceRequest, type SourceSignatureOptions, type SourceSignatureVerificationOptions, type SourceSignatureVerificationResult, } from './signing.js';
+export { dataSource, type DataSourceOptions, } from './factory.js';
+export { createPushQueue, InMemoryPushQueueStorage, STANDARD_WEBHOOKS_RETRY_SCHEDULE, type PushQueue, type PushQueueItem, type PushQueueOptions, type PushQueueStorage, } from './pushQueue.js';
+export { createSourceConnector, DEFAULT_RECONNECT_SCHEDULE, type SourceConnector, type SourceConnectorOptions, type ConnectorWebSocket, type ConnectorWebSocketFactory, type ConnectorStatus, } from './connector.js';
+export { SOURCE_CONNECTOR_PROTOCOL_VERSION, SOURCE_CONNECTOR_WS_PATH, WS_SOURCE_SUBPROTOCOL, sourceConnectorSubprotocols, encodeFrame, decodeFrame, ConnectorProtocolError, connectorFrameSchema, type ConnectorFrame, type RegisterFrame, type ReadyFrame, type RequestFrame, type ResponseFrame, type ErrorFrame, } from './connectorProtocol.js';
+export { type DataSourceAdapter, type MutationAdapter, type AdapterReadRequest, type AdapterCommitResult, type Row as AdapterRow, } from './adapter.js';
+export { operationSchema, operationTypeSchema, sourceCommitEchoSchema, sourceCommitEchoOperationSchema, sourceCommitEchoMarkerSchema, changeSetSchema, outboxEventSchema, eventsPageSchema, migrationSchema, adapterCapabilitiesSchema, type Operation, type ChangeSet, type OutboxEvent, type EventsPage, type Migration, type AdapterCapabilities, type SourceCommitEchoMarkerWire, } from './contract.js';
+export { prismaDataSource, type PrismaLike, type PrismaDataSourceOptions } from './adapters/prisma.js';
+export { adapterTableMigrations, endpointOutboxMigrations, idempotencyLedgerMigrations, } from './migrations.js';
+export { createKyselyMutationAdapter, createKyselyMutationCore, kyselyDataSource, kyselyDirectMutation, kyselyOperationRowId, type KyselyCompiledQuery, type KyselyDeleteBuilder, type KyselyInsertBuilder, type KyselyInsertValuesBuilder, type KyselyLike, type KyselyMutationCore, type KyselyReturningExecutable, type KyselySelectBuilder, type KyselyTransactionBuilder, type KyselyUpdateBuilder, type KyselyUpdateSetBuilder, } from './adapters/kysely.js';
+export { sourceOperationsIntentHash, sourceChangeIntentHash, assertSourceIdempotencyIntent, assertSourceIdempotencyRetention, sourceEchoTransactionIdSchema, encodeSourceEchoTransactionId, decodeSourceEchoTransactionId, type SourceEchoTransactionId, } from './idempotency.js';
+export { ABLO_FOOTPRINT, ABLO_PUBLICATION, ABLO_REPLICATION_SLOT, ABLO_REPLICATION_ROLE, ABLO_WRITE_ROLE, ABLO_IDEMPOTENCY_TABLE, ABLO_OUTBOX_TABLE, REPLICATION_SLOT_NAME, isValidReplicationSlotName, footprintNamesFor, type FootprintArtifact, type FootprintKind, type FootprintNames, type FootprintPlane, } from '../footprint.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/source/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/source/index.ts"],"names":[],"mappings":"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"}

package/dist/source/index.js

@@ -0,0 +1,29 @@
+/**
+ * The entry point for the Data Source API, re-exporting the pieces you need from
+ * their individual modules:
+ *
+ *   - `types.ts`   — the shared wire and handler types, plus `sourceEventForOperation`
+ *   - `signing.ts` — request signing and verification
+ *   - `factory.ts` — the `dataSource()` endpoint factory
+ *
+ * Import from here; the sibling modules import one another directly.
+ */
+export { sourceEventForOperation, ABLO_POSTGRES_COMMIT_ECHO_PREFIX, ABLO_SOURCE_CLIENT_TX_ID_MAX_LENGTH, ABLO_SOURCE_ECHO_MAX_OPERATIONS, ABLO_SOURCE_ECHO_MAX_PAYLOAD_BYTES, } from './types.js';
+export { ABLO_SOURCE_HEADERS, SourceSignatureError, signAbloSourceRequest, verifyAbloSourceRequest, } from './signing.js';
+export { dataSource, } from './factory.js';
+export { createPushQueue, InMemoryPushQueueStorage, STANDARD_WEBHOOKS_RETRY_SCHEDULE, } from './pushQueue.js';
+// 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 './connectorProtocol.js';
+export { operationSchema, operationTypeSchema, sourceCommitEchoSchema, sourceCommitEchoOperationSchema, sourceCommitEchoMarkerSchema, changeSetSchema, outboxEventSchema, eventsPageSchema, migrationSchema, adapterCapabilitiesSchema, } from './contract.js';
+export { prismaDataSource } from './adapters/prisma.js';
+export { adapterTableMigrations, endpointOutboxMigrations, idempotencyLedgerMigrations, } from './migrations.js';
+export { createKyselyMutationAdapter, createKyselyMutationCore, kyselyDataSource, kyselyDirectMutation, kyselyOperationRowId, } from './adapters/kysely.js';
+export { sourceOperationsIntentHash, sourceChangeIntentHash, assertSourceIdempotencyIntent, assertSourceIdempotencyRetention, sourceEchoTransactionIdSchema, encodeSourceEchoTransactionId, decodeSourceEchoTransactionId, } from './idempotency.js';
+// What Ablo leaves inside a customer's database, declared once — read by the
+// setup SQL, the replication runtime, and the audit that reports it back.
+export { ABLO_FOOTPRINT, ABLO_PUBLICATION, ABLO_REPLICATION_SLOT, ABLO_REPLICATION_ROLE, ABLO_WRITE_ROLE, ABLO_IDEMPOTENCY_TABLE, ABLO_OUTBOX_TABLE, REPLICATION_SLOT_NAME, isValidReplicationSlotName, footprintNamesFor, } from '../footprint.js';
+//# sourceMappingURL=index.js.map

package/dist/source/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/source/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,uBAAuB,EACvB,gCAAgC,EAChC,mCAAmC,EACnC,+BAA+B,EAC/B,kCAAkC,GA8BnC,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,GAIxB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,UAAU,GAEX,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,eAAe,EACf,wBAAwB,EACxB,gCAAgC,GAKjC,MAAM,gBAAgB,CAAC;AAExB,gFAAgF;AAChF,mFAAmF;AACnF,+EAA+E;AAC/E,+DAA+D;AAC/D,OAAO,EACL,qBAAqB,EACrB,0BAA0B,GAM3B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,iCAAiC,EACjC,wBAAwB,EACxB,qBAAqB,EACrB,2BAA2B,EAC3B,WAAW,EACX,WAAW,EACX,sBAAsB,EACtB,oBAAoB,GAOrB,MAAM,wBAAwB,CAAC;AAUhC,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,sBAAsB,EACtB,+BAA+B,EAC/B,4BAA4B,EAC5B,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,yBAAyB,GAQ1B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,gBAAgB,EAAiD,MAAM,sBAAsB,CAAC;AACvG,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,2BAA2B,GAC5B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,2BAA2B,EAC3B,wBAAwB,EACxB,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,GAYrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,0BAA0B,EAC1B,sBAAsB,EACtB,6BAA6B,EAC7B,gCAAgC,EAChC,6BAA6B,EAC7B,6BAA6B,EAC7B,6BAA6B,GAE9B,MAAM,kBAAkB,CAAC;AAC1B,6EAA6E;AAC7E,0EAA0E;AAC1E,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,eAAe,EACf,sBAAsB,EACtB,iBAAiB,EACjB,qBAAqB,EACrB,0BAA0B,EAC1B,iBAAiB,GAKlB,MAAM,iBAAiB,CAAC"}

package/dist/source/kysely.d.ts

@@ -0,0 +1,3 @@
+/** Public compatibility facade for the Kysely source and direct-write adapters. */
+export * from './adapters/kysely.js';
+//# sourceMappingURL=kysely.d.ts.map

package/dist/source/kysely.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kysely.d.ts","sourceRoot":"","sources":["../../src/source/kysely.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,cAAc,sBAAsB,CAAC"}

package/dist/source/kysely.js

@@ -0,0 +1,3 @@
+/** Public compatibility facade for the Kysely source and direct-write adapters. */
+export * from './adapters/kysely.js';
+//# sourceMappingURL=kysely.js.map

package/dist/source/kysely.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kysely.js","sourceRoot":"","sources":["../../src/source/kysely.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,cAAc,sBAAsB,CAAC"}

package/dist/source/migrations.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The canonical table-creation SQL every ORM adapter ships for its own infrastructure
+ * tables: `ablo_idempotency`, whose legacy-named `client_tx_id` column stores the
+ * scoped server correlation, and (for endpoint wrappers only) `ablo_outbox`, the
+ * transactional outbox the `events()` feed reads. Direct wrappers install only
+ * the ledger migration because WAL is their authoritative feed.
+ *
+ * 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';
+/** The idempotency ledger shared by direct and endpoint mutation wrappers. New
+ *  rows carry a bounded `expires_at` (set by the adapter at write time) so the
+ *  customer can prune them; the `infinity` column default is only a fallback for
+ *  a row inserted without one. */
+export declare function idempotencyLedgerMigrations(): readonly Migration[];
+/** Endpoint-only transactional outbox and its correlation columns. */
+export declare function endpointOutboxMigrations(): readonly Migration[];
+/** Full endpoint adapter migrations (ledger + outbox). */
+export declare function adapterTableMigrations(): readonly Migration[];
+//# sourceMappingURL=migrations.d.ts.map

package/dist/source/migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../src/source/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAyB/C;;;kCAGkC;AAClC,wBAAgB,2BAA2B,IAAI,SAAS,SAAS,EAAE,CAgClE;AAED,sEAAsE;AACtE,wBAAgB,wBAAwB,IAAI,SAAS,SAAS,EAAE,CA2B/D;AAED,0DAA0D;AAC1D,wBAAgB,sBAAsB,IAAI,SAAS,SAAS,EAAE,CAE7D"}