backlex 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,569 @@
+import { L as ListQuery, k as ListResponse, C as Condition, f as DurationParts, R as RelativeNow, A as AggregateQuery, a as AggregateRow, S as SearchQuery, m as SearchResponse, I as ImportSummary, h as ItemQuery, i as ItemResponse, d as BatchResponse, c as BatchOperation, g as ItemEvent, l as ResumableUploadResult, D as DeviceToken, P as PhoneNumber, j as JobStatus, J as Job, F as FlagState } from './types-CbcbXGiA.js';
+export { B as BacklexError, U as Upload, n as UploadStatus } from './types-CbcbXGiA.js';
+export { VerifyWebhookOptions, verifyWebhook } from './webhook.js';
+
+/**
+ * Offline-first sync for a single collection.
+ *
+ * Pulls the server changefeed (`GET /api/items/:slug/changes`) into a local
+ * store, keeps it live over SSE, and lets the app read/write while offline:
+ * writes apply optimistically to the local store and queue, then flush through
+ * the batch endpoint on reconnect. Conflicts resolve last-write-wins by
+ * `updated_at`, with locally-queued (not-yet-flushed) writes held until they
+ * land.
+ *
+ * The store is pluggable — `memoryStore()` works anywhere; `indexedDbStore()`
+ * persists across reloads in the browser.
+ */
+type QueuedOp = {
+    kind: "create";
+    tempId: string;
+    data: Record<string, unknown>;
+} | {
+    kind: "update";
+    id: string;
+    data: Record<string, unknown>;
+} | {
+    kind: "delete";
+    id: string;
+};
+interface SyncStore {
+    get(id: string): Promise<Record<string, unknown> | undefined>;
+    set(id: string, row: Record<string, unknown>): Promise<void>;
+    remove(id: string): Promise<void>;
+    all(): Promise<Record<string, unknown>[]>;
+    getMeta(key: string): Promise<string | null>;
+    setMeta(key: string, value: string): Promise<void>;
+    queueGet(): Promise<QueuedOp[]>;
+    queueSet(ops: QueuedOp[]): Promise<void>;
+}
+/** In-memory store — non-persistent; the default and the testing baseline. */
+declare const memoryStore: () => SyncStore;
+/** IndexedDB-backed store (browser). One object store for rows + one for meta;
+ *  the write queue lives under a meta key. Falls back to throwing if IndexedDB
+ *  is unavailable — use `memoryStore()` outside the browser. */
+declare const indexedDbStore: (opts: {
+    collection: string;
+    dbName?: string;
+}) => SyncStore;
+/** The subset of the backlex client `createSync` needs. The full client satisfies it. */
+interface SyncClientLike {
+    request: <T>(method: string, path: string, body?: unknown) => Promise<T>;
+    subscribe: (channel: string, onEvent: (e: {
+        event: "created" | "updated" | "deleted";
+        data: Record<string, unknown>;
+    }) => void, onError?: (err: unknown) => void) => () => void;
+}
+interface SyncOptions {
+    collection: string;
+    store?: SyncStore;
+    /** Primary-key field. Default `id`. */
+    pk?: string;
+    /** Rows per changefeed page. Default 200. */
+    pageSize?: number;
+    /** Called after the local store changes (pull / live / local write). */
+    onChange?: () => void;
+}
+declare const createSync: (client: SyncClientLike, options: SyncOptions) => {
+    pull: () => Promise<number>;
+    flush: () => Promise<void>;
+    live: () => (() => void);
+    start: () => Promise<void>;
+    stop: () => void;
+    getAll: () => Promise<Record<string, unknown>[]>;
+    get: (id: string) => Promise<Record<string, unknown> | undefined>;
+    create: (data: Record<string, unknown>) => Promise<string>;
+    update: (id: string, data: Record<string, unknown>) => Promise<void>;
+    remove: (id: string) => Promise<void>;
+    store: SyncStore;
+};
+
+/**
+ * Type-safe fluent query builder — a Drizzle/Supabase-style ergonomics layer
+ * that COMPILES to the canonical JSON `Condition` / `ListQuery` the REST API
+ * already speaks. It is NOT a new wire format: `.toQuery()` returns a plain
+ * `ListQuery`, so everything (permissions, AI plans, serialization) stays on
+ * the one JSON grammar.
+ *
+ *   const { data } = await client.from<Order>("orders").query()
+ *     .where(f => f.and(
+ *       f.eq("status", "active"),
+ *       f.gte("total", 100),
+ *       f.rel("customer", c => c.eq("tier", "gold")),   // → "customer.tier"
+ *       f.gte("placed_at", f.now({ sub: { months: 1 } })),
+ *     ))
+ *     .select("id", "total", "customer.name")
+ *     .orderBy("-placed_at", "id")
+ *     .limit(50)
+ *     .list();
+ *
+ * Field args are typed `keyof T | (string & {})` — autocomplete for known
+ * columns, dotted relation paths still allowed, no codegen required.
+ */
+/** A known column of `T`, or any string (dotted relation paths, computed). */
+type FieldKey<T> = (keyof T & string) | (string & {});
+/** `field` ascending, or `-field` descending. */
+type SortKey<T> = FieldKey<T> | `-${string}`;
+interface FilterBuilder<T> {
+    eq(field: FieldKey<T>, value: unknown): Condition;
+    neq(field: FieldKey<T>, value: unknown): Condition;
+    gt(field: FieldKey<T>, value: unknown): Condition;
+    gte(field: FieldKey<T>, value: unknown): Condition;
+    lt(field: FieldKey<T>, value: unknown): Condition;
+    lte(field: FieldKey<T>, value: unknown): Condition;
+    in(field: FieldKey<T>, values: unknown[]): Condition;
+    nin(field: FieldKey<T>, values: unknown[]): Condition;
+    between(field: FieldKey<T>, lo: unknown, hi: unknown): Condition;
+    isNull(field: FieldKey<T>, isNull?: boolean): Condition;
+    empty(field: FieldKey<T>): Condition;
+    nempty(field: FieldKey<T>): Condition;
+    contains(field: FieldKey<T>, value: string): Condition;
+    icontains(field: FieldKey<T>, value: string): Condition;
+    startsWith(field: FieldKey<T>, value: string): Condition;
+    endsWith(field: FieldKey<T>, value: string): Condition;
+    and(...conds: Condition[]): Condition;
+    or(...conds: Condition[]): Condition;
+    not(cond: Condition): Condition;
+    /** Traverse a relation: keys produced by `build` are prefixed with `head.`. */
+    rel<R = Record<string, unknown>>(head: FieldKey<T>, build: (f: FilterBuilder<R>) => Condition): Condition;
+    /** Relative-date value, e.g. `f.now({ sub: { months: 1 } })`. */
+    now(opts?: {
+        add?: DurationParts;
+        sub?: DurationParts;
+    }): RelativeNow;
+}
+declare class QueryBuilder<T extends Record<string, unknown>> {
+    private readonly listFn;
+    private _filter?;
+    private _sort;
+    private _fields;
+    private _expand;
+    private _limit?;
+    private _offset?;
+    private _meta?;
+    private _locale?;
+    private _q?;
+    constructor(listFn: (q: ListQuery) => Promise<ListResponse<T>>);
+    where(build: (f: FilterBuilder<T>) => Condition): this;
+    /** Replace the filter with a raw canonical condition (escape hatch). */
+    filter(cond: Condition): this;
+    select(...fields: FieldKey<T>[]): this;
+    orderBy(...sorts: SortKey<T>[]): this;
+    /** Inline single-hop relations (replaces each FK with the related object). */
+    expand(...rels: FieldKey<T>[]): this;
+    /** Project `i18n_text` fields to one locale, or `"*"` for the full map. */
+    locale(loc: string): this;
+    /** Free-text search across readable text fields. */
+    search(text: string): this;
+    limit(n: number): this;
+    offset(n: number): this;
+    withMeta(m: "filter_count" | "total_count" | "*"): this;
+    /** Assemble the plain `ListQuery` — the canonical JSON the REST API takes. */
+    toQuery(): ListQuery;
+    list(): Promise<ListResponse<T>>;
+}
+
+interface ClientOptions {
+    url: string;
+    /** Static API key (`pak_...`) for server-to-server calls. Browser apps
+     *  should rely on the cookie session / a workspace session token and omit
+     *  this. */
+    apiKey?: string;
+    /**
+     * Workspace slug. When set, the client operates in **app mode**: `auth.*`
+     * targets that workspace's own auth surface (`/api/t/<slug>/auth/*`, the
+     * "auth as a service" pool — distinct from the admin/control-plane auth),
+     * and the session token returned by `auth.signUp` / `auth.signIn` is
+     * captured and sent as `Authorization: Bearer <token>` on every subsequent
+     * request (data + auth). Persist it across page loads with `auth.getToken()`
+     * / restore it with `auth.setToken()`.
+     */
+    workspace?: string;
+    /** Restore a previously-saved workspace session token (app mode). */
+    token?: string;
+    /**
+     * Scope every request to a specific tenant/workspace by sending the
+     * `X-Backlex-Tenant` header (slug or id). Needed for anonymous public reads
+     * and for a `pak_` key addressing a tenant other than its home one. The server
+     * ignores it for app-mode bearer sessions (the tenant comes from the session).
+     */
+    tenant?: string;
+    /** Optional fetch override (testing / Node polyfill). */
+    fetch?: typeof fetch;
+}
+interface AuthUser {
+    id: string;
+    email: string;
+    name?: string | null;
+    image?: string | null;
+}
+interface AuthResult {
+    user: AuthUser;
+    token?: string;
+}
+interface AuthSession {
+    id: string;
+    token: string;
+    userId: string;
+    expiresAt: string;
+    ipAddress?: string | null;
+    userAgent?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface PublicProvider {
+    id: string;
+    kind: "credential" | "magic-link" | "email-otp" | "passkey" | "social";
+    label: string;
+    enabled: boolean;
+}
+interface AuthSurface {
+    tenantId: string | null;
+    providers: PublicProvider[];
+    policy: {
+        openSignup: boolean;
+        requireEmailVerification: boolean;
+    } & Record<string, unknown>;
+}
+/** The per-collection data API returned by `client.from<T>(slug)`. Exported so
+ *  generated SDKs (see `backlex gen-types --sdk`) and apps can name the shape. */
+interface CollectionClient<T extends Record<string, unknown>> {
+    list(q?: ListQuery): Promise<ListResponse<T>>;
+    /** Fluent, type-safe query builder that compiles to `ListQuery`. */
+    query(): QueryBuilder<T>;
+    /** Run a single-function aggregate (count/sum/avg/min/max), optionally grouped. */
+    aggregate(body: AggregateQuery): Promise<{
+        data: AggregateRow[];
+    }>;
+    /** Relevance search — full-text, vector, or `hybrid` (RRF). Requires the
+     *  matching capability enabled on the collection. Rows come back best-first
+     *  with the caller's read permission + tenant scope enforced. */
+    search(body: SearchQuery): Promise<SearchResponse<T>>;
+    /** Export every readable row as a JSON or CSV string. */
+    exportItems(format?: "json" | "csv"): Promise<string>;
+    /** Bulk-import rows from a JSON array (or a raw JSON/CSV string). */
+    importItems(body: string | Partial<T>[], format?: "json" | "csv"): Promise<ImportSummary>;
+    one(id: string, opts?: ItemQuery): Promise<ItemResponse<T>>;
+    create(data: Partial<T>): Promise<ItemResponse<T>>;
+    update(id: string, patch: Partial<T>): Promise<ItemResponse<T>>;
+    delete(id: string): Promise<{
+        ok: boolean;
+    }>;
+    createMany(rows: Partial<T>[], opts?: {
+        atomic?: boolean;
+    }): Promise<BatchResponse<T>>;
+    updateMany(updates: {
+        id: string;
+        data: Partial<T>;
+    }[], opts?: {
+        atomic?: boolean;
+    }): Promise<BatchResponse<T>>;
+    deleteMany(ids: string[], opts?: {
+        atomic?: boolean;
+    }): Promise<BatchResponse<T>>;
+    batch(operations: BatchOperation<T>[], opts?: {
+        atomic?: boolean;
+    }): Promise<BatchResponse<T>>;
+    publish(id: string): Promise<ItemResponse<T>>;
+    unpublish(id: string): Promise<ItemResponse<T>>;
+    schedulePublish(id: string, at: Date | string | null): Promise<ItemResponse<T>>;
+}
+declare const createClient: (opts: ClientOptions) => {
+    from: <T extends Record<string, unknown>>(slug: string) => CollectionClient<T>;
+    subscribe: <T = Record<string, unknown>>(channel: string, onEvent: (e: ItemEvent<T>) => void, onError?: (err: unknown) => void) => (() => void);
+    auth: {
+        /** Email + password sign-up. In app mode this creates a *workspace* end-
+         *  user (in `app_users`), not a control-plane account. */
+        signUp: (input: {
+            email: string;
+            password: string;
+            name?: string;
+        }) => Promise<AuthResult>;
+        /** Email + password sign-in. */
+        signIn: (input: {
+            email: string;
+            password: string;
+        }) => Promise<AuthResult>;
+        /**
+         * Begin an OAuth sign-in. Returns `{ url }` — the provider's authorize
+         * page — which a browser app should navigate to (`location.href = url`).
+         * `provider` must be one of the ids returned by `auth.providers()`.
+         */
+        signInSocial: (provider: string, input?: {
+            callbackURL?: string;
+            errorCallbackURL?: string;
+        }) => Promise<{
+            url: string;
+            redirect: boolean;
+        }>;
+        /** Send a one-time sign-in link by email (requires the `magic` provider
+         *  to be enabled for the workspace). */
+        signInMagicLink: (input: {
+            email: string;
+            callbackURL?: string;
+        }) => Promise<{
+            status: boolean;
+        }>;
+        /** Email a one-time numeric code (requires the `email-otp` provider). `type`
+         *  defaults to `"sign-in"`; use `"email-verification"` / `"forget-password"`
+         *  for those flows. Complete a sign-in with `signInEmailOTP`. */
+        sendVerificationOTP: (input: {
+            email: string;
+            type?: "sign-in" | "email-verification" | "forget-password";
+        }) => Promise<{
+            success: boolean;
+        }>;
+        /** Complete an email-OTP sign-in with the code from `sendVerificationOTP`. In
+         *  app mode the returned session token is captured and replayed as a bearer. */
+        signInEmailOTP: (input: {
+            email: string;
+            otp: string;
+        }) => Promise<AuthResult>;
+        /** Send a password-reset email. `redirectTo` is the link the email points at. */
+        requestPasswordReset: (input: {
+            email: string;
+            redirectTo?: string;
+        }) => Promise<{
+            status: boolean;
+        }>;
+        /** Complete a reset with the token from the email and a new password. */
+        resetPassword: (input: {
+            newPassword: string;
+            token: string;
+        }) => Promise<{
+            status: boolean;
+        }>;
+        /** Mint a fresh short-lived access JWT from the stored session token (app
+         *  mode). The SDK's own requests keep using the session token; use this when a
+         *  downstream service needs a proper access token. */
+        refresh: () => Promise<{
+            accessToken: string;
+            refreshToken: string;
+            expiresIn: number;
+            tokenType: string;
+        }>;
+        /** Change the signed-in user's password (requires the current password). */
+        changePassword: (input: {
+            newPassword: string;
+            currentPassword: string;
+            revokeOtherSessions?: boolean;
+        }) => Promise<Record<string, unknown>>;
+        /** Update the signed-in user's profile (e.g. `{ name, image }`). */
+        updateUser: (attributes: Record<string, unknown>) => Promise<Record<string, unknown>>;
+        /** Send an email-verification link to the signed-in (or named) user. */
+        sendVerificationEmail: (input: {
+            email: string;
+            callbackURL?: string;
+        }) => Promise<{
+            status: boolean;
+        }>;
+        signOut: () => Promise<{
+            success: boolean;
+        }>;
+        /** Current session, or `{ user: null }`. */
+        getSession: () => Promise<{
+            user: AuthUser | null;
+        } & Record<string, unknown>>;
+        /** List the signed-in user's active sessions (one row per device/login). */
+        listSessions: () => Promise<AuthSession[]>;
+        /** Revoke one session by its `token` (from `listSessions`). */
+        revokeSession: (input: {
+            token: string;
+        }) => Promise<{
+            status: boolean;
+        }>;
+        /** Revoke every session **except** the current one (sign out other devices). */
+        revokeOtherSessions: () => Promise<{
+            status: boolean;
+        }>;
+        /** Revoke **all** sessions, including the current one. */
+        revokeSessions: () => Promise<{
+            status: boolean;
+        }>;
+        /** Public description of this workspace's auth surface (provider list +
+         *  policy flags) — what a sign-in screen needs to render. No secrets. */
+        providers: () => Promise<AuthSurface>;
+        /** The current workspace session token (app mode) — persist this across
+         *  reloads and pass it back via `createClient({ token })`. */
+        getToken: () => string | null;
+        /** Restore a workspace session token (app mode). */
+        setToken: (token: string | null) => void;
+    };
+    storage: {
+        list: (prefix?: string) => Promise<{
+            data: {
+                key: string;
+                size: number;
+                contentType?: string;
+                ownerId: string | null;
+                uploadedAt: string;
+            }[];
+        }>;
+        put: (key: string, body: BodyInit, contentType?: string, folderId?: string) => Promise<any>;
+        download: (key: string) => Promise<Response>;
+        delete: (key: string) => Promise<{
+            ok: boolean;
+        }>;
+        /**
+         * Resumable upload (TUS 1.0.0). Splits `data` into chunks and PATCHes them
+         * to `/api/uploads`, resuming from the server's committed offset after a
+         * transient failure. `data` may be a `Blob`/`File`, `ArrayBuffer`, or
+         * `Uint8Array`. Returns the final key + the TUS session `location` (persist
+         * it to resume across page reloads via `resumeUpload`). The standard TUS
+         * protocol means Uppy / tus-js-client can also target `/api/uploads`.
+         */
+        uploadResumable: (input: {
+            key: string;
+            data: Blob | ArrayBuffer | Uint8Array;
+            contentType?: string;
+            folderId?: string;
+            /** Bytes per PATCH. Default 8 MiB (object stores need ≥5 MiB non-final parts). */
+            chunkSize?: number;
+            onProgress?: (sent: number, total: number) => void;
+            signal?: AbortSignal;
+        }) => Promise<ResumableUploadResult>;
+        /** Resume a previously-started resumable upload at the server's offset. */
+        resumeUpload: (location: string, data: Blob | ArrayBuffer | Uint8Array, opts2?: {
+            chunkSize?: number;
+            onProgress?: (sent: number, total: number) => void;
+            signal?: AbortSignal;
+        }) => Promise<void>;
+    };
+    messaging: {
+        /** Register (or refresh) the current user's push device. Re-registering the
+         *  same token reactivates it and updates last-seen, so call this on every
+         *  app launch. `web-push` requires `keys` (the VAPID subscription keys). */
+        registerDevice: (input: {
+            platform: "fcm" | "apns" | "web-push";
+            token: string;
+            keys?: {
+                p256dh: string;
+                auth: string;
+            };
+            deviceName?: string;
+        }) => Promise<{
+            data: {
+                id: string;
+            };
+        }>;
+        /** Remove one of the caller's registered devices by id. */
+        unregister: (id: string) => Promise<{
+            ok: boolean;
+        }>;
+        /** List the caller's registered devices. */
+        listDevices: () => Promise<{
+            data: DeviceToken[];
+        }>;
+        /** Register (or refresh) the current user's phone number for SMS. Number
+         *  must be E.164 (e.g. "+14155552671"). Re-registering reactivates it. */
+        registerPhone: (input: {
+            phoneNumber: string;
+        }) => Promise<{
+            data: {
+                id: string;
+            };
+        }>;
+        /** Remove one of the caller's registered phone numbers by id. */
+        unregisterPhone: (id: string) => Promise<{
+            ok: boolean;
+        }>;
+        /** List the caller's registered phone numbers. */
+        listPhones: () => Promise<{
+            data: PhoneNumber[];
+        }>;
+    };
+    jobs: {
+        /** Enqueue a durable background job. `type` is `function` (run a named
+         *  function with `payload.name` + `payload.input`) or `webhook.deliver`.
+         *  Jobs retry with backoff and dead-letter after `maxAttempts`. Pass
+         *  `runAt` (ISO string) to schedule for later. Admin-scoped. */
+        enqueue: (input: {
+            type: "function" | "webhook.deliver";
+            payload?: Record<string, unknown>;
+            queue?: string;
+            runAt?: string;
+            maxAttempts?: number;
+            priority?: number;
+        }) => Promise<{
+            id: string;
+        }>;
+        /** List jobs (newest first), optionally filtered by queue/status. */
+        list: (q?: {
+            queue?: string;
+            status?: JobStatus;
+            limit?: number;
+        }) => Promise<{
+            jobs: Job[];
+        }>;
+        /** Fetch a single job by id. */
+        get: (id: string) => Promise<Job>;
+        /** Requeue a failed / dead-lettered / cancelled job to run again. */
+        retry: (id: string) => Promise<{
+            ok: boolean;
+        }>;
+        /** Cancel a pending job. */
+        cancel: (id: string) => Promise<{
+            ok: boolean;
+        }>;
+        /** Delete a job row. */
+        remove: (id: string) => Promise<{
+            ok: boolean;
+        }>;
+    };
+    flags: {
+        /** Fetch + cache the evaluated flag map. */
+        all: () => Promise<Record<string, FlagState>>;
+        /** Resolved value for a flag (remote config payload), or `undefined`. Uses
+         *  the cache if `all()` was already called this session; pass
+         *  `{ refresh: true }` to force a re-fetch. */
+        get: (key: string, opts?: {
+            refresh?: boolean;
+        }) => Promise<unknown>;
+        /** Whether a flag is on for the caller. */
+        isEnabled: (key: string, opts?: {
+            refresh?: boolean;
+        }) => Promise<boolean>;
+    };
+    sync: (options: SyncOptions) => {
+        pull: () => Promise<number>;
+        flush: () => Promise<void>;
+        live: () => (() => void);
+        start: () => Promise<void>;
+        stop: () => void;
+        getAll: () => Promise<Record<string, unknown>[]>;
+        get: (id: string) => Promise<Record<string, unknown> | undefined>;
+        create: (data: Record<string, unknown>) => Promise<string>;
+        update: (id: string, data: Record<string, unknown>) => Promise<void>;
+        remove: (id: string) => Promise<void>;
+        store: SyncStore;
+    };
+    /** Raw escape hatch — issues a request with auth headers applied. */
+    request: <T>(method: string, path: string, body?: unknown, extraHeaders?: Record<string, string>) => Promise<T>;
+};
+/** A registry mapping each collection slug to its row type — the shape
+ *  `backlex gen-types --sdk` emits as `Collections`. */
+type CollectionsMap = Record<string, Record<string, unknown>>;
+/** `{ [slug]: CollectionClient<Row> }` — the typed `collections` accessor. */
+type TypedCollections<R extends CollectionsMap> = {
+    [K in keyof R]: CollectionClient<R[K]>;
+};
+/** A `BacklexClient` augmented with a strongly-typed `collections` accessor,
+ *  so `db.collections.<slug>.list()` returns `ListResponse<Row>`. */
+type TypedClient<R extends CollectionsMap> = BacklexClient & {
+    collections: TypedCollections<R>;
+};
+/**
+ * Wrap a client with a typed `collections` accessor keyed by collection slug.
+ * Generated SDKs call this with the generated `Collections` registry:
+ *
+ *   export const createTypedClient = (opts: ClientOptions) =>
+ *     typedCollections<Collections>(createClient(opts));
+ *
+ * Access is a thin proxy over `client.from(slug)` — no per-collection runtime
+ * code is generated; all the type information lives in `R`.
+ */
+declare const typedCollections: <R extends CollectionsMap>(client: BacklexClient) => TypedClient<R>;
+
+type BacklexClient = ReturnType<typeof createClient>;
+
+export { AggregateQuery, AggregateRow, type BacklexClient, BatchOperation, BatchResponse, type ClientOptions, type CollectionClient, type CollectionsMap, DeviceToken, type FieldKey, type FilterBuilder, FlagState, ImportSummary, ItemEvent, ItemQuery, ItemResponse, Job, JobStatus, ListQuery, ListResponse, PhoneNumber, QueryBuilder, type QueuedOp, ResumableUploadResult, SearchQuery, SearchResponse, type SortKey, type SyncOptions, type SyncStore, type TypedClient, type TypedCollections, createClient, createSync, indexedDbStore, memoryStore, typedCollections };