@abloatai/ablo 0.35.0 → 0.37.0

package/dist/source/contract.d.ts

@@ -1,195 +0,0 @@
-/**
- * Defines the data an ORM adapter exchanges with Ablo, expressed as Zod schemas
- * rather than plain interfaces so every value is validated where it crosses the
- * boundary. A malformed operation or outbox row is rejected at the edge instead of
- * failing deep inside a transaction, and each TypeScript type is inferred from the
- * one schema that validates it.
- *
- * These schemas describe the adapter's own contract: the change set it commits,
- * the outbox row it stores, and the table migrations it ships. The operation
- * vocabulary is not restated here — `operationSchema` is projected from the
- * core's `commitOperationSchema`, so an action or field added to the commit
- * contract reaches a data source by construction. The assertion at the end of
- * this file then pins the published `SourceOperation` interface to that
- * projection, which is what keeps the interface tied to the core rather than
- * merely tied to a second local copy of it.
- */
-import { z } from 'zod';
-/**
- * Served, not mirrored. The commit vocabulary is declared once in the core; a
- * data source speaks the same five actions, so it re-exports them rather than
- * listing them again under a second name.
- */
-export declare const operationTypeSchema: z.ZodEnum<{
-    CREATE: "CREATE";
-    UPDATE: "UPDATE";
-    DELETE: "DELETE";
-    ARCHIVE: "ARCHIVE";
-    UNARCHIVE: "UNARCHIVE";
-}>;
-export type OperationType = z.infer<typeof operationTypeSchema>;
-/**
- * A single operation within a change set, and the runtime validator for it.
- *
- * The field set is projected from `commitOperationSchema` — an operation
- * reaching a data source is a commit operation minus the two fields the core
- * settles internally (`bypass`, `fenceToken`). The two `min(1)` overrides are
- * deliberate and local: this is a customer-implemented boundary, so an empty
- * model name or row id is rejected here rather than forwarded. Stating them as
- * an extension keeps the tightening visible as a choice instead of hiding it
- * inside a second copy of the shape.
- */
-export declare const operationSchema: z.ZodObject<{
-    type: z.ZodEnum<{
-        CREATE: "CREATE";
-        UPDATE: "UPDATE";
-        DELETE: "DELETE";
-        ARCHIVE: "ARCHIVE";
-        UNARCHIVE: "UNARCHIVE";
-    }>;
-    readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-    onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
-        reject: "reject";
-        overwrite: "overwrite";
-        notify: "notify";
-    }>>>;
-    transactionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    model: z.ZodString;
-    id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    input: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
-}, z.core.$strip>;
-export type Operation = z.infer<typeof operationSchema>;
-/** The supported customer-transaction echo mechanism. */
-export declare const sourceCommitEchoSchema: z.ZodObject<{
-    kind: z.ZodLiteral<"postgres-wal">;
-    payload: z.ZodString;
-}, z.core.$strip>;
-export declare const sourceCommitEchoOperationSchema: z.ZodObject<{
-    model: z.ZodString;
-    id: z.ZodString;
-    action: z.ZodEnum<{
-        I: "I";
-        U: "U";
-        D: "D";
-    }>;
-    transactionId: z.ZodString;
-}, z.core.$strict>;
-export declare const sourceCommitEchoMarkerSchema: z.ZodObject<{
-    version: z.ZodLiteral<1>;
-    correlationId: z.ZodString;
-    operations: z.ZodReadonly<z.ZodArray<z.ZodObject<{
-        model: z.ZodString;
-        id: z.ZodString;
-        action: z.ZodEnum<{
-            I: "I";
-            U: "U";
-            D: "D";
-        }>;
-        transactionId: z.ZodString;
-    }, z.core.$strict>>>;
-}, z.core.$strict>;
-export type SourceCommitEchoMarkerWire = z.infer<typeof sourceCommitEchoMarkerSchema>;
-/**
- * The unit a mutation wrapper commits atomically. `correlationId` is derived by
- * Ablo from the authenticated plane, participant, and public idempotency key; it
- * is the customer-ledger identity. It is intentionally not a raw caller-authored
- * `clientTxId` or an operation transaction id.
- */
-export declare const changeSetSchema: z.ZodObject<{
-    operations: z.ZodArray<z.ZodObject<{
-        type: z.ZodEnum<{
-            CREATE: "CREATE";
-            UPDATE: "UPDATE";
-            DELETE: "DELETE";
-            ARCHIVE: "ARCHIVE";
-            UNARCHIVE: "UNARCHIVE";
-        }>;
-        readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-        onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
-            reject: "reject";
-            overwrite: "overwrite";
-            notify: "notify";
-        }>>>;
-        transactionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        model: z.ZodString;
-        id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        input: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
-    }, z.core.$strip>>;
-    correlationId: z.ZodString;
-    intentHash: z.ZodOptional<z.ZodString>;
-    echo: z.ZodOptional<z.ZodObject<{
-        kind: z.ZodLiteral<"postgres-wal">;
-        payload: z.ZodString;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-export type ChangeSet = z.infer<typeof changeSetSchema>;
-/**
- * A row in the adapter's `ablo_outbox` table. The adapter writes it in the same
- * transaction as the underlying row change — the transactional-outbox pattern — so
- * a change and its event commit together or not at all. The `events()` feed later
- * reads these rows back and hands them to Ablo, and `cursor` is the monotonic
- * ordering key Ablo round-trips to resume where it left off.
- */
-export declare const outboxEventSchema: z.ZodObject<{
-    id: z.ZodString;
-    model: z.ZodString;
-    entityId: z.ZodString;
-    type: z.ZodEnum<{
-        CREATE: "CREATE";
-        UPDATE: "UPDATE";
-        DELETE: "DELETE";
-        ARCHIVE: "ARCHIVE";
-        UNARCHIVE: "UNARCHIVE";
-    }>;
-    data: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
-    organizationId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    clientTxId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    correlationId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    transactionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    occurredAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-    cursor: z.ZodString;
-}, z.core.$strip>;
-export type OutboxEvent = z.infer<typeof outboxEventSchema>;
-/** A page of outbox events returned by `events()`. */
-export declare const eventsPageSchema: z.ZodObject<{
-    events: z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
-        model: z.ZodString;
-        entityId: z.ZodString;
-        type: z.ZodEnum<{
-            CREATE: "CREATE";
-            UPDATE: "UPDATE";
-            DELETE: "DELETE";
-            ARCHIVE: "ARCHIVE";
-            UNARCHIVE: "UNARCHIVE";
-        }>;
-        data: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
-        organizationId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        clientTxId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        correlationId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        transactionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        occurredAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-        cursor: z.ZodString;
-    }, z.core.$strip>>;
-    nextCursor: z.ZodNullable<z.ZodString>;
-}, z.core.$strip>;
-export type EventsPage = z.infer<typeof eventsPageSchema>;
-/**
- * A table-creation migration an adapter ships, so you never hand-write the
- * `ablo_idempotency` and `ablo_outbox` tables yourself. An adapter returns these
- * from its `migrations()` method.
- */
-export declare const migrationSchema: z.ZodObject<{
-    name: z.ZodString;
-    up: z.ZodString;
-}, z.core.$strip>;
-export type Migration = z.infer<typeof migrationSchema>;
-/** Describes what an adapter's backend supports, so callers check a capability rather than infer it from behavior. */
-export declare const adapterCapabilitiesSchema: z.ZodObject<{
-    transactions: z.ZodBoolean;
-    propose: z.ZodBoolean;
-    schemaIntrospection: z.ZodBoolean;
-    postgresWalEcho: z.ZodOptional<z.ZodBoolean>;
-    outboxEvents: z.ZodBoolean;
-}, z.core.$strip>;
-export type AdapterCapabilities = z.infer<typeof adapterCapabilitiesSchema>;

package/dist/source/contract.js

@@ -1,164 +0,0 @@
-/**
- * Defines the data an ORM adapter exchanges with Ablo, expressed as Zod schemas
- * rather than plain interfaces so every value is validated where it crosses the
- * boundary. A malformed operation or outbox row is rejected at the edge instead of
- * failing deep inside a transaction, and each TypeScript type is inferred from the
- * one schema that validates it.
- *
- * These schemas describe the adapter's own contract: the change set it commits,
- * the outbox row it stores, and the table migrations it ships. The operation
- * vocabulary is not restated here — `operationSchema` is projected from the
- * core's `commitOperationSchema`, so an action or field added to the commit
- * contract reaches a data source by construction. The assertion at the end of
- * this file then pins the published `SourceOperation` interface to that
- * projection, which is what keeps the interface tied to the core rather than
- * merely tied to a second local copy of it.
- */
-import { z } from 'zod';
-import { correlationIdSchema } from '../transaction/wire/commit.js';
-import { commitOperationSchema, commitOperationTypeSchema, } from '../transaction/coordination/schema.js';
-import { ABLO_SOURCE_CLIENT_TX_ID_MAX_LENGTH, ABLO_SOURCE_ECHO_MAX_OPERATIONS, ABLO_SOURCE_ECHO_MAX_PAYLOAD_BYTES, } from './types.js';
-const jsonObject = z.record(z.string(), z.unknown());
-/**
- * Served, not mirrored. The commit vocabulary is declared once in the core; a
- * data source speaks the same five actions, so it re-exports them rather than
- * listing them again under a second name.
- */
-export const operationTypeSchema = commitOperationTypeSchema;
-/**
- * A single operation within a change set, and the runtime validator for it.
- *
- * The field set is projected from `commitOperationSchema` — an operation
- * reaching a data source is a commit operation minus the two fields the core
- * settles internally (`bypass`, `fenceToken`). The two `min(1)` overrides are
- * deliberate and local: this is a customer-implemented boundary, so an empty
- * model name or row id is rejected here rather than forwarded. Stating them as
- * an extension keeps the tightening visible as a choice instead of hiding it
- * inside a second copy of the shape.
- */
-export const operationSchema = commitOperationSchema
-    .omit({ bypass: true, fenceToken: true })
-    .extend({
-    model: z.string().min(1),
-    id: z.string().min(1).nullish(),
-    input: jsonObject.nullish(),
-});
-/** The supported customer-transaction echo mechanism. */
-export const sourceCommitEchoSchema = z.object({
-    kind: z.literal('postgres-wal'),
-    payload: z
-        .string()
-        .min(1)
-        .refine((value) => new TextEncoder().encode(value).byteLength <= ABLO_SOURCE_ECHO_MAX_PAYLOAD_BYTES, `WAL echo payload exceeds ${ABLO_SOURCE_ECHO_MAX_PAYLOAD_BYTES} UTF-8 bytes`),
-});
-export const sourceCommitEchoOperationSchema = z.strictObject({
-    model: z.string().min(1),
-    id: z.string().min(1),
-    action: z.enum(['I', 'U', 'D']),
-    transactionId: z.string().min(1).max(ABLO_SOURCE_CLIENT_TX_ID_MAX_LENGTH),
-});
-export const sourceCommitEchoMarkerSchema = z
-    .strictObject({
-    version: z.literal(1),
-    correlationId: correlationIdSchema,
-    operations: z
-        .array(sourceCommitEchoOperationSchema)
-        .min(1)
-        .max(ABLO_SOURCE_ECHO_MAX_OPERATIONS)
-        .readonly(),
-})
-    .superRefine(({ operations }, ctx) => {
-    const seen = new Set();
-    for (const [index, operation] of operations.entries()) {
-        if (seen.has(operation.transactionId)) {
-            ctx.addIssue({
-                code: 'custom',
-                path: ['operations', index, 'transactionId'],
-                message: 'WAL echo operation transactionIds must be unique',
-            });
-        }
-        seen.add(operation.transactionId);
-    }
-});
-/**
- * The unit a mutation wrapper commits atomically. `correlationId` is derived by
- * Ablo from the authenticated plane, participant, and public idempotency key; it
- * is the customer-ledger identity. It is intentionally not a raw caller-authored
- * `clientTxId` or an operation transaction id.
- */
-export const changeSetSchema = z.object({
-    operations: z.array(operationSchema).min(1),
-    correlationId: correlationIdSchema,
-    intentHash: z.string().regex(/^[a-f0-9]{64}$/).optional(),
-    echo: sourceCommitEchoSchema.optional(),
-});
-/**
- * A row in the adapter's `ablo_outbox` table. The adapter writes it in the same
- * transaction as the underlying row change — the transactional-outbox pattern — so
- * a change and its event commit together or not at all. The `events()` feed later
- * reads these rows back and hands them to Ablo, and `cursor` is the monotonic
- * ordering key Ablo round-trips to resume where it left off.
- */
-export const outboxEventSchema = z.object({
-    /** Stable, globally-unique id — Ablo's replay-protection key. */
-    id: z.string().min(1),
-    model: z.string().min(1),
-    entityId: z.string().min(1),
-    type: operationTypeSchema,
-    data: jsonObject.nullish(),
-    organizationId: z.string().nullish(),
-    /** Legacy source transaction id. Never use this field to settle a queued commit. */
-    clientTxId: z.string().nullish(),
-    /** Scoped server-authored identity that correlates this event to a queued commit. */
-    correlationId: correlationIdSchema.nullish(),
-    /** Stable identity of this operation within the correlated source commit. */
-    transactionId: z
-        .string()
-        .min(1)
-        .max(ABLO_SOURCE_CLIENT_TX_ID_MAX_LENGTH)
-        .nullish(),
-    occurredAt: z.number().nullish(),
-    /** Monotonic ordering key (bigint as string). `events()` pages by `cursor > ?`. */
-    cursor: z.string().min(1),
-});
-/** A page of outbox events returned by `events()`. */
-export const eventsPageSchema = z.object({
-    events: z.array(outboxEventSchema),
-    nextCursor: z.string().nullable(),
-});
-/**
- * A table-creation migration an adapter ships, so you never hand-write the
- * `ablo_idempotency` and `ablo_outbox` tables yourself. An adapter returns these
- * from its `migrations()` method.
- */
-export const migrationSchema = z.object({
-    /** Stable name, used as the migration filename + applied-ledger key. */
-    name: z.string().min(1),
-    /** The forward SQL. */
-    up: z.string().min(1),
-});
-/** Describes what an adapter's backend supports, so callers check a capability rather than infer it from behavior. */
-export const adapterCapabilitiesSchema = z.object({
-    /** `commit` is atomic across all operations in the change set. */
-    transactions: z.boolean(),
-    /** A dry-run `propose` is available; when false, proposing a change happens before the adapter is called. */
-    propose: z.boolean(),
-    /** The backend can be introspected for its schema. */
-    schemaIntrospection: z.boolean(),
-    /** The adapter can atomically emit the requested Postgres WAL marker. */
-    postgresWalEcho: z.boolean().optional(),
-    /** The wrapper atomically writes and serves an endpoint transactional outbox. */
-    outboxEvents: z.boolean(),
-});
-const _operationContractInSync = [
-    true,
-    true,
-];
-void _operationContractInSync;
-const _echoContractInSync = [
-    true,
-    true,
-];
-void _echoContractInSync;
-const _echoMarkerContractInSync = [true, true];
-void _echoMarkerContractInSync;

package/dist/source/factory.d.ts

@@ -1,92 +0,0 @@
-/**
- * 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 type { Schema, SchemaRecord, InferCreate } from '../transaction/schema/schema.js';
-import type { DataSourceAdapter } from './adapter.js';
-import type { SourceApiKey, SourceAuthorizeContext, SourceCommitHandler, SourceEventsHandler, SourceModelHandlers, SourceRequest, SourceScope } from './types.js';
-type SourceModels<S extends SchemaRecord, TAuth> = Partial<{
-    readonly [K in keyof S & string]: SourceModelHandlers<InferCreate<Schema<S>, K> & {
-        readonly id: string;
-    } & Record<string, unknown>, InferCreate<Schema<S>, K>, TAuth>;
-}>;
-export type DataSourceOptions<S extends SchemaRecord, TAuth = unknown> = {
-    readonly schema: Schema<S>;
-    /**
-     * Your Ablo project credential. Ablo signs each Data Source call with the same
-     * project API key your server-side SDK already uses, so your environment holds a
-     * single Ablo credential and every request is signature-verified before any
-     * handler runs.
-     */
-    readonly apiKey: SourceApiKey;
-    /**
-     * How much clock skew to tolerate when verifying a request's signed timestamp.
-     * Defaults to five minutes.
-     */
-    readonly signatureToleranceMs?: number;
-    /**
-     * Attaches your own context to a verified request and returns it — for example a
-     * database handle, an account scope, or the current actor. Keep database
-     * credentials inside this function's environment and never send them to Ablo. The
-     * signature has already been checked against `apiKey` by the time this runs, so
-     * `authorize` only needs to supply business context, not re-verify the caller.
-     */
-    readonly authorize?: (context: SourceAuthorizeContext) => Promise<TAuth> | TAuth;
-    /**
-     * Resolves the set of operations a request's key may perform. When you provide
-     * it, the handler checks the operation the request is asking for (`load`, `list`,
-     * `commit`, or `events`) against the returned set and responds 403
-     * `source_forbidden` if it is not allowed, before any model handler runs. A
-     * typical implementation reads a key id from the request — a `webhook-id` prefix,
-     * a custom header, or the API key itself — and looks that key's scopes up in your
-     * store. Omit it to allow every operation; return an empty set to deny them all.
-     */
-    readonly resolveScopes?: (params: {
-        readonly auth: TAuth;
-        readonly request: Request;
-        readonly body: SourceRequest;
-    }) => Promise<ReadonlySet<SourceScope> | readonly SourceScope[]> | ReadonlySet<SourceScope> | readonly SourceScope[];
-    /**
-     * Handles a commit atomically across every model it touches. Prefer this in real
-     * applications: a single user action can change several models at once and should
-     * run inside one transaction you control.
-     */
-    readonly commit?: SourceCommitHandler<TAuth>;
-    /**
-     * Reports changes that happened outside the SDK — cron jobs, dashboard edits,
-     * batch imports — which Ablo polls for. Each event you return becomes a delta and
-     * fans out to connected clients. You can return your outbox rows directly: Ablo
-     * dedupes on stable `event.id`, appends the authoritative event, and uses a
-     * server-authored `correlationId` plus per-operation `transactionId` to settle
-     * the matching queued write. Store both fields for mediated endpoint commits.
-     */
-    readonly events?: SourceEventsHandler<TAuth>;
-    /**
-     * Groups per-model handlers under a `models` key. The spread form below is
-     * usually shorter — `dataSource({ schema, files: { load, list, commit } })` —
-     * but this explicit form is available when you prefer it.
-     */
-    readonly models?: SourceModels<S, TAuth>;
-    /**
-     * An ORM adapter, such as `prismaDataSource(prisma, schema)`. When set, it serves
-     * all four operations on its own — reads for `load` and `list`, an idempotent
-     * `commit` backed by the outbox, and `events` — so you write no handlers by hand.
-     * Because rows travel as JSON, the adapter is applied at a single generic
-     * dispatch point and needs no per-model types. Use either an adapter or
-     * hand-written handlers, not both.
-     */
-    readonly adapter?: DataSourceAdapter;
-} & SourceModels<S, TAuth>;
-/**
- * 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 declare function dataSource<const S extends SchemaRecord, TAuth = unknown>(options: DataSourceOptions<S, TAuth>): (request: Request) => Promise<Response>;
-export {};