@abloatai/ablo 0.25.0 → 0.27.0

package/dist/source/contract.d.ts

@@ -1,19 +1,16 @@
 /**
- * Data Source adapter contract — Zod-first.
+ * 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.
  *
- * The wire shapes an ORM adapter (Prisma/Drizzle/Kysely) consumes and produces
- * are defined here as Zod schemas, not hand-typed interfaces, so they are
- * VALIDATED at the boundary (a malformed op / outbox row is rejected at the
- * edge, not deep inside a transaction) and every inferred type flows from one
- * source. This mirrors the server's `tenant-connection.schema.ts` convention:
- * schema-validate what crosses a trust boundary, infer the TS types from it.
- *
- * Scope note: the existing `SourceOperation` / `SourceEvent` interfaces in
- * `index.ts` are the established cross-package wire types — this module does NOT
- * redefine them. It owns the ADAPTER-level contract (the change envelope the
- * adapter commits, the outbox row it persists, the migration it ships) and keeps
- * `operationSchema` structurally compatible with `SourceOperation` (asserted at
- * the bottom of the file) so the two never drift.
+ * These schemas describe the adapter's own contract: the change set it commits,
+ * the outbox row it stores, and the table migrations it ships. They do not
+ * redefine the shared `SourceOperation` and `SourceEvent` wire types, which live
+ * in `types.ts`; instead `operationSchema` is kept structurally compatible with
+ * `SourceOperation`, a compatibility the assertion at the end of this file proves
+ * at compile time so the schema and the interface cannot drift apart.
  */
 import { z } from 'zod';
 /** Mirrors `SourceOperation['type']`. */
@@ -26,8 +23,9 @@ export declare const operationTypeSchema: z.ZodEnum<{
 }>;
 export type OperationType = z.infer<typeof operationTypeSchema>;
 /**
- * One operation in a change set. Structurally compatible with `SourceOperation`
- * (see the assertion below) — this is its runtime validator.
+ * A single operation within a change set, and the runtime validator for it. It is
+ * structurally compatible with the shared `SourceOperation` type, as the assertion
+ * at the end of this file confirms.
  */
 export declare const operationSchema: z.ZodObject<{
     type: z.ZodEnum<{
@@ -50,9 +48,9 @@ export declare const operationSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type Operation = z.infer<typeof operationSchema>;
 /**
- * The atomic unit an adapter commits: one or more operations under a single
- * `clientTxId`. The `clientTxId` is the idempotency key — committing the same
- * change set twice must produce the same result exactly once.
+ * The unit an adapter commits atomically: one or more operations grouped under a
+ * single `clientTxId`. That `clientTxId` is the idempotency key, so committing the
+ * same change set twice applies it once and returns the same result.
  */
 export declare const changeSetSchema: z.ZodObject<{
     operations: z.ZodArray<z.ZodObject<{
@@ -78,10 +76,11 @@ export declare const changeSetSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type ChangeSet = z.infer<typeof changeSetSchema>;
 /**
- * A row in the adapter-owned `ablo_outbox` table. Written in the SAME
- * transaction as the app-row mutation (transactional outbox), then read back by
- * `events()` and handed to Ablo. `cursor` is the monotonic ordering key Ablo
- * round-trips to resume.
+ * 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;
@@ -124,16 +123,16 @@ export declare const eventsPageSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type EventsPage = z.infer<typeof eventsPageSchema>;
 /**
- * A table-creation migration an adapter ships so a customer never hand-writes the
- * `ablo_idempotency` / `ablo_outbox` tables — the adapter returns them from
- * `migrations()`.
+ * 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>;
-/** What an adapter's backend can do — a capability profile (no behavior inference). */
+/** 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;

package/dist/source/contract.js

@@ -1,19 +1,16 @@
 /**
- * Data Source adapter contract — Zod-first.
+ * 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.
  *
- * The wire shapes an ORM adapter (Prisma/Drizzle/Kysely) consumes and produces
- * are defined here as Zod schemas, not hand-typed interfaces, so they are
- * VALIDATED at the boundary (a malformed op / outbox row is rejected at the
- * edge, not deep inside a transaction) and every inferred type flows from one
- * source. This mirrors the server's `tenant-connection.schema.ts` convention:
- * schema-validate what crosses a trust boundary, infer the TS types from it.
- *
- * Scope note: the existing `SourceOperation` / `SourceEvent` interfaces in
- * `index.ts` are the established cross-package wire types — this module does NOT
- * redefine them. It owns the ADAPTER-level contract (the change envelope the
- * adapter commits, the outbox row it persists, the migration it ships) and keeps
- * `operationSchema` structurally compatible with `SourceOperation` (asserted at
- * the bottom of the file) so the two never drift.
+ * These schemas describe the adapter's own contract: the change set it commits,
+ * the outbox row it stores, and the table migrations it ships. They do not
+ * redefine the shared `SourceOperation` and `SourceEvent` wire types, which live
+ * in `types.ts`; instead `operationSchema` is kept structurally compatible with
+ * `SourceOperation`, a compatibility the assertion at the end of this file proves
+ * at compile time so the schema and the interface cannot drift apart.
  */
 import { z } from 'zod';
 const jsonObject = z.record(z.string(), z.unknown());
@@ -26,8 +23,9 @@ export const operationTypeSchema = z.enum([
     'UNARCHIVE',
 ]);
 /**
- * One operation in a change set. Structurally compatible with `SourceOperation`
- * (see the assertion below) — this is its runtime validator.
+ * A single operation within a change set, and the runtime validator for it. It is
+ * structurally compatible with the shared `SourceOperation` type, as the assertion
+ * at the end of this file confirms.
  */
 export const operationSchema = z.object({
     type: operationTypeSchema,
@@ -39,19 +37,20 @@ export const operationSchema = z.object({
     onStale: z.enum(['reject', 'overwrite', 'notify']).nullish(),
 });
 /**
- * The atomic unit an adapter commits: one or more operations under a single
- * `clientTxId`. The `clientTxId` is the idempotency key — committing the same
- * change set twice must produce the same result exactly once.
+ * The unit an adapter commits atomically: one or more operations grouped under a
+ * single `clientTxId`. That `clientTxId` is the idempotency key, so committing the
+ * same change set twice applies it once and returns the same result.
  */
 export const changeSetSchema = z.object({
     operations: z.array(operationSchema).min(1),
     clientTxId: z.string().min(1),
 });
 /**
- * A row in the adapter-owned `ablo_outbox` table. Written in the SAME
- * transaction as the app-row mutation (transactional outbox), then read back by
- * `events()` and handed to Ablo. `cursor` is the monotonic ordering key Ablo
- * round-trips to resume.
+ * 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. */
@@ -61,7 +60,7 @@ export const outboxEventSchema = z.object({
     type: operationTypeSchema,
     data: jsonObject.nullish(),
     organizationId: z.string().nullish(),
-    /** Round-tripped so Ablo can filter SDK-origin echoes after a direct append. */
+    /** The originating transaction id, carried so Ablo can drop echoes of changes the SDK itself wrote. */
     clientTxId: z.string().nullish(),
     occurredAt: z.number().nullish(),
     /** Monotonic ordering key (bigint as string). `events()` pages by `cursor > ?`. */
@@ -73,9 +72,9 @@ export const eventsPageSchema = z.object({
     nextCursor: z.string().nullable(),
 });
 /**
- * A table-creation migration an adapter ships so a customer never hand-writes the
- * `ablo_idempotency` / `ablo_outbox` tables — the adapter returns them from
- * `migrations()`.
+ * 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. */
@@ -83,11 +82,11 @@ export const migrationSchema = z.object({
     /** The forward SQL. */
     up: z.string().min(1),
 });
-/** What an adapter's backend can do — a capability profile (no behavior inference). */
+/** 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 supported (else proposal lives above the adapter). */
+    /** 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(),

package/dist/source/factory.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Builds the Data Source request handler returned by `abloSource()` and its alias
+ * `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 '../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 AbloSourceOptions<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 the stable `event.id` and drops echoes of the SDK's own writes when a
+     * row carries the originating `clientTxId`, so store both fields in your outbox
+     * table.
+     */
+    readonly events?: SourceEventsHandler<TAuth>;
+    /**
+     * Groups per-model handlers under a `models` key. The spread form below is
+     * usually shorter — `abloSource({ 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 abloSource<const S extends SchemaRecord, TAuth = unknown>(options: AbloSourceOptions<S, TAuth>): (request: Request) => Promise<Response>;
+export type DataSourceOptions<S extends SchemaRecord, TAuth = unknown> = AbloSourceOptions<S, TAuth>;
+export declare function dataSource<const S extends SchemaRecord, TAuth = unknown>(options: DataSourceOptions<S, TAuth>): (request: Request) => Promise<Response>;
+export {};

package/dist/source/factory.js

@@ -0,0 +1,268 @@
+/**
+ * Builds the Data Source request handler returned by `abloSource()` and its alias
+ * `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') {
+        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 };
+}
+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 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;
+        // 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,
+                    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);
+}