selfstore 1.8.24 → 1.8.26

package/dist/simple-GdtB5IrG.d.ts

@@ -0,0 +1,267 @@
+import { a as Snapshot, b as PasswordPolicy, c as SnapshotFile, B as BackupTarget, d as StatusDescriptor, S as StoreError, e as LocalStoreState, L as LocalStore } from './store-CKGrIFQU.js';
+import { L as LocalCache, K as KV } from './cache-ilsK3Tki.js';
+import { SyncConfig } from './sync.js';
+import { R as ResumeOffer, C as ConnectTargets } from './connect-DoB_DN__.js';
+import { f as BackupsManager } from './manager-yCM0M0FL.js';
+import { a as DriveAuth } from './drive--mndByvF.js';
+import { W as WebdavConfig, S as S3Config } from './s3-dG1SCnV1.js';
+
+/** What a file body may be handed in as. */
+type FileBytes = Uint8Array | ArrayBuffer | Blob;
+
+/** A record as the simple store sees it: plain JSON with a string id (the id
+ *  field name can be remapped per collection via `sync.ids`). */
+type SimpleRecord = Record<string, unknown>;
+
+/** A file on its way into the store. Omit `id` to get the content hash, which
+ *  is the id that makes the multi-device union safe - see `putFile`. */
+interface PutFileInput {
+    /** Defaults to the SHA-256 of the bytes. */
+    id?: string;
+    /** Defaults to the id. Cosmetic: nothing keys on it. */
+    name?: string;
+    /** Defaults to 'application/octet-stream'. */
+    mime?: string;
+    bytes: FileBytes;
+}
+/** Unlock callback for the ultra-sensitive cacheLock mode: return the session
+ *  secret - a password (Argon2id-derived) or an app-provided key (e.g. a passkey
+ *  PRF result). Called at boot; called again with { failed: true } after a wrong
+ *  secret so the app can re-prompt. Throw to abort the boot (user cancelled). */
+type CacheUnlock = (attempt: {
+    failed: boolean;
+}) => Promise<string | CryptoKey>;
+/** Options - every one of them optional, the defaults carry a real app. */
+interface SimpleOptions {
+    /** Your DATA schema version (default 1). Bump it together with `migrate`. */
+    schema?: number;
+    /** Upgrade a snapshot written by an older schema version. */
+    migrate?: (fromVersion: number, snap: Snapshot) => Snapshot;
+    /** Per-collection merge tuning (id field mapping, strategies). The default -
+     *  records keyed by `id`, later edit wins, deletes propagate - fits most apps. */
+    sync?: SyncConfig;
+    /**
+     * Google Drive, when this app uses it. Two shapes for two situations:
+     *
+     * `{ clientId }` is the whole wiring - the library builds the browser
+     * connection, keeps ONE session for the app (several would mean several
+     * consent screens), reuses its token across a reload, remembers which
+     * account holds the backup and hands that back to Google so the chooser
+     * stops appearing. Nothing else to write.
+     *
+     * A `DriveAuth` instead, for an app that gets its tokens elsewhere - a
+     * server broker holding a refresh token, a native shell.
+     *
+     * Either way, providing it here is also what lets a connected Drive backup
+     * restore itself on the next start.
+     */
+    drive?: DriveAuth | {
+        clientId: string;
+        scope?: string;
+    };
+    /** Where the working copy lives (default: IndexedDB named after the app;
+     *  in-memory when IndexedDB does not exist, e.g. tests or SSR). */
+    cache?: LocalCache;
+    /** Auto-save debounce in ms. */
+    debounceMs?: number;
+    /** Cross-tab coordination (default on in browsers). */
+    multiTab?: boolean;
+    /** Refuse to ever write or export a plaintext backup: connecting a
+     *  destination then demands a password (or a group). Off by default. */
+    requireEncryption?: boolean;
+    /** Reject a backup password weaker than this policy (length, character
+     *  classes) at protect()/addKey time. Preview the rules with
+     *  checkPasswordPolicy for a live UI hint. Omit for no policy. */
+    passwordPolicy?: PasswordPolicy;
+    /** Ultra-sensitive mode: seal the local cache under a key derived from a
+     *  secret held in memory (this callback), never on disk - so a copy of the
+     *  browser profile cannot read it. One unlock per session; branch it on the
+     *  app's existing login to leave the UX unchanged. Browser (IndexedDB) only. */
+    cacheLock?: CacheUnlock;
+    /** Wire tab focus / network return / interval / tab hide automatically
+     *  (default true in browsers). Pass false to drive syncing yourself. */
+    autoSync?: boolean;
+}
+/** What connecting a destination did. 'merged': it already held a backup and
+ *  both sides were folded together. 'started': it was empty, this device's data
+ *  is now its content. 'manual': non-Chromium file fallback - offer
+ *  downloadBackup() instead. 'cancelled': the user closed the picker/consent. */
+type ConnectOutcome = 'merged' | 'started' | 'manual' | 'cancelled';
+interface SimpleStore<S extends Record<string, SimpleRecord> = Record<string, SimpleRecord>> {
+    /** Every record of a collection (treat as read-only; write via put/remove). */
+    all<K extends keyof S & string>(collection: K): readonly S[K][];
+    /** One record by id, or undefined. */
+    get<K extends keyof S & string>(collection: K, id: string): S[K] | undefined;
+    /** Insert or replace one record (auto-saves, debounced). Throws a TypeError
+     *  when the record has no non-empty string id. */
+    put<K extends keyof S & string>(collection: K, record: S[K]): Promise<void>;
+    /** Insert or replace many records in one save. */
+    putAll<K extends keyof S & string>(collection: K, records: S[K][]): Promise<void>;
+    /** Delete one record by id (propagates to other devices). Unknown id: no-op. */
+    remove<K extends keyof S & string>(collection: K, id: string): Promise<void>;
+    /** Empty a collection (every removal propagates). */
+    clear<K extends keyof S & string>(collection: K): Promise<void>;
+    /** Called after any data change: your writes, another tab, another device,
+     *  a restore. Returns an unsubscribe. */
+    onChange(fn: () => void): () => void;
+    /** Every file (treat as read-only; write via putFile/removeFile). */
+    allFiles(): readonly SnapshotFile[];
+    /** One file by id, or undefined. */
+    getFile(id: string): SnapshotFile | undefined;
+    /**
+     * Store bytes alongside the collections and return the file's id.
+     *
+     * Files are **immutable per id**. The multi-device merge unions them by id
+     * and has no clock to order two bodies, so when two devices hold DIFFERENT
+     * bytes under one id, one is kept and the other is dropped - with no
+     * conflict reported, because at that level there is nothing to compare.
+     *
+     * Hence the default id: the SHA-256 of the bytes. Different bytes land on
+     * different ids and the union keeps both, which is what makes a CRDT
+     * document (Yjs, Automerge) safe to carry here - store its UPDATES, let the
+     * union collect them, fold them at load. Tie a file's lifetime to a record
+     * so deleting the record tells you which files to remove.
+     *
+     * Naming the id yourself puts that rule in your hands: identical bytes
+     * under an existing id are a no-op, different bytes are refused with a
+     * TypeError. `{ replace: true }` does it anyway - right for a body only
+     * ever written on one device (a thumbnail, a rendered export), a silent
+     * loser as soon as two devices write it.
+     */
+    putFile(file: PutFileInput, opts?: {
+        replace?: boolean;
+    }): Promise<string>;
+    /** Delete one file by id (propagates to other devices). Unknown id: no-op. */
+    removeFile(id: string): Promise<void>;
+    /** Connect Google Drive as the durable home. An existing backup there is
+     *  MERGED with this device (multi-device); an encrypted one needs its
+     *  password up front (PASSWORD_REQUIRED is thrown before anything changes). */
+    connectDrive(auth: DriveAuth, opts?: {
+        password?: string;
+    }): Promise<ConnectOutcome>;
+    /** Connect a disk file (File System Access; falls back to manual download). */
+    connectFile(opts?: {
+        password?: string;
+    }): Promise<ConnectOutcome>;
+    /** Connect a WebDAV server (Nextcloud, ownCloud, your own). */
+    connectWebdav(config: WebdavConfig, opts?: {
+        password?: string;
+    }): Promise<ConnectOutcome>;
+    /** Connect an S3-compatible bucket you control (Amazon S3, R2, B2, MinIO). */
+    connectS3(config: S3Config, opts?: {
+        password?: string;
+    }): Promise<ConnectOutcome>;
+    /** Connect any custom BackupTarget with the same merge semantics. */
+    connectTarget(target: BackupTarget, opts?: {
+        password?: string;
+    }): Promise<ConnectOutcome>;
+    /** Back to device-only (the destination keeps its last backup). */
+    disconnect(): Promise<void>;
+    /** Also write the same encrypted backup to this second destination on
+     *  every save. A broken copy never gates the store (state.replicas). */
+    addReplica(target: BackupTarget, opts?: {
+        id?: string;
+    }): string;
+    /** Stop writing the copy (the destination keeps its last backup). */
+    removeReplica(id: string): void;
+    /** Encrypt the durable backup end to end with this password (reversible). */
+    protect(password: string): Promise<void>;
+    /** Remove the backup password. */
+    unprotect(): Promise<void>;
+    /** status.action === 'unlock': supply the password to resume. */
+    unlock(password: string): Promise<boolean>;
+    /** status.action === 'reconnect': re-run the destination's auth gesture. */
+    reconnect(): Promise<boolean>;
+    /** The portable backup file (a real ZIP; encrypted when protect() is on).
+     *
+     *  `{ plaintext: true }` asks for a READABLE copy of a protected store: the
+     *  same ZIP with `selfstore.json` in the clear, which any tool can open and
+     *  git can diff. It is the answer to "can I actually get my data out", and
+     *  it costs nothing: the store, its password and its destination are
+     *  untouched, so the real backup stays encrypted. Before this, the only way
+     *  out was `unprotect()`, which rewrites the destination and leaves it
+     *  readable until you remember to undo it.
+     *
+     *  Refused while locked (there is nothing readable to write), and refused on
+     *  a store created with `requireEncryption` - that flag means this store
+     *  never produces cleartext, and an escape hatch would make it a lie. */
+    exportBackup(opts?: {
+        plaintext?: boolean;
+    }): Promise<Blob>;
+    /** Download the backup (also resolves the 'manual' file mode's pending flag).
+     *  False when the user closed the save dialog: nothing was written, the
+     *  pending flag stands, and the app must not record a backup. */
+    downloadBackup(filename?: string): Promise<boolean>;
+    /** Load a backup file into this store, replacing the local data (removals
+     *  propagate like edits). Throws PASSWORD_REQUIRED / DECRYPT_FAILED. */
+    importBackup(file: Blob | Uint8Array, opts?: {
+        password?: string;
+    }): Promise<void>;
+    /** Headless status: { state, severity, action, labelKey } - map labelKey to
+     *  your own copy. */
+    readonly status: StatusDescriptor;
+    /** The last problem: { code, labelKey, message } - show labelKey, log message. */
+    readonly error: StoreError | null;
+    /** The full underlying state (advanced reads: journal, peers, mode...). */
+    readonly state: LocalStoreState;
+    /** Fires on any state change (status flips included) - for framework bindings. */
+    subscribe(fn: () => void): () => void;
+    /** Save now (called for you on tab hide when autoSync is on). */
+    flush(): Promise<void>;
+    /** Converge with the destination now (a user gesture like pull-to-refresh). */
+    sync(): Promise<void>;
+    /** Drop timers and listeners (tests, SPA teardown). */
+    dispose(): void;
+    /** The escape hatch: the full advanced store this simple one is built on -
+     *  peers, groups, custom strategies, everything (see selfstore/advanced). */
+    readonly advanced: LocalStore;
+    /** The attachment point for 'selfstore/flows': the engine plus the cache KV
+     *  and backup file name a flow needs to build destination targets. Apps on
+     *  the advanced store hand a flow the same three by themselves. */
+    readonly flowHost: {
+        engine: LocalStore;
+        kv: KV;
+        backupName: string;
+    };
+    /** Who holds the destination, when it is known - the Google address behind a
+     *  Drive backup. Learned on connect and remembered across sessions, so a
+     *  surface can NAME the destination ("Google Drive" is not an address) and a
+     *  re-grant can skip the account chooser. Null for a file, or before a first
+     *  connect. Reading it costs nothing: no call goes out. */
+    readonly account: string | null;
+    /** The destination this device already used, ready to hand to a connect flow
+     *  as `options.resume` - so a returning visitor is offered "reopen my backup"
+     *  ahead of the plain destinations, instead of re-deriving a decision the
+     *  library already has on file. Null when there is nothing to resume. */
+    resumeOffer(): ResumeOffer | null;
+    /**
+     * The several-backups manager for this store's destination, or null when
+     * there is nothing to manage several of (no Drive configured).
+     *
+     * The port under it - list, open by id, create, rename, delete - was the last
+     * thing an app still assembled from the session the store had built, and the
+     * one place it could pick the wrong file id. Built once and remembered; the
+     * backups module is imported on demand, so an app that never asks does not
+     * carry it.
+     */
+    backups(): Promise<BackupsManager | null>;
+    /**
+     * The destinations this store can offer, ready for a connect flow or widget:
+     * Drive first when the app configured it, a file always.
+     *
+     * Consumers were assembling this by hand from the very session the store
+     * built - and the order and the "no client id means no Drive card" rule were
+     * rediscovered each time. An app wanting a different offer (a WebDAV server,
+     * its own target) still writes its own object; this is the default, not a
+     * ceiling.
+     */
+    destinations(): ConnectTargets;
+}
+/**
+ * Open (or create) the app's local store. Awaits the initial load, so the
+ * returned store is ready: data readable, destination restored, first converge
+ * done. See SimpleOptions for the defaults.
+ */
+declare function selfstore<S extends Record<string, SimpleRecord> = Record<string, SimpleRecord>>(app: string, options?: SimpleOptions): Promise<SimpleStore<S>>;
+
+export { type CacheUnlock as C, type FileBytes as F, type PutFileInput as P, type SimpleRecord as S, type ConnectOutcome as a, type SimpleOptions as b, type SimpleStore as c, selfstore as s };

package/dist/{store-CIbiNoiE.d.ts → store-CKGrIFQU.d.ts}

@@ -149,7 +149,7 @@ interface EncodeOptions {
     extraSecrets?: string[];
 }
 
-type SelfstoreErrorCode = 'BAD_FORMAT' | 'UNSUPPORTED_VERSION' | 'PASSWORD_REQUIRED' | 'DECRYPT_FAILED' | 'TOO_LARGE' | 'VERIFY_FAILED' | 'FOREIGN_BACKUP' | 'AUTH_EXPIRED' | 'TARGET_UNAVAILABLE' | 'TARGET_WRITE_FAILED' | 'TARGET_GONE' | 'NOT_CONNECTED' | 'WEAK_PASSWORD' | 'ENCRYPTION_REQUIRED' | 'UNEXPECTEDLY_UNENCRYPTED' | 'SCHEMA_TOO_NEW' | 'IDENTITY_REQUIRED' | 'SIGNATURE_INVALID' | 'NOT_A_RECIPIENT' | 'MANIFEST_ROLLBACK' | 'CLOCK_DRIFT';
+type SelfstoreErrorCode = 'BAD_FORMAT' | 'UNSUPPORTED_VERSION' | 'PASSWORD_REQUIRED' | 'DECRYPT_FAILED' | 'TOO_LARGE' | 'VERIFY_FAILED' | 'FOREIGN_BACKUP' | 'AUTH_EXPIRED' | 'TARGET_UNAVAILABLE' | 'TARGET_WRITE_FAILED' | 'TARGET_GONE' | 'NOT_CONNECTED' | 'WEAK_PASSWORD' | 'ENCRYPTION_REQUIRED' | 'UNEXPECTEDLY_UNENCRYPTED' | 'SCHEMA_TOO_NEW' | 'IDENTITY_REQUIRED' | 'SIGNATURE_INVALID' | 'NOT_A_RECIPIENT' | 'MANIFEST_ROLLBACK' | 'CLOCK_DRIFT' | 'NOTARY_UNAVAILABLE' | 'NOTARY_REFUSED';
 /**
  * i18n key for an error code: lower-camel-cased under `error.`, e.g.
  * 'error.authExpired'. The library ships the key, the app owns the copy;
@@ -627,4 +627,4 @@ interface LocalStore {
 }
 declare function createLocalStore(opts: LocalStoreOptions): LocalStore;
 
-export { AuthExpiredError as A, type BackupTarget as B, errorLabelKey as C, isAuthExpired as D, type EncodeOptions as E, isReservedStoreMode as F, isSelfstoreError as G, type Header as H, type KdfParams as K, type LocalStore as L, type MirrorState as M, type PeerSource as P, RESERVED_COLLECTION_PREFIX as R, type StoreError as S, type TargetKind as T, type BuiltinTargetKind as a, type LocalStoreOptions as b, type LocalStoreState as c, type Mode as d, type PasswordCheck as e, type PasswordPolicy as f, type PasswordRequirement as g, type PeerState as h, RESERVED_STORE_MODES as i, type RecipientStanza as j, type ReplicaState as k, SelfstoreError as l, type SelfstoreErrorCode as m, type Severity as n, type Snapshot as o, type SnapshotFile as p, type StatusAction as q, type StatusDescriptor as r, type StatusInput as s, type StorageState as t, type StoreGroupConfig as u, type SyncJournalEntry as v, type SyncSource as w, checkPasswordPolicy as x, createLocalStore as y, deriveStatus as z };
+export { AuthExpiredError as A, type BackupTarget as B, errorLabelKey as C, isAuthExpired as D, type EncodeOptions as E, isReservedStoreMode as F, isSelfstoreError as G, type Header as H, type KdfParams as K, type LocalStore as L, type MirrorState as M, type PeerSource as P, RESERVED_COLLECTION_PREFIX as R, type StoreError as S, type TargetKind as T, type Snapshot as a, type PasswordPolicy as b, type SnapshotFile as c, type StatusDescriptor as d, type LocalStoreState as e, type BuiltinTargetKind as f, type LocalStoreOptions as g, type Mode as h, type PasswordCheck as i, type PasswordRequirement as j, type PeerState as k, RESERVED_STORE_MODES as l, type RecipientStanza as m, type ReplicaState as n, SelfstoreError as o, type SelfstoreErrorCode as p, type Severity as q, type StatusAction as r, type StatusInput as s, type StorageState as t, type StoreGroupConfig as u, type SyncJournalEntry as v, type SyncSource as w, checkPasswordPolicy as x, createLocalStore as y, deriveStatus as z };

package/dist/sync.js

@@ -1,5 +1,5 @@
-export { changes, createMeta, createNode, detectConflicts, merge, stamp } from './chunk-23UAUYSW.js';
+export { changes, createMeta, createNode, detectConflicts, merge, stamp } from './chunk-GSZSZGSD.js';
 import './chunk-FJGWTBAL.js';
-import './chunk-XMC67RNM.js';
+import './chunk-CSYEIXNY.js';
 //# sourceMappingURL=sync.js.map
 //# sourceMappingURL=sync.js.map

package/dist/webdav-5SHNR7CL.js

@@ -0,0 +1,10 @@
+export { connect, fromSession, peer } from './chunk-GHSHIDF3.js';
+import './chunk-LF3CC2P3.js';
+import './chunk-RVOBONZF.js';
+import './chunk-QBCU7OOP.js';
+import './chunk-F4ZZEJ5H.js';
+import './chunk-5UYPKCDB.js';
+import './chunk-WXI2NAPA.js';
+import './chunk-CSYEIXNY.js';
+//# sourceMappingURL=webdav-5SHNR7CL.js.map
+//# sourceMappingURL=webdav-5SHNR7CL.js.map

package/dist/{webdav-EEQKX5TZ.js.map → webdav-5SHNR7CL.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"webdav-EEQKX5TZ.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"webdav-5SHNR7CL.js"}

package/dist/widgets.d.ts

@@ -1,11 +1,11 @@
-import { S as StoreLike, F as FlowHost, C as ConnectTargets, a as ConnectFlowOptions, b as ConnectKind, c as ConnectFlow } from './connect-Bob2mofK.js';
+import { S as StoreLike, F as FlowHost, C as ConnectTargets, a as ConnectFlowOptions, b as ConnectKind, c as ConnectFlow } from './connect-DoB_DN__.js';
 import { ShareEngine, ShareLevel, ShareFlow, JoinEngine, JoinFlow, ReplicaFlow } from './flows.js';
-import { f as BackupsManager } from './manager-Di6lNE4E.js';
-import './store-CIbiNoiE.js';
+import { f as BackupsManager } from './manager-yCM0M0FL.js';
+import './store-CKGrIFQU.js';
 import './cache-ilsK3Tki.js';
 import './sync.js';
-import './drive-86CHuTij.js';
-import './s3-BsbVn3fw.js';
+import './drive--mndByvF.js';
+import './s3-dG1SCnV1.js';
 import './machine-ALMkT3mk.js';
 
 /** Flat key -> string map; widgets merge a partial override over EN defaults. */

package/dist/widgets.js

@@ -1,14 +1,15 @@
-import { saveToDisk, datedName } from './chunk-AUH35AAQ.js';
-import { connectFlow, shareFlow, joinFlow } from './chunk-LYO36VYB.js';
-import './chunk-3BWBBGFW.js';
-import { isOpenSupported } from './chunk-GW5CYP4C.js';
-import './chunk-3KAAPYPO.js';
-import './chunk-JTNFZV2B.js';
-import './chunk-757ZOSUI.js';
-import './chunk-HHPJPEEG.js';
-import './chunk-OY2A5DCB.js';
-import './chunk-RREJ2MFN.js';
-import './chunk-XMC67RNM.js';
+import { saveToDisk, datedName } from './chunk-LQS7AMOD.js';
+import { connectFlow, shareFlow, joinFlow } from './chunk-2PIYIIHY.js';
+import './chunk-FQ5O4PHK.js';
+import { isOpenSupported } from './chunk-2TIRUEXR.js';
+import './chunk-2BNTCXQN.js';
+import './chunk-25U6AKIX.js';
+import './chunk-LF3CC2P3.js';
+import './chunk-RVOBONZF.js';
+import './chunk-F4ZZEJ5H.js';
+import './chunk-5UYPKCDB.js';
+import './chunk-WXI2NAPA.js';
+import './chunk-CSYEIXNY.js';
 
 // src/widgets/icons.ts
 var INK = "#8a8f98";