@spooky-sync/core 0.0.1-canary.280 → 0.0.1-canary.281

package/dist/types.d.ts

@@ -1,5 +1,6 @@
-import { QueryPlan, QueryPlan as QueryPlan$1, RecordId, SchemaStructure, WhereNode } from "@spooky-sync/query-builder";
-import { Level as Level$1, LoggerOptions } from "pino";
+import { AccessDefinition, ColumnSchema, QueryPlan, QueryPlan as QueryPlan$1, RecordId, SchemaStructure, TypeNameToTypeMap, WhereNode } from "@spooky-sync/query-builder";
+import { RecordId as RecordId$1, Surreal, SurrealEvents, SurrealTransaction } from "surrealdb";
+import { Level, Level as Level$1, Logger, LoggerOptions } from "pino";
 
 //#region src/modules/auth/impersonation.d.ts
 
@@ -480,6 +481,734 @@ type LocalEngineChoice = 'surrealdb' | 'sqlite' | LocalStore;
 /** Thrown when relation decomposition nests past {@link MAX_RELATION_DEPTH} —
  *  a guard against a cyclic schema producing unbounded fan-out. */
 //#endregion
+//#region src/services/logger/index.d.ts
+type Logger$1 = Logger;
+//#endregion
+//#region src/services/database/database.d.ts
+declare abstract class AbstractDatabaseService {
+  protected client: Surreal;
+  protected logger: Logger$1;
+  protected events: DatabaseEventSystem;
+  /**
+   * Per-query deadline in ms; `0` disables. The remote service sets it from
+   * `queryTimeoutMs` (see `RemoteDatabaseService`), the local one from
+   * `localOpTimeoutMs` (see `LocalDatabaseService`): a local query can be
+   * legitimately slow, but it must never be endless - every query waits on the
+   * previous link of {@link query}'s chain, and one that never settled wedged
+   * every later local op behind it.
+   */
+  protected queryTimeoutMs: number;
+  /** The error a deadline expiry rejects with; the local service substitutes
+   *  its typed `LocalOpTimeoutError`. "timed out" in the message is
+   *  load-bearing either way: `classifySyncError` keys off it. */
+  protected timeoutError(_query: string): Error;
+  protected abstract eventType: typeof DatabaseEventTypes.LocalQuery | typeof DatabaseEventTypes.RemoteQuery;
+  constructor(client: Surreal, logger: Logger$1, events: DatabaseEventSystem);
+  abstract connect(): Promise<void>;
+  getClient(): Surreal;
+  getEvents(): DatabaseEventSystem;
+  tx(): Promise<SurrealTransaction>;
+  /**
+   * How many statements may be in flight at once.
+   *
+   * `1` serializes every statement behind the previous one. The local engines
+   * need that: overlapping ops trip the WASM / SQLite transaction layer. The
+   * remote service raises it (`RemoteDatabaseService`): a SurrealDB socket
+   * multiplexes requests by id, and serializing them capped the client at one
+   * statement per round trip (~5/s at 170ms RTT), so the `_00_list_ref` poll
+   * alone could hold every registration behind it and one slow one-shot read
+   * stalled the whole client. The scheduler's `MAX_CONCURRENT_DOWN` only means
+   * something when this is above 1.
+   */
+  protected maxConcurrentQueries: number;
+  private inFlightQueries;
+  private queryWaiters;
+  /** FIFO slot acquisition, so `maxConcurrentQueries = 1` keeps strict order. */
+  private acquireQuerySlot;
+  private releaseQuerySlot;
+  /**
+   * Hook run right before a statement is sent, inside its slot. The remote
+   * service uses it to hold statements while a connect is in flight, so a
+   * query never runs on a socket that is open but has not had its namespace
+   * and token applied yet. The default does nothing.
+   */
+  protected beforeQuery(): Promise<void>;
+  /**
+   * Execute a statement under {@link maxConcurrentQueries}.
+   *
+   * A statement that never settles would hold its slot forever, and with a
+   * limit of 1 that blocks every later statement behind it. {@link
+   * queryTimeoutMs} bounds each one: on expiry this promise rejects and the
+   * slot is released, even though the underlying RPC is still parked in the
+   * SDK's pending map.
+   */
+  query<T extends unknown[]>(query: string, vars?: Record<string, unknown>): Promise<T>;
+  /**
+   * Like {@link query} but never rejects on a statement error: every
+   * statement answers on its own as `{ status: 'OK', result }` or
+   * `{ status: 'ERR', error }`. This is what lets a batched outbox push judge
+   * each mutation separately.
+   */
+  queryResponses(query: string, vars?: Record<string, unknown>): Promise<Array<{
+    status: 'OK';
+    result: unknown;
+  } | {
+    status: 'ERR';
+    error: string;
+  }>>;
+  private runStatement;
+  execute<T>(query: SealedQuery<T>, vars?: Record<string, unknown>): Promise<T>;
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/services/database/remote.d.ts
+/** Transport events the SDK publishes, mapped 1:1 to {@link ConnectionState}. */
+type RemoteConnectionEvent = ConnectionState | 'error';
+declare class RemoteDatabaseService extends AbstractDatabaseService {
+  private config;
+  protected eventType: "DATABASE_REMOTE_QUERY";
+  private readonly reconnectConfig;
+  /**
+   * In-flight `connect()`, so concurrent callers (boot + supervisor revive +
+   * an `online` event landing at the same moment) share one attempt instead of
+   * racing two sockets. Cleared on settle, so a later call always reconnects.
+   */
+  private connecting;
+  /**
+   * The token to re-authenticate a freshly opened socket with, kept current by
+   * {@link setAuthToken}.
+   *
+   * `config.token` is fixed at construction and most apps never set it: they
+   * sign in later, which authenticates the socket that happens to be open at
+   * the time. That is enough for the SDK's OWN reconnects (it replays
+   * `version`/`use`/`authenticate` itself), but not for the supervisor's revive
+   * loop, which builds a socket from scratch. Without this the revived socket
+   * came back UNAUTHENTICATED and stayed that way for the life of the page,
+   * while the client's `currentUserId` — restored from local storage — kept
+   * reporting the user as signed in.
+   *
+   * The visible damage is silent and total: `fn::query::register` sends
+   * `<string>($auth.id OR '')`, so every view registered afterwards is stamped
+   * with an empty identity, and every `$auth.id` predicate in it resolves
+   * false. Public tables keep returning rows while everything owned by the user
+   * returns nothing, on a page that still looks signed in.
+   */
+  private authToken;
+  constructor(config: Sp00kyConfig<any>['database'], logger: Logger$1);
+  getConfig(): Sp00kyConfig<any>['database'];
+  /**
+   * Send one SurrealQL statement so that it survives the page going away.
+   *
+   * A WebSocket `send()` during `pagehide` is not guaranteed to flush — the
+   * browser may tear the socket down first, and the frame is simply lost.
+   * Measured: an unload-time release over the live socket reached the server
+   * zero times out of one. `fetch` with `keepalive` is the primitive the
+   * platform actually guarantees here, so this goes over SurrealDB's HTTP
+   * `/sql` endpoint instead of the RPC socket.
+   *
+   * Best-effort by design: no await, no retry, errors swallowed. Every caller
+   * must have a server-side fallback that makes a lost beacon a non-event.
+   */
+  beaconSql(sql: string): void;
+  /**
+   * Record the token every future connect should authenticate with, or `null`
+   * on sign-out. See {@link authToken}.
+   *
+   * Does not touch the CURRENT socket: callers authenticate that themselves
+   * (sign-in and session restore both already do). This only makes the next
+   * from-scratch connect reproduce that state.
+   */
+  setAuthToken(token: string | null): void;
+  /** Resolved reconnect tunables; the supervisor reads its own knobs here. */
+  getReconnectConfig(): Required<ReconnectConfig>;
+  /** Current transport state as reported by the SDK. */
+  getStatus(): ConnectionState;
+  /**
+   * Observe transport events. Thin passthrough so callers (the supervisor,
+   * sync, CRDT) don't have to reach through `getClient()`.
+   */
+  subscribeConnection<K extends RemoteConnectionEvent>(event: K, cb: (...payload: SurrealEvents[K]) => void): () => void;
+  /**
+   * Tear the socket down on purpose. Used by the heartbeat watchdog when a
+   * socket stops answering but never closes: `close()` makes the SDK publish
+   * `disconnected`, which is what drives the supervisor's revive loop.
+   */
+  forceClose(): Promise<void>;
+  /**
+   * Hold statements while a connect is in flight.
+   *
+   * `connect()` opens the socket, then selects the namespace/database, then
+   * authenticates - three round trips. The SDK considers the connection ready
+   * after the first, so a query queued during the other two ran on a socket
+   * with no namespace ("Specify a namespace to use") or, worse, no identity.
+   * Seen 2026-09-06 after the supervisor rebuilt a socket: a collection
+   * recount failed with exactly that error. Waiting on the in-flight connect
+   * costs nothing when no connect is running; a failed connect is not
+   * swallowed here - the query then fails on its own, as before.
+   */
+  protected beforeQuery(): Promise<void>;
+  /**
+   * Open (or re-open) the remote connection.
+   *
+   * Safe to call repeatedly: concurrent calls share the in-flight attempt, and
+   * a call after a `disconnected` builds a fresh socket. `use()` and
+   * `authenticate()` are re-applied here for the cold path; the SDK also
+   * replays them itself on its own internal reconnects.
+   */
+  connect(): Promise<void>;
+  private doConnect;
+  signin(params: any): Promise<any>;
+  signup(params: any): Promise<any>;
+  authenticate(token: string): Promise<any>;
+  invalidate(): Promise<void>;
+}
+//#endregion
+//#region src/modules/auth/events/index.d.ts
+declare const AuthEventTypes: {
+  readonly AuthStateChanged: "AUTH_STATE_CHANGED";
+  readonly ImpersonationChanged: "IMPERSONATION_CHANGED";
+};
+type AuthEventTypeMap = {
+  [AuthEventTypes.AuthStateChanged]: EventDefinition<typeof AuthEventTypes.AuthStateChanged, string | null>;
+  [AuthEventTypes.ImpersonationChanged]: EventDefinition<typeof AuthEventTypes.ImpersonationChanged, ImpersonationInfo | null>;
+};
+type AuthEventSystem = EventSystem<AuthEventTypeMap>;
+declare function createAuthEventSystem(): AuthEventSystem;
+//#endregion
+//#region src/modules/auth/index.d.ts
+/** What `fn::_00_impersonate::list_users` returns per row. */
+interface ImpersonationCandidate {
+  id: string;
+  is_admin: boolean;
+  [field: string]: unknown;
+}
+/** An open session, as `fn::_00_impersonate::active` lists it. */
+interface ActiveImpersonation {
+  session: string;
+  target: string;
+  admin: string;
+  reason: string;
+  started_at: unknown;
+  expires_at: unknown;
+}
+/** What a sign-out hook sees: the session that is about to end. */
+interface SignOutContext {
+  /** `table:id` of the signed-in record, or null. */
+  userId: string | null;
+  token: string | null;
+  /** The session is an admin impersonation (its token is the target's). */
+  impersonating: boolean;
+}
+type SignOutHook = (ctx: SignOutContext) => Promise<void> | void;
+/** Upper bound on the before-sign-out hooks, so a dead socket never holds a sign-out. */
+declare const SIGN_OUT_HOOK_TIMEOUT_MS = 2000;
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+type MapColumnType<T extends ColumnSchema> = T['optional'] extends true ? TypeNameToTypeMap[T['type']] | undefined : TypeNameToTypeMap[T['type']];
+type ExtractAccessParams<S extends SchemaStructure, Name extends keyof S['access'], Method extends 'signIn' | 'signup'> = S['access'] extends undefined ? never : S['access'][Name] extends AccessDefinition ? Prettify<{ [K in keyof S['access'][Name][Method]['params']]: MapColumnType<S['access'][Name][Method]['params'][K]> }> : never;
+declare class AuthService<S extends SchemaStructure> {
+  private schema;
+  private remote;
+  private persistenceClient;
+  private logger;
+  token: string | null;
+  currentUser: any | null;
+  isAuthenticated: boolean;
+  /**
+   * The record-access method name for the current session (e.g. `"account"`),
+   * derived from the token's `AC` claim. Consumed by the in-browser SSP's
+   * permission injection so `$access`-gated table predicates resolve locally,
+   * mirroring the server's `$access`. Null when logged out.
+   */
+  access: string | null;
+  isLoading: boolean;
+  private events;
+  private signOutHooks;
+  /** The impersonation last announced, for change detection. */
+  private announcedImpersonation;
+  /** Target of an impersonation that just ended, until the client purges its
+   *  local bucket (see `consumeEndedImpersonation`). */
+  private endedImpersonationTarget;
+  private impersonationTimers;
+  get eventSystem(): AuthEventSystem;
+  constructor(schema: S, remote: RemoteDatabaseService, persistenceClient: PersistenceClient, logger: Logger$1);
+  init(): Promise<void>;
+  getAccessDefinition<Name extends keyof S['access']>(name: Name): AccessDefinition | undefined;
+  /**
+   * Subscribe to auth state changes.
+   * callback is called immediately with current value and whenever validation status changes.
+   */
+  subscribe(cb: (userId: string | null) => void): () => void;
+  /**
+   * Run `hook` at the start of every sign-out, while the token and the socket
+   * still belong to the leaving user (Web Push removes this device's
+   * subscription here). Hooks are best-effort: they run in parallel, errors
+   * are swallowed, and the sign-out goes on after
+   * {@link SIGN_OUT_HOOK_TIMEOUT_MS} whatever they are doing. Returns a disposer.
+   */
+  onBeforeSignOut(hook: SignOutHook): () => void;
+  private runSignOutHooks;
+  private notifyListeners;
+  /**
+   * The impersonation the current session is, or null. Derived from the
+   * token in use, so it always describes the identity the server sees.
+   */
+  get impersonation(): ImpersonationInfo | null;
+  /** Subscribe to impersonation changes; called immediately with the current value. */
+  subscribeImpersonation(cb: (info: ImpersonationInfo | null) => void): () => void;
+  /**
+   * Act as `targetId` (a record id such as `user:abc`). Admins only, and only
+   * when the project enabled `impersonation` in sp00ky.yml: the server refuses
+   * everything else. `reason` is recorded in the audit log.
+   *
+   * The admin's session is kept aside and restored by
+   * {@link stopImpersonating}. Local data switches to the target's bucket
+   * exactly as on a sign-in, and that bucket is removed on stop.
+   */
+  impersonate(targetId: string, reason: string): Promise<ImpersonationInfo>;
+  /**
+   * Return to the admin session. Always leaves the impersonated identity,
+   * even when the server cannot be reached: the admin token is restored
+   * locally first and verified afterwards, and a rejected admin token ends in
+   * a full sign-out rather than staying on the target.
+   */
+  stopImpersonating(opts?: {
+    serverEnded?: boolean;
+  }): Promise<void>;
+  /** Re-sign the impersonation token before it expires. */
+  renewImpersonation(): Promise<void>;
+  /** Users an admin may pick from. Admin-only on the server. */
+  searchImpersonationTargets(search: string): Promise<ImpersonationCandidate[]>;
+  /** Open impersonation sessions. Admin-only on the server. */
+  listActiveImpersonations(): Promise<ActiveImpersonation[]>;
+  /**
+   * The target of an impersonation that ended, once. The bucket switch calls
+   * this after leaving a bucket so it can delete that user's local data.
+   */
+  consumeEndedImpersonation(): string | null;
+  /**
+   * Restore a session from the locally cached JWT, with NO network.
+   *
+   * This is what makes a warm boot paint instantly and what makes an offline
+   * boot possible at all: the token is in local storage, and it already carries
+   * both the access method and the `$auth.id` record id. Everything the client
+   * needs to route queries (`setCurrentUserId`) and to satisfy `$auth`-gated
+   * permission predicates in the in-browser SSP (`setSessionAuth`) is therefore
+   * available before a socket exists.
+   *
+   * The session is OPTIMISTIC: the token is unverified here. `check()` runs
+   * afterwards in the background and downgrades to a real sign-out if the
+   * server rejects it. Nothing is trusted that the server has not also seen -
+   * the local store only ever holds rows the server previously sent.
+   *
+   * Returns the restored user id, or null when there is no usable token.
+   */
+  restoreSessionFromToken(): Promise<string | null>;
+  /**
+   * Check for existing session and validate
+   */
+  check(accessToken?: string): Promise<void>;
+  /**
+   * The server refused `token`. A refused impersonation token (stopped,
+   * expired, or revoked) returns to the admin session instead of signing the
+   * admin out; anything else signs out.
+   */
+  private rejectToken;
+  /**
+   * Sign out and clear session. While impersonating this ends the
+   * impersonation and signs the admin out too.
+   */
+  signOut(): Promise<void>;
+  private setSession;
+  /** Fallback when the token carries no `AC` claim: if the schema defines
+   *  exactly one record-access method, assume the session used it. */
+  private defaultAccessName;
+  signUp<Name extends keyof S['access'] & string>(accessName: Name, params: ExtractAccessParams<S, Name, 'signup'>): Promise<void>;
+  signIn<Name extends keyof S['access'] & string>(accessName: Name, params: ExtractAccessParams<S, Name, 'signIn'>): Promise<void>;
+}
+//#endregion
+//#region src/push/types.d.ts
+/**
+ * Web Push wire types shared by the page (`db.webPush`), the service worker
+ * bridge (`@spooky-sync/core/sw`) and the live feed. Pure: types plus a few
+ * dependency-free helpers, safe in any context.
+ *
+ * `PushPayload` mirrors `packages/push-core/src/config.rs` (`PushPayload`,
+ * `PayloadKind`, `Op`, `NotificationTemplate`). Keep the two in step.
+ */
+/** Payload format version this build understands. */
+declare const PUSH_PAYLOAD_VERSION = 1;
+type PushPayloadKind = 'rule' | 'message';
+type PushOp = 'create' | 'update' | 'delete';
+type PushUrgency = 'very-low' | 'low' | 'normal' | 'high';
+/** One button on a notification (`NotificationAction` plus a per-action `url`). */
+interface PushNotificationAction {
+  action: string;
+  title: string;
+  icon?: string;
+  /** Opened instead of the notification's `url` when this action is clicked. */
+  url?: string;
+  [key: string]: unknown;
+}
+/**
+ * What a content push shows. Every key other than `title` and `url` is passed
+ * to `showNotification` as is, unknown ones included (`vibrate`, `timestamp`,
+ * whatever a browser adds later).
+ */
+interface PushNotification {
+  title?: string;
+  body?: string;
+  icon?: string;
+  badge?: string;
+  image?: string;
+  lang?: string;
+  dir?: string;
+  /** Defaults to the push's `topic`. */
+  tag?: string;
+  /** Opened (or focused) on click. */
+  url?: string;
+  requireInteraction?: boolean;
+  renotify?: boolean;
+  silent?: boolean;
+  actions?: PushNotificationAction[];
+  /** Merged into the notification's `data` next to the bridge's own keys. */
+  data?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+/**
+ * The JSON every push carries (then RFC 8291 encrypted). `notification`
+ * present: a content push the service worker shows as is. Absent: a
+ * content-free nudge, the app renders from its own data.
+ */
+interface PushPayload {
+  v: number;
+  kind: PushPayloadKind;
+  /** Rule name (`kind: 'rule'`). */
+  rule?: string;
+  /** `_00_push_message` id (`kind: 'message'`). */
+  message?: string;
+  /** The row that fired the rule. */
+  table?: string;
+  id?: string;
+  op?: PushOp;
+  topic?: string;
+  notification?: PushNotification;
+  data?: Record<string, unknown>;
+  /** Epoch ms when the engine built it. */
+  ts: number;
+}
+/** Page -> service worker: the session to use for live rendering. */
+interface BridgeTokenMessage {
+  type: 'sp00ky:token';
+  token: string;
+  userId: string;
+  /** The SurrealDB endpoint (`wss://host/rpc`), not the push endpoint. */
+  endpoint: string;
+  namespace: string;
+  database: string;
+  /** VAPID public key (base64url) the page subscribed with, for `pushsubscriptionchange`. */
+  publicKey?: string;
+  /** This browser's push endpoint, when subscribed. */
+  pushEndpoint?: string;
+}
+/** Page -> service worker: forget the session and close every notification. */
+interface BridgeSignOutMessage {
+  type: 'sp00ky:signout';
+}
+/** Service worker -> page messages. */
+type WebPushClientMessage = /** A push arrived while this page was visible, so nothing was shown. */
+{
+  type: 'sp00ky:push';
+  payload: PushPayload;
+}
+/** A notification was clicked and the bridge was told to route in-app. */ | {
+  type: 'sp00ky:navigate';
+  url: string;
+  payload?: PushPayload;
+  action?: string;
+}
+/** The browser rotated the push subscription; the page should `sync()`. */ | {
+  type: 'sp00ky:subscriptionchange';
+  endpoint?: string;
+};
+/** `urlBase64ToUint8Array`: the VAPID key as `applicationServerKey` wants it. */
+
+/** A payload this build can act on (`v` known, `kind` set). */
+declare function isPushPayload(value: unknown): value is PushPayload;
+//#endregion
+//#region src/modules/web-push/index.d.ts
+/**
+ * `db.webPush`: this browser's Web Push subscription, on the page.
+ *
+ * Every server call is a `fn::push::*` function over the client's remote
+ * connection (see `apps/cli/src/push_tables.surql`). Nothing here touches a
+ * browser API at import time, and every method answers "unsupported" instead
+ * of throwing where there is no window, service worker or push manager
+ * (SSR, Node, workers, iOS Safari outside a home-screen app).
+ */
+interface WebPushConfig {
+  /**
+   * Registered with `navigator.serviceWorker.register(url)` when the page has
+   * no service worker yet. Leave unset when the app (or vite-plugin-pwa)
+   * registers its own.
+   */
+  serviceWorkerUrl?: string;
+  /**
+   * Reconcile this browser's subscription after sign-in (see `sync()`): a
+   * rotated key, a browser that dropped the subscription or a server row that
+   * went away are repaired without a prompt. Default `true`.
+   */
+  autoSync?: boolean;
+  /**
+   * Let `sync()` subscribe a signed-in user whenever notification permission
+   * is already granted, even if they never subscribed on this browser.
+   * Default `false`: only a user who called `subscribe()` here is restored.
+   */
+  autoResubscribe?: boolean;
+  /**
+   * Remove this device's subscription for the user on `signOut()` (before the
+   * token is dropped, bounded by a short timeout). Default `true`.
+   */
+  unsubscribeOnSignOut?: boolean;
+  /**
+   * Post the session token to the app's service worker whenever it changes,
+   * while notifications are allowed, so `@spooky-sync/core/sw` can render from
+   * live data. Never posts an impersonation token. Default `true`.
+   */
+  bridge?: boolean;
+}
+type WebPushUnsupportedReason = 'no-window' | 'insecure-context' | 'no-service-worker' | 'no-push-manager' | 'no-notification' | 'ios-not-installed';
+interface WebPushSupport {
+  supported: boolean;
+  permission: NotificationPermission | 'unsupported';
+  reason?: WebPushUnsupportedReason;
+}
+interface WebPushInfo {
+  /** A host with push on has published its key. */
+  enabled: boolean;
+  /** VAPID public key (base64url), the browser's `applicationServerKey`. */
+  publicKey?: string;
+  /** Id of that key. */
+  kid?: string;
+}
+interface WebPushDevice {
+  /** `_00_push_subscription:<id>` */
+  id: string;
+  endpoint: string;
+  /** Key id the device subscribed under. */
+  kid: string;
+  label?: string;
+  userAgent?: string;
+  /** Rule names this device receives; undefined = every rule. */
+  rules?: string[];
+  meta?: Record<string, unknown>;
+  createdAt?: Date;
+  updatedAt?: Date;
+  lastOkAt?: Date;
+  lastError?: string;
+  failures: number;
+  disabledAt?: Date;
+  disabledReason?: string;
+  /** Subscribed under the current key (pushes reach it). Undefined when unknown. */
+  current?: boolean;
+  /** This browser. */
+  thisDevice: boolean;
+}
+interface WebPushSubscribeOptions {
+  /** Defaults to the page's service worker registration (`serviceWorker.ready`). */
+  registration?: ServiceWorkerRegistration;
+  /** Shown in the device list ("Work laptop"). */
+  label?: string;
+  /** Rule names this device wants. Omitted or empty: every rule. */
+  rules?: string[];
+  /** Free-form app data about the device. */
+  meta?: Record<string, unknown>;
+  /** Ask for notification permission when it is still `default`. Default `true`. Call from a user gesture. */
+  requestPermission?: boolean;
+}
+interface WebPushUnsubscribeOptions {
+  /** Remove every device of the user, not only this one. */
+  all?: boolean;
+  /** Keep the browser's PushSubscription (only the server row goes). */
+  keepBrowserSubscription?: boolean;
+}
+interface WebPushSyncOptions {
+  registration?: ServiceWorkerRegistration;
+  /** Overrides `webPush.autoResubscribe` for this call. */
+  autoResubscribe?: boolean;
+}
+/**
+ * What `sync()` did. `ok`: nothing to repair. `resubscribed`: the browser
+ * subscription was (re)created. `registered`: the server row was re-created.
+ * The rest say why nothing happened.
+ */
+type WebPushSyncStatus = 'ok' | 'resubscribed' | 'registered' | 'unsupported' | 'signed-out' | 'impersonating' | 'permission-default' | 'permission-denied' | 'not-subscribed' | 'disabled' | 'no-registration' | 'error';
+interface WebPushUpdateOptions {
+  label?: string;
+  /** Rule names; `null` or `[]` resets the device to every rule. */
+  rules?: string[] | null;
+  meta?: Record<string, unknown>;
+}
+/** A push to yourself (`fn::push::notify`). */
+interface WebPushMessageInput {
+  /** Omit for a content-free nudge. */
+  notification?: PushNotification;
+  data?: Record<string, unknown>;
+  topic?: string;
+  urgency?: PushUrgency;
+  /** Push-service TTL, seconds. */
+  ttl?: number;
+  /** In the future: scheduled. */
+  sendAt?: Date | string | number;
+}
+interface WebPushMessage {
+  /** `_00_push_message:<id>` */
+  id: string;
+  status: string;
+  sendAt?: Date;
+  createdAt?: Date;
+}
+type WebPushErrorCode = 'unsupported' | 'signed-out' | 'impersonating' | 'disabled' | 'permission-denied' | 'permission-default' | 'no-registration' | 'not-subscribed' | 'subscribe-failed' | 'server';
+declare class WebPushError extends Error {
+  readonly code: WebPushErrorCode;
+  readonly cause?: unknown | undefined;
+  constructor(code: WebPushErrorCode, message: string, cause?: unknown | undefined);
+}
+interface WebPushAuthPort {
+  readonly token: string | null;
+  readonly currentUser: {
+    id?: unknown;
+  } | null;
+  readonly isAuthenticated: boolean;
+  readonly impersonation: unknown;
+  subscribe(cb: (userId: unknown) => void): () => void;
+  onBeforeSignOut(hook: (ctx: SignOutContext) => Promise<void> | void): () => void;
+}
+interface WebPushRemotePort {
+  query<T extends unknown[]>(sql: string, vars?: Record<string, unknown>): Promise<T>;
+}
+/** Browser globals, read at call time. Injectable for tests. */
+interface WebPushGlobals {
+  window?: unknown;
+  navigator?: Navigator & {
+    standalone?: boolean;
+  };
+  Notification?: {
+    permission: NotificationPermission;
+    requestPermission(cb?: (p: NotificationPermission) => void): Promise<NotificationPermission> | void;
+  };
+  isSecureContext?: boolean;
+  matchMedia?: (query: string) => {
+    matches: boolean;
+  };
+  PushManager?: unknown;
+}
+interface WebPushModuleDeps {
+  remote: WebPushRemotePort;
+  auth: WebPushAuthPort;
+  persistence: PersistenceClient;
+  logger: Logger$1;
+  database: {
+    endpoint?: string;
+    namespace: string;
+    database: string;
+  };
+  /** Transport state; auto-sync waits for `connected`. */
+  connection?: {
+    subscribe(cb: (state: string) => void): () => void;
+  };
+  config?: WebPushConfig;
+  globals?: () => WebPushGlobals;
+}
+declare const PUSH_ENDPOINT_KEY = "sp00ky_push_endpoint";
+/** `table:id` of a record id value, without the SDK's escaping. */
+
+/** Where Web Push can work, from the given globals. */
+declare function detectWebPushSupport(g: WebPushGlobals): WebPushSupport;
+declare class WebPushModule {
+  private readonly deps;
+  private readonly logger;
+  private readonly config;
+  private readonly globals;
+  private infoCache;
+  private lastInfo;
+  private readonly bridges;
+  private readonly disposers;
+  private syncedFor;
+  private syncTimer;
+  private attached;
+  constructor(deps: WebPushModuleDeps);
+  /**
+   * Wire sign-out, auto-sync and the token bridge. Called by the client once;
+   * a no-op beyond the sign-out hook where push is unsupported.
+   */
+  attach(): () => void;
+  dispose(): void;
+  support(): WebPushSupport;
+  /** Is push on for this deployment, and with which key. Cached; `refresh` re-reads. */
+  info(options?: {
+    refresh?: boolean;
+  }): Promise<WebPushInfo>;
+  /** This browser holds a push subscription registered for the signed-in user. No server round trip. */
+  isSubscribed(): Promise<boolean>;
+  /** The user's devices, this one marked. */
+  devices(): Promise<WebPushDevice[]>;
+  /**
+   * Ask for permission (when still `default`), subscribe this browser with the
+   * deployment's key and register it for the signed-in user. Call it from a
+   * click handler: permission prompts need a user gesture.
+   */
+  subscribe(options?: WebPushSubscribeOptions): Promise<WebPushDevice>;
+  /** Remove this device (or every device, `all`) for the signed-in user. Returns how many rows went. */
+  unsubscribe(options?: WebPushUnsubscribeOptions): Promise<number>;
+  /**
+   * Reconcile after sign-in (runs by itself with `autoSync`). Needs granted
+   * permission and a user who subscribed on this browser (or
+   * `autoResubscribe`). Repairs a missing browser subscription, one made with
+   * a rotated key, and a missing, disabled or stale server row. Never throws.
+   */
+  sync(options?: WebPushSyncOptions): Promise<WebPushSyncStatus>;
+  /** Change this device's label, rule filter or meta. */
+  update(options: WebPushUpdateOptions): Promise<WebPushDevice | null>;
+  /** Push to yourself, now or at `sendAt` (reminders). Omit `notification` for a nudge. */
+  notify(message: WebPushMessageInput): Promise<WebPushMessage>;
+  /** Cancel a scheduled message. `true` when it was still pending. */
+  cancel(id: string | RecordId$1): Promise<boolean>;
+  /** A visible test notification to every device of the user. */
+  test(options?: {
+    title?: string;
+    body?: string;
+  }): Promise<WebPushMessage>;
+  /**
+   * Post the session to the service worker now and whenever the token
+   * changes (`{ type: 'sp00ky:token', token, userId, endpoint, namespace,
+   * database }`). Never posts an impersonation token. Returns a disposer.
+   * With `webPush.bridge` (the default) this already runs while notification
+   * permission is granted.
+   */
+  bridge(registration?: ServiceWorkerRegistration): () => void;
+  /** Messages from the push service worker (`sp00ky:push` while visible, `sp00ky:navigate`, ...). */
+  onMessage(cb: (message: WebPushClientMessage) => void): () => void;
+  private userId;
+  private assertSignedIn;
+  private assertNotImpersonating;
+  private call;
+  private listRaw;
+  private register;
+  private readStored;
+  private writeStored;
+  /** The page's registration: given, existing, registered from config, or `ready` within `waitMs`. */
+  private registration;
+  /** This browser's subscription, without waiting for a worker. */
+  private currentSubscription;
+  private thisEndpoint;
+  private postToWorker;
+  private startBridge;
+  private refreshBridges;
+  private tokenMessage;
+  /** Sign-out hook: tell the worker, and drop this device's row for the user. Bounded. */
+  private beforeSignOut;
+}
+//#endregion
 //#region src/types.d.ts
 /**
  * A pino browser transmit object for forwarding logs to an external sink (e.g. OpenTelemetry).
@@ -833,6 +1562,16 @@ interface Sp00kyConfig<S extends SchemaStructure> {
    * Defaults to 30000; `0` disables the timeout.
    */
   downTimeoutMs?: number;
+  /**
+   * Web Push on this page (`client.webPush`, `db.webPush`). Everything is
+   * optional and the defaults need no service worker configuration here:
+   * `autoSync` (repair this browser's subscription after sign-in),
+   * `unsubscribeOnSignOut` (drop this device's subscription on `signOut()`),
+   * `bridge` (post the session to the service worker for live rendering) are
+   * on; `serviceWorkerUrl` registers a worker when the app does not.
+   * See the `push-notifications` docs page.
+   */
+  webPush?: WebPushConfig;
 }
 /** Tunables for sync-health reporting. See {@link Sp00kyConfig.syncHealth}. */
 interface SyncHealthConfig {
@@ -1249,4 +1988,4 @@ interface DebounceOptions {
   delay?: number;
 }
 //#endregion
-export { ORIGIN_TOKEN_KEY as $, RunOptions as A, SyncHealthStatus as B, QueryTimeToLive as C, RecordVersionArray as D, ReconnectConfig as E, StorageHealth as F, DatabaseEventTypes as G, UpdateOptions as H, StorageHealthStatus as I, EventSystem as J, SealedQuery as K, StoreType as L, Sp00kyConfig as M, Sp00kyQueryResult as N, RecordVersionDiff as O, Sp00kyQueryResultPromise as P, ImpersonationTimers as Q, SyncHealth as R, QueryStatusCallback as S, QueryUpdateCallback as T, LocalStore as U, TimingPhase as V, DatabaseEventSystem as W, ImpersonationInfo as X, IMPERSONATION_ACCESS as Y, ImpersonationTimerHost as Z, QueryConfig as _, Level$1 as a, sameImpersonation as at, QueryState as b, MutationCallback as c, PersistenceClient as d, SESSION_POLL_MS as et, PhaseStat as f, QueryAuthorityCallback as g, PreloadRefresh as h, InlineRow as i, renewDelayMs as it, ServerViewMeta as j, RegistrationTimings as k, MutationEvent as l, PreloadOptions as m, DebounceOptions as n, decodeTokenClaims as nt, MATERIALIZATION_SAMPLE_WINDOW as o, PinoTransmit as p, EventDefinition as q, EventSubscriptionOptions as r, impersonationFromToken as rt, MembershipOutcome as s, ConnectionState as t, TokenClaims as tt, MutationEventType as u, QueryConfigRecord as v, QueryTimings as w, QueryStatus as x, QueryHash as y, SyncHealthConfig as z };
+export { WebPushSupport as $, RunOptions as A, SealedQuery as At, SyncHealthStatus as B, decodeTokenClaims as Bt, QueryTimeToLive as C, AuthEventSystem as Ct, RecordVersionArray as D, RemoteDatabaseService as Dt, ReconnectConfig as E, createAuthEventSystem as Et, StorageHealth as F, ImpersonationTimerHost as Ft, WebPushDevice as G, UpdateOptions as H, renewDelayMs as Ht, StorageHealthStatus as I, ImpersonationTimers as It, WebPushInfo as J, WebPushError as K, StoreType as L, ORIGIN_TOKEN_KEY as Lt, Sp00kyConfig as M, EventSystem as Mt, Sp00kyQueryResult as N, IMPERSONATION_ACCESS as Nt, RecordVersionDiff as O, Logger$1 as Ot, Sp00kyQueryResultPromise as P, ImpersonationInfo as Pt, WebPushSubscribeOptions as Q, SyncHealth as R, SESSION_POLL_MS as Rt, QueryStatusCallback as S, SignOutHook as St, QueryUpdateCallback as T, AuthEventTypes as Tt, PUSH_ENDPOINT_KEY as U, sameImpersonation as Ut, TimingPhase as V, impersonationFromToken as Vt, WebPushConfig as W, WebPushMessageInput as X, WebPushMessage as Y, WebPushModule as Z, QueryConfig as _, ActiveImpersonation as _t, Level$1 as a, detectWebPushSupport as at, QueryState as b, SIGN_OUT_HOOK_TIMEOUT_MS as bt, MutationCallback as c, PUSH_PAYLOAD_VERSION as ct, PersistenceClient as d, PushOp as dt, WebPushSyncOptions as et, PhaseStat as f, PushPayload as ft, QueryAuthorityCallback as g, isPushPayload as gt, PreloadRefresh as h, WebPushClientMessage as ht, InlineRow as i, WebPushUpdateOptions as it, ServerViewMeta as j, EventDefinition as jt, RegistrationTimings as k, LocalStore as kt, MutationEvent as l, PushNotification as lt, PreloadOptions as m, PushUrgency as mt, DebounceOptions as n, WebPushUnsubscribeOptions as nt, MATERIALIZATION_SAMPLE_WINDOW as o, BridgeSignOutMessage as ot, PinoTransmit as p, PushPayloadKind as pt, WebPushErrorCode as q, EventSubscriptionOptions as r, WebPushUnsupportedReason as rt, MembershipOutcome as s, BridgeTokenMessage as st, ConnectionState as t, WebPushSyncStatus as tt, MutationEventType as u, PushNotificationAction as ut, QueryConfigRecord as v, AuthService as vt, QueryTimings as w, AuthEventTypeMap as wt, QueryStatus as x, SignOutContext as xt, QueryHash as y, ImpersonationCandidate as yt, SyncHealthConfig as z, TokenClaims as zt };