tempest-react-sdk 0.19.1 → 0.21.0

package/dist/tempest-react-sdk.d.ts

@@ -1531,6 +1531,44 @@ export declare interface CreateLoggerOptions {
  */
 export declare function createOfflineStore<TItem, TKey extends string | number = string>(config: OfflineStoreConfig<TItem>): OfflineStore<TItem, TKey>;
 
+/**
+ * Create an offline-first sync engine over an IndexedDB outbox.
+ *
+ * The engine drains queued mutations to the server (`deliver`) and pulls the
+ * server delta back (`pullPage` + `applyRemote`), advancing a watermark so each
+ * run only fetches what changed. `flush` is single-flight and skips cleanly
+ * while offline; failed deliveries stay queued with their attempt count bumped.
+ *
+ * Dexie is an **optional peer dependency** (via {@link createOfflineStore}) —
+ * install it (`npm i dexie`) when you use this engine.
+ *
+ * @typeParam TPayload - Record snapshot carried by outbox entries.
+ * @typeParam TRemote - Server item shape returned by `pullPage`.
+ * @param config - Transport callbacks + outbox/watermark configuration.
+ * @returns The sync handle (`enqueue`, `flush`, `pendingCount`, …).
+ *
+ * @example
+ * const sync = createOfflineSync<Note, NoteDto>({
+ *     databaseName: "NotesOutbox",
+ *     watermark: { storageKey: "notes.watermark" },
+ *     deliver: async (entry) => {
+ *         if (entry.op === "delete") return api.remove(entry.recordId);
+ *         await api.upsert(entry.recordId, entry.payload!);
+ *     },
+ *     pullPage: async (since, cursor) => {
+ *         const page = await api.changes(since, cursor);
+ *         return { items: page.items, nextCursor: page.next, serverTime: page.now };
+ *     },
+ *     applyRemote: async (dto) => {
+ *         if (dto.deleted) return localStore.remove(dto.id);
+ *         await localStore.save(fromDto(dto));
+ *     },
+ * });
+ * await sync.enqueue("create", note.id, note);
+ * await sync.flush("after-mutation");
+ */
+export declare function createOfflineSync<TPayload = unknown, TRemote = unknown>(config: OfflineSyncConfig<TPayload, TRemote>): OfflineSync<TPayload>;
+
 /**
  * Build a {@link RoutingBackend} backed by an OSRM server **you host**. OSRM
  * only serves a driving profile, so motorcycle/bus durations are derived by
@@ -4226,6 +4264,85 @@ export declare interface OfflineStoreConfig<TItem> {
     ownerField?: keyof TItem & string;
 }
 
+/**
+ * Offline-first sync engine: a durable outbox plus a paginated delta pull.
+ *
+ * @typeParam TPayload - Record snapshot carried by outbox entries.
+ */
+export declare interface OfflineSync<TPayload> {
+    /**
+     * Queue a mutation. Returns the generated entry id.
+     *
+     * @param op - The mutation kind.
+     * @param recordId - Primary key of the affected record.
+     * @param payload - Record snapshot (for `create`/`update`).
+     */
+    enqueue: (op: OutboxOp, recordId: string, payload?: TPayload) => Promise<string>;
+    /**
+     * Run a full sync (drain the outbox, then pull the delta). Concurrent
+     * calls share one in-flight promise, so triggers never overlap.
+     *
+     * @param trigger - Label for why the run happened. Default `"manual"`.
+     */
+    flush: (trigger?: SyncTrigger) => Promise<SyncRunSummary>;
+    /** Number of mutations still queued. */
+    pendingCount: () => Promise<number>;
+    /** The queued mutations in FIFO order. */
+    listPending: () => Promise<OutboxEntry<TPayload>[]>;
+    /** Drop every queued mutation (e.g. on logout). */
+    clearOutbox: () => Promise<void>;
+    /** Reset the pull watermark (e.g. on logout / account switch). */
+    resetWatermark: () => void;
+}
+
+/**
+ * Configuration for {@link createOfflineSync}.
+ *
+ * The engine owns the outbox, the single-flight flush, the offline guard, the
+ * paginated pull loop and the watermark; the three transport callbacks
+ * (`deliver`, `pullPage`, `applyRemote`) are where the app plugs in its own
+ * endpoints, record shape and conflict resolution.
+ *
+ * @typeParam TPayload - Record snapshot carried by outbox entries.
+ * @typeParam TRemote - Server item shape returned by `pullPage`.
+ */
+export declare interface OfflineSyncConfig<TPayload, TRemote> {
+    /** IndexedDB database name for the outbox (kept separate per queue). */
+    databaseName: string;
+    /** Outbox object-store name. Default `"outbox"`. */
+    tableName?: string;
+    /** Outbox schema version. Default `1`. */
+    version?: number;
+    /** Prefix for generated entry ids. Default `"outbox"`. */
+    idPrefix?: string;
+    /**
+     * Deliver one queued mutation to the server. Throwing keeps the entry
+     * queued (its `attempts`/`lastError` are bumped) for the next run.
+     */
+    deliver: (entry: OutboxEntry<TPayload>) => Promise<void>;
+    /** Fetch one page of the server delta since `since`, from `cursor`. */
+    pullPage: (since: string | null, cursor: string | null) => Promise<PullPage<TRemote>>;
+    /**
+     * Merge one pulled item into the local store. The app owns conflict
+     * resolution here (e.g. last-write-wins, keeping newer local pending
+     * edits, resolving tombstones and downloading blobs).
+     */
+    applyRemote: (item: TRemote) => Promise<void>;
+    /** Watermark persistence, or `{ storageKey }` for a `localStorage` default. */
+    watermark: WatermarkStore | {
+        storageKey: string;
+    };
+    /** Called after an entry is delivered and acked. */
+    onEntryDelivered?: (entry: OutboxEntry<TPayload>) => void | Promise<void>;
+    /** Called after an entry fails delivery (it stays queued). */
+    onEntryFailed?: (entry: OutboxEntry<TPayload>, error: unknown) => void | Promise<void>;
+    /**
+     * Connectivity check. Default reads `navigator.onLine` (always online in
+     * non-browser environments). When it returns `false`, `flush` is skipped.
+     */
+    isOnline?: () => boolean;
+}
+
 /** Offset-paginated response envelope (fastapi-pagination `Page[T]`). */
 export declare interface OffsetPage<T> {
     /** The rows for the current page. */
@@ -4314,6 +4431,39 @@ export declare interface OSRMBackendOptions {
     modeDurationFactors?: Partial<Record<TravelMode, number>>;
 }
 
+/**
+ * A single queued mutation.
+ *
+ * @typeParam TPayload - The record snapshot shape carried by
+ *   `create`/`update` entries (omitted for `delete`).
+ */
+export declare interface OutboxEntry<TPayload = unknown> {
+    /** Stable per-entry id (generated with {@link randomId}). */
+    id: string;
+    /** The mutation kind. */
+    op: OutboxOp;
+    /** Primary key of the record the mutation targets. */
+    recordId: string;
+    /** Epoch milliseconds when the mutation was queued. */
+    enqueuedAt: number;
+    /** How many delivery attempts have been made so far. */
+    attempts: number;
+    /** Last delivery error message, kept for UI/debug. */
+    lastError?: string;
+    /** Record snapshot for `create`/`update`. Omitted for `delete`. */
+    payload?: TPayload;
+}
+
+/**
+ * Mutation kinds queued in the outbox.
+ *
+ * `create`/`update` carry a snapshot of the record; `delete` needs only the
+ * record id. The distinction between `create` and `update` is advisory — the
+ * engine treats both as "deliver this record" and leaves the create-vs-update
+ * decision to the app's `deliver` callback (a `PUT` upsert usually ignores it).
+ */
+export declare type OutboxOp = "create" | "update" | "delete";
+
 export { Outlet }
 
 /**
@@ -4657,6 +4807,23 @@ export declare type ProgressVariant = "primary" | "success" | "warning" | "dange
  */
 export declare function projectMercator(coord: Coordinate): MercatorPoint;
 
+/**
+ * One page of the server delta pull.
+ *
+ * @typeParam TRemote - The server-side item shape.
+ */
+export declare interface PullPage<TRemote> {
+    /** Items changed since the watermark, in this page. */
+    items: TRemote[];
+    /** Cursor for the next page, or `null` when this is the last page. */
+    nextCursor: string | null;
+    /**
+     * Server clock to persist as the next watermark once the whole delta is
+     * applied. `null` leaves the watermark unchanged.
+     */
+    serverTime: string | null;
+}
+
 /**
  * Service-worker context helpers for handling `push` and `notificationclick`
  * events. Import these inside your own `sw.ts` — they expect to run in the
@@ -5574,6 +5741,26 @@ export declare interface SwitchProps extends Omit<InputHTMLAttributes<HTMLInputE
     wrapperClassName?: string;
 }
 
+/** Outcome of a single {@link OfflineSync.flush} run. */
+export declare interface SyncRunSummary {
+    /** The trigger passed to `flush`. */
+    trigger: SyncTrigger;
+    /** Entries delivered to the server this run. */
+    succeeded: number;
+    /** Entries that failed and stay queued for the next run. */
+    failed: number;
+    /** Total wall-clock milliseconds the run took. */
+    durationMs: number;
+    /** `true` when the run was skipped because the device was offline. */
+    skipped: boolean;
+}
+
+/**
+ * Why a sync run was triggered. The listed values are the common ones; any
+ * string is accepted so apps can add their own telemetry labels.
+ */
+export declare type SyncTrigger = "boot" | "online-event" | "after-mutation" | "manual" | "interval" | (string & {});
+
 export declare interface TabItem {
     id: string;
     label: ReactNode;
@@ -6919,6 +7106,15 @@ export declare interface UseOAuthCallbackResult<T> {
     status: "pending" | "success" | "error";
 }
 
+/**
+ * Create an object URL for a `Blob` (or `File`) and revoke it automatically on
+ * unmount or whenever the blob changes. Returns `null` for nullish input.
+ *
+ * @param blob - the blob to expose as an object URL, or `null`/`undefined`.
+ * @returns The object URL string, or `null` when there is no blob.
+ */
+export declare function useObjectUrl(blob: Blob | null | undefined): string | null;
+
 /**
  * Query a single record by id through the active {@link useDataProvider}.
  *
@@ -7710,6 +7906,19 @@ export declare interface VisuallyHiddenProps extends HTMLAttributes<HTMLElement>
     as?: keyof JSX_2.IntrinsicElements;
 }
 
+/**
+ * Pluggable persistence for the pull watermark (the "changed since" cursor).
+ * Pass an object with a `storageKey` to use a `localStorage`-backed default.
+ */
+export declare interface WatermarkStore {
+    /** Read the current watermark, or `null` when none is stored. */
+    get: () => string | null;
+    /** Persist a new watermark. */
+    set: (value: string) => void;
+    /** Drop the watermark (e.g. on logout / account switch). */
+    clear: () => void;
+}
+
 /**
  * Browser-side Web Push helper. Wraps `Notification.requestPermission`,
  * `pushManager.subscribe`, and the corresponding teardown. Transport is up to