@wells-nelson/data-storage 0.0.0-stage → 1.0.0

package/dist/sql.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Generates the Supabase migration for an app's tables: `_deleted` / `_modified` replication
+ * columns with their trigger and checkpoint index, `current_email()`, a membership table with
+ * an `is_<noun>_member` helper and RLS on every table, the creator-becomes-member trigger, the
+ * "touch rows on new share" trigger, the members RPC (active / pending) and the realtime
+ * publication. With `roles`, members are viewer / editor / owner and the last owner is protected.
+ *
+ * Pure string building: no database or Svelte dependency, so it runs from a plain Node script.
+ */
+export type ColumnType = 'text' | 'number' | 'boolean';
+export interface ColumnSpec {
+    type: ColumnType;
+    /** SQL default expression. Defaults: '' / 0 / false; none for id references. */
+    default?: string | null;
+}
+export interface MigrationTable {
+    name: string;
+    /** Every column except `id`, `_deleted` and `_modified`, in order. */
+    columns: Record<string, ColumnType | ColumnSpec>;
+}
+export interface MigrationConfig {
+    /** First line of the header comment, e.g. "My App: schema for RxDB <-> Supabase replication." */
+    title?: string;
+    /** The container table, e.g. 'projects'. Must be one of `tables`. */
+    container: string;
+    /** Column on child tables pointing at the container, e.g. 'project_id'. */
+    containerField: string;
+    /** Singular noun, e.g. 'project' (names `project_members`, `is_project_member`, `get_project_members`…). */
+    noun: string;
+    /** All replicated tables, parents first. */
+    tables: MigrationTable[];
+    roles?: boolean;
+    membersTable?: string;
+    membersRpc?: string;
+}
+/**
+ * Turn RxDB flat schemas into migration tables. `refs` fields (and the container field) become
+ * `text not null` with no default; `defaults` overrides per column, e.g. `{ tasks: { open: 'true' } }`.
+ */
+export declare function tablesFromSchemas(collections: readonly string[], schemas: Record<string, {
+    properties: Record<string, {
+        type?: unknown;
+    }>;
+}>, options: {
+    containerField: string;
+    refs?: Record<string, readonly string[] | undefined>;
+    defaults?: Record<string, Record<string, string>>;
+}): MigrationTable[];
+export declare function generateMigration(config: MigrationConfig): string;

package/dist/sql.js

@@ -0,0 +1,274 @@
+/**
+ * Generates the Supabase migration for an app's tables: `_deleted` / `_modified` replication
+ * columns with their trigger and checkpoint index, `current_email()`, a membership table with
+ * an `is_<noun>_member` helper and RLS on every table, the creator-becomes-member trigger, the
+ * "touch rows on new share" trigger, the members RPC (active / pending) and the realtime
+ * publication. With `roles`, members are viewer / editor / owner and the last owner is protected.
+ *
+ * Pure string building: no database or Svelte dependency, so it runs from a plain Node script.
+ */
+const SQL_TYPES = { text: 'text', number: 'double precision', boolean: 'boolean' };
+const DEFAULTS = { text: "''", number: '0', boolean: 'false' };
+function columnSql(name, spec) {
+    const { type, default: def } = typeof spec === 'string' ? { type: spec, default: undefined } : spec;
+    const value = def === undefined ? DEFAULTS[type] : def;
+    return `  ${name} ${SQL_TYPES[type]} not null${value === null ? '' : ` default ${value}`}`;
+}
+/**
+ * Turn RxDB flat schemas into migration tables. `refs` fields (and the container field) become
+ * `text not null` with no default; `defaults` overrides per column, e.g. `{ tasks: { open: 'true' } }`.
+ */
+export function tablesFromSchemas(collections, schemas, options) {
+    return collections.map((name) => {
+        const columns = {};
+        const refs = new Set([options.containerField, ...(options.refs?.[name] ?? [])]);
+        for (const [col, prop] of Object.entries(schemas[name].properties)) {
+            if (col === 'id')
+                continue;
+            const type = prop.type === 'number' ? 'number' : prop.type === 'boolean' ? 'boolean' : 'text';
+            const override = options.defaults?.[name]?.[col];
+            columns[col] = { type, default: override ?? (refs.has(col) ? null : undefined) };
+        }
+        return { name, columns };
+    });
+}
+export function generateMigration(config) {
+    const { container, containerField: cf, noun, roles = false } = config;
+    const members = config.membersTable ?? `${noun}_members`;
+    const rpc = config.membersRpc ?? `get_${noun}_members`;
+    const isMember = `is_${noun}_member`;
+    const roleType = `${noun}_role`;
+    const children = config.tables.filter((t) => t.name !== container);
+    const all = config.tables.map((t) => t.name);
+    if (!all.includes(container))
+        throw new Error(`The container table "${container}" must be in tables.`);
+    const list = (names) => names.map((n) => `'${n}'`).join(',');
+    const out = [];
+    const add = (s) => out.push(out.length === 0 ? s.replace(/^\n/, '') : s);
+    const cap = (w) => w.charAt(0).toUpperCase() + w.slice(1);
+    add(`
+-- ${config.title ?? 'Schema for RxDB <-> Supabase replication.'}
+--
+-- Every replicated table mirrors an RxDB collection 1:1 (same snake_case column names) plus:
+--   _deleted   soft-delete flag (rows are never hard-deleted by the app)
+--   _modified  server timestamp used as the replication checkpoint (set by trigger)
+-- Access is granted per ${noun} through ${members}, matched on the signed-in user's email so a
+-- ${noun} can be shared with someone who hasn't signed up yet (a "pending" member).${roles ? '\n-- Roles: viewer < editor < owner.' : ''}
+
+-- ---------------------------------------------------------------- helpers
+
+create or replace function public.set_modified()
+returns trigger
+language plpgsql
+as $$
+begin
+  new._modified := clock_timestamp();
+  return new;
+end;
+$$;
+
+create or replace function public.current_email()
+returns text
+language sql
+stable
+as $$
+  select lower(coalesce(auth.jwt() ->> 'email', ''));
+$$;
+
+-- ---------------------------------------------------------------- membership
+`);
+    if (roles)
+        add(`\ncreate type public.${roleType} as enum ('viewer', 'editor', 'owner');\n`);
+    add(`
+create table public.${members} (
+  id uuid primary key default gen_random_uuid(),
+  ${cf} text not null,
+  email text not null check (email = lower(email)),${roles ? `\n  role public.${roleType} not null,` : ''}
+  invited_by uuid default auth.uid(),
+  created_at timestamptz not null default now(),
+  unique (${cf}, email)
+);
+create index ${members}_email_idx on public.${members} (email);
+
+-- security definer so policies can call it without recursing into ${members}' own RLS.
+create or replace function public.${isMember}(p_${cf} text${roles ? `, p_min_role public.${roleType} default 'viewer'` : ''})
+returns boolean
+language sql
+stable
+security definer
+set search_path = public
+as $$
+  select exists (
+    select 1 from public.${members} m
+    where m.${cf} = p_${cf} and m.email = public.current_email()${roles ? ' and m.role >= p_min_role' : ''}
+  );
+$$;
+
+alter table public.${members} enable row level security;
+`);
+    if (roles) {
+        add(`
+create policy "members read members" on public.${members}
+  for select to authenticated using (public.${isMember}(${cf}));
+create policy "owners invite" on public.${members}
+  for insert to authenticated with check (public.${isMember}(${cf}, 'owner'));
+create policy "owners change roles" on public.${members}
+  for update to authenticated using (public.${isMember}(${cf}, 'owner'));
+-- Owners remove anyone; everyone can remove themselves (leave the ${noun}).
+create policy "owners remove, members leave" on public.${members}
+  for delete to authenticated using (public.${isMember}(${cf}, 'owner') or email = public.current_email());
+
+-- A ${noun} can never end up without an owner.
+create or replace function public.prevent_last_owner_removal()
+returns trigger
+language plpgsql
+security definer
+set search_path = public
+as $$
+begin
+  if old.role = 'owner' and (tg_op = 'DELETE' or new.role <> 'owner') then
+    if not exists (
+      select 1 from public.${members}
+      where ${cf} = old.${cf} and role = 'owner' and id <> old.id
+    ) then
+      -- A ${noun} that is itself deleted may drop its last owner.
+      if exists (select 1 from public.${container} t where t.id = old.${cf} and not t._deleted) then
+        raise exception 'cannot remove the last owner of a ${noun}';
+      end if;
+    end if;
+  end if;
+  return coalesce(new, old);
+end;
+$$;
+
+create trigger ${members}_keep_owner before update or delete on public.${members}
+  for each row execute function public.prevent_last_owner_removal();
+`);
+    }
+    else {
+        add(`
+create policy "members read memberships of their ${container}" on public.${members}
+  for select to authenticated using (public.${isMember}(${cf}));
+create policy "members share their ${container}" on public.${members}
+  for insert to authenticated with check (public.${isMember}(${cf}));
+create policy "members unshare their ${container}" on public.${members}
+  for delete to authenticated using (public.${isMember}(${cf}));
+`);
+    }
+    add(`\n-- ---------------------------------------------------------------- replicated tables\n`);
+    for (const table of config.tables) {
+        const cols = ['  id text primary key', ...Object.entries(table.columns).map(([n, s]) => columnSql(n, s))];
+        cols.push('  _deleted boolean not null default false', '  _modified timestamptz not null default now()');
+        add(`\ncreate table public.${table.name} (\n${cols.join(',\n')}\n);\n`);
+    }
+    const writer = roles ? 'editor' : null;
+    add(`
+do $$
+declare t text;
+begin
+  foreach t in array array[${list(all)}] loop
+    execute format('create index %1$s_modified_idx on public.%1$s (_modified, id)', t);
+    execute format(
+      'create trigger %1$s_set_modified before insert or update on public.%1$s
+         for each row execute function public.set_modified()', t);
+    execute format('alter table public.%1$s enable row level security', t);
+  end loop;
+${children.length === 0
+        ? ''
+        : `
+  -- ${cap(noun)} data: ${roles ? 'viewers read, editors write' : 'members read and write'}.
+  foreach t in array array[${list(children.map((c) => c.name))}] loop
+    execute format('create index %1$s_${noun}_idx on public.%1$s (${cf})', t);
+    execute format(
+      'create policy "members read" on public.%1$s for select to authenticated
+         using (public.${isMember}(${cf}))', t);
+${writer
+            ? `    execute format(
+      'create policy "editors insert" on public.%1$s for insert to authenticated
+         with check (public.${isMember}(${cf}, %2$L))', t, '${writer}');
+    execute format(
+      'create policy "editors update" on public.%1$s for update to authenticated
+         using (public.${isMember}(${cf}, %2$L)) with check (public.${isMember}(${cf}, %2$L))', t, '${writer}');`
+            : `    execute format(
+      'create policy "members insert" on public.%1$s for insert to authenticated
+         with check (public.${isMember}(${cf}))', t);
+    execute format(
+      'create policy "members update" on public.%1$s for update to authenticated
+         using (public.${isMember}(${cf})) with check (public.${isMember}(${cf}))', t);`}
+  end loop;
+`}end;
+$$;
+
+-- ${cap(container)}: any signed-in user creates one (and becomes ${roles ? 'its owner' : 'a member'}); ${roles ? 'only owners rename / delete' : 'members rename / delete'}.
+create policy "members read" on public.${container}
+  for select to authenticated using (public.${isMember}(id));
+create policy "signed-in users create ${container}" on public.${container}
+  for insert to authenticated with check (auth.uid() is not null);
+create policy "${roles ? 'owners' : 'members'} update" on public.${container}
+  for update to authenticated using (public.${isMember}(id${roles ? ", 'owner'" : ''})) with check (public.${isMember}(id${roles ? ", 'owner'" : ''}));
+
+-- The creator of a ${noun} becomes its first ${roles ? 'owner' : 'member'}.
+create or replace function public.add_creator_membership()
+returns trigger
+language plpgsql
+security definer
+set search_path = public
+as $$
+begin
+  if public.current_email() <> '' then
+    insert into public.${members} (${cf}, email${roles ? ', role' : ''})
+    values (new.id, public.current_email()${roles ? ", 'owner'" : ''})
+    on conflict (${cf}, email) do nothing;
+  end if;
+  return new;
+end;
+$$;
+
+create trigger ${container}_add_creator after insert on public.${container}
+  for each row execute function public.add_creator_membership();
+
+-- When a ${noun} is shared with someone, bump _modified on all of its rows so their replication
+-- (which only pulls rows newer than its checkpoint) picks the whole ${noun} up.
+create or replace function public.touch_${noun}_for_new_member()
+returns trigger
+language plpgsql
+security definer
+set search_path = public
+as $$
+begin
+  if new.email is distinct from public.current_email() then
+    update public.${container} set _modified = clock_timestamp() where id = new.${cf};
+${children.map((c) => `    update public.${c.name} set _modified = clock_timestamp() where ${cf} = new.${cf};`).join('\n')}
+  end if;
+  return new;
+end;
+$$;
+
+create trigger ${members}_touch after insert on public.${members}
+  for each row execute function public.touch_${noun}_for_new_member();
+
+-- Members of a ${noun}${roles ? ' with their role' : ''}, flagging which emails belong to a registered user
+-- ("active") vs pending invites.
+create or replace function public.${rpc}(p_${cf} text)
+returns table (id uuid, email text, ${roles ? `role public.${roleType}, ` : ''}active boolean)
+language sql
+stable
+security definer
+set search_path = public, auth
+as $$
+  select m.id, m.email, ${roles ? 'm.role, ' : ''}exists (select 1 from auth.users u where lower(u.email) = m.email) as active
+  from public.${members} m
+  where m.${cf} = p_${cf} and public.${isMember}(p_${cf})
+  order by ${roles ? 'm.role desc, ' : ''}m.created_at;
+$$;
+
+revoke all on function public.${rpc}(text) from public, anon;
+grant execute on function public.${rpc}(text) to authenticated;
+
+-- ---------------------------------------------------------------- realtime
+
+alter publication supabase_realtime
+  add table ${all.map((n) => `public.${n}`).join(', ')};
+`);
+    return out.join('');
+}

package/dist/store.d.ts

@@ -0,0 +1,79 @@
+import { AppState } from './app.svelte.js';
+import { CloudSync } from './cloud.svelte.js';
+import { type RemapHook } from './containers.js';
+import { type StorageFactory } from './database.js';
+import { type DataSet } from './dataset.js';
+import type { EnvConfig } from './env.js';
+import { DevicePrefs } from './prefs.svelte.js';
+import { type MembersConfig } from './supabase.js';
+import { Tombstones } from './tombstones.svelte.js';
+import type { CollectionName, DocMap, Nouns, StoreSchema } from './types.js';
+/**
+ * `C` is the container collection; pass it (`createSyncedStore<Docs, 'projects'>`) so container
+ * rows are typed as that document rather than a union of every document.
+ */
+export interface SyncedStoreConfig<D extends DocMap, C extends CollectionName<D> = CollectionName<D>> extends StoreSchema<D, C> {
+    /** Prefix for database names and localStorage keys, e.g. 'demo' → `demo_local`, `demo:hidden`. */
+    appKey: string;
+    nouns: Nouns;
+    /** From `envConfig(import.meta.env)`. */
+    env: EnvConfig;
+    /** RxDB storage, e.g. `getRxStorageDexie` (browser) or `getRxStorageMemory` (tests). */
+    storage: StorageFactory;
+    /** viewer / editor / owner roles (needs the roles variant of the SQL migration). */
+    roles?: boolean;
+    /** Override membership table / RPC names (defaults: `<noun>_members`, `get_<noun>_members`). */
+    members?: Partial<Omit<MembersConfig, 'roles' | 'containerField'>>;
+    /** Fields per collection holding ids of other rows in the container (rewritten when copying). */
+    refs?: {
+        [N in CollectionName<D>]?: (keyof D[N] & string)[];
+    };
+    /** Rewrite composite ids / ids inside text fields when copying (see `RemapHook`). */
+    remap?: RemapHook<D>;
+    /** A `DevicePrefs` subclass with app-specific prefs. */
+    prefs?: DevicePrefs;
+}
+/**
+ * Wire the whole storage layer for an app from one config: app state (local + cloud data
+ * sets), cloud sync, tombstones, device prefs, the Supabase members API and container
+ * operations. Create it once in a module and import it where needed.
+ */
+export declare function createSyncedStore<D extends DocMap, C extends CollectionName<D> = CollectionName<D>>(config: SyncedStoreConfig<D, C>): {
+    config: SyncedStoreConfig<D, C>;
+    roles: boolean;
+    app: AppState<D>;
+    cloud: CloudSync<D>;
+    tombstones: Tombstones;
+    prefs: DevicePrefs;
+    supabase: import("./supabase.js").SupabaseApi;
+    ops: {
+        rx: <N extends CollectionName<D>>(ds: DataSet<D>, name: N) => import("rxdb").RxCollection<D[N]>;
+        touch: (ds: DataSet<D>, containerId: string) => void;
+        removeDocs: <N extends CollectionName<D>>(ds: DataSet<D>, name: N, ids: string[]) => Promise<void>;
+        docsWhere: <N extends CollectionName<D>>(ds: DataSet<D>, name: N, selector: Partial<Record<keyof D[N] & string, string | number | boolean>>) => Promise<D[N][]>;
+        insertDoc: <N extends CollectionName<D>>(ds: DataSet<D>, name: N, doc: D[N], containerId: string) => void;
+        patch: <N extends CollectionName<D>>(ds: DataSet<D>, name: N, id: string, containerId: string, fields: Partial<D[N]>) => void;
+        createContainer: (ds: DataSet<D>, fields: Omit<D[C], "id" | "updated_at" | "created_at">) => string;
+        renameContainer: (ds: DataSet<D>, containerId: string, name: string) => void;
+        readContainer: (ds: DataSet<D>, containerId: string) => Promise<import("./containers.js").ContainerDocs<D>>;
+        removeContainerDocs: (ds: DataSet<D>, containerId: string) => Promise<void>;
+        insertContainerDocs: (to: DataSet<D>, docs: Partial<import("./containers.js").ContainerDocs<D>>) => Promise<void>;
+        remapContainer: (docs: import("./containers.js").ContainerDocs<D>, containerId: string, newIds: boolean) => {
+            rows: import("./containers.js").ContainerDocs<D>;
+            containerId: string;
+        };
+        copyContainer: (from: DataSet<D>, to: DataSet<D>, containerId: string, newIds: boolean) => Promise<string>;
+        makeCloud: (containerId: string) => Promise<void>;
+        makeLocal: (containerId: string) => Promise<string>;
+        deleteContainer: (ds: DataSet<D>, containerId: string) => Promise<void>;
+        leaveContainer: (containerId: string) => Promise<void>;
+        keepRevokedCopy: (containerId: string) => Promise<string>;
+        removeRevoked: (containerId: string) => Promise<void>;
+        entries: (localRows: D[C][], cloudRows: D[C][]) => import("./containers.js").ContainerEntry<D[C]>[];
+    };
+    init: (options?: {
+        beforeReady?: (local: DataSet<D>) => Promise<void>;
+    }) => Promise<void>;
+    resetDevice: () => Promise<void>;
+};
+export type SyncedStore<D extends DocMap, C extends CollectionName<D> = CollectionName<D>> = ReturnType<typeof createSyncedStore<D, C>>;

package/dist/store.js

@@ -0,0 +1,86 @@
+import { tick } from 'svelte';
+import { AppState } from './app.svelte.js';
+import { CloudSync } from './cloud.svelte.js';
+import { createContainerOps } from './containers.js';
+import { openDatabase, setStorageFactory } from './database.js';
+import { createDataSet } from './dataset.js';
+import { DevicePrefs, defaultPrefsKeys } from './prefs.svelte.js';
+import { createSupabaseApi } from './supabase.js';
+import { Tombstones } from './tombstones.svelte.js';
+/**
+ * Wire the whole storage layer for an app from one config: app state (local + cloud data
+ * sets), cloud sync, tombstones, device prefs, the Supabase members API and container
+ * operations. Create it once in a module and import it where needed.
+ */
+export function createSyncedStore(config) {
+    const roles = config.roles ?? false;
+    const supabase = createSupabaseApi(config.env, {
+        table: `${config.nouns.singular}_members`,
+        membersRpc: `get_${config.nouns.singular}_members`,
+        noun: config.nouns.singular,
+        ...config.members,
+        containerField: config.containerField,
+        roles
+    });
+    const app = new AppState();
+    const tombstones = new Tombstones(config.appKey);
+    const prefs = config.prefs ?? new DevicePrefs(defaultPrefsKeys(config.appKey, config.nouns));
+    const cloud = new CloudSync({
+        appKey: config.appKey,
+        schema: config,
+        app,
+        supabase,
+        roles,
+        storage: config.storage
+    });
+    const ops = createContainerOps({
+        schema: config,
+        app,
+        cloud,
+        tombstones,
+        prefs,
+        supabase,
+        roles,
+        refs: config.refs,
+        remap: config.remap
+    });
+    let started;
+    /**
+     * Open the local database, then restore any Supabase session (which opens the cloud
+     * database). Safe to call more than once. A failure ends up in `app.fatal`.
+     */
+    function init(options = {}) {
+        started ??= (async () => {
+            setStorageFactory(config.storage);
+            const db = await openDatabase(`${config.appKey}_local`, config, { storage: config.storage });
+            const local = createDataSet('local', db, config);
+            await options.beforeReady?.(local).catch((err) => console.error('Startup hook failed', err));
+            app.local = local;
+            app.ready = true;
+            await cloud.init();
+        })().catch((err) => {
+            console.error(err);
+            app.fatal = err instanceof Error ? err.message : String(err);
+        });
+        return started;
+    }
+    /**
+     * Unmount the app, sign out locally and remove the local database. Pass to
+     * `wipeAllData({ beforeWipe })` from `@wells-nelson/interactions` for a dev "start over".
+     */
+    async function resetDevice() {
+        // Unmount first so no live query is still reading the databases being removed.
+        app.ready = false;
+        await tick();
+        try {
+            await cloud.signOut();
+        }
+        catch (err) {
+            console.warn('Sign-out during reset failed', err);
+        }
+        const local = app.local;
+        app.local = null;
+        await local?.db.remove();
+    }
+    return { config, roles, app, cloud, tombstones, prefs, supabase, ops, init, resetDevice };
+}

package/dist/supabase.d.ts

@@ -0,0 +1,45 @@
+import { type SupabaseClient } from '@supabase/supabase-js';
+import type { EnvConfig } from './env.js';
+import type { Role } from './types.js';
+export interface MembersConfig {
+    /** Membership table, e.g. 'project_members'. */
+    table: string;
+    /** Column holding the container id, e.g. 'project_id'. */
+    containerField: string;
+    /** RPC returning a container's members with their active/pending state, e.g. 'get_project_members'. */
+    membersRpc: string;
+    /** The RPC's container id parameter (default `p_<containerField>`). */
+    rpcParam?: string;
+    /** Members carry a viewer / editor / owner role. */
+    roles: boolean;
+    /** Singular container noun for error messages, e.g. 'project'. */
+    noun: string;
+}
+export interface Member {
+    id: string;
+    email: string;
+    /** True when the email belongs to a registered user; false means the invite is pending. */
+    active: boolean;
+    /** Only when roles are on. */
+    role?: Role | null;
+}
+export interface SupabaseApi {
+    readonly configured: boolean;
+    /** The shared client (PKCE, created on first use), or null in local-only mode. */
+    getClient(): SupabaseClient | null;
+    fetchMembers(containerId: string): Promise<Member[]>;
+    inviteMember(containerId: string, email: string, role?: Role): Promise<void>;
+    setMemberRole(memberId: string, role: Role): Promise<void>;
+    removeMember(memberId: string): Promise<void>;
+    /** Remove the signed-in user's own membership. */
+    leave(containerId: string, email: string): Promise<void>;
+    /** Every container the user belongs to, with their role (null without roles). */
+    fetchMyMemberships(email: string): Promise<Map<string, Role | null>>;
+}
+/** Turn Postgres errors from triggers / RLS into messages a person can act on. */
+export declare function friendlyError(error: {
+    message: string;
+    code?: string;
+}, noun: string): Error;
+/** Supabase client plus the members API, with table and RPC names from `members`. */
+export declare function createSupabaseApi(env: EnvConfig, members: MembersConfig): SupabaseApi;

package/dist/supabase.js

@@ -0,0 +1,77 @@
+import { createClient } from '@supabase/supabase-js';
+/** Turn Postgres errors from triggers / RLS into messages a person can act on. */
+export function friendlyError(error, noun) {
+    if (error.message.includes('last owner')) {
+        return new Error(`A ${noun} must always have at least one owner. Make someone else an owner first.`);
+    }
+    if (error.code === '42501')
+        return new Error(`You don't have permission to do that on this ${noun}.`);
+    if (error.code === '23505')
+        return new Error(`That email already has access to this ${noun}.`);
+    return new Error(error.message);
+}
+/** Supabase client plus the members API, with table and RPC names from `members`. */
+export function createSupabaseApi(env, members) {
+    let client = null;
+    const { table, containerField, membersRpc, roles, noun } = members;
+    const rpcParam = members.rpcParam ?? `p_${containerField}`;
+    function getClient() {
+        if (!env.cloudConfigured)
+            return null;
+        client ??= createClient(env.supabaseUrl, env.supabaseAnonKey, {
+            auth: { flowType: 'pkce', persistSession: true, autoRefreshToken: true, detectSessionInUrl: true }
+        });
+        return client;
+    }
+    function requireClient() {
+        const sb = getClient();
+        if (!sb)
+            throw new Error('Cloud sync is not configured.');
+        return sb;
+    }
+    const fail = (error) => {
+        if (error)
+            throw friendlyError(error, noun);
+    };
+    return {
+        configured: env.cloudConfigured,
+        getClient,
+        async fetchMembers(containerId) {
+            const { data, error } = await requireClient().rpc(membersRpc, { [rpcParam]: containerId });
+            fail(error);
+            return (data ?? []);
+        },
+        async inviteMember(containerId, email, role) {
+            const row = { [containerField]: containerId, email: email.trim().toLowerCase() };
+            if (roles)
+                row.role = role ?? 'viewer';
+            const { error } = await requireClient().from(table).insert(row);
+            fail(error);
+        },
+        async setMemberRole(memberId, role) {
+            if (!roles)
+                throw new Error('Roles are not enabled.');
+            const { error } = await requireClient().from(table).update({ role }).eq('id', memberId);
+            fail(error);
+        },
+        async removeMember(memberId) {
+            const { error } = await requireClient().from(table).delete().eq('id', memberId);
+            fail(error);
+        },
+        async leave(containerId, email) {
+            const { error } = await requireClient()
+                .from(table)
+                .delete()
+                .eq(containerField, containerId)
+                .eq('email', email.toLowerCase());
+            fail(error);
+        },
+        async fetchMyMemberships(email) {
+            const columns = roles ? `${containerField}, role` : containerField;
+            const { data, error } = await requireClient().from(table).select(columns).eq('email', email.toLowerCase());
+            fail(error);
+            const rows = (data ?? []);
+            return new Map(rows.map((r) => [r[containerField], roles ? r.role : null]));
+        }
+    };
+}

package/dist/tombstones.svelte.d.ts

@@ -0,0 +1,16 @@
+import type { Location } from './types.js';
+/**
+ * Tombstones for deleted rows. A deletion hides its rows from the UI immediately (before the
+ * async delete finishes), and keeps hiding them if a sync briefly brings an older copy back.
+ * Keys include the data set, because moving a container between local and cloud keeps its ids.
+ * Entries are pruned after a week.
+ */
+export declare class Tombstones {
+    #private;
+    /** @param prefix localStorage key prefix, e.g. 'demo' (stored as `demo:hidden`). */
+    constructor(prefix: string);
+    has(location: Location, id: string): boolean;
+    hide(location: Location, ids: string[]): void;
+    /** Rows written again on purpose (e.g. a container moved back to this data set) become visible. */
+    unhide(location: Location, ids: string[]): void;
+}

package/dist/tombstones.svelte.js

@@ -0,0 +1,45 @@
+import { Persisted } from './persisted.svelte.js';
+const KEEP_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Tombstones for deleted rows. A deletion hides its rows from the UI immediately (before the
+ * async delete finishes), and keeps hiding them if a sync briefly brings an older copy back.
+ * Keys include the data set, because moving a container between local and cloud keeps its ids.
+ * Entries are pruned after a week.
+ */
+export class Tombstones {
+    #ids;
+    /** @param prefix localStorage key prefix, e.g. 'demo' (stored as `demo:hidden`). */
+    constructor(prefix) {
+        this.#ids = new Persisted(`${prefix}:hidden`, {});
+        const cutoff = Date.now() - KEEP_MS;
+        const kept = Object.fromEntries(Object.entries(this.#ids.value).filter(([, t]) => t > cutoff));
+        if (Object.keys(kept).length !== Object.keys(this.#ids.value).length)
+            this.#ids.value = kept;
+    }
+    has(location, id) {
+        return `${location}:${id}` in this.#ids.value;
+    }
+    hide(location, ids) {
+        if (ids.length === 0)
+            return;
+        const next = { ...this.#ids.value };
+        const t = Date.now();
+        for (const id of ids)
+            next[`${location}:${id}`] = t;
+        this.#ids.value = next;
+    }
+    /** Rows written again on purpose (e.g. a container moved back to this data set) become visible. */
+    unhide(location, ids) {
+        const next = { ...this.#ids.value };
+        let changed = false;
+        for (const id of ids) {
+            const key = `${location}:${id}`;
+            if (key in next) {
+                delete next[key];
+                changed = true;
+            }
+        }
+        if (changed)
+            this.#ids.value = next;
+    }
+}