@tinycloud/replica 0.2.3-beta.0 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tinycloud/replica",
-  "version": "0.2.3-beta.0",
+  "version": "0.2.3",
   "description": "Durable, read-only local replicas of a TinyCloud KV prefix over the tinycloud.kv/sync change feed.",
   "author": "TinyCloud, Inc.",
   "license": "EGPL",
@@ -45,7 +45,7 @@
   "dependencies": {
     "@noble/curves": "^1.9.2",
     "@noble/hashes": "^1.8.0",
-    "@tinycloud/sdk-services": "3.2.5-beta.0"
+    "@tinycloud/sdk-services": "3.2.5"
   },
   "devDependencies": {
     "@tinycloud/web-sdk-wasm": "1.7.6",

package/dist/browser.d.ts

@@ -1,336 +0,0 @@
-/**
- * Typed replica errors. Every failure a caller can act on has its own code;
- * hosts (CLI, worker) map codes to their own exit codes or UI states.
- */
-declare const ReplicaErrorCode: {
-    /** Another process holds the sync lease. */
-    readonly BUSY: "REPLICA_BUSY";
-    /** No replica with this name exists. */
-    readonly NOT_FOUND: "REPLICA_NOT_FOUND";
-    /** The replica exists but its stored configuration differs from the request. */
-    readonly CONFIG_MISMATCH: "REPLICA_CONFIG_MISMATCH";
-    /** The runtime has no supported durable store (e.g. Node < 22.13). */
-    readonly RUNTIME_UNSUPPORTED: "RUNTIME_UNSUPPORTED";
-    /** A required open() argument is missing or malformed (e.g. `principal`). */
-    readonly INVALID_ARGUMENT: "REPLICA_INVALID_ARGUMENT";
-    /** The local store failed (I/O, corruption, schema). */
-    readonly STORAGE_ERROR: "STORAGE_ERROR";
-    /** The local disk is full. */
-    readonly STORAGE_FULL: "STORAGE_FULL";
-    /** The key is outside the replica's prefix. */
-    readonly NOT_COVERED: "NOT_COVERED";
-    /** Syncing the secrets space or the vault namespace needs an explicit opt-in. */
-    readonly SECRETS_OPT_IN_REQUIRED: "SECRETS_OPT_IN_REQUIRED";
-    /** No grant is installed, or none covers the requested scope. */
-    readonly GRANT_MISSING: "GRANT_MISSING";
-    /** The grant bytes are not a verifiable UCAN, or its signature is wrong. */
-    readonly GRANT_INVALID: "GRANT_INVALID";
-    /** SIWE/CACAO and other non-UCAN grants cannot be used for a replica. */
-    readonly GRANT_FORMAT_UNSUPPORTED: "GRANT_FORMAT_UNSUPPORTED";
-    /** The grant was issued to a different device. */
-    readonly GRANT_AUDIENCE_MISMATCH: "GRANT_AUDIENCE_MISMATCH";
-    /** The grant lacks `tinycloud.kv/sync` or `tinycloud.kv/get` on the prefix. */
-    readonly GRANT_NOT_COVERING: "GRANT_NOT_COVERING";
-    readonly GRANT_NOT_YET_VALID: "GRANT_NOT_YET_VALID";
-    readonly GRANT_EXPIRED: "GRANT_EXPIRED";
-    /** The configured node does not advertise whole-space KV sync support. */
-    readonly REPLICATION_ROOT_UNSUPPORTED: "REPLICATION_ROOT_UNSUPPORTED";
-    readonly GRANT_REVOKED: "GRANT_REVOKED";
-    /** The node refused the invocation for a reason other than revocation. */
-    readonly GRANT_UNAUTHORIZED: "GRANT_UNAUTHORIZED";
-    /** The node refused the retention grant. */
-    readonly RETENTION_GRANT_REFUSED: "RETENTION_GRANT_REFUSED";
-    /** The node could not be reached. */
-    readonly NETWORK_ERROR: "NETWORK_ERROR";
-    /** The node answered with an unexpected status. */
-    readonly NODE_ERROR: "NODE_ERROR";
-    /** The node's answer violates the wire contract. */
-    readonly PROTOCOL_ERROR: "PROTOCOL_ERROR";
-    /** The node asked for a fresh bootstrap (410). Handled inside sync. */
-    readonly RESET_REQUIRED: "RESET_REQUIRED";
-    /** The feed now comes from a different node than the one pinned. */
-    readonly SOURCE_CHANGED: "SOURCE_CHANGED";
-    /** The feed delivered a key outside the replica's prefix. */
-    readonly SCOPE_VIOLATION: "SCOPE_VIOLATION";
-    /** Fetched bytes do not hash to the ETag the node attested for them. */
-    readonly CONTENT_MISMATCH: "CONTENT_MISMATCH";
-    /** A stored blob no longer hashes to its name. */
-    readonly INTEGRITY_ERROR: "INTEGRITY_ERROR";
-    /** The replica handle was closed; in-flight calls settle with this code. */
-    readonly CLOSED: "REPLICA_CLOSED";
-};
-type ReplicaErrorCode = (typeof ReplicaErrorCode)[keyof typeof ReplicaErrorCode];
-/**
- * The package ships separate entry bundles (`.`, `./sqlite`), each with its own
- * copy of this class, so identity is a registered symbol, not `instanceof`.
- */
-declare const REPLICA_ERROR: unique symbol;
-declare class ReplicaError extends Error {
-    readonly [REPLICA_ERROR] = true;
-    readonly code: ReplicaErrorCode;
-    readonly detail?: Record<string, unknown>;
-    constructor(code: ReplicaErrorCode, message: string, detail?: Record<string, unknown>, options?: {
-        cause?: unknown;
-    });
-}
-
-type LocalReadPolicy = "whileGrantValid" | "retainAfterExpiry";
-type Coverage = "empty" | "bootstrapping" | "complete";
-type AuthorityState = "valid" | "expired" | "revoked" | "not-yet-valid";
-type ReplicaLastError = {
-    at: string;
-    code: string;
-    message: string;
-};
-type ReplicaStatus = {
-    name: string;
-    replicaId: string;
-    source: {
-        host: string;
-        nodeDid: string | null;
-        space: string;
-        prefix: string;
-    };
-    device: {
-        did: string;
-        delegationCid: string | null;
-        pendingDelegationCid: string | null;
-        pendingDelegationError: ReplicaLastError | null;
-    };
-    authority: {
-        state: AuthorityState;
-        notBefore: string | null;
-        expiresAt: string | null;
-        retainUntil: string | null;
-        localReadPolicy: LocalReadPolicy;
-        retentionGrantCid: string | null;
-        revokedDetail: string | null;
-        retentionRevokedDetail: string | null;
-    };
-    consistency: "observed";
-    coverage: Coverage;
-    lastSyncAt: string | null;
-    lastCompleteAt: string | null;
-    counts: {
-        keys: number;
-        contentMissing: number;
-        tombstones: number;
-    };
-    bytes: number;
-    durability: string;
-    syncing: boolean;
-    /** A revocation purge has not removed every content file yet; the next open retries it. */
-    purgePending: boolean;
-    lastError: ReplicaLastError | null;
-    lastReset: {
-        at: string;
-        reason: string;
-    } | null;
-};
-
-type SyncReport = {
-    pages: number;
-    changes: number;
-    deleted: number;
-    fetched: number;
-    contentMissing: number;
-    repaired: number;
-    resets: number;
-    coverage: Coverage;
-    cursorAdvanced: boolean;
-    promotedGrant: boolean;
-    blobsCollected: number;
-};
-
-/**
- * The main-thread ↔ worker RPC contract (TC-19). Requests are `{id, op, …}`;
- * replies are `{id, ok:true, result}` or `{id, ok:false, err}`; the worker
- * posts unsolicited `{event}` messages. Values cross as transferable
- * ArrayBuffers, never as broadcast events.
- */
-
-type OpenResult = {
-    replicaId: string;
-    deviceDid: string;
-    /** The verification method (DID fragment form) the app delegates to. */
-    verificationMethod: string;
-    status: ReplicaStatus | null;
-    created: boolean;
-};
-type SyncResult = {
-    status: "synced";
-} & SyncReport | {
-    status: "busy";
-};
-type GetResult = {
-    status: "present";
-    key: string;
-    value: ArrayBuffer;
-    etag: string;
-    metadata: Record<string, string>;
-} | {
-    status: "content_missing";
-    key: string;
-    etag: string;
-    metadata: Record<string, string>;
-} | {
-    status: "deleted" | "absent" | "coverage_incomplete" | "not_covered";
-    key: string;
-};
-type ListResult = {
-    entries: Array<{
-        key: string;
-        etag: string;
-        metadata: Record<string, string>;
-        content: boolean;
-    }>;
-};
-type StatusResult = {
-    status: ReplicaStatus;
-    persistence: {
-        persisted: boolean | null;
-        locksSupported: boolean;
-    };
-};
-
-/**
- * The main-thread browser API (TC-19): a thin RPC client over the replica
- * worker. IndexedDB, the network and the device key live in the worker; the
- * client's local reads never touch the network, and its sync calls are the
- * only path that does.
- *
- * The worker ships as `dist/replica.worker.js`, a self-contained ESM bundle
- * spawned via `new Worker(new URL("./replica.worker.js", import.meta.url),
- * { type: "module" })` — webpack 5 and Vite detect that form. A `worker`
- * option accepts a `Worker` or `URL` escape hatch. In Vite dev mode, list
- * `@tinycloud/replica` in `optimizeDeps.exclude` so the worker URL resolves
- * inside the package (vitejs/vite#20859).
- *
- * Trust boundary: the browser origin, exactly as the OS user is the CLI's.
- * Run one app per origin — any same-origin script can open the IndexedDB
- * databases directly. `principal` (required) is the signed-in user's
- * identity DID; it partitions replicas per user on that origin, it is not
- * an authorization check — the node authorizes at sync time, and local
- * reads are gated by the stored grant's node-attested window, like the CLI.
- */
-
-/**
- * `reset()` result. With `purge: true` the replica's contents are erased in
- * a single commit — the database file itself is never deleted: a small
- * empty database named by a hash remains (holding no user data) and the
- * next `openReplica` reinitializes it in place. Once the commit lands the
- * result is final `{ purged: true }` — nothing after it can change the
- * outcome.
- */
-type ResetResult = {
-    reset: true;
-    purged: boolean;
-};
-type BrowserReplicaOpenOptions = {
-    /** The TinyCloud host to sync from; pinned for the replica's life. */
-    host: string;
-    /** The space id (native form) the replica covers. */
-    space: string;
-    /** The KV prefix: `/` for the whole space, or a folder such as `notes/`. */
-    prefix: string;
-    /** A display name; defaults to the prefix. */
-    name?: string;
-    /**
-     * The signed-in user's identity DID (for example `did:pkh:eip155:1:0x…`),
-     * as the app knows it. Replicas for different principals get different
-     * databases on the same origin; signing in again and installing the new
-     * session's grant continues the same replica from its cursor. This is an
-     * app-asserted partition label, not an authorization check — the trust
-     * boundary is the browser origin, and the node authorizes at sync time.
-     */
-    principal: string;
-    /** Replicating the `secrets` space or a `vault/` prefix needs this opt-in. */
-    allowSecrets?: boolean;
-    /**
-     * Spawn this worker instead of the bundled one (custom bundler layouts).
-     * A factory (`() => Worker`) is also accepted: it runs after `principal`
-     * validation, so a bad open never spawns a worker — useful for tests.
-     */
-    worker?: Worker | URL | string | (() => Worker);
-};
-type BrowserReplicaGetResult = GetResult;
-type BrowserReplicaListResult = ListResult;
-type BrowserReplicaStatus = StatusResult;
-type BrowserReplicaSyncResult = SyncResult;
-type BrowserReplicaOpenResult = OpenResult;
-/** Subscriptions for worker events (other tabs' commits, resets). */
-type BrowserReplicaEvents = {
-    /** Another tab's worker committed a page (`serial` is monotonic). */
-    onCommitted?: (serial: number) => void;
-    /** The replica's authority state changed. */
-    onAuthority?: (state: string) => void;
-    /** The replica was reset in this tab or observed elsewhere. */
-    onReset?: (reason: string) => void;
-};
-/**
- * Open (or create) a replica in a dedicated worker. The first call also asks
- * the browser for durable storage (`navigator.storage.persist()`), so an
- * eviction under pressure is less likely; `status()` reports the outcome.
- * In environments without IndexedDB the returned promise rejects with
- * `RUNTIME_UNSUPPORTED` — there is no in-memory fallback, reads would lose
- * their durability guarantee.
- *
- * `principal` partitions the replica per signed-in user and is required: the
- * same host/space/prefix under two principals yields two databases. A device
- * grant chained to a web session (about one hour under an OpenKey session)
- * gives about that session's length of offline reads; after sign-in rotates
- * the session key, install the new grant and the replica continues from its
- * cursor.
- */
-declare function openReplica(options: BrowserReplicaOpenOptions, events?: BrowserReplicaEvents): Promise<BrowserReplica>;
-declare class BrowserReplica {
-    #private;
-    /** The open() result: replicaId, deviceDid and the status at open time. */
-    opened: OpenResult | null;
-    /** Settles when the worker reports it is listening (or fails to start). */
-    readonly ready: Promise<void>;
-    /** For tests and advanced use: drive an already-spawned worker. */
-    constructor(worker: Worker, events?: BrowserReplicaEvents);
-    /** Open or create the replica; `openReplica` calls this for you. */
-    open(options: BrowserReplicaOpenOptions & {
-        persisted?: boolean;
-    }): Promise<BrowserReplica>;
-    /** The DID the app delegates to (`tcw.delegateTo(deviceDid, […sync…])`). */
-    get deviceDid(): string;
-    /** Install a signed grant: the compact UCAN (`delegation.delegationHeader.Authorization`). */
-    installGrant(delegation: string): Promise<{
-        cid: string;
-        audience: string;
-        expiresAt: number | null;
-    }>;
-    /** Pull the feed and commit each page atomically. `busy` when another tab syncs. */
-    sync(options?: {
-        limit?: number;
-    }): Promise<SyncResult>;
-    /** Local read: never touches the network. */
-    get(key: string): Promise<GetResult>;
-    /** Local read: never touches the network. */
-    list(options?: {
-        prefix?: string;
-        after?: string;
-        limit?: number;
-    }): Promise<ListResult>;
-    /** Replica status plus browser persistence facts. */
-    status(): Promise<StatusResult>;
-    /** Opt in to post-expiry reads under a `tinycloud.kv/retain` grant. */
-    setRetentionGrant(cid: string | null): Promise<{
-        retentionGrantCid: string | null;
-    }>;
-    /**
-     * Clear entries and cursor (keeps config and grant); `purge` erases the
-     * replica permanently in place — the database file is never deleted, so
-     * the result is final the moment it resolves (see {@link ResetResult}).
-     */
-    reset(options?: {
-        purge?: boolean;
-    }): Promise<ResetResult>;
-    /** Close the worker-side handles and terminate the worker. */
-    close(): Promise<void>;
-}
-
-export { BrowserReplica, type BrowserReplicaEvents, type BrowserReplicaGetResult, type BrowserReplicaListResult, type BrowserReplicaOpenOptions, type BrowserReplicaOpenResult, type BrowserReplicaStatus, type BrowserReplicaSyncResult, ReplicaError, ReplicaErrorCode, type ResetResult, openReplica };