@abloatai/ablo 0.26.0 → 0.28.0

package/dist/source/factory.d.ts

@@ -1,13 +1,9 @@
 /**
- * The `abloSource()` / `dataSource()` endpoint factory — the customer-owned
- * Data Source handler. Takes the options (schema, apiKey, handlers or ORM
- * adapter), verifies the signed request, enforces per-key scopes, and
- * dispatches the four wire operations (`load`/`list`/`commit`/`events`) to
- * the configured handlers.
- *
- * `AbloSourceOptions` lives here (not `types.ts`) because it references the
- * ORM `DataSourceAdapter` — keeping it with the factory keeps `types.ts` a
- * dependency-free leaf for `adapter.ts`/`contract.ts` to import from.
+ * 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';
@@ -20,39 +16,33 @@ type SourceModels<S extends SchemaRecord, TAuth> = Partial<{
 export type AbloSourceOptions<S extends SchemaRecord, TAuth = unknown> = {
     readonly schema: Schema<S>;
     /**
-     * Customer-visible Ablo credential. In the API-key-only onboarding
-     * path, Ablo signs Data Source calls with the same project API key
-     * that the customer's server-side SDK uses. This keeps the customer
-     * env surface to one Ablo credential while preserving signed request
-     * verification before any handler runs.
+     * 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;
     /**
-     * Clock-skew window for signed source requests. Default: 5 minutes.
+     * How much clock skew to tolerate when verifying a request's signed timestamp.
+     * Defaults to five minutes.
      */
     readonly signatureToleranceMs?: number;
     /**
-     * Verify the Ablo request and return customer-owned context such as
-     * a database handle, account scope, or current actor. Keep database
-     * credentials in this function's environment; never send them to Ablo.
-     *
-     * Signature verification is handled by `apiKey` before this function
-     * runs. `authorize` should only attach business context.
+     * 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;
     /**
-     * Optional per-request scope resolver. When set, the helper checks
-     * the resolved scope set against the request's operation
-     * (`load`/`list`/`commit`/`events`) and returns 403
-     * `source_forbidden` if not allowed — before any model handler
-     * runs.
-     *
-     * Customers typically extract a key id from the request (e.g.
-     * `webhook-id` prefix, a custom header, or the API key itself) and
-     * look up the scopes for that key in their store.
-     *
-     * When omitted, all operations are allowed. Returning an empty set
-     * denies all operations.
+     * 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;
@@ -60,45 +50,43 @@ export type AbloSourceOptions<S extends SchemaRecord, TAuth = unknown> = {
         readonly body: SourceRequest;
     }) => Promise<ReadonlySet<SourceScope> | readonly SourceScope[]> | ReadonlySet<SourceScope> | readonly SourceScope[];
     /**
-     * Top-level atomic commit handler. Prefer this for real applications:
-     * one UI/action commit can span several models and should run inside
-     * one customer-owned transaction.
+     * 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>;
     /**
-     * External-write feed. Ablo polls this to learn about changes that
-     * happened outside the SDK (cron jobs, dashboard edits, batch
-     * imports). Each returned event becomes a delta and fans out to
-     * connected clients.
-     *
-     * Handlers may return the raw outbox feed. Ablo dedupes stable
-     * `event.id` values and filters SDK-origin echoes when rows carry
-     * the originating `clientTxId`; customers should persist both fields
-     * in their outbox table.
+     * 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>;
     /**
-     * Optional grouped form. The object-key form below is usually terser:
-     * `abloSource({ schema, files: { load, list, commit } })`.
+     * 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 (`prismaDataSource(prisma, schema)`, …). When set, it serves
-     * ALL four operations — read (load/list), commit (idempotent + outbox), and
-     * events — so no hand-written `commit`/`events`/model handlers are needed. The
-     * adapter is consumed at the generic dispatch layer (rows are JSON on the wire),
-     * which is why it carries no per-model types and needs no cast at the call site.
-     * Mutually exclusive with hand-written handlers.
+     * 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>;
 /**
- * Create a customer-owned data source endpoint.
+ * Creates a Data Source endpoint you host in front of your own database.
  *
- * App code still talks to Ablo with `ablo.files.load/list/update`.
- * This helper is only for customers who keep canonical rows in their own
- * database and want Ablo Cloud to call a narrow, signed endpoint instead
- * of receiving database credentials.
+ * 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>;

package/dist/source/factory.js

@@ -1,13 +1,9 @@
 /**
- * The `abloSource()` / `dataSource()` endpoint factory — the customer-owned
- * Data Source handler. Takes the options (schema, apiKey, handlers or ORM
- * adapter), verifies the signed request, enforces per-key scopes, and
- * dispatches the four wire operations (`load`/`list`/`commit`/`events`) to
- * the configured handlers.
- *
- * `AbloSourceOptions` lives here (not `types.ts`) because it references the
- * ORM `DataSourceAdapter` — keeping it with the factory keeps `types.ts` a
- * dependency-free leaf for `adapter.ts`/`contract.ts` to import from.
+ * 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';
@@ -18,9 +14,9 @@ function json(data, status = 200) {
     });
 }
 /**
- * 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.
+ * 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') {
@@ -89,10 +85,9 @@ async function resolveApiKey(apiKey, context) {
     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.
+ * 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) {
@@ -129,12 +124,12 @@ function sameModel(operations) {
     return operations.every((op) => op.model === first) ? first : null;
 }
 /**
- * Create a customer-owned data source endpoint.
+ * Creates a Data Source endpoint you host in front of your own database.
  *
- * App code still talks to Ablo with `ablo.files.load/list/update`.
- * This helper is only for customers who keep canonical rows in their own
- * database and want Ablo Cloud to call a narrow, signed endpoint instead
- * of receiving database credentials.
+ * 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) {
@@ -180,9 +175,9 @@ export function abloSource(options) {
         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.
+        // 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 });
@@ -202,9 +197,9 @@ export function abloSource(options) {
             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.
+        // 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);
         }

package/dist/source/index.d.ts

@@ -1,21 +1,19 @@
 /**
- * `@abloatai/ablo/source` — the Data Source barrel.
+ * The entry point for the Data Source API, re-exporting the pieces you need from
+ * their individual modules:
  *
- * Pure re-exports only: the implementation lives in cohesive leaf modules so
- * sibling source/* files (`pushQueue.ts`, `adapter.ts`, `contract.ts`, the ORM
- * adapters) import the leaves directly instead of routing a runtime circular
- * dependency through this barrel.
- *
- *   - `types.ts`   — shared wire/handler types + `sourceEventForOperation`
- *   - `signing.ts` — Standard Webhooks request signing/verification
+ *   - `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.
  */
 export { sourceEventForOperation, type SourcePrimitive, type SourceWhere, type SourceListQuery, type SourceListPage, type SourceListResult, type SourceRequestContext, type SourceOperation, type SourceDelta, type SourceEvent, type SourceEventForOperationOptions, type SourceCommitResult, 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, type DataSourcePrimitive, type DataSourceWhere, type DataSourceListQuery, type DataSourceListPage, type DataSourceListResult, type DataSourceRequestContext, type DataSourceOperation, type DataSourceDelta, type DataSourceEvent, type DataSourceEventForOperationOptions, type DataSourceCommitResult, type DataSourceCommitParams, type DataSourceScope, type DataSourceEventsResult, type DataSourceEventsHandler, type DataSourceAuthorizeContext, type DataSourceHandlerContext, type DataSourceModelHandlers, type DataSourceCommitHandler, type DataSourceApiKey, type DataSourceLoadRequest, type DataSourceListRequest, type DataSourceCommitRequest, type DataSourceEventsRequest, type DataSourceRequest, type DataSourceResponse, } from './types.js';
 export { ABLO_SOURCE_HEADERS, SourceSignatureError, signAbloSourceRequest, verifyAbloSourceRequest, type SourceSignatureOptions, type SourceSignatureVerificationOptions, type SourceSignatureVerificationResult, type DataSourceSignatureOptions, type DataSourceSignatureVerificationOptions, type DataSourceSignatureVerificationResult, } from './signing.js';
 export { abloSource, dataSource, type AbloSourceOptions, 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 './connector-protocol.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 AdapterReadRequest, type AdapterCommitResult, type Row as AdapterRow, } from './adapter.js';
 export { operationSchema, operationTypeSchema, changeSetSchema, outboxEventSchema, eventsPageSchema, migrationSchema, adapterCapabilitiesSchema, type Operation, type ChangeSet, type OutboxEvent, type EventsPage, type Migration, type AdapterCapabilities, } from './contract.js';
 export { prismaDataSource, type PrismaLike, type PrismaDataSourceOptions } from './adapters/prisma.js';

package/dist/source/index.js

@@ -1,26 +1,24 @@
 /**
- * `@abloatai/ablo/source` — the Data Source barrel.
+ * The entry point for the Data Source API, re-exporting the pieces you need from
+ * their individual modules:
  *
- * Pure re-exports only: the implementation lives in cohesive leaf modules so
- * sibling source/* files (`pushQueue.ts`, `adapter.ts`, `contract.ts`, the ORM
- * adapters) import the leaves directly instead of routing a runtime circular
- * dependency through this barrel.
- *
- *   - `types.ts`   — shared wire/handler types + `sourceEventForOperation`
- *   - `signing.ts` — Standard Webhooks request signing/verification
+ *   - `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.
  */
 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';
-// ── Data Source adapter interface (Zod contract + one interface, per-ORM packages) ──
+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';

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 './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,9 +16,8 @@
  *     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 './factory.js';
 export function dataSourceNext(options) {

package/dist/source/pushQueue.d.ts

@@ -1,100 +1,122 @@
 /**
- * Customer-side push retry queue.
+ * A durable retry queue for delivering source events to the server.
  *
- * The push path (`POST /api/source/events` on Ablo Cloud) acks
- * synchronously. If the customer's app crashes mid-call, the network
- * drops, or Ablo returns 5xx, those events would otherwise be lost
- * — the poll path is the durability backstop, but it's higher
- * latency.
+ * When your application changes a row, it can push the resulting event to
+ * the server, which acknowledges delivery synchronously. If your process
+ * crashes mid-call, the network drops, or the server returns a 5xx, that
+ * event would be lost without a safety net. This queue is the safety net:
+ * it persists each event first, then delivers it from a background worker
+ * with automatic retries. (Polling the change feed is the slower fallback
+ * for anything the queue never manages to deliver.)
  *
- * `PushQueue` lives in the customer's process and gives them a
- * queue+worker pattern matching Stripe / Svix semantics:
+ * The queue follows a familiar enqueue-and-worker shape:
  *
- *   - `enqueue(events)` returns immediately after persisting
- *   - background worker delivers and retries per the Standard
- *     Webhooks schedule (0, 5s, 5m, 30m, 2h, 5h, 10h, 14h, 20h, 24h
- *     — ~3 days total)
- *   - exhausted items move to DLQ for customer-owned monitoring
+ *   - `enqueue(events)` returns as soon as the events are persisted.
+ *   - A background worker delivers them and retries on failure, following
+ *     the Standard Webhooks schedule (0, 5s, 5m, 30m, 2h, 5h, 10h, 14h,
+ *     20h, 24h — roughly three days in total).
+ *   - Items that exhaust every retry move to a dead-letter queue you can
+ *     monitor.
  *
- * Persistence is pluggable — `InMemoryPushQueueStorage` for single-
- * process customers, a SQL implementation against the customer's own
- * outbox table for production.
+ * Persistence is pluggable through {@link PushQueueStorage}. Use
+ * {@link InMemoryPushQueueStorage} for a single process, or implement that
+ * interface against your own outbox table for production durability.
  */
 import type { SourceEvent } from './types.js';
+/** One queued delivery: a batch of source events plus its retry bookkeeping. */
 export interface PushQueueItem {
     readonly id: string;
     readonly events: readonly SourceEvent[];
     readonly attempts: number;
-    /** Timestamp (ms) of the next attempt. Workers skip earlier items. */
+    /** When the next attempt is due, in epoch milliseconds. The worker skips items due later. */
     readonly nextAttemptAt: number;
-    /** Most recent error message, when any attempt has failed. */
+    /** The most recent error message, set once an attempt has failed. */
     readonly lastError?: string;
-    /** `dlq` once retries exhausted. */
+    /** `pending` while awaiting delivery, `delivered` on success, `dlq` once retries are exhausted. */
     readonly status: 'pending' | 'delivered' | 'dlq';
 }
+/**
+ * The persistence behind a {@link PushQueue}. Implement it against your own
+ * durable table (or use {@link InMemoryPushQueueStorage}) so queued events
+ * survive a process restart. The queue calls these methods; you decide where
+ * the rows actually live.
+ */
 export interface PushQueueStorage {
     /**
-     * Append a new item; returns the persisted record. Implementations
-     * generate a stable id (used as the `webhook-id`) and set
-     * `nextAttemptAt = now`.
+     * Append a new item and return the persisted record. Generate a stable id
+     * — it doubles as the `webhook-id` on the delivered request — and set
+     * `nextAttemptAt` to the current time so the item is due immediately.
      */
     enqueue(events: readonly SourceEvent[]): Promise<PushQueueItem>;
-    /** Items whose `nextAttemptAt <= now` and `status === 'pending'`. */
+    /** Return pending items whose `nextAttemptAt` is at or before `now`, up to `limit`. */
     due(now: number, limit: number): Promise<readonly PushQueueItem[]>;
-    /** Bump attempt count + reschedule. */
+    /** Increase the attempt count and set the next attempt time after a failed delivery. */
     reschedule(id: string, nextAttemptAt: number, lastError: string): Promise<void>;
-    /** Mark the item delivered (no further attempts). */
+    /** Mark the item delivered so no further attempts are made. */
     markDelivered(id: string): Promise<void>;
-    /** Mark the item DLQ (retries exhausted). */
+    /** Move the item to the dead-letter queue after its retries are exhausted. */
     markDlq(id: string, lastError: string): Promise<void>;
-    /** Read DLQ contents — customer monitors this. */
+    /** Read the dead-letter queue. Your monitoring reads this to surface deliveries that never succeeded. */
     listDlq(): Promise<readonly PushQueueItem[]>;
 }
 /**
- * Standard Webhooks retry schedule. Index = attempt number; value =
- * delay-ms after the previous attempt. After the last entry, items
- * move to DLQ.
+ * The default retry schedule, taken from the Standard Webhooks
+ * specification. The index is the attempt number and the value is the delay
+ * in milliseconds after the previous attempt failed. Once an item runs off
+ * the end of this array, it moves to the dead-letter queue.
  *
- * Source: https://www.standardwebhooks.com/
+ * See https://www.standardwebhooks.com/.
  */
 export declare const STANDARD_WEBHOOKS_RETRY_SCHEDULE: readonly number[];
+/** Configuration for {@link createPushQueue}. */
 export interface PushQueueOptions {
+    /** The URL the worker delivers events to. */
     readonly endpoint: string;
+    /** The API key used to sign each delivery. */
     readonly apiKey: string;
+    /** Where queued items are persisted. */
     readonly storage: PushQueueStorage;
     /**
-     * Override the retry delays. Default: Standard Webhooks schedule.
-     * The number of attempts equals the array length; the i-th entry
-     * is the delay after attempt `i` failed.
+     * Override the retry delays. Defaults to {@link STANDARD_WEBHOOKS_RETRY_SCHEDULE}.
+     * The number of attempts equals the array length, and the i-th entry is the
+     * delay after attempt `i` failed.
      */
     readonly retrySchedule?: readonly number[];
-    /** Worker poll interval. Default 1000ms. */
+    /** How often the worker checks for due items, in milliseconds. Defaults to 1000. */
     readonly tickIntervalMs?: number;
-    /** Max items pulled per tick. Default 50. */
+    /** The most items the worker delivers per tick. Defaults to 50. */
     readonly batchSize?: number;
-    /** Pluggable for tests / non-Node fetch impls. */
+    /** A custom fetch implementation, for tests or runtimes without a global `fetch`. */
     readonly fetch?: typeof fetch;
-    /** Pluggable for tests. */
+    /** A custom clock source, mainly for tests. Defaults to `Date.now`. */
     readonly now?: () => number;
-    /** Random jitter on retry delays. Default ±10%. Set to 0 to disable. */
+    /** Random jitter applied to each retry delay, as a fraction. Defaults to ±10%; set 0 to disable. */
     readonly jitter?: number;
+    /** Called when an item is dead-lettered or the worker loop hits an error. */
     readonly onError?: (item: PushQueueItem, err: unknown) => void;
 }
+/** A running push queue: persist events, deliver them, and recover dead-lettered ones. */
 export interface PushQueue {
+    /** Persist a batch of events for delivery and return the queued item. */
     enqueue(events: readonly SourceEvent[]): Promise<PushQueueItem>;
-    /** Run the worker loop until `signal` aborts. */
+    /** Run the delivery worker until `signal` aborts. */
     run(signal: AbortSignal): Promise<void>;
-    /** Drain the DLQ by re-enqueueing — customer-triggered redrive. */
+    /**
+     * Re-enqueue every dead-lettered item for another round of delivery. Call
+     * this yourself once you have fixed whatever caused the failures. Returns
+     * the number of items re-enqueued.
+     */
     redriveDlq(): Promise<number>;
 }
+/** Create a {@link PushQueue} from the given {@link PushQueueOptions}. */
 export declare function createPushQueue(options: PushQueueOptions): PushQueue;
+/**
+ * A {@link PushQueueStorage} that keeps items in memory. It is not durable —
+ * items are lost when the process restarts — so it suits development and
+ * low-volume use. For production, implement {@link PushQueueStorage} against
+ * your own table.
+ */
 export declare class InMemoryPushQueueStorage implements PushQueueStorage {
-    /**
-     * Real implementation, not a mock. Suitable for low-volume single-
-     * process customers; not durable across restarts (in-flight items
-     * are lost). Production customers should swap in a SQL-backed
-     * storage that writes to their existing outbox table.
-     */
     private items;
     private nextId;
     private readonly now;