@abloatai/ablo 0.24.0 → 0.26.0

package/dist/source/index.d.ts

@@ -1,468 +1,18 @@
-import type { Schema, SchemaRecord, InferCreate } from '../schema/schema.js';
-import type { Environment } from '../environment.js';
-import type { DataSourceAdapter } from './adapter.js';
-export type SourcePrimitive = string | number | boolean | null;
-export type SourceWhere = readonly [field: string, value: SourcePrimitive] | readonly [
-    field: string,
-    op: '=' | '!=' | '<' | '<=' | '>' | '>=' | 'IN' | 'NOT IN' | 'IS' | 'IS NOT' | 'LIKE' | 'NOT LIKE' | 'ILIKE' | 'NOT ILIKE',
-    value: SourcePrimitive | readonly SourcePrimitive[]
-];
-export interface SourceListQuery {
-    readonly where?: readonly SourceWhere[];
-    readonly limit?: number;
-    readonly orderBy?: string;
-    readonly order?: 'asc' | 'desc';
-    readonly related?: readonly string[];
-    /**
-     * Opaque cursor returned by a previous `list` call. The customer's
-     * `list` handler defines what this encodes (page index, last id,
-     * keyset). Ablo treats it as a black box — round-trips it back to
-     * fetch the next page until the handler returns no `nextCursor`.
-     */
-    readonly cursor?: string;
-}
 /**
- * Optional structured shape for a `list` handler that supports
- * pagination. Handlers may keep returning a plain `Row[]` (no
- * pagination, single-shot) or upgrade to this shape to expose a
- * cursor that Ablo will round-trip on the next request.
- */
-export interface SourceListPage<Row> {
-    readonly rows: readonly Row[];
-    readonly nextCursor?: string;
-}
-export type SourceListResult<Row> = readonly Row[] | SourceListPage<Row>;
-/**
- * Read-side scope context that Ablo attaches to source requests so
- * the customer's `authorize` / model handlers can refuse calls that
- * fall outside the participant's permitted syncGroups.
- *
- * This is informational — the customer is the only side that can
- * actually enforce, since the canonical data lives in their store.
- * Mirrors how Auth0 Custom DB scripts receive the requested scope and
- * trust the script to honor it.
- */
-export interface SourceRequestContext {
-    readonly participantId?: string;
-    readonly participantKind?: 'user' | 'agent' | 'system';
-    readonly organizationId?: string;
-    readonly requiredSyncGroups?: readonly string[];
-    /**
-     * Production/sandbox mode for this request. Customers branch their source
-     * handlers on this (`if (mode === 'sandbox') db = sandboxDb`) so sandbox
-     * traffic exercises the same code path against an isolated store.
-     *
-     * Mirrors Stripe's `sk_test_` / `sk_live_` prefixes: same wire
-     * shape, same handler code, different namespace. Ablo's server-side
-     * fan-out does not yet partition deltas by mode — that lands when
-     * `sync_deltas.mode` ships. Until then, isolation is enforced
-     * customer-side via this field, which is the right boundary anyway
-     * (the customer's database is where the canonical data lives).
-     *
-     * Defaults to `'production'` when omitted so callers that don't opt in
-     * keep the existing behavior.
-     */
-    readonly mode?: Environment;
-}
-export interface SourceOperation {
-    readonly type: 'CREATE' | 'UPDATE' | 'DELETE' | 'ARCHIVE' | 'UNARCHIVE';
-    readonly model: string;
-    readonly id?: string | null;
-    readonly input?: Record<string, unknown> | null;
-    readonly transactionId?: string | null;
-    readonly readAt?: number | null;
-    readonly onStale?: 'reject' | 'overwrite' | 'notify' | null;
-}
-export interface SourceDelta {
-    readonly model: string;
-    readonly id: string;
-    readonly type: SourceOperation['type'];
-    readonly data?: Record<string, unknown> | null;
-    readonly transactionId?: string | null;
-}
-/**
- * A change that happened in the customer's store. The source's
- * `events` handler returns these so Ablo can append them to
- * `sync_deltas` and fan them out to connected clients exactly like
- * SDK-originated commits.
- *
- * The events handler can return everything from the outbox unfiltered. Ablo
- * dedupes stable `event.id` values and uses `clientTxId` to filter SDK-origin
- * echoes after the direct append has already succeeded. If the direct append
- * failed, the same outbox event repairs it on poll/push because no matching
- * `mutation_log` row exists yet.
- */
-export interface SourceEvent {
-    /**
-     * Globally unique event id from the customer's outbox. Used by Ablo
-     * for replay protection — re-delivering the same id is a no-op.
-     */
-    readonly id: string;
-    readonly model: string;
-    readonly entityId: string;
-    readonly type: SourceOperation['type'];
-    readonly data?: Record<string, unknown> | null;
-    /**
-     * Tenant the event belongs to. Multi-tenant customers populate this
-     * from the row's organization column. Single-tenant deployments may
-     * omit it and let the poller fall back to its configured default.
-     * Drives the sync-group fan-out: clients in `org:${organizationId}`
-     * receive the resulting delta.
-     */
-    readonly organizationId?: string;
-    /**
-     * Originating Ablo SDK commit id, when known. If the customer's
-     * outbox stores the `clientTxId` Ablo passed into the matching
-     * `commit` handler, round-trip it here and Ablo will skip events
-     * whose commit already produced a delta. External-origin events
-     * (cron jobs, batch imports, manual edits) leave this unset.
-     */
-    readonly clientTxId?: string;
-    /**
-     * Wall-clock time the event occurred in the source. Optional; used
-     * only for ordering hints. Ablo trusts the customer's response order
-     * over this field.
-     */
-    readonly occurredAt?: number;
-}
-export interface SourceEventForOperationOptions {
-    /**
-     * Stable id from the customer's outbox table. This is Ablo's replay-
-     * protection key; retries must return the same id.
-     */
-    readonly eventId: string;
-    readonly operation: SourceOperation;
-    /**
-     * Committed row id. Defaults to `operation.id`; pass this for generated-id
-     * CREATEs where the database assigns the id inside the transaction.
-     */
-    readonly entityId?: string;
-    /**
-     * Canonical row payload after the write. Pass `null` for DELETE. When omitted
-     * the event carries no row payload, which is valid but less useful for
-     * realtime hydration.
-     */
-    readonly data?: Record<string, unknown> | null;
-    /**
-     * Batch idempotency key from the Data Source commit request. Round-tripping it
-     * lets Ablo filter SDK-origin echoes after the direct append succeeds, while
-     * still using the outbox event to repair a failed direct append.
-     */
-    readonly clientTxId?: string;
-    readonly organizationId?: string;
-    readonly occurredAt?: number | Date;
-}
-/**
- * Build the source-event marker customers should write to their outbox table in
- * the SAME transaction as their app-row mutation.
+ * `@abloatai/ablo/source` — the Data Source barrel.
  *
- * This helper does not persist anything. It only standardizes the marker shape
- * so Prisma/Drizzle/Kysely/raw-SQL adapters all emit the fields Ablo's
- * reconciler expects.
- */
-export declare function sourceEventForOperation(options: SourceEventForOperationOptions): SourceEvent;
-export interface SourceCommitResult<Row = Record<string, unknown>> {
-    /**
-     * Canonical rows after the write. Ablo uses these to update hosted
-     * realtime projections and append deltas.
-     */
-    readonly rows?: readonly Row[];
-    /**
-     * Optional explicit deltas when the source already computes them.
-     * Most sources can return rows and let Ablo derive the delta payload.
-     */
-    readonly deltas?: readonly SourceDelta[];
-}
-export interface SourceCommitParams<TAuth = unknown> {
-    readonly operations: readonly SourceOperation[];
-    readonly clientTxId?: string;
-    readonly context: SourceHandlerContext<TAuth>;
-}
-/**
- * Operation-level permission tag used by `resolveScopes`. Mirrors the
- * four wire request types: an API key carries the set of operations
- * it's allowed to invoke. Stripe's restricted-key model at the
- * operation granularity — model-level scoping is a future addition.
- */
-export type SourceScope = 'load' | 'list' | 'commit' | 'events';
-export interface SourceEventsResult {
-    readonly events: readonly SourceEvent[];
-    /**
-     * Cursor for the next poll. When omitted Ablo treats the feed as
-     * fully drained for this round and uses the last event's cursor (or
-     * the initial cursor) for the next call.
-     */
-    readonly nextCursor?: string;
-}
-export type SourceEventsHandler<TAuth = unknown> = (params: {
-    /**
-     * Cursor returned by a previous `events` call. Undefined on the
-     * first poll for a freshly-onboarded source. The customer decides
-     * what it encodes (last event id, timestamp, LSN, etc).
-     */
-    readonly cursor?: string;
-    /**
-     * Caller-suggested upper bound on returned events. Customers may
-     * return fewer; returning more risks tripping Ablo's per-poll cap.
-     */
-    readonly limit?: number;
-    readonly context: SourceHandlerContext<TAuth>;
-}) => Promise<SourceEventsResult> | SourceEventsResult;
-export interface SourceAuthorizeContext {
-    readonly request: Request;
-    readonly body: unknown;
-    readonly rawBody: string;
-}
-export interface SourceHandlerContext<TAuth = unknown> {
-    readonly auth: TAuth;
-    readonly request: Request;
-    /**
-     * `webhook-id` from the signed request — globally unique per the
-     * Standard Webhooks spec. Customers should dedupe by this id to
-     * defend against replay (Ablo doesn't dedupe at the source-handler
-     * boundary; commit idempotency is `clientTxId`, and event replay
-     * protection is the outbox event `id`).
-     */
-    readonly messageId?: string;
-    readonly signedAt?: number;
-    /**
-     * Scope context Ablo attached to this request. Present when the
-     * caller (sync-server) opted into scope-aware source mode. Customers
-     * can use it in `authorize` (to reject out-of-scope calls) and in
-     * `list` / `load` (to filter rows the participant is allowed to see).
-     *
-     * Absent for calls made without scope context, such as tests or
-     * single-tenant deployments that do not need scoped fan-out yet.
-     */
-    readonly scope?: SourceRequestContext;
-}
-export interface SourceModelHandlers<Row, CreateInput, TAuth = unknown> {
-    load?(params: {
-        readonly id: string;
-        readonly context: SourceHandlerContext<TAuth>;
-    }): Promise<Row | null> | Row | null;
-    list?(params: {
-        readonly query: SourceListQuery;
-        readonly context: SourceHandlerContext<TAuth>;
-    }): Promise<SourceListResult<Row>> | SourceListResult<Row>;
-    /**
-     * Apply one or more operations for this model in the customer's own
-     * transaction. The source must be idempotent by operation/clientTxId.
-     */
-    commit?(params: {
-        readonly operations: readonly SourceOperation[];
-        readonly clientTxId?: string;
-        readonly context: SourceHandlerContext<TAuth>;
-    }): Promise<SourceCommitResult<Row>> | SourceCommitResult<Row>;
-}
-export type SourceCommitHandler<TAuth = unknown> = (params: SourceCommitParams<TAuth>) => Promise<SourceCommitResult> | SourceCommitResult;
-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 SourceApiKey = string | ((context: SourceAuthorizeContext) => Promise<string> | string);
-export interface SourceSignatureOptions {
-    readonly apiKey: string;
-    readonly body: string;
-    /**
-     * Unique message id (`webhook-id` per the Standard Webhooks spec).
-     * Required: it goes into the HMAC input for replay defense, and
-     * receivers may dedupe by it.
-     */
-    readonly messageId: string;
-    /**
-     * Unix timestamp in seconds. Defaults to the current time.
-     */
-    readonly timestamp?: number;
-}
-export interface SourceSignatureVerificationOptions {
-    readonly request: Request;
-    readonly body: string;
-    readonly apiKey: string;
-    readonly toleranceMs?: number;
-}
-export interface SourceSignatureVerificationResult {
-    readonly messageId: string;
-    readonly signedAt: number;
-}
-/**
- * HTTP headers used on signed source requests. Conforms to the
- * Standard Webhooks specification (https://www.standardwebhooks.com/)
- * so customer code can verify our signatures with any of the official
- * libraries (svix, standardwebhooks, hookdeck, etc.) — no Ablo-
- * specific verifier required.
- */
-export declare const ABLO_SOURCE_HEADERS: {
-    readonly signature: "webhook-signature";
-    readonly timestamp: "webhook-timestamp";
-    readonly id: "webhook-id";
-    readonly idempotencyKey: "Idempotency-Key";
-};
-export declare class SourceSignatureError extends Error {
-    readonly code: 'source_signature_missing' | 'source_id_missing' | 'source_timestamp_missing' | 'source_timestamp_invalid' | 'source_timestamp_expired' | 'source_signature_invalid' | 'source_forbidden';
-    constructor(code: SourceSignatureError['code'], message: string);
-}
-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.
-     */
-    readonly apiKey: SourceApiKey;
-    /**
-     * Clock-skew window for signed source requests. Default: 5 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.
-     */
-    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.
-     */
-    readonly resolveScopes?: (params: {
-        readonly auth: TAuth;
-        readonly request: Request;
-        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.
-     */
-    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.
-     */
-    readonly events?: SourceEventsHandler<TAuth>;
-    /**
-     * Optional grouped form. The object-key form below is usually terser:
-     * `abloSource({ schema, files: { load, list, commit } })`.
-     */
-    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.
-     */
-    readonly adapter?: DataSourceAdapter;
-} & SourceModels<S, TAuth>;
-export type SourceLoadRequest = {
-    readonly type: 'load';
-    readonly model: string;
-    readonly id: string;
-    readonly scope?: SourceRequestContext;
-};
-export type SourceListRequest = {
-    readonly type: 'list';
-    readonly model: string;
-    readonly query?: SourceListQuery;
-    readonly scope?: SourceRequestContext;
-};
-export type SourceCommitRequest = {
-    readonly type: 'commit';
-    /**
-     * Optional single-model hint. Omit for cross-model commits; top-level
-     * `commit` receives the whole operation array unchanged.
-     */
-    readonly model?: string;
-    readonly operations: readonly SourceOperation[];
-    readonly clientTxId?: string;
-    readonly scope?: SourceRequestContext;
-};
-export type SourceEventsRequest = {
-    readonly type: 'events';
-    readonly cursor?: string;
-    readonly limit?: number;
-    readonly scope?: SourceRequestContext;
-};
-export type SourceRequest = SourceLoadRequest | SourceListRequest | SourceCommitRequest | SourceEventsRequest;
-export type SourceResponse<Row = Record<string, unknown>> = {
-    readonly row: Row | null;
-} | {
-    readonly rows: readonly Row[];
-    readonly nextCursor?: string;
-} | {
-    readonly rows?: readonly Row[];
-    readonly deltas?: readonly SourceDelta[];
-};
-export declare function signAbloSourceRequest(options: SourceSignatureOptions): Promise<{
-    readonly headers: Record<string, string>;
-    readonly signedAt: number;
-    readonly signature: string;
-}>;
-export declare function verifyAbloSourceRequest(options: SourceSignatureVerificationOptions): Promise<SourceSignatureVerificationResult>;
-/**
- * Create a customer-owned data source endpoint.
+ * 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.
  *
- * 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.
+ *   - `types.ts`   — shared wire/handler types + `sourceEventForOperation`
+ *   - `signing.ts` — Standard Webhooks request signing/verification
+ *   - `factory.ts` — the `abloSource()` / `dataSource()` endpoint factory
  */
-export type DataSourcePrimitive = SourcePrimitive;
-export type DataSourceWhere = SourceWhere;
-export type DataSourceListQuery = SourceListQuery;
-export type DataSourceListPage<Row> = SourceListPage<Row>;
-export type DataSourceListResult<Row> = SourceListResult<Row>;
-export type DataSourceRequestContext = SourceRequestContext;
-export type DataSourceOperation = SourceOperation;
-export type DataSourceDelta = SourceDelta;
-export type DataSourceEvent = SourceEvent;
-export type DataSourceEventForOperationOptions = SourceEventForOperationOptions;
-export type DataSourceCommitResult<Row = Record<string, unknown>> = SourceCommitResult<Row>;
-export type DataSourceCommitParams<TAuth = unknown> = SourceCommitParams<TAuth>;
-export type DataSourceScope = SourceScope;
-export type DataSourceEventsResult = SourceEventsResult;
-export type DataSourceEventsHandler<TAuth = unknown> = SourceEventsHandler<TAuth>;
-export type DataSourceAuthorizeContext = SourceAuthorizeContext;
-export type DataSourceHandlerContext<TAuth = unknown> = SourceHandlerContext<TAuth>;
-export type DataSourceModelHandlers<Row, CreateInput, TAuth = unknown> = SourceModelHandlers<Row, CreateInput, TAuth>;
-export type DataSourceCommitHandler<TAuth = unknown> = SourceCommitHandler<TAuth>;
-export type DataSourceApiKey = SourceApiKey;
-export type DataSourceSignatureOptions = SourceSignatureOptions;
-export type DataSourceSignatureVerificationOptions = SourceSignatureVerificationOptions;
-export type DataSourceSignatureVerificationResult = SourceSignatureVerificationResult;
-export type DataSourceOptions<S extends SchemaRecord, TAuth = unknown> = AbloSourceOptions<S, TAuth>;
-export type DataSourceLoadRequest = SourceLoadRequest;
-export type DataSourceListRequest = SourceListRequest;
-export type DataSourceCommitRequest = SourceCommitRequest;
-export type DataSourceEventsRequest = SourceEventsRequest;
-export type DataSourceRequest = SourceRequest;
-export type DataSourceResponse<Row = Record<string, unknown>> = SourceResponse<Row>;
-export declare function abloSource<const S extends SchemaRecord, TAuth = unknown>(options: AbloSourceOptions<S, TAuth>): (request: Request) => Promise<Response>;
-export declare function dataSource<const S extends SchemaRecord, TAuth = unknown>(options: DataSourceOptions<S, TAuth>): (request: Request) => Promise<Response>;
+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';