@wells-nelson/data-storage 1.0.1 → 1.0.3

package/README.md

@@ -14,6 +14,7 @@ Peer dependencies: `svelte`, `rxdb`, `rxjs`, `@tanstack/db`, `@tanstack/rxdb-db-
 import { createSyncedStore, envConfig, field, flatSchema } from '@wells-nelson/data-storage';
 import { getRxStorageDexie } from 'rxdb/plugins/storage-dexie';
 
+// Docs maps collection names to document types, as a `type` or an `interface`.
 // Pass the container collection as the second type argument so its rows are typed precisely.
 export const store = createSyncedStore<Docs, 'projects'>({
 	appKey: 'demo', // demo_local, demo_cloud_<user>, demo:hidden, demo:sync:<user>, demo:defaultProject…
@@ -33,7 +34,9 @@ export const store = createSyncedStore<Docs, 'projects'>({
 		if (collection === 'task_links') return { ...row, id: `${row.from_id}:${row.to_id}` };
 		if (collection === 'notes') return { ...row, mentions: row.mentions.split(',').map(map).join(',') };
 		return row;
-	}
+	},
+	// Optional: report failed writes, sync errors and crashes (needs report_client_error, below).
+	reportErrors: { version } // from '$app/env'
 });
 ```
 
@@ -45,22 +48,50 @@ onMount(() => void store.init({ beforeReady: importDevSeed }));
 `store` holds:
 
 - `app`: `local` / `cloud` data sets (`DataSet`: the RxDB database plus a TanStack DB
-  collection per RxDB collection), `ready`, `fatal`.
+  collection per RxDB collection), `ready`, `fatal`, `writeError` (a local write that failed;
+  show it until dismissed) and `persisted` (whether the browser keeps the data for good).
 - `cloud`: `CloudSync`: session (Google, email link), replication, `pendingIds`, `hasPending`,
   `lastSync`, `online`, `active`, `error`, `rejectedWrite`, `roleOf`, `revokedIds`,
-  `forceResync`, `signOut`.
+  `forceResync`, `signOut`. Each collection replicates on its own; a container created in or moved to
+  the cloud (`createContainer`, `makeCloud`) holds its other rows back until its own row has reached
+  Supabase (`expectNewContainer`, at most 20 s), so row level security doesn't refuse them.
 - `ops`: container operations (`createContainer`, `renameContainer`, `makeCloud`, `makeLocal`,
-  `deleteContainer`, `leaveContainer`, `keepRevokedCopy`, `removeRevoked`, `entries`) and the row
+  `deleteContainer`, `leaveContainer`, `keepRevokedCopy`, `removeRevoked`, `entries`,
+  `exportContainers`, `importContainers`) and the row
   helpers they're built from (`insertDoc`, `patch`, `removeDocs`, `docsWhere`, `touch`…).
-- `supabase`: lazy PKCE client and members API (`fetchMembers`, `inviteMember`, `setMemberRole`,
+- `supabase`: PKCE client (`loadClient()`; supabase-js is only downloaded when a session may exist or
+  the user signs in) and members API (`fetchMembers`, `inviteMember`, `setMemberRole`,
   `removeMember`, `leave`, `fetchMyMemberships`) with friendly error messages.
 - `tombstones`: hides deleted rows at once and keeps hiding them if a sync briefly restores
   them; pruned after a week.
 - `prefs`: `DevicePrefs` (default container, "already prompted", collapsed sections). Pass a
   subclass as `prefs` for app-specific ones and override `replaceContainer` to keep them in step.
+- `requestPersistence()`: asks the browser to keep the data (called on start; call it again from
+  a button). Sets `app.persisted`.
 - `resetDevice()`: teardown for a dev wipe.
 
-Without roles everyone is an owner. Table and RPC names default to `<noun>_members` and
+Without roles everyone is an owner.
+
+**Session key.** The session is stored under `<appKey>-auth` (`authStorageKey` to change it), so
+apps sharing an origin, e.g. two GitHub Pages project sites, don't share or end each other's
+sessions. A session stored under supabase-js's default key is moved to the new key once; the old key
+is removed, so a second app on the origin asks to sign in again.
+
+**Lazy loading.** `@supabase/supabase-js` and RxDB's Supabase replication are loaded with dynamic
+`import()`: signed-out users never download them. They load on start when a session is stored or
+the page is a sign-in redirect, and otherwise on sign-in.
+
+**Backups.** `ops.exportContainers([{ id, location }])` returns every row of those containers as a
+JSON-ready object (`format: 'wells-nelson-containers'`, the `appKey`, a version).
+`ops.importContainers(data)` checks a parsed file (format, app, every row against the schema)
+before writing anything, then adds each container as a new local-only container with fresh ids.
+`DeviceDataCard` in `@wells-nelson/interactions/account` is the UI.
+
+**Errors.** `persist()` (TanStack writes) and other quiet failures go through `reportError(kind,
+err)`; failed writes also set `app.writeError`. With `reportErrors`, the store sends each report
+(once per kind and message, at most 20 per page load) to the schema's `report_client_error`
+function with a plain `fetch`, so signed-out devices report too, and also catches uncaught errors
+and rejections. `setErrorReporter` swaps in another destination (e.g. Sentry). Table and RPC names default to `<noun>_members` and
 `get_<noun>_members`; override with e.g. `members: { membersRpc: 'get_list_collaborators' }`.
 
 ## A schema other than `public`
@@ -73,7 +104,8 @@ createSyncedStore({ ..., supabaseSchema: 'my_app' });
 generateMigration({ ..., schema: 'my_app' });
 ```
 
-The migration creates the schema with the grants Supabase's API roles need. In the Supabase
+The migration creates the schema with the grants Supabase's API roles need (tables only for
+`authenticated`; `anon` only gets `report_client_error`). In the Supabase
 dashboard, add the schema under **Project Settings → Data API → Exposed schemas**; until then,
 the API can't see it. The store's client reads and writes that schema. It also fixes RxDB's
 realtime subscription, which otherwise always listens on `public`.
@@ -92,4 +124,19 @@ const sql = generateMigration({
 });
 ```
 
+What it sets up besides the tables:
+
+- `current_email()` returns the signed-in user's email only once it's confirmed (read from
+  `auth.users`), so an unverified sign-up can't claim invites made to that email.
+- RLS on every table; nothing for `anon` except `report_client_error`. Functions are revoked from
+  `public` and `anon` and granted to `authenticated`.
+- Nothing new (rows, members) goes into a deleted container (`is_<noun>_live`); containers can only
+  be created by users with an email. With roles, the last-owner trigger locks the container row, so
+  two owners demoting each other at once can't both succeed; viewers see only the owners and
+  themselves.
+- The members RPC's `active` means "signed in since being invited" (only owners see it, with roles),
+  so it never reveals whether an email has an account.
+- `client_errors` and `report_client_error(...)`: write-only error reports, capped at 300 an hour and
+  kept 30 days.
+
 The sandbox's Data storage page runs this store in the browser and shows the migration.

package/dist/app.svelte.d.ts

@@ -4,10 +4,18 @@ import type { DocMap, Location } from './types.js';
  * Holds the two data sets: `local` (this device only, never synced) is always open;
  * `cloud` exists only while signed in and replicates to Supabase.
  */
-export declare class AppState<D extends DocMap> {
+export declare class AppState<D extends DocMap<D>> {
     local: DataSet<D> | null;
     cloud: DataSet<D> | null;
     ready: boolean;
     fatal: string | null;
+    /** A local write that failed (e.g. storage full). Show it until dismissed. */
+    writeError: string | null;
+    /**
+     * Whether the browser keeps this site's data until the user clears it (`true`), or may evict
+     * it under storage pressure or, in Safari, after 7 days without a visit (`false`). Null until
+     * known, or where the browser can't say.
+     */
+    persisted: boolean | null;
     dataSet(location: Location): DataSet<D>;
 }

package/dist/app.svelte.js

@@ -7,6 +7,14 @@ export class AppState {
     cloud = $state.raw(null);
     ready = $state(false);
     fatal = $state(null);
+    /** A local write that failed (e.g. storage full). Show it until dismissed. */
+    writeError = $state(null);
+    /**
+     * Whether the browser keeps this site's data until the user clears it (`true`), or may evict
+     * it under storage pressure or, in Safari, after 7 days without a visit (`false`). Null until
+     * known, or where the browser can't say.
+     */
+    persisted = $state(null);
     dataSet(location) {
         const ds = location === 'local' ? this.local : this.cloud;
         if (!ds)

package/dist/cloud.svelte.d.ts

@@ -10,7 +10,7 @@ export declare function isRejection(err: unknown): boolean;
  * doesn't expose is reported as the setting to change.
  */
 export declare function errorMessage(err: unknown, schema?: string): string;
-export interface CloudSyncOptions<D extends DocMap> {
+export interface CloudSyncOptions<D extends DocMap<D>> {
     /** Prefix for database names and localStorage keys, e.g. 'demo'. */
     appKey: string;
     schema: StoreSchema<D>;
@@ -25,7 +25,7 @@ export interface CloudSyncOptions<D extends DocMap> {
  * pending changes per container (cleared once replication settles), last sync time, blocked
  * containers, membership / revocation checks, cached roles and rejected writes.
  */
-export declare class CloudSync<D extends DocMap> {
+export declare class CloudSync<D extends DocMap<D>> {
     #private;
     readonly configured: boolean;
     user: User | null;
@@ -56,6 +56,14 @@ export declare class CloudSync<D extends DocMap> {
     /** Record our role right away (e.g. after creating a container or changing roles). */
     setRole(containerId: string, role: Role): void;
     init(): Promise<void>;
+    /**
+     * Hold back a new cloud container's other rows until the container's own row has reached
+     * Supabase. Each collection replicates on its own, and the server only accepts a child row once
+     * its container exists (row level security checks the membership the container insert
+     * creates); without this, a container copied to the cloud with its rows has some of them
+     * rejected until the next retry.
+     */
+    expectNewContainer(containerId: string): void;
     /** Record that a container has local changes that still need to reach Supabase. */
     markPending(containerId: string): void;
     clearPending(containerId: string): void;

package/dist/cloud.svelte.js

@@ -1,12 +1,14 @@
-import { replicateSupabase } from 'rxdb/plugins/replication-supabase';
 import { tick } from 'svelte';
 import { openDatabase } from './database.js';
 import { createDataSet, disposeDataSet } from './dataset.js';
+import { reportError } from './errors.js';
 import { Persisted } from './persisted.svelte.js';
 import { replicationClient, schemaNotExposed } from './supabase.js';
 import { containerIdOf } from './types.js';
 const emptyState = () => ({ pending: {}, blocked: [], revoked: [], roles: {}, lastSync: null });
 const MEMBERSHIP_CHECK_INTERVAL = 30_000;
+/** Longest a new container's other rows wait for the container row to be pushed. */
+const CONTAINER_WAIT_MS = 20_000;
 /** Push errors caused by the server refusing the write (RLS, triggers), not by connectivity. */
 export function isRejection(err) {
     const e = err;
@@ -64,6 +66,10 @@ export class CloudSync {
     #lastMembershipCheck = 0;
     #signingOut = false;
     #queue = Promise.resolve();
+    #attached = null;
+    /** New cloud containers whose own row hasn't reached Supabase yet (see `expectNewContainer`). */
+    #unsent = new Map();
+    #unsentWaits = new Map();
     constructor(options) {
         this.#appKey = options.appKey;
         this.#schema = options.schema;
@@ -126,7 +132,21 @@ export class CloudSync {
             });
             window.addEventListener('offline', () => (this.online = false));
         }
-        const sb = this.#sb.getClient();
+        // supabase-js (and the replication) only load when there may be a session: a stored one or
+        // a sign-in redirect. Otherwise they load when the user signs in.
+        if (this.#sb.mayHaveSession())
+            await this.#attach();
+    }
+    /** Load the client, restore its session and follow auth changes (once). */
+    #attach() {
+        this.#attached ??= this.#doAttach().catch((err) => {
+            this.#attached = null;
+            throw err;
+        });
+        return this.#attached;
+    }
+    async #doAttach() {
+        const sb = await this.#sb.loadClient();
         if (!sb)
             return;
         const { data } = await sb.auth.getSession();
@@ -167,12 +187,43 @@ export class CloudSync {
         this.user = user;
         this.sessionExpired = false;
         this.#app.cloud = createDataSet('cloud', db, this.#schema);
-        this.#startReplication(db);
+        await this.#startReplication(db);
         this.#scheduleSettle();
     }
-    #startReplication(db) {
+    /**
+     * Hold back a new cloud container's other rows until the container's own row has reached
+     * Supabase. Each collection replicates on its own, and the server only accepts a child row once
+     * its container exists (row level security checks the membership the container insert
+     * creates); without this, a container copied to the cloud with its rows has some of them
+     * rejected until the next retry.
+     */
+    expectNewContainer(containerId) {
+        if (this.#unsent.has(containerId))
+            return;
+        let release;
+        const sent = new Promise((resolve) => (release = resolve));
+        this.#unsent.set(containerId, release);
+        this.#unsentWaits.set(containerId, sent);
+    }
+    #containerSent(containerId) {
+        this.#unsent.get(containerId)?.();
+        this.#unsent.delete(containerId);
+        this.#unsentWaits.delete(containerId);
+    }
+    /** Waits while the container's own row is still on its way (bounded: if it's refused, the server decides). */
+    async #afterContainer(containerId) {
+        const sent = this.#unsentWaits.get(containerId);
+        if (!sent)
+            return;
+        let timer;
+        await Promise.race([sent, new Promise((r) => (timer = setTimeout(r, CONTAINER_WAIT_MS)))]);
+        clearTimeout(timer);
+    }
+    async #startReplication(db) {
+        const { replicateSupabase } = await import('rxdb/plugins/replication-supabase');
         const sb = replicationClient(this.#sb.getClient(), this.#sb.schema);
         this.#schema.collections.forEach((name, index) => {
+            const isContainer = name === this.#schema.container;
             const rep = replicateSupabase({
                 replicationIdentifier: `supabase-${name}`,
                 client: sb,
@@ -185,7 +236,14 @@ export class CloudSync {
                 pull: { batchSize: 200 },
                 push: {
                     batchSize: 50,
-                    modifier: (doc) => this.#state.value.blocked.includes(containerIdOf(this.#schema, name, doc)) ? null : doc
+                    modifier: async (doc) => {
+                        const containerId = containerIdOf(this.#schema, name, doc);
+                        if (this.#state.value.blocked.includes(containerId))
+                            return null;
+                        if (!isContainer)
+                            await this.#afterContainer(containerId);
+                        return doc;
+                    }
                 }
             });
             this.#replications.push(rep);
@@ -193,13 +251,20 @@ export class CloudSync {
                 this.error = errorMessage(err, this.#sb.schema);
                 if (isRejection(err))
                     this.rejectedWrite = this.error;
+                // Offline failures are expected; anything else is worth knowing about.
+                if (isRejection(err) || this.online)
+                    reportError('sync', this.error, `${name} ${err.parameters?.direction ?? ''}`);
             }), rep.active$.subscribe((isActive) => {
                 if (isActive)
                     this.#activeReps.add(index);
                 else
                     this.#activeReps.delete(index);
                 this.active = this.#activeReps.size > 0;
-            }), rep.received$.subscribe(() => this.#scheduleSettle()), rep.sent$.subscribe(() => this.#scheduleSettle()));
+            }), rep.received$.subscribe(() => this.#scheduleSettle()), rep.sent$.subscribe((doc) => {
+                if (isContainer)
+                    this.#containerSent(doc.id);
+                this.#scheduleSettle();
+            }));
         });
     }
     async #teardown(removeData) {
@@ -211,6 +276,8 @@ export class CloudSync {
         this.#replications = [];
         this.#activeReps.clear();
         this.active = false;
+        for (const id of [...this.#unsent.keys()])
+            this.#containerSent(id);
         await Promise.allSettled(reps.map((r) => r.cancel()));
         const ds = this.#app.cloud;
         this.#app.cloud = null;
@@ -324,6 +391,7 @@ export class CloudSync {
         await this.checkMemberships(true);
     }
     async signInWithGoogle(redirectTo) {
+        await this.#attach();
         const sb = this.#sb.getClient();
         if (!sb)
             throw new Error('Cloud sync is not configured.');
@@ -333,6 +401,7 @@ export class CloudSync {
     }
     /** Email a magic sign-in link. The link has to be opened in this browser (PKCE). */
     async signInWithEmail(email, redirectTo) {
+        await this.#attach();
         const sb = this.#sb.getClient();
         if (!sb)
             throw new Error('Cloud sync is not configured.');

package/dist/containers.d.ts

@@ -7,7 +7,7 @@ import type { SupabaseApi } from './supabase.js';
 import type { Tombstones } from './tombstones.svelte.js';
 import type { CollectionName, DocMap, Location, Role, StoreSchema } from './types.js';
 /** Every row of one container, by collection. */
-export type ContainerDocs<D extends DocMap> = {
+export type ContainerDocs<D extends DocMap<D>> = {
     [N in CollectionName<D>]: D[N][];
 };
 /**
@@ -15,8 +15,8 @@ export type ContainerDocs<D extends DocMap> = {
  * `refs` fields: composite ids and ids inside text fields. `map` turns an old id into the copy's
  * id (the identity when ids are kept).
  */
-export type RemapHook<D extends DocMap> = <N extends CollectionName<D>>(collection: N, row: D[N], map: (id: string) => string) => D[N];
-export interface ContainerOpsOptions<D extends DocMap, C extends CollectionName<D> = CollectionName<D>> {
+export type RemapHook<D extends DocMap<D>> = <N extends CollectionName<D>>(collection: N, row: D[N], map: (id: string) => string) => D[N];
+export interface ContainerOpsOptions<D extends DocMap<D>, C extends CollectionName<D> = CollectionName<D>> {
     schema: StoreSchema<D, C>;
     app: AppState<D>;
     cloud: CloudSync<D>;
@@ -29,6 +29,8 @@ export interface ContainerOpsOptions<D extends DocMap, C extends CollectionName<
         [N in CollectionName<D>]?: (keyof D[N] & string)[];
     };
     remap?: RemapHook<D>;
+    /** The store's appKey, written into exports and checked on import. */
+    appKey?: string;
 }
 /** A container as listed by the app (one entry even while it moves between data sets). */
 export interface ContainerEntry<T> {
@@ -36,18 +38,31 @@ export interface ContainerEntry<T> {
     location: Location;
     role: Role;
 }
-/** Persisting a TanStack DB transaction in the background, logging failures. */
+/**
+ * Persisting a TanStack DB transaction in the background. A failure is reported and shown
+ * (`app.writeError` through the store), not just logged.
+ */
 export declare function persist(tx: {
     when(state: 'settled'): Promise<unknown>;
 }): void;
+/** The file format of `exportContainers`. */
+export interface ContainerExport {
+    format: 'wells-nelson-containers';
+    version: 1;
+    /** The store's appKey: a file only imports into the app that wrote it. */
+    app: string;
+    exportedAt: string;
+    /** One entry per container: every row of it, by collection. */
+    containers: Record<string, Record<string, unknown>[]>[];
+}
 export declare const now: () => number;
 export declare const uid: () => `${string}-${string}-${string}-${string}-${string}`;
-export type ContainerOps<D extends DocMap, C extends CollectionName<D> = CollectionName<D>> = ReturnType<typeof createContainerOps<D, C>>;
+export type ContainerOps<D extends DocMap<D>, C extends CollectionName<D> = CollectionName<D>> = ReturnType<typeof createContainerOps<D, C>>;
 /**
  * Operations on whole containers and the low-level row helpers they're built from. Every write
  * to a cloud data set marks the container pending so the profile can show unsynced changes.
  */
-export declare function createContainerOps<D extends DocMap, C extends CollectionName<D> = CollectionName<D>>(options: ContainerOpsOptions<D, C>): {
+export declare function createContainerOps<D extends DocMap<D>, C extends CollectionName<D> = CollectionName<D>>(options: ContainerOpsOptions<D, C>): {
     rx: <N extends CollectionName<D>>(ds: DataSet<D>, name: N) => RxCollection<D[N]>;
     touch: (ds: DataSet<D>, containerId: string) => void;
     removeDocs: <N extends CollectionName<D>>(ds: DataSet<D>, name: N, ids: string[]) => Promise<void>;
@@ -64,6 +79,11 @@ export declare function createContainerOps<D extends DocMap, C extends Collectio
         containerId: string;
     };
     copyContainer: (from: DataSet<D>, to: DataSet<D>, containerId: string, newIds: boolean) => Promise<string>;
+    exportContainers: (items: {
+        id: string;
+        location: Location;
+    }[]) => Promise<ContainerExport>;
+    importContainers: (data: unknown) => Promise<string[]>;
     makeCloud: (containerId: string) => Promise<void>;
     makeLocal: (containerId: string) => Promise<string>;
     deleteContainer: (ds: DataSet<D>, containerId: string) => Promise<void>;

package/dist/containers.js

@@ -1,6 +1,10 @@
-/** Persisting a TanStack DB transaction in the background, logging failures. */
+import { writeFailed } from './errors.js';
+/**
+ * Persisting a TanStack DB transaction in the background. A failure is reported and shown
+ * (`app.writeError` through the store), not just logged.
+ */
 export function persist(tx) {
-    tx.when('settled').catch((err) => console.error('Failed to save change', err));
+    tx.when('settled').catch(writeFailed);
 }
 export const now = () => Date.now();
 export const uid = () => crypto.randomUUID();
@@ -63,9 +67,11 @@ export function createContainerOps(options) {
         const t = now();
         const hasCreatedAt = 'created_at' in (schema.schemas[container].properties ?? {});
         const doc = { ...fields, id, updated_at: t, ...(hasCreatedAt ? { created_at: t } : {}) };
-        insertDoc(ds, container, doc, id);
-        if (ds.location === 'cloud')
+        if (ds.location === 'cloud') {
             cloud.setRole(id, 'owner');
+            cloud.expectNewContainer(id);
+        }
+        insertDoc(ds, container, doc, id);
         return id;
     }
     function renameContainer(ds, containerId, name) {
@@ -135,6 +141,7 @@ export function createContainerOps(options) {
         if (to.location === 'cloud') {
             cloud.markPending(cid);
             cloud.setRole(cid, 'owner');
+            cloud.expectNewContainer(cid);
         }
         // Rows deliberately written again (e.g. a container moved back here) must not stay hidden.
         for (const name of collections)
@@ -142,6 +149,80 @@ export function createContainerOps(options) {
         await insertContainerDocs(to, rows);
         return cid;
     }
+    /**
+     * Every row of the given containers as one JSON-ready object (a backup the user keeps). Each
+     * container is read from the data set it lives in.
+     */
+    async function exportContainers(items) {
+        const containers = [];
+        for (const { id, location } of items) {
+            const docs = await readContainer(app.dataSet(location), id);
+            if (docs[container].length === 0)
+                continue;
+            containers.push(docs);
+        }
+        return {
+            format: 'wells-nelson-containers',
+            version: 1,
+            app: options.appKey ?? '',
+            exportedAt: new Date().toISOString(),
+            containers
+        };
+    }
+    /** Keep only the schema's fields, and only with the schema's types; anything else is not a backup. */
+    function cleanRow(name, row) {
+        const props = schema.schemas[name].properties;
+        if (!row || typeof row !== 'object')
+            throw new Error('This file is not a backup of this app.');
+        const out = {};
+        for (const [key, prop] of Object.entries(props)) {
+            const value = row[key];
+            const type = prop.type === 'number' ? 'number' : prop.type === 'boolean' ? 'boolean' : 'string';
+            if (typeof value !== type || (type === 'number' && !Number.isFinite(value))) {
+                throw new Error(`This backup has an invalid ${name} row (${key}).`);
+            }
+            out[key] = value;
+        }
+        return out;
+    }
+    /**
+     * Add every container of an `exportContainers` file to this device as new local-only
+     * containers (fresh ids, so importing twice makes two copies and nothing is overwritten).
+     * Returns the new container ids.
+     */
+    async function importContainers(data) {
+        const file = data;
+        if (!file || file.format !== 'wells-nelson-containers' || !Array.isArray(file.containers)) {
+            throw new Error('This file is not a backup of this app.');
+        }
+        if (file.version !== 1)
+            throw new Error('This backup was made by a newer version of the app. Update the app first.');
+        if (options.appKey && file.app !== options.appKey)
+            throw new Error('This backup is from a different app.');
+        // Check everything before writing anything.
+        const parsed = file.containers.map((entry) => {
+            const docs = {};
+            for (const name of collections) {
+                const rows = entry[name] ?? [];
+                if (!Array.isArray(rows))
+                    throw new Error('This file is not a backup of this app.');
+                docs[name] = rows.map((r) => cleanRow(name, r));
+            }
+            const head = docs[container][0];
+            if (docs[container].length !== 1 || !head)
+                throw new Error('This file is not a backup of this app.');
+            return { docs, id: head.id };
+        });
+        const local = app.dataSet('local');
+        const ids = [];
+        for (const { docs, id } of parsed) {
+            const { rows, containerId } = remapContainer(docs, id, true);
+            await insertContainerDocs(local, rows);
+            prefs.markPrompted([containerId]);
+            ids.push(containerId);
+        }
+        return ids;
+    }
     /** Remove a cloud container from this device only; nothing is deleted on Supabase. */
     async function purgeCloudContainer(containerId) {
         const ds = app.dataSet('cloud');
@@ -272,6 +353,8 @@ export function createContainerOps(options) {
         insertContainerDocs,
         remapContainer,
         copyContainer,
+        exportContainers,
+        importContainers,
         makeCloud,
         makeLocal,
         deleteContainer,

package/dist/database.d.ts

@@ -1,9 +1,9 @@
 import { type RxCollection, type RxConflictHandler, type RxDatabase, type RxStorage } from 'rxdb/plugins/core';
 import type { CollectionName, DocMap, StoreSchema } from './types.js';
-export type Collections<D extends DocMap> = {
+export type Collections<D extends DocMap<D>> = {
     [N in CollectionName<D>]: RxCollection<D[N]>;
 };
-export type Database<D extends DocMap> = RxDatabase<Collections<D>>;
+export type Database<D extends DocMap<D>> = RxDatabase<Collections<D>>;
 export declare function docsEqual(a: Record<string, unknown>, b: Record<string, unknown>): boolean;
 /**
  * Last write wins: whichever side carries the newer `updated_at` (client clock) is kept.
@@ -21,4 +21,4 @@ export interface OpenDatabaseOptions {
     multiInstance?: boolean;
 }
 /** Create an RxDB database with one collection per schema, all using last-write-wins. */
-export declare function openDatabase<D extends DocMap>(name: string, schema: Pick<StoreSchema<D>, 'collections' | 'schemas'>, { storage, multiInstance }?: OpenDatabaseOptions): Promise<Database<D>>;
+export declare function openDatabase<D extends DocMap<D>>(name: string, schema: Pick<StoreSchema<D>, 'collections' | 'schemas'>, { storage, multiInstance }?: OpenDatabaseOptions): Promise<Database<D>>;

package/dist/dataset.d.ts

@@ -7,12 +7,12 @@ export type TSCollection<T extends object> = ReturnType<typeof makeCollection<T>
  * One RxDB database plus a TanStack DB collection on top of each RxDB collection.
  * Components query the TanStack collections; bulk operations go straight to RxDB.
  */
-export type DataSet<D extends DocMap> = {
+export type DataSet<D extends DocMap<D>> = {
     location: Location;
     db: Database<D>;
 } & {
     [N in CollectionName<D>]: TSCollection<D[N]>;
 };
-export declare function createDataSet<D extends DocMap>(location: Location, db: Database<D>, schema: Pick<StoreSchema<D>, 'collections' | 'container' | 'containerField' | 'indexContainerField'>): DataSet<D>;
-export declare function disposeDataSet<D extends DocMap>(ds: DataSet<D>, collections: readonly CollectionName<D>[]): Promise<void>;
+export declare function createDataSet<D extends DocMap<D>>(location: Location, db: Database<D>, schema: Pick<StoreSchema<D>, 'collections' | 'container' | 'containerField' | 'indexContainerField'>): DataSet<D>;
+export declare function disposeDataSet<D extends DocMap<D>>(ds: DataSet<D>, collections: readonly CollectionName<D>[]): Promise<void>;
 export {};

package/dist/errors.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Client error reporting. Library code calls `reportError` where something fails without the
+ * user necessarily noticing (a local write, sync, device prefs); the store installs a reporter
+ * that sends each report to the app's Supabase project (see `remoteReporter`). Reports are
+ * de-duplicated by kind and message and capped per page load.
+ */
+export type ErrorKind = 'write' | 'sync' | 'prefs' | 'unhandled' | (string & {});
+export interface ErrorReport {
+    kind: ErrorKind;
+    message: string;
+    /** Extra context, e.g. a stack trace. */
+    detail?: string;
+}
+export type ErrorReporter = (report: ErrorReport) => void;
+/** Where reports go (null to stop reporting). */
+export declare function setErrorReporter(next: ErrorReporter | null): void;
+/** Forget what was reported (tests). */
+export declare function resetErrorReports(): void;
+export declare function describeError(err: unknown): {
+    message: string;
+    detail?: string;
+};
+/** Report an error once per kind and message (and at most 20 per page load). Never throws. */
+export declare function reportError(kind: ErrorKind, err: unknown, detail?: string): void;
+/** Called with a message whenever a local write fails (see `persist`). Returns an unsubscribe. */
+export declare function onWriteError(listener: (message: string) => void): () => undefined;
+/** A local write failed: tell listeners (the store shows it) and report it. */
+export declare function writeFailed(err: unknown): void;
+export interface RemoteReporterOptions {
+    supabaseUrl: string;
+    supabaseAnonKey: string;
+    /** Postgres schema holding `report_client_error` (see the generated migration). */
+    schema: string;
+    /** App name stored with each report, e.g. the store's appKey. */
+    app: string;
+    /** The deployed version, stored with each report. */
+    version?: string;
+}
+/**
+ * Sends reports to the `report_client_error` function of the app's Supabase schema with a plain
+ * `fetch` (no supabase-js needed, so signed-out devices report too). Only the path of the page
+ * is sent, never its query or any user data beyond the error itself.
+ */
+export declare function remoteReporter(options: RemoteReporterOptions): ErrorReporter;