@carlonicora/nextjs-jsonapi 6.20.4 → 6.20.6

package/dist/offline/index.d.mts

@@ -1,767 +0,0 @@
-type GetterKeys<T> = {
-    [K in keyof T]: T[K] extends () => any ? never : K;
-}[keyof T];
-type FieldSelector<T> = {
-    type: string;
-    fields: ReadonlyArray<GetterKeys<T>>;
-};
-
-type ApiRequestDataTypeInterface = {
-    name: string;
-    cache?: string;
-    inclusions?: Record<string, {
-        types?: string[];
-        fields?: FieldSelector<any>[];
-        include?: string[];
-    }>;
-    model: new () => any;
-};
-
-interface JsonApiHydratedDataInterface {
-    jsonApi: any;
-    included: any[];
-    allData?: any[];
-}
-
-interface ApiDataInterface {
-    get included(): any[];
-    get type(): string;
-    get id(): string;
-    get createdAt(): Date;
-    get updatedAt(): Date;
-    get self(): string | undefined;
-    get jsonApi(): any;
-    get identifier(): string;
-    generateApiUrl(params?: any): string;
-    dehydrate(): JsonApiHydratedDataInterface;
-    rehydrate(data: JsonApiHydratedDataInterface): this;
-    createJsonApi(data: any): any;
-}
-
-type OfflineChangeResolution = {
-    kind: "mine" | "merged";
-    /** Per conflicting field: whose value wins. */
-    choices?: Record<string, "mine" | "theirs" | "merged">;
-    /** The model-built JSON:API document holding only the fields chosen "merged", with their hand-merged values. */
-    mergedBody?: Record<string, unknown>;
-};
-
-type StoredRecord = {
-    type: string;
-    id: string;
-    rootId: string;
-    resource: any;
-    updatedAt: Date | null;
-    base: any | null;
-    localOnly: boolean;
-};
-type StoredLink = {
-    fromType: string;
-    fromId: string;
-    toType: string;
-    toId: string;
-    kind: string;
-    props: Record<string, unknown>;
-};
-type QueueStatus = "pending" | "sending" | "conflict" | "failed";
-/** The `resolution` of a server-side `OfflineChange` (C1b): kind, per-field choices, merged body. */
-type QueueResolution = OfflineChangeResolution;
-type QueueEntry = {
-    seq: number;
-    rootId: string;
-    method: OfflineMethod;
-    path: string;
-    body?: any;
-    recordType?: string;
-    recordId?: string;
-    base: any | null;
-    resolution?: QueueResolution;
-    createdAt: Date;
-    status: QueueStatus;
-    /**
-     * The id of the package (`offline-change-sets`) the entry was last sent in, kept until the
-     * server answers for it: a package that never got its answer is sent again with the same id,
-     * so the server applies it once.
-     */
-    packageId?: string;
-};
-type ConflictKind = "fields" | "deleted-on-server" | "changed-on-server" | "could-not-apply";
-type Conflict = {
-    id: string;
-    queueSeq: number;
-    kind: ConflictKind;
-    recordType?: string;
-    recordId?: string;
-    mine: any;
-    theirs: any;
-    base: any;
-    /** The merge the server settled, as a resource: its current resource with the merged attributes. */
-    merged?: any;
-    fields: string[];
-    blocks?: Record<string, string[]>;
-    reason?: string;
-};
-type SyncState = {
-    serverTime: Date | null;
-    locked: boolean;
-    lockedFrom: Date | null;
-};
-/** A record a sync could not read (403/404, or absent from the answer), with its `updatedAt` then. */
-type SkippedRecord = {
-    type: string;
-    id: string;
-    updatedAt: Date;
-};
-interface DeviceStore {
-    getRecord(type: string, id: string): Promise<StoredRecord | undefined>;
-    /** With `rootId`: every record that root record uses, shared records included. */
-    listRecords(filter: {
-        type: string;
-        rootId?: string;
-        ids?: string[];
-    }): Promise<StoredRecord[]>;
-    putRecord(record: Omit<StoredRecord, "base" | "localOnly"> & {
-        base?: any | null;
-        localOnly?: boolean;
-    }): Promise<void>;
-    /** Removes the record (every root record's copy) and every link from or to it. */
-    deleteRecord(type: string, id: string): Promise<void>;
-    /**
-     * The record leaves `rootId`. A shared record (an artwork, a template) that another
-     * root record still uses is kept for that root record; it is deleted only when no root record keeps it.
-     */
-    removeRecordFromRoot(type: string, id: string, rootId: string): Promise<void>;
-    linksFrom(fromId: string, kind?: string): Promise<StoredLink[]>;
-    linksTo(toId: string, kind?: string): Promise<StoredLink[]>;
-    replaceRootLinks(rootId: string, links: StoredLink[]): Promise<void>;
-    putLink(link: StoredLink): Promise<void>;
-    deleteLink(link: Pick<StoredLink, "fromId" | "toId" | "kind">): Promise<void>;
-    enqueue(entry: Omit<QueueEntry, "seq" | "createdAt" | "status">): Promise<number>;
-    queue(filter?: {
-        status?: QueueStatus;
-    }): Promise<QueueEntry[]>;
-    setQueueStatus(seq: number, status: QueueStatus): Promise<void>;
-    /** Stores (or with `null` clears) the package id of the given entries. */
-    setQueuePackage(seqs: number[], packageId: string | null): Promise<void>;
-    removeQueueEntry(seq: number): Promise<void>;
-    addConflict(c: Omit<Conflict, "id">): Promise<string>;
-    conflicts(): Promise<Conflict[]>;
-    removeConflict(id: string): Promise<void>;
-    getSyncState(rootId: string): Promise<SyncState>;
-    /** The store writes ISO strings and parses them back with `new Date`. */
-    setSyncState(rootId: string, s: SyncState): Promise<void>;
-    /** The records the last sync of `rootId` skipped: asked for again only once they change. */
-    skippedRecords(rootId: string): Promise<SkippedRecord[]>;
-    /** Replaces the skipped records of `rootId`. */
-    setSkippedRecords(rootId: string, records: SkippedRecord[]): Promise<void>;
-    /**
-     * Records, links, queue, conflicts, sync_state, skipped records — kept only when its queue is empty. A shared
-     * record another root record still uses is kept for that root record.
-     */
-    removeRoot(rootId: string): Promise<void>;
-    transaction<T>(fn: (store: DeviceStore) => Promise<T>): Promise<T>;
-}
-
-/** Header of a request the server runs as an offline replay. Never answered locally. */
-declare const OFFLINE_REPLAY_HEADER = "x-offline-replay";
-type OfflineMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
-/** A Module (matched by its endpoint), a ":param" capture, or a literal segment ("playing", "merge"). */
-type PatternSegment = ApiRequestDataTypeInterface | string;
-/** `url` (beyond the contract, optional): the absolute URL the request was made to, for the `links` of a list. */
-type OfflineRequest = {
-    method: OfflineMethod;
-    path: string;
-    query: URLSearchParams;
-    body?: any;
-    url?: string;
-};
-/** `body` is a JSON:API document, `undefined` for a 204. */
-type OfflineAnswer = {
-    status: number;
-    body: any;
-};
-type LocalAnswerContext = {
-    request: OfflineRequest;
-    params: Record<string, string>;
-    store: DeviceStore;
-};
-type LocalAnswer = (ctx: LocalAnswerContext) => Promise<OfflineAnswer>;
-type OfflineRoute = {
-    method: OfflineMethod;
-    pattern: PatternSegment[];
-    answer: LocalAnswer;
-    queue: boolean;
-};
-/**
- * A type the API reads only as a list per target record: each changed record's target is the
- * other end of its sync link of `linkKind` (from the record to the target), and `endpoint`
- * builds that target's list path with `EndpointCreator`.
- */
-type OfflineLinkedListFetch = {
-    linkKind: string;
-    endpoint: (rootId: string, target: {
-        type: string;
-        id: string;
-    }) => string;
-};
-/** One more kind of root record beside `rootModule` (e.g. a notebook). Optional. */
-type OfflineRootKind = {
-    /** The module of the root records of this kind. Sync reads `{module}/:rootId/sync`. */
-    module: ApiRequestDataTypeInterface;
-    /** The ids of the roots of this kind to keep on the device. Throw to keep the device copy unchanged. */
-    listSyncRoots: () => Promise<string[]>;
-    /**
-     * Per record type, the full list endpoint (query string included) that downloads every record of
-     * that type under one root of this kind, built from the stored root record. Replaces the type's
-     * `fetch` mode under this kind only. Never given `updatedSince`.
-     */
-    typeEndpoints?: {
-        module: ApiRequestDataTypeInterface;
-        endpoint: (root: {
-            id: string;
-            resource: StoredRecord["resource"];
-        }) => string;
-    }[];
-    /** The module whose model reads this kind's sync answer. Default: the library's `RootSync` module (`root-syncs`). */
-    syncModule?: ApiRequestDataTypeInterface;
-};
-type LocalWriteBase = {
-    store: DeviceStore;
-    module: ApiRequestDataTypeInterface;
-    id: string;
-};
-/** What a generic local write (`afterLocalWrite`) did, inside its transaction. */
-type OfflineLocalWriteContext = (LocalWriteBase & {
-    method: "POST";
-    resource: StoredRecord["resource"];
-    previous: null;
-}) | (LocalWriteBase & {
-    method: "PUT" | "PATCH";
-    resource: StoredRecord["resource"];
-    previous: StoredRecord["resource"];
-}) | (LocalWriteBase & {
-    method: "DELETE";
-    resource: null;
-    previous: StoredRecord["resource"];
-});
-type OfflineTypeConfig = {
-    module: ApiRequestDataTypeInterface;
-    /**
-     * How the sync fetches the type's changed records: the root record's list (`root-list`), one
-     * GET per record (`by-id`), or (`linked-list`) the list of each record's target, found through
-     * the sync answer's links of `linkedList.linkKind` (e.g. player notes, read per target only).
-     */
-    fetch: "root-list" | "by-id" | "linked-list";
-    /** Required with `fetch: "linked-list"`. */
-    linkedList?: OfflineLinkedListFetch;
-    readOnly: boolean;
-    serverOwnedFields: string[];
-    /**
-     * Relationship name → Neo4j relationship type (`faction` → `MEMBER_OF`). A link the device
-     * writes from a request's relationships carries the mapped type, the kind synced links carry;
-     * an unmapped name is stored as the name itself.
-     */
-    relationshipKinds?: Record<string, string>;
-    /** The string attributes the server's fulltext index covers (default: every string attribute). */
-    searchFields?: string[];
-    /** The server's order with no `orderBy` (default `updatedAt DESC`). */
-    defaultOrderBy?: string;
-    /**
-     * Called by the generic POST/PUT/PATCH/DELETE local answers inside the same transaction as the
-     * write and the enqueue (a throw rolls both back). Never called by sync or write-through.
-     */
-    afterLocalWrite?: (ctx: OfflineLocalWriteContext) => Promise<void>;
-};
-type OfflineConfig = {
-    getUserId: () => string | undefined;
-    /**
-     * Offline mode is off on each device until the user turns it on (`turnOnOffline`), stored per
-     * user per device. Default (undefined/false): always on, every device keeps the copy.
-     */
-    requireOptIn?: boolean;
-    /** The module whose records own every other record (in Wyrdli, Modules.Campaign). */
-    rootModule: ApiRequestDataTypeInterface;
-    types: OfflineTypeConfig[];
-    routes: OfflineRoute[];
-    /** Ids of the root records to keep on the device. */
-    listSyncRoots: () => Promise<string[]>;
-    /** More kinds of root records beside `rootModule`, each synced and kept on its own (optional). */
-    extraRootKinds?: OfflineRootKind[];
-    shellPath: (locale: string) => string;
-    syncIntervalMs: number;
-    /**
-     * Where the device worker loads SQLite from at run time (default `/offline-sqlite/index.mjs`).
-     * SQLite is never bundled: its own helper worker uses a computed URL that app bundlers refuse.
-     * The app serves the files of `dist/offline/sqlite/` at this URL's folder.
-     */
-    sqliteModuleUrl?: string;
-    /**
-     * Where the device-copy worker is started from (default `/offline-sqlite/device-worker.mjs`).
-     * It is a standalone file in `dist/offline/sqlite/`, never bundled by the app.
-     */
-    deviceWorkerUrl?: string;
-};
-declare const DEFAULT_SQLITE_MODULE_URL = "/offline-sqlite/index.mjs";
-declare const DEVICE_WORKER_FILE = "device-worker.mjs";
-declare const DEFAULT_DEVICE_WORKER_URL = "/offline-sqlite/device-worker.mjs";
-/**
- * The files of `dist/offline/sqlite/` the app serves: the device worker and the SQLite files
- * copied from @sqlite.org/sqlite-wasm.
- */
-declare const OFFLINE_SQLITE_FILES: readonly ["device-worker.mjs", "index.mjs", "sqlite3.wasm", "sqlite3-opfs-async-proxy.js"];
-/** Thrown by a local answer for something that only the server can do. Answered as a 503 "needs-connection". */
-declare class NeedsConnectionError extends Error {
-    readonly status = 503;
-    readonly code = "needs-connection";
-    constructor(message?: string);
-}
-/** Segments joined with "/", modules by their endpoint. */
-declare function patternToString(pattern: PatternSegment[]): string;
-
-/**
- * Opts the app into offline mode (the `./offline` entry's `configureOffline`). It also registers
- * the browser device-store opener, so the store, the worker and SQLite are reachable only from
- * this entry, never from the request path every other entry shares.
- */
-declare function configureOffline(config: OfflineConfig): void;
-
-/**
- * The signed-in user's device store cannot be used: it could not be opened (opfs-sahpool holds
- * one connection per origin, so a second tab cannot open it) or the user logged out. A request
- * answered from the device copy then needs a connection (503 "needs-connection").
- */
-declare class DeviceStoreUnavailableError extends NeedsConnectionError {
-    constructor(message?: string);
-}
-/**
- * This browser cannot keep the device copy at all: not a secure context (https or `localhost`),
- * no private file storage (`navigator.storage.getDirectory`), or the worker reports the OPFS
- * APIs missing. Offline mode switches off for the page (`markOfflineUnavailable`). A failure on
- * a browser that can keep the copy (the file held by another tab) is a `DeviceStoreUnavailableError`.
- */
-declare class OfflineUnavailableError extends DeviceStoreUnavailableError {
-    constructor(reason: string);
-}
-/** Whether this browser can keep the device copy (true until found otherwise). */
-declare function isOfflineAvailable(): boolean;
-/**
- * Configured, the browser can keep the device copy (see `markOfflineUnavailable`), and offline
- * mode is on on this device for the signed-in user (see `requireOptIn`).
- */
-declare function isOfflineConfigured(): boolean;
-/**
- * Whether offline mode is on on this device for `userId`. Always true without
- * `OfflineConfig.requireOptIn`; otherwise the stored switch, false with no user.
- */
-declare function isOfflineEnabledOnDevice(userId?: string | null): boolean;
-/**
- * Reads the device switch and the last sync time of the signed-in user into the offline state
- * (`enabled`, `lastSyncedAt`). Does nothing before `configureOffline`.
- */
-declare function refreshOfflineDeviceState(): void;
-declare function getOfflineConfig(): OfflineConfig;
-/** Replaces how a user's device store is opened (tests pass `openMemoryDeviceStore`). */
-declare function setDeviceStoreOpener(opener: ((userId: string) => Promise<DeviceStore>) | null): void;
-/**
- * The signed-in user's device store, opened once per user id. Only the signed-in user's file is
- * ever opened; with no signed-in user the request needs a connection.
- */
-declare function getOfflineStore(): Promise<DeviceStore>;
-/** Forgets the opened store of a user (logout, deleted file). */
-declare function forgetOfflineStore(userId: string): void;
-
-type OfflineState = {
-    online: boolean;
-    pending: number;
-    conflicts: number;
-    draining: boolean;
-    lockedRootIds: string[];
-    /**
-     * False once this browser was found unable to keep the device copy (no secure context, no
-     * private file storage, or the worker reports the OPFS APIs missing). Offline mode is then off
-     * for the rest of the page: `isOfflineConfigured()` answers false and nothing offline runs.
-     */
-    available: boolean;
-    /**
-     * Offline mode is on on this device for the signed-in user. Always true once configured
-     * without `OfflineConfig.requireOptIn`; otherwise the GM's per-device switch.
-     */
-    enabled: boolean;
-    /** The running full sync: root records done out of the total, null when no sync runs. */
-    syncProgress: {
-        done: number;
-        total: number;
-    } | null;
-    /** When the last full sync on this device finished (epoch ms), null when never. */
-    lastSyncedAt: number | null;
-    /** How many root records the last full sync kept on this device, null when unknown. */
-    rootCount: number | null;
-};
-declare function getOfflineState(): OfflineState;
-declare function subscribeOfflineState(listener: (s: OfflineState) => void): () => void;
-/** Applies a partial change. Listeners run once, and only when a value actually changed. */
-declare function setOfflineState(patch: Partial<OfflineState>): void;
-
-declare function useOfflineState(): OfflineState;
-declare function useNeedsConnection(): boolean;
-
-type RouteMatch = {
-    route: OfflineRoute;
-    params: Record<string, string>;
-};
-declare function matchPattern(pattern: PatternSegment[], path: string): Record<string, string> | null;
-/** The first route, in the order given, whose method and pattern match. The query string is ignored. */
-declare function matchRoute(routes: OfflineRoute[], method: OfflineMethod, path: string): RouteMatch | null;
-
-type ApiData = {
-    data: any;
-    ok: boolean;
-    status: number;
-    statusText: string;
-    token?: string;
-    refreshToken?: string;
-    /** Set by `directFetch` when the API could not be reached at all (the 503 it reports). */
-    networkError?: boolean;
-};
-
-type LocalTransportRequest = {
-    method: string;
-    url: string;
-    body?: any;
-    files?: unknown;
-};
-/**
- * Answers a request from the device copy: the app's custom routes first, then the generic ones.
- * The result has the `ApiData` shape `directFetch` returns, so `translateResponse` and
- * `rehydrate()` run unchanged.
- */
-declare function localTransport(request: LocalTransportRequest): Promise<ApiData>;
-
-type WriteThroughRequest = {
-    method: string;
-    url: string;
-};
-/**
- * After a successful online write, copies the answer into the device copy so it is never behind
- * the GM's own work: the resource and its `included` for POST/PUT/PATCH, the record removed for a
- * DELETE. It never fails the request: a problem is logged and the next sync repairs the copy.
- */
-declare function writeThrough(request: WriteThroughRequest, response: ApiData): Promise<void>;
-
-/** A JSON:API errors document with one error, answered with `status`. */
-declare function errorAnswer(status: number, title: string, detail: string, code?: string): OfflineAnswer;
-declare function needsConnectionAnswer(detail?: string): OfflineAnswer;
-declare function notFoundAnswer(detail: string): OfflineAnswer;
-/** A single document of one stored record, with `included` (`includedFor`). */
-declare function singleAnswer(store: DeviceStore, record: StoredRecord, status?: number): Promise<OfflineAnswer>;
-/**
- * The `included` of a local answer: the stored records linked to `records` (the synced links),
- * then the stored records their relationships point to, and one level further the stored records
- * the relationships of those included records point to (an NPC's root record, then the root record's
- * owner), so a model reads the same nested relationships it reads from the server.
- *
- * Stored resources point at each other (a root record at its owner, the owner at the root record's
- * company, the company back at the owner); `RehydrationFactory` skips a resource met again inside
- * its own chain, so those circles never recurse.
- */
-declare function includedFor(store: DeviceStore, records: StoredRecord[]): Promise<any[]>;
-/** The server's default list order (`defineEntity` sets `defaultOrderBy: "updatedAt DESC"`). */
-declare const SERVER_DEFAULT_ORDER_BY = "updatedAt DESC";
-type ListOptions = {
-    /** The string attributes the server's fulltext index covers (default: every string attribute). */
-    searchFields?: string[];
-    /** The order with no `orderBy` (default `updatedAt DESC`, the server's). */
-    defaultOrderBy?: string;
-};
-/**
- * `search` as the server runs it: the term is split into letter/digit tokens and a record
- * matches when every token appears, case-insensitive, inside one of its indexed string
- * attributes (the fulltext query `*token* AND ...`).
- */
-declare function searchRecords(records: StoredRecord[], query: URLSearchParams, options?: ListOptions): StoredRecord[];
-/**
- * Orders records as the server's `ORDER BY` does for `orderBy` (`field` or `field ASC|DESC`),
- * or for the default order when there is none. `null` when the server would refuse the
- * `orderBy` (400).
- */
-declare function orderRecords(records: StoredRecord[], query: URLSearchParams, options?: ListOptions): StoredRecord[] | null;
-/**
- * One list answer for a set of stored records, as the server answers a list: `search`, then
- * `orderBy` (or the default order), then paged the way `JsonApiPaginator` pages (`fetchAll`,
- * `page[size]`, `page[offset]`), with `included`. App answers pass the records they selected.
- */
-declare function listAnswer(ctx: LocalAnswerContext, records: StoredRecord[], options?: ListOptions): Promise<OfflineAnswer>;
-/**
- * A list document of stored records in the order the caller settled, every record in one page,
- * with `included`: for an app's custom list query that has its own `ORDER BY` and no paging.
- */
-declare function orderedListAnswer(store: DeviceStore, records: StoredRecord[]): Promise<OfflineAnswer>;
-/**
- * A list document of resources the device computed rather than stored (a query-result
- * projection such as a search hit, built by its model), answered as they are, nothing included.
- */
-declare function resourceListAnswer(resources: any[]): OfflineAnswer;
-/**
- * The kind a link written on the device carries for relationship `name`: the Neo4j type the
- * type config maps it to (the kind synced links carry), otherwise the name itself.
- */
-declare function linkKindFor(typeConfig: OfflineTypeConfig | undefined, name: string): string;
-/**
- * Every kind a link of relationship `name` may carry on the device: the name (written on the
- * device before a mapping existed) and the mapped Neo4j type (synced). `undefined` when the
- * Neo4j type is not known: then a link of any kind may be the one.
- */
-declare function linkKindsOf(typeConfig: OfflineTypeConfig | undefined, name: string): string[] | undefined;
-/**
- * The stored links of `id` whose kind is one of `kinds` (Neo4j types and/or relationship
- * names). `out`: links from `id`; `in`: links to `id`; `both`: either.
- */
-declare function linksOfKind(store: DeviceStore, id: string, kinds: string[], direction?: "out" | "in" | "both"): Promise<StoredLink[]>;
-/** The `data` of a JSON:API document a model built (`createJsonApi()` or a dedicated method). */
-type ResourceDocumentData = {
-    attributes?: Record<string, unknown>;
-    relationships?: Record<string, unknown>;
-    meta?: Record<string, unknown>;
-};
-/**
- * The resource a create document stands for, under `identity`: the document's attributes,
- * relationships and meta, as the device stores a record it creates.
- */
-declare function resourceFromDocument(document: any, identity: {
-    type: string;
-    id: string;
-}): any;
-/**
- * A stored resource with a document's `data` written over it: attributes and relationships merged
- * by name, and meta merged when the document carries one, as the device applies an edit.
- */
-declare function mergeResource(before: any, identity: {
-    type: string;
-    id: string;
-}, data: ResourceDocumentData): any;
-
-declare abstract class AbstractApiData implements ApiDataInterface {
-    static identifierFields: string[];
-    get identifier(): string;
-    protected _jsonApi?: any;
-    protected _included?: any[];
-    protected _id?: string;
-    protected _type?: string;
-    protected _createdAt?: Date;
-    protected _updatedAt?: Date;
-    protected _self?: string;
-    get type(): string;
-    get id(): string;
-    get self(): string | undefined;
-    get createdAt(): Date;
-    get updatedAt(): Date;
-    get included(): any[];
-    get jsonApi(): any;
-    ingestJsonApi(_data: JsonApiHydratedDataInterface): void;
-    generateApiUrl(_params?: any): string;
-    createJsonApi(_data?: any): any;
-    protected _readIncluded<T extends ApiDataInterface>(data: JsonApiHydratedDataInterface, type: string, dataType: ApiRequestDataTypeInterface): T | T[] | undefined;
-    /**
-     * Read included relationships with polymorphic type resolution.
-     * Determines the correct model class based on the JSON:API type in included data.
-     */
-    protected _readIncludedPolymorphic<T extends ApiDataInterface>(data: JsonApiHydratedDataInterface, relationshipKey: string, candidateModules: ApiRequestDataTypeInterface[]): T | T[] | undefined;
-    /**
-     * Read included relationship data and augment with relationship meta properties.
-     * Handles both single relationships (one-to-one) and array relationships (one-to-many).
-     *
-     * For single relationships: meta is read from `relationships[type].meta`
-     * For array relationships: per-item meta is read from `relationships[type].data[].meta`
-     *
-     * @param data - Hydrated JSON:API data
-     * @param type - Relationship type key (e.g., "guide", "persons")
-     * @param dataType - Module reference for rehydration
-     * @returns Related object(s) augmented with meta properties, or undefined
-     */
-    protected _readIncludedWithMeta<T extends ApiDataInterface, M extends Record<string, any>>(data: JsonApiHydratedDataInterface, type: string, dataType: ApiRequestDataTypeInterface): (T & M) | (T & M)[] | undefined;
-    /**
-     * Copies relationship meta onto a rehydrated entity as own data properties. Object.assign throws
-     * when the model declares a getter-only accessor of the same name (an app's `Chunk` with
-     * `get relevance()`); an own property shadows that getter, so the model reads the meta value.
-     */
-    private static _mergeMeta;
-    dehydrate(): JsonApiHydratedDataInterface;
-    rehydrate(data: JsonApiHydratedDataInterface): this;
-}
-
-type RootSyncEntry = {
-    type: string;
-    id: string;
-    updatedAt: Date;
-};
-type RootSyncLink = {
-    fromType: string;
-    fromId: string;
-    toType: string;
-    toId: string;
-    kind: string;
-    props: Record<string, unknown>;
-};
-interface RootSyncInterface extends ApiDataInterface {
-    get serverTime(): Date;
-    get locked(): boolean;
-    get lockedFrom(): Date | undefined;
-    get entries(): RootSyncEntry[];
-    get links(): RootSyncLink[];
-}
-
-/** The sync answer for one root record (`root-syncs`, id = root record id). Read-only. */
-declare class RootSync extends AbstractApiData implements RootSyncInterface {
-    private _serverTime?;
-    private _locked;
-    private _lockedFrom?;
-    private _entries?;
-    private _links?;
-    get serverTime(): Date;
-    get locked(): boolean;
-    get lockedFrom(): Date | undefined;
-    get entries(): RootSyncEntry[];
-    get links(): RootSyncLink[];
-    rehydrate(data: JsonApiHydratedDataInterface): this;
-    createJsonApi(_data?: any): any;
-}
-
-/**
- * Opens the device copy of `userId` (`nja-offline-<userId>.sqlite3` in the OPFS,
- * through the worker). Only one user's file is open at a time: opening another
- * user's file closes the previous one first.
- */
-declare function openDeviceStore(userId: string): Promise<DeviceStore>;
-/** The same store and schema over an in-memory database, for tests. */
-declare function openMemoryDeviceStore(): Promise<DeviceStore>;
-/**
- * Closes `userId`'s device copy in every page and removes every OPFS entry of it. The files can
- * only be removed once no page holds them, so the removal waits for every page to let go.
- */
-declare function deleteDeviceStore(userId: string): Promise<void>;
-/** Whether `userId`'s device copy holds unsent changes. Never opens another user's file. */
-declare function hasUnsentChanges(userId: string): Promise<boolean>;
-/**
- * A user signed in on this browser: their device copy may be opened again (it is blocked after
- * a logout), and every other user's device copy is deleted when it has nothing unsent, and kept
- * untouched (never opened) when it has. When the images cache was not this user's (another user
- * signed in before, or no owner is known), it is deleted: the user's sync downloads their artwork.
- */
-declare function onUserSignedIn(userId: string): Promise<void>;
-/** Locked now: the server said so, or the lock date it gave has passed. */
-declare function isRootLocked(s: {
-    locked: boolean;
-    lockedFrom: Date | null;
-}, now: Date): boolean;
-
-/** How many record reads one root record's sync keeps in flight at once (after the root record). */
-declare const SYNC_FETCH_CONCURRENCY = 4;
-/**
- * Brings one root record's device copy up to date with the sync answer (C2): records changed since
- * the stored server time are fetched (C3), records gone from the root record are deleted, the links
- * are replaced, and artwork images are downloaded. The root record is fetched first; the other
- * reads then run up to SYNC_FETCH_CONCURRENCY at a time. The sync state is stored only once every
- * fetch succeeded (or answered 403/404); the first failure stops the sync before anything is
- * written. A record with a waiting change is never overwritten.
- */
-declare function syncRoot(rootId: string, kind?: OfflineRootKind): Promise<void>;
-/**
- * Syncs every root record of every kind (`listSyncRoots()` of the primary kind and of each
- * `extraRootKinds` entry), then removes from the device the known root records no kind lists
- * (unless they still have waiting changes). A kind whose list throws keeps its device copy
- * unchanged; the primary kind's list throwing stops the sync. Does nothing offline.
- */
-declare function syncAll(): Promise<void>;
-
-type DrainResult = {
-    applied: number;
-    conflicts: number;
-    stoppedForLogin: boolean;
-};
-/**
- * Sends every waiting change of the unlocked root records in ONE `offline-change-sets` request,
- * after renewing the sign-in. Applied entries are removed and their answer written to the
- * device copy; conflicts become Conflict rows; waiting entries stay pending. A network error
- * or an expired sign-in stops it and keeps every entry.
- */
-declare function drainQueue(): Promise<DrainResult>;
-
-/** The unresolved conflicts of the signed-in user's device. */
-declare function useConflicts(): Conflict[];
-
-type ConflictChoice = {
-    kind: "mine";
-} | {
-    kind: "theirs";
-}
-/**
- * Per conflicting field: whose value wins. `mergedBody`: the JSON:API document the record
- * type's model built with createJsonApi() holding only the fields chosen "merged".
- */
- | {
-    kind: "fields";
-    choices: Record<string, "mine" | "theirs" | "merged">;
-    mergedBody?: any;
-} | {
-    kind: "restore";
-} | {
-    kind: "accept-deletion";
-} | {
-    kind: "delete-anyway";
-} | {
-    kind: "retry";
-} | {
-    kind: "discard";
-};
-/**
- * Applies the GM's choice for one conflict. "keep mine", per-field choices, "restore" and "delete anyway"
- * queue one more change (sent with the next package); "keep theirs" and "let the deletion
- * stand" only update the device. Online, the queue is sent right away.
- */
-declare function resolveConflict(id: string, choice: ConflictChoice): Promise<void>;
-
-/** Stops every running offline runtime (timers, listeners). Called on logout. */
-declare function stopOfflineRuntime(): void;
-/**
- * Starts the offline runtime: drain-then-sync on open (online) and on every reconnect, syncAll
- * every `syncIntervalMs` while online, a probe of the API while the session is offline but the
- * browser is online (a probe that reaches the API runs the drain and the sync, and the session
- * goes online once they succeeded), and the lock dates checked every minute. Returns the stop
- * function.
- */
-declare function startOfflineRuntime(): () => void;
-
-/**
- * How many changes the signed-in user's device still has to send (every queue entry: pending,
- * sending, in conflict or failed). The app warns before logging out when this is above 0.
- */
-declare function prepareOfflineLogout(): Promise<{
-    pending: number;
-}>;
-/**
- * Deletes the user's device database and the cached artwork images. Call it right before logging
- * out. The runtime is stopped first and the store blocked until the next sign-in
- * (`onUserSignedIn`), so a sync still running cannot open, and so recreate, the deleted file.
- * The device switch (`requireOptIn`) is turned off too: after a logout nothing is downloaded again
- * until the user turns offline mode back on.
- */
-declare function finishOfflineLogout(userId: string): Promise<void>;
-
-/**
- * Turns offline mode on on this device for the signed-in user (`OfflineConfig.requireOptIn`).
- * It does not start the runtime: the app starts it once `enabled` is true in the offline state.
- */
-declare function turnOnOffline(): Promise<void>;
-/**
- * Turns offline mode off on this device for the signed-in user and deletes this device's copy
- * (database and cached images). Refuses, changing nothing, while the copy has changes still to
- * send: the answer then carries how many.
- */
-declare function turnOffOffline(): Promise<{
-    turnedOff: true;
-} | {
-    turnedOff: false;
-    pending: number;
-}>;
-
-export { type Conflict, type ConflictChoice, type ConflictKind, DEFAULT_DEVICE_WORKER_URL, DEFAULT_SQLITE_MODULE_URL, DEVICE_WORKER_FILE, type DeviceStore, DeviceStoreUnavailableError, type DrainResult, type ListOptions, type LocalAnswer, type LocalAnswerContext, NeedsConnectionError, OFFLINE_REPLAY_HEADER, OFFLINE_SQLITE_FILES, type OfflineAnswer, type OfflineChangeResolution, type OfflineConfig, type OfflineLinkedListFetch, type OfflineLocalWriteContext, type OfflineMethod, type OfflineRequest, type OfflineRootKind, type OfflineRoute, type OfflineState, type OfflineTypeConfig, OfflineUnavailableError, type PatternSegment, type QueueEntry, type QueueResolution, type QueueStatus, type ResourceDocumentData, RootSync, type RouteMatch, SERVER_DEFAULT_ORDER_BY, SYNC_FETCH_CONCURRENCY, type SkippedRecord, type StoredLink, type StoredRecord, type SyncState, configureOffline, deleteDeviceStore, drainQueue, errorAnswer, finishOfflineLogout, forgetOfflineStore, getOfflineConfig, getOfflineState, getOfflineStore, hasUnsentChanges, includedFor, isOfflineAvailable, isOfflineConfigured, isOfflineEnabledOnDevice, isRootLocked, linkKindFor, linkKindsOf, linksOfKind, listAnswer, localTransport, matchPattern, matchRoute, mergeResource, needsConnectionAnswer, notFoundAnswer, onUserSignedIn, openDeviceStore, openMemoryDeviceStore, orderRecords, orderedListAnswer, patternToString, prepareOfflineLogout, refreshOfflineDeviceState, resolveConflict, resourceFromDocument, resourceListAnswer, searchRecords, setDeviceStoreOpener, setOfflineState, singleAnswer, startOfflineRuntime, stopOfflineRuntime, subscribeOfflineState, syncAll, syncRoot, turnOffOffline, turnOnOffline, useConflicts, useNeedsConnection, useOfflineState, writeThrough };