@syncular/client 0.1.2 → 0.2.0

package/dist/client.d.ts

@@ -1,78 +1,329 @@
-import type { BlobRef, SyncAuthLeaseIssueRequest } from '@syncular/core';
-import type { SyncularDatabase } from './database';
-import type { MutationsApi } from './mutations';
-import type { SyncularAuthLeaseRecord, SyncularBlobUploadQueueProcessOptions, SyncularBlobUploadQueueStats, SyncularClientEventSink, SyncularClientEventType, SyncularConflictResolution, SyncularConflictStats, SyncularConflictSummary, SyncularConnectionState, SyncularDiagnosticSnapshot, SyncularLifecycleState, SyncularNetworkStatusSource, SyncularOutboxStats, SyncularPresenceEntry, SyncularPresenceSink, SyncularRealtimeOptions, SyncularRuntimeClient, SyncularSubscriptionSpec, SyncularSyncRequestOptions, SyncularSyncResult } from './types';
-export interface SyncularClientLifecycleOptions {
-    initialSync?: boolean;
-    realtime?: boolean | SyncularRealtimeOptions;
-    syncOnRealtimeConnect?: boolean;
-    pollIntervalMs?: number | false;
-    network?: SyncularNetworkStatusSource | false;
-    subscriptions?: readonly SyncularSubscriptionSpec[];
+/**
+ * SyncClient — the B3 client protocol core (SPEC.md §§3–8 client side).
+ *
+ * A plain library running on whatever thread it is constructed on
+ * (worker-OPTIONAL, REVISE B3): storage behind `ClientDatabase`, network
+ * behind `SyncTransport`/`SegmentDownloader`/`RealtimeConnector`, multi-tab
+ * ownership behind `LeaderLock`. One combined push+pull request per
+ * `sync()` round (§7.2); local reads go straight to the database.
+ */
+import { type RowValue, type ScopeMap, type WakeReason } from '@syncular/core';
+import { type BlobRef, type BlobTransport, type CachedBlob } from './blob.js';
+import type { ClientDatabase, SqlRow, SqlValue } from './database.js';
+import type { EncryptionConfig } from './encryption.js';
+import { type InvalidationListener } from './invalidation.js';
+import { type LeaderLock } from './leader-lock.js';
+import { type OutboxCommit, type OutboxOperation } from './outbox.js';
+import { type ClientSchema } from './schema.js';
+import { type SubscriptionRecord } from './state.js';
+import type { RealtimeConnector, SegmentDownloader, SyncTransport } from './transport.js';
+import { type WindowBase } from './window.js';
+export type MutationInput = {
+    readonly table: string;
+    readonly op: 'upsert';
+    /** Full-row values keyed by column name (§6.1: full row payloads). */
+    readonly values: Readonly<Record<string, unknown>>;
+    readonly baseVersion?: number;
+} | {
+    readonly table: string;
+    readonly op: 'delete';
+    readonly rowId: string;
+    readonly baseVersion?: number;
+};
+/** A §6.3 conflict result, surfaced to the app — never auto-resolved. */
+export interface ConflictRecord {
+    readonly clientCommitId: string;
+    readonly opIndex: number;
+    readonly table: string;
+    readonly rowId: string;
+    readonly code: string;
+    readonly message: string;
+    readonly serverVersion: number;
+    /** The current server row, decoded — resolve without a round-trip. */
+    readonly serverRow: Readonly<Record<string, RowValue>>;
+    /** The losing local operation (absent only for malformed op indexes). */
+    readonly operation?: OutboxOperation;
 }
-export interface SyncularClientStatus {
-    lifecycle: SyncularLifecycleState;
-    connection: SyncularConnectionState;
-    outbox: SyncularOutboxStats | null;
-    conflicts: SyncularConflictStats | null;
-    isConnected: boolean;
-    isSyncing: boolean;
-    hasPendingMutations: boolean;
-    hasConflicts: boolean;
-    requiresAction: boolean;
+/** A non-conflict `error` result from a rejected commit (§6.3). */
+export interface RejectionRecord {
+    readonly clientCommitId: string;
+    readonly opIndex: number;
+    readonly code: string;
+    readonly message: string;
+    readonly retryable: boolean;
+    readonly operation?: OutboxOperation;
 }
-export interface SyncularBlobClientLike {
-    getUploadQueueStats(): Promise<SyncularBlobUploadQueueStats>;
-    processUploadQueue(options?: SyncularBlobUploadQueueProcessOptions): Promise<{
-        uploaded: number;
-        failed: number;
-    }>;
-    retrieve(ref: BlobRef): Promise<Uint8Array>;
+export interface SchemaFloor {
+    readonly requiredSchemaVersion?: number;
+    readonly latestSchemaVersion?: number;
 }
-export interface SyncularPresenceClientLike {
-    get<TMetadata = Record<string, unknown>>(scopeKey: string): SyncularPresenceEntry<TMetadata>[];
-    join(scopeKey: string, metadata?: Record<string, unknown>): void;
-    leave(scopeKey: string): void;
-    updateMetadata(scopeKey: string, metadata: Record<string, unknown>): void;
-    onChange<TMetadata = Record<string, unknown>>(listener: SyncularPresenceSink<TMetadata>): () => void;
+/**
+ * §7.3.5: the client's view of its current auth lease — opaque state, the
+ * mirror of `schemaFloor`. `leaseId`/`expiresAtMs` come from the last
+ * `LEASE` frame; `errorCode` is set (and syncing stops on the lease) when
+ * the server rejects a round with a request-level lease code (§7.3.4).
+ * The lease is never cryptographically verified by the client (§7.3
+ * non-goal 1), and lease errors never purge local data (§7.3.4).
+ */
+export interface LeaseState {
+    readonly leaseId?: string;
+    readonly expiresAtMs?: number;
+    /** `sync.auth_lease_required` | `sync.auth_lease_revoked` when stopped. */
+    readonly errorCode?: string;
 }
-export interface SyncularConflictsClientLike {
-    list(): Promise<SyncularConflictSummary[]>;
-    retryKeepLocal(id: string): Promise<string>;
-    resolve(id: string, resolution: SyncularConflictResolution): Promise<void>;
+export interface SyncSummary {
+    /** Commits sent in this round's push half. */
+    readonly pushed: number;
+    /** clientCommitIds drained (`applied` or `cached`, §6.3). */
+    readonly applied: readonly string[];
+    /** clientCommitIds rejected and dropped from the outbox. */
+    readonly rejected: readonly string[];
+    /** clientCommitIds kept for retry (`sync.idempotency_cache_miss`). */
+    readonly retryable: readonly string[];
+    /** New conflict records surfaced this round. */
+    readonly conflicts: readonly ConflictRecord[];
+    /** `COMMIT` frames applied locally. */
+    readonly commitsApplied: number;
+    /** Snapshot rows applied from segments. */
+    readonly segmentRowsApplied: number;
+    /** Subscriptions still mid-bootstrap (resume token pending). */
+    readonly bootstrapping: readonly string[];
+    /** Subscriptions reset via `sync.cursor_expired` (re-pull needed). */
+    readonly resets: readonly string[];
+    /** Subscriptions revoked this round (§3.3 purge ran). */
+    readonly revoked: readonly string[];
+    /** Subscriptions stopped by a fatal configuration error (§3.3/§5.6
+     * fail-closed: no local scope-column mapping). */
+    readonly failed: readonly string[];
+    /** Present when the server declared a schema floor — syncing stopped. */
+    readonly schemaFloor?: SchemaFloor;
+    /** §6.1 splitBatch: outbox commits held back from THIS request because
+     * including them would exceed the per-request operation cap. They remain
+     * queued; sync-needed stays raised and `syncUntilIdle` keeps going. */
+    readonly deferredCommits?: number;
 }
-export interface SyncularClientLike<DB> {
-    db: SyncularDatabase<DB>['db'];
-    dialect?: SyncularDatabase<DB>['dialect'] | unknown;
-    mutations: MutationsApi<DB, any>;
-    leasedMutations: MutationsApi<DB, any>;
-    blobs: SyncularBlobClientLike;
-    on<T extends SyncularClientEventType>(event: T, listener: SyncularClientEventSink<T>): () => void;
-    getStatus(): SyncularClientStatus;
-    setSubscriptions(subscriptions: readonly SyncularSubscriptionSpec[]): Promise<void>;
-    resumeFromBackground(options?: SyncularSyncRequestOptions): Promise<SyncularSyncResult>;
-    issueAuthLease(request: SyncAuthLeaseIssueRequest): Promise<SyncularAuthLeaseRecord>;
-    upsertAuthLease(lease: SyncularAuthLeaseRecord): Promise<void>;
-    authLease(leaseId: string): Promise<SyncularAuthLeaseRecord | null>;
-    activeAuthLeases(actorId?: string | null, nowMs?: number): Promise<SyncularAuthLeaseRecord[]>;
-    diagnosticSnapshot(): Promise<SyncularDiagnosticSnapshot>;
-    presence: SyncularPresenceClientLike;
-    conflicts: SyncularConflictsClientLike;
-    start(): Promise<void>;
-    stop(): Promise<void>;
-    sync(): Promise<SyncularSyncResult>;
-    close(): Promise<void>;
+export interface SyncClientLimits {
+    readonly limitCommits?: number;
+    readonly limitSnapshotRows?: number;
+    readonly maxSnapshotPages?: number;
+    /**
+     * §4.2 accept bitmask; defaults to inline + external rows (0b0011)
+     * plus sqlite images (bit 2) when the database backend implements
+     * `withSqliteImage` and a segment downloader is configured (§5.3).
+     */
+    readonly accept?: number;
+}
+export interface SyncClientConfig {
+    readonly database: ClientDatabase;
+    readonly schema: ClientSchema;
+    readonly transport: SyncTransport;
+    readonly segments?: SegmentDownloader;
+    /** Blob upload/download (§5.9). Required to use `uploadBlob`/`fetchBlob`. */
+    readonly blobs?: BlobTransport;
+    /**
+     * §5.9.7 B1 blob-cache size cap (bytes). When the sum of cached body sizes
+     * exceeds this, zero-ref, non-pinned bodies are evicted LRU-first after each
+     * cache write (referenced/pinned bodies are never evicted — correctness
+     * beats the cap). Absent ⇒ retain until storage pressure (the shipped
+     * default; a referenced body always stays resolvable without a re-download).
+     */
+    readonly blobCacheMaxBytes?: number;
+    readonly realtime?: RealtimeConnector;
+    /** Stable per-device id (§1.5); defaults to a persisted random UUID. */
+    readonly clientId?: string;
+    readonly leaderLock?: LeaderLock;
+    readonly lockName?: string;
+    readonly limits?: SyncClientLimits;
+    readonly now?: () => number;
+    /** §8: hello `requiresSync` or a wake-up — run a pull soon. */
+    readonly onSyncNeeded?: (reason: 'hello' | WakeReason) => void;
+    readonly onConflict?: (conflict: ConflictRecord) => void;
+    /**
+     * §7.4.5: the schema-bump `upgrading` state changed. `true` when a reset
+     * (wipe + re-bootstrap) began, `false` when the first post-reset
+     * bootstrap round reached idle — the app's cue to re-run live queries.
+     */
+    readonly onUpgrading?: (upgrading: boolean) => void;
+    /**
+     * §8.6 presence: a scope-mate's presence on a key this client holds
+     * changed (join/update/leave). Fired after the local presence map is
+     * updated — the app's cue to re-render who's-online.
+     */
+    readonly onPresence?: (scopeKey: string) => void;
+    /**
+     * §5.11 client-side encryption. Supplies the key material (`keyProvider`)
+     * and key selection (`keyIdFor`) for columns the generated schema marks
+     * `encrypted`. Absent ⇒ no columns are encrypted (a schema with encrypted
+     * columns then fails loud on the first encode/apply — a missing key is
+     * `client.decrypt_failed`, never silent plaintext).
+     */
+    readonly encryption?: EncryptionConfig;
+}
+/** §8.6 a peer's ephemeral presence document on a scope key. */
+export interface PresencePeer {
+    readonly actorId: string;
+    readonly clientId: string;
+    readonly doc: Record<string, unknown>;
 }
-type LifecycleClient = Pick<SyncularRuntimeClient, 'addDiagnosticListener' | 'connectionState' | 'forceSubscriptionsBootstrap' | 'setSubscriptions' | 'startRealtime' | 'stopRealtime' | 'syncOnce'>;
-export declare function getSyncularClientStatus(client: Pick<SyncularRuntimeClient, 'connectionState' | 'lifecycleState'>): SyncularClientStatus;
-export declare class SyncularClientLifecycle {
+export interface SubscribeInput {
+    readonly id: string;
+    readonly table: string;
+    readonly scopes: ScopeMap;
+    readonly params?: string;
+}
+/**
+ * The live state of a window base (§4.8) — the completeness oracle (I3),
+ * as plain serializable data so it crosses the worker/follower boundary
+ * unchanged. `units` are the scope values currently windowed-in; a query
+ * touching only these is answerable in full locally. Use
+ * {@link windowComplete} for the per-value verdict a live query renders
+ * "this data may be partial" from.
+ */
+export interface WindowState {
+    /** Windowed-in units for this base, ordered by value. */
+    readonly units: readonly string[];
+}
+/** True iff `unit` is windowed-in for this snapshot (a registry hit, I3). */
+export declare function windowComplete(state: WindowState, unit: string): boolean;
+export declare class SyncClient {
     #private;
-    private readonly client;
-    private readonly options;
-    constructor(client: LifecycleClient, options?: SyncularClientLifecycleOptions);
+    constructor(config: SyncClientConfig);
+    /** Acquire leadership, create local tables, resolve the clientId. */
     start(): Promise<void>;
-    stop(): Promise<void>;
-    sync(): Promise<SyncularSyncResult>;
+    close(): Promise<void>;
+    get clientId(): string;
+    /** The underlying database — raw SQL is the local query API (B3). */
+    get database(): ClientDatabase;
+    query(sql: string, params?: readonly SqlValue[]): SqlRow[];
+    /**
+     * Subscribe to fine-grained invalidation. The callback fires ONCE per
+     * apply batch (never per row, I1) with the `{tables, scopeKeys}` touched
+     * this batch (§3.1 vocabulary, I2). Returns an unsubscribe function.
+     *
+     * Every local mutation flows through the same choke point: `COMMIT`
+     * apply, segment apply, the optimistic overlay rebuild, the §3.3 purge,
+     * the §7.4.3 schema-bump reset, and local `mutate`. `tables` is the
+     * reliable floor; `scopeKeys` refines it wherever the source carried
+     * per-row scopes (COMMIT changes) or a scope map (segments/purge).
+     */
+    onInvalidate(listener: InvalidationListener): () => void;
+    /**
+     * Stage a blob for attachment (§5.9.7): hash the bytes into the content
+     * address, cache them locally, and queue the upload (flushed before the
+     * next push — B4). Returns the canonical `BlobRef` **string** to store in
+     * a `blob_ref` column of a mutation. The referencing row MUST be written
+     * (via `mutate`) after this call so upload-before-push holds (§5.9.3).
+     */
+    uploadBlob(bytes: Uint8Array, options?: {
+        readonly mediaType?: string;
+        readonly name?: string;
+    }): Promise<BlobRef>;
+    /** Serialize a BlobRef to the canonical string a `blob_ref` column holds. */
+    blobRefString(ref: BlobRef): string;
+    /**
+     * Resolve blob bytes for a `blobId` (§5.9.7): a content-addressed cache
+     * hit serves without a network fetch (B1); a miss downloads via the blob
+     * transport (§5.9.5), verifies the content address, caches, and returns.
+     * Accepts a raw `blob_ref` column string or a bare `blobId`.
+     */
+    fetchBlob(blobIdOrRef: string): Promise<CachedBlob>;
+    /** Flush any queued blob uploads (§5.9.7 B4); safe to call standalone. */
+    flushBlobUploads(): Promise<void>;
+    get conflicts(): readonly ConflictRecord[];
+    get rejections(): readonly RejectionRecord[];
+    /** Non-undefined once the server declared a schema floor (§1.6). */
+    get schemaFloor(): SchemaFloor | undefined;
+    /**
+     * §7.4.5: true while a schema-bump reset + first re-bootstrap is in
+     * flight — the app's "upgrading…" cue. Clears when the first post-reset
+     * bootstrap round reaches idle (every subscription past its fresh
+     * bootstrap).
+     */
+    get upgrading(): boolean;
+    /**
+     * §7.3.5: the current auth-lease state (opaque). Undefined until a
+     * `LEASE` frame arrives. `errorCode` is set when a round was rejected
+     * with a request-level lease code — syncing on the lease has stopped.
+     */
+    get leaseState(): LeaseState | undefined;
+    /** §7.3.5: remaining lease validity in ms (`expiresAtMs − now`), or
+     * `undefined` if no lease is held. Negative once expired. */
+    leaseRemainingMs(now?: number): number | undefined;
+    /** True when syncing is stopped pending a client upgrade. */
+    get stopped(): boolean;
+    /** §8: a hello/wake-up asked for a pull that has not run yet. */
+    get syncNeeded(): boolean;
+    /**
+     * §8.6 presence on a scope key: the current peers present there (a map
+     * of `actorId clientId` → peer). Empty for a key with no present peers.
+     * Ephemeral — reflects only what the socket has delivered.
+     */
+    presence(scopeKey: string): readonly PresencePeer[];
+    /** Every scope key this client currently has presence state for. */
+    presenceKeys(): string[];
+    /**
+     * §8.6: subscribe to presence changes (join/update/leave on any held key).
+     * The subscribable twin of the `onPresence` config callback — React's
+     * `usePresence` targets this so many components can watch one client.
+     * Returns an unsubscribe function.
+     */
+    onPresence(listener: (scopeKey: string) => void): () => void;
+    /**
+     * §8.6.2 publish (or clear, `doc: null`) this client's presence document
+     * for `scopeKey`. Requires a live socket; the document is ephemeral and
+     * lost on disconnect (the server emits leave). Authorization is the
+     * connection's registration (§8.6.3) — an unheld key is rejected loudly
+     * by the server with `presence.forbidden`.
+     */
+    setPresence(scopeKey: string, doc: Record<string, unknown> | null): void;
+    subscriptions(): SubscriptionRecord[];
+    subscription(id: string): SubscriptionRecord | undefined;
+    pendingCommits(): OutboxCommit[];
+    subscribe(input: SubscribeInput): void;
+    unsubscribe(id: string): void;
+    /**
+     * Set the live window units for a base (§4.8): a value-sharded family of
+     * subscriptions, one per unit. Computes the diff against the registry —
+     * added units get fresh subscriptions (image-lane bootstrap on the next
+     * sync); removed units are unsubscribed and evicted, fused in one local
+     * transaction (E1–E4). Idempotent: calling with the same units is a
+     * no-op. Re-entry (a unit removed then re-added) cancels any deferred
+     * eviction and fresh-bootstraps.
+     *
+     * The change takes effect on the next `sync()`/socket round — the pull's
+     * subscription list (now with the added unit, without the removed one)
+     * re-registers realtime at round end (§8.7). No socket cycle needed.
+     */
+    setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
+    /**
+     * The completeness oracle (§4.8 I3): which units of a base are windowed-in
+     * locally, and a per-unit verdict a live query renders "may be partial"
+     * from. A query whose scope footprint includes an un-windowed unit is
+     * NOT answerable in full — the host widens or shows partial, never
+     * silently-complete.
+     */
+    windowState(base: WindowBase): WindowState;
+    /**
+     * Record one atomic local commit (§7.1): appended to the outbox in
+     * schema-agnostic form and applied optimistically to the local mirror.
+     * Returns the generated `clientCommitId`.
+     */
+    mutate(mutations: readonly MutationInput[]): string;
+    /**
+     * One combined push+pull round (§1.5, §7.2). The core owns one loop: a
+     * concurrent `sync()` while one is already outstanding is rejected loudly
+     * (the app must coalesce its own wake-ups, §8.4) — this check is
+     * SYNCHRONOUS so the second caller sees the first still in flight before
+     * the op chain would otherwise queue it. The round then runs serialized on
+     * the operation chain so it never interleaves with a delta apply or a
+     * `setWindow` at an await point.
+     */
+    sync(): Promise<SyncSummary>;
+    /**
+     * Pull repeatedly until quiescent: no commits delivered, no bootstrap
+     * pages pending, no resets to recover (§4.5 "pull again" SHOULD).
+     */
+    syncUntilIdle(maxRounds?: number): Promise<SyncSummary>;
+    connectRealtime(): Promise<void>;
+    disconnectRealtime(): void;
 }
-export {};
-//# sourceMappingURL=client.d.ts.map