@multiplatform.one/frappe 6.1.0 → 6.3.0

package/src/sync/types.ts

@@ -75,6 +75,12 @@ export interface Subscription {
   };
   /** Tombstones for tracking deleted documents with timestamps */
   tombstones?: Map<string, number>;
+  /**
+   * True when the last network refresh for this subscription failed and its
+   * membership is being served from the persisted cache. Cleared by the next
+   * successful refresh or CDC backfill.
+   */
+  stale?: boolean;
 }
 
 export enum Operation {
@@ -140,7 +146,13 @@ export interface BackfillArgs {
 
 /** Types of realtime events */
 export enum RealtimeEventType {
+  /** Real Frappe event: emitted to the per-doc room on every save (and on delete). */
+  DocUpdate = "doc_update",
+  /** Real Frappe event: emitted to the doctype room on every save (and on delete). */
+  ListUpdate = "list_update",
+  /** Designed wire-protocol event (forward-compat) — stock Frappe never emits it. */
   DocChanged = "doc_changed",
+  /** Designed wire-protocol event (forward-compat) — stock Frappe never emits it. */
   DocDeleted = "doc_deleted",
   Connected = "connected",
   PermEpochBump = "perm_epoch_bump",
@@ -175,6 +187,13 @@ export interface SyncOptions {
   onTrace?: (info: { event: string; details?: unknown }) => void;
   onResetCache?: () => void;
   onBackfillAll?: () => void;
+  /**
+   * Internal: invoked after realtime-driven cache/membership changes
+   * (doc_update/list_update reconcile, doc_deleted eviction, rehydration,
+   * connection state flips) so the sync store can notify its listeners.
+   * Wired by SyncModule; not intended for consumer use.
+   */
+  onStoreChange?: () => void;
   /** Connection management configuration */
   connectionConfig?: ConnectionConfig;
   /** Multi-tab coordination configuration */
@@ -183,6 +202,13 @@ export interface SyncOptions {
   mutationTTL?: number;
   /** Batch size for fetching documents (default: 100) */
   batchSize?: number;
+  /**
+   * Max CDC pages drained per backfill when the server reports has_more
+   * (default: 20). Bounds catch-up work after long offline periods in both
+   * drain paths: the subscription drain (SubscriptionManager.backfillSub)
+   * and the periodic/recovery path (BackfillManager.incrementalBackfill).
+   */
+  backfillMaxPages?: number;
   /** Maximum number of documents to keep in normalized cache (default: unlimited) */
   maxCacheSize?: number;
   /** Enable automatic mutation batching (default: false) */
@@ -208,6 +234,15 @@ export interface SyncOptions {
   tombstoneMaxAge?: number;
   /** Maximum number of tombstones per subscription before cleanup (default: 1000) */
   tombstoneMaxCount?: number;
+  /**
+   * How long (in milliseconds) a subscription restored from a persisted
+   * snapshot may stay unadopted before it is garbage-collected (default:
+   * 30 minutes). Restored subscriptions are re-adopted (id, checkpoint, and
+   * cached membership reused) when an identical query subscribes; unadopted
+   * ones are excluded from backfill and dropped after this grace period.
+   * Only relevant when `persistKey` is set.
+   */
+  restoredSubscriptionTTL?: number;
   /** Callback when tab becomes leader */
   onBecomeLeader?: () => void;
   /** Callback when tab loses leadership */
@@ -333,6 +368,10 @@ export interface DebugSubscription {
   tombstoneCount: number;
   checkpoint?: string;
   cursor?: string;
+  /** Serving persisted cache after a failed network refresh. */
+  stale?: boolean;
+  /** Restored from a persisted snapshot and not yet re-adopted by a live query. */
+  restored?: boolean;
   progressiveCache?: {
     docIds: string[];
     nextCursor?: string;

package/src/sync/virtualPageManager.ts

@@ -213,12 +213,16 @@ export class VirtualPageManager<Data extends FrappeDocData = FrappeDocData> {
   private cacheGeneration = 0;
   private readonly batchSize: number;
   private islands = new Map<string, PageIsland[]>();
+  private normalizedCache: NormalizedCache;
+  private db: DbModule;
 
   constructor(
-    private normalizedCache: NormalizedCache,
-    private db: DbModule,
+    normalizedCache: NormalizedCache,
+    db: DbModule,
     options: { batchSize?: number } = {},
   ) {
+    this.normalizedCache = normalizedCache;
+    this.db = db;
     this.batchSize = options.batchSize || 100;
   }
 
@@ -947,7 +951,7 @@ export class VirtualPageManager<Data extends FrappeDocData = FrappeDocData> {
   }
 
   private async ensureCached(subscription: VirtualSubscription, requiredIndex: number) {
-    let cache = subscription.getProgressiveCache();
+    const cache = subscription.getProgressiveCache();
     if (cache.docIds.length >= requiredIndex || !cache.hasMore) return;
 
     const pageSize = subscription.viewWindow.pageSize;
@@ -956,7 +960,7 @@ export class VirtualPageManager<Data extends FrappeDocData = FrappeDocData> {
   }
 
   private recordIsland(subscriptionId: string, island: PageIsland): void {
-    let existing = this.islands.get(subscriptionId) || [];
+    const existing = this.islands.get(subscriptionId) || [];
 
     // Add the new island to the list
     existing.push(island);

package/src/useLiveQuery.ts

@@ -0,0 +1,58 @@
+import { useLiveQuery as useLiveQueryBase } from "@tanstack/react-db";
+
+/**
+ * Result returned while server rendering: mirrors the shape
+ * `@tanstack/react-db` produces during its initial client-side "loading"
+ * state so SSR markup matches the client's first paint.
+ */
+const SSR_LIVE_QUERY_RESULT = Object.freeze({
+  state: undefined,
+  data: undefined,
+  collection: undefined,
+  status: "loading",
+  isLoading: true,
+  isReady: false,
+  isIdle: false,
+  isError: false,
+  isCleanedUp: false,
+  isEnabled: true,
+});
+
+/**
+ * True when this module is evaluated during web server rendering.
+ *
+ * Resolved once at module init, guarded like `frappe-ui`'s
+ * `frappeStoryTarget` precedent: on web, Vite provides `import.meta.env`
+ * (dev + build + SSR), so `.SSR` reads the real flag; on native
+ * (Metro/Hermes — no Vite define), `import.meta.env` is undefined at
+ * runtime and a bare `import.meta.env.SSR` member access THROWS
+ * (`Cannot read property 'SSR' of undefined`, crashing every
+ * live-query consumer on device). The optional access + try/catch land
+ * native on `false`, which is correct — native is always a client.
+ */
+const IS_SSR: boolean = (() => {
+  try {
+    return (import.meta as ImportMeta & { env?: { SSR?: boolean } }).env?.SSR === true;
+  } catch {
+    return false;
+  }
+})();
+
+/**
+ * SSR-safe wrapper around `useLiveQuery` from `@tanstack/react-db`.
+ *
+ * The upstream hook calls `useSyncExternalStore(subscribe, getSnapshot)`
+ * without a `getServerSnapshot`, so react-dom/server throws "Missing
+ * getServerSnapshot, which is required for server-rendered content" the
+ * moment any component using it is server rendered (e.g. deep-linking a
+ * web route). On the server we skip the subscription entirely and return
+ * a static "loading" result; the live query takes over on the client.
+ *
+ * `IS_SSR` is constant for the lifetime of the process, so hook order
+ * never varies within a renderer.
+ */
+export const useLiveQuery: typeof useLiveQueryBase = ((...args: unknown[]) => {
+  if (IS_SSR) return SSR_LIVE_QUERY_RESULT;
+  // oxlint-disable-next-line rules-of-hooks -- branch is process-constant
+  return (useLiveQueryBase as (...args: unknown[]) => unknown)(...args);
+}) as typeof useLiveQueryBase;

package/src/util.spec.ts

@@ -1,17 +1,48 @@
-import { describe, expect, it, vi } from "vitest";
-import { isBrowser } from "./util";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { isBrowser, isGjs } from "./util";
 
 describe("isBrowser", () => {
   it("returns true in a browser-like (happy-dom) environment", () => {
     expect(isBrowser()).toBe(true);
   });
 
-  it("returns false when isWindowDefined is false", async () => {
+  it("returns false when neither isNative nor isWindowDefined", async () => {
     vi.resetModules();
-    vi.doMock("@multiplatform.one/platform", () => ({ isWindowDefined: false }));
+    vi.doMock("@multiplatform.one/platform", () => ({ isNative: false, isWindowDefined: false }));
     const { isBrowser: isBrowserFresh } = await import("./util");
     expect(isBrowserFresh()).toBe(false);
     vi.doUnmock("@multiplatform.one/platform");
     vi.resetModules();
   });
 });
+
+describe("isGjs", () => {
+  afterEach(() => {
+    delete (globalThis as { imports?: unknown }).imports;
+  });
+
+  it("returns false in a browser-like environment", () => {
+    expect(isGjs()).toBe(false);
+  });
+
+  it("detects the GJS imports.gi global", () => {
+    (globalThis as { imports?: unknown }).imports = { gi: {} };
+    expect(isGjs()).toBe(true);
+  });
+
+  it("does not false-positive on an imports global without gi", () => {
+    (globalThis as { imports?: unknown }).imports = { something: true };
+    expect(isGjs()).toBe(false);
+  });
+
+  it("makes isBrowser() true on GJS even without isNative/isWindowDefined", async () => {
+    vi.resetModules();
+    vi.doMock("@multiplatform.one/platform", () => ({ isNative: false, isWindowDefined: false }));
+    (globalThis as { imports?: unknown }).imports = { gi: {} };
+    const fresh = await import("./util");
+    expect(fresh.isGjs()).toBe(true);
+    expect(fresh.isBrowser()).toBe(true);
+    vi.doUnmock("@multiplatform.one/platform");
+    vi.resetModules();
+  });
+});

package/src/util.ts

@@ -1,13 +1,40 @@
 import { isNative, isWindowDefined } from "@multiplatform.one/platform";
 
 /**
- * True in any CLIENT runtime — web browser or React Native — false in
- * Node/SSR. This gates the live sync pipeline (SyncModule/collections), which
- * is fully native-capable (MMKV storage, RN realtime transport, guarded
- * localStorage/BroadcastChannel). Window-presence alone is the wrong test:
- * @tamagui/constants hardcodes isWindowDefined=false on native, which used to
- * silently disable every collection on iOS/Android.
+ * True when running under GJS (GNOME JavaScript — the GTK desktop runtime).
+ *
+ * GJS always exposes the legacy `imports` global with its `gi` GObject
+ * Introspection namespace, in both script and ESM (`gjs -m`) modes — verified
+ * on GJS 1.7x/1.8x. No browser, Node, or React Native runtime defines
+ * `globalThis.imports.gi`, so this cannot false-positive elsewhere (a page
+ * would have to deliberately fake the GI namespace). Checked lazily — GJS
+ * embeds could in theory construct the global after module init.
+ */
+export function isGjs(): boolean {
+  try {
+    const gjsImports = (globalThis as { imports?: { gi?: unknown } }).imports;
+    return (
+      typeof gjsImports === "object" &&
+      gjsImports !== null &&
+      typeof gjsImports.gi === "object" &&
+      gjsImports.gi !== null
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * True in any CLIENT runtime — web browser, React Native, or GJS (GNOME) —
+ * false in Node/SSR. This gates the live sync pipeline
+ * (SyncModule/collections), which is fully capable on all three:
+ * native has MMKV storage and the RN realtime transport; GJS runs with
+ * WHATWG timers, an entry-installed fetch/WebSocket polyfill (libsoup), and
+ * guarded storage/BroadcastChannel no-ops. Window-presence alone is the
+ * wrong test: @tamagui/constants hardcodes isWindowDefined=false on native,
+ * which used to silently disable every collection on iOS/Android, and GJS
+ * has no real window either.
  */
 export function isBrowser(): boolean {
-  return isNative || isWindowDefined;
+  return isNative || isWindowDefined || isGjs();
 }

package/types/auth.d.ts

@@ -0,0 +1,13 @@
+import type { HttpClient } from "./core/http";
+export declare class AuthModule {
+    private readonly http;
+    constructor(http: HttpClient);
+    loginWithUsernamePassword(input: {
+        username: string;
+        password: string;
+    }): Promise<import("./core/http").HttpResponse<unknown>>;
+    getLoggedInUser(): Promise<string>;
+    logout(): Promise<import("./core/http").HttpResponse<unknown>>;
+    forgetPassword(email: string): Promise<import("./core/http").HttpResponse<unknown>>;
+}
+//# sourceMappingURL=auth.d.ts.map

package/types/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;gBAEtB,IAAI,EAAE,UAAU;IAItB,yBAAyB,CAAC,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE;IAOvE,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC;IAOlC,MAAM;IAIN,cAAc,CAAC,KAAK,EAAE,MAAM;CAKnC"}

package/types/call.d.ts

@@ -0,0 +1,10 @@
+import type { HttpClient } from "./core/http";
+export declare class CallModule {
+    private readonly http;
+    constructor(http: HttpClient);
+    get<T>(method: string, params?: Record<string, any>): Promise<import("./core/http").HttpResponse<T>>;
+    post<T>(method: string, body?: any): Promise<import("./core/http").HttpResponse<T>>;
+    put<T>(method: string, body?: any): Promise<import("./core/http").HttpResponse<T>>;
+    delete<T>(method: string, body?: any): Promise<import("./core/http").HttpResponse<T>>;
+}
+//# sourceMappingURL=call.d.ts.map

package/types/call.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"call.d.ts","sourceRoot":"","sources":["../src/call.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;gBAEtB,IAAI,EAAE,UAAU;IAI5B,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAInD,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG;IAIlC,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG;IAIjC,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG;CAGrC"}

package/types/collection.d.ts

@@ -0,0 +1,127 @@
+import type { CollectionConfig } from "@tanstack/db";
+import type { FixtureProvider } from "./fixtures";
+import type { SyncModule } from "./sync";
+import type { SubscriptionQuery } from "./sync/types";
+/**
+ * Configuration for creating a Frappe-backed TanStack DB collection.
+ *
+ * @typeParam TDoc - The document type stored in the collection
+ */
+export interface FrappeCollectionOptionsConfig<_TDoc extends object & {
+    name: string;
+    doctype: string;
+}> {
+    /** The Frappe SyncModule instance to use for data sync */
+    sync: SyncModule;
+    /** Fields to subscribe to from the doctype */
+    fields?: readonly string[];
+    /** Frappe filters to apply to the subscription */
+    filters?: Record<string, unknown> | Array<[string, string, unknown]>;
+    /** Optional override for the collection id (defaults to doctype) */
+    id?: string;
+    /** Order-by configuration */
+    orderBy?: SubscriptionQuery["orderBy"];
+    /** Limit for the subscription */
+    limit?: number;
+    /**
+     * Called when the initial subscription fetch fails (network down,
+     * PermissionError/403, bad doctype). Without this the collection just
+     * looks empty — consumers should surface an honest error state instead.
+     */
+    onSyncError?: (error: unknown) => void;
+}
+/**
+ * Creates TanStack DB collection options wired to Frappe's SyncModule.
+ *
+ * This follows TanStack DB's collection options creator pattern (Pattern B),
+ * where mutation handlers are built-in and delegate to SyncModule.
+ *
+ * @typeParam TDoc - The Frappe document type
+ * @param doctype - The Frappe doctype name (e.g. "ToDo", "Pokemon")
+ * @param config - Configuration for the collection
+ * @returns A CollectionConfig object suitable for `createCollection()`
+ *
+ * @example
+ * ```typescript
+ * const pokemonCollection = createCollection(
+ *   frappeCollectionOptions<Pokemon>("Pokemon", {
+ *     sync: syncModule,
+ *     fields: ["name", "pokemon_name", "poke_id"],
+ *   })
+ * );
+ * ```
+ */
+export declare function frappeCollectionOptions<TDoc extends object & {
+    name: string;
+    doctype: string;
+}>(doctype: string, config: FrappeCollectionOptionsConfig<TDoc>): CollectionConfig<TDoc, string>;
+/**
+ * Creates a TanStack DB Collection backed by a Frappe doctype via SyncModule.
+ *
+ * Convenience wrapper that calls `createCollection(frappeCollectionOptions(...))`.
+ *
+ * @typeParam TDoc - The Frappe document type
+ * @param doctype - The Frappe doctype name
+ * @param config - Configuration for the collection
+ * @returns A TanStack DB Collection instance
+ *
+ * @example
+ * ```typescript
+ * const pokemonCollection = createFrappeCollection<Pokemon>("Pokemon", {
+ *   sync: syncModule,
+ *   fields: ["name", "pokemon_name", "poke_id"],
+ * });
+ *
+ * // Use with useLiveQuery
+ * const { data } = useLiveQuery((q) =>
+ *   q.from({ pokemon: pokemonCollection })
+ * );
+ *
+ * // Direct mutations
+ * pokemonCollection.insert({ name: "pikachu", doctype: "Pokemon", ... });
+ * ```
+ */
+export declare function createFrappeCollection<TDoc extends object & {
+    name: string;
+    doctype: string;
+}>(doctype: string, config: FrappeCollectionOptionsConfig<TDoc>): import("@tanstack/db").Collection<TDoc, string, import("@tanstack/db").UtilsRecord, never, TDoc> & import("@tanstack/db").NonSingleResult;
+/**
+ * Configuration for creating a fixture-backed TanStack DB collection.
+ * Used when fixtures are provided (e.g. in Storybook or tests).
+ */
+export interface FixtureCollectionOptionsConfig<_TDoc extends object & {
+    name: string;
+    doctype: string;
+}> {
+    /** The fixture provider to use for data */
+    fixtures: FixtureProvider;
+    /** Fields to load from the doctype */
+    fields?: readonly string[];
+    /** Frappe filters to apply */
+    filters?: Record<string, unknown> | Array<[string, string, unknown]>;
+    /** Optional override for the collection id */
+    id?: string;
+    /** Order-by configuration */
+    orderBy?: SubscriptionQuery["orderBy"];
+    /** Limit for the query */
+    limit?: number;
+    /** Offset for pagination */
+    limitStart?: number;
+}
+/**
+ * Creates TanStack DB collection options wired to a FixtureProvider.
+ * Used when config.fixtures is set (e.g. in tests or Storybook).
+ */
+export declare function fixtureCollectionOptions<TDoc extends object & {
+    name: string;
+    doctype: string;
+}>(doctype: string, config: FixtureCollectionOptionsConfig<TDoc>): CollectionConfig<TDoc, string>;
+/**
+ * Creates a TanStack DB Collection backed by a FixtureProvider.
+ * Used when config.fixtures is set (e.g. in tests or Storybook).
+ */
+export declare function createFixtureCollection<TDoc extends object & {
+    name: string;
+    doctype: string;
+}>(doctype: string, config: FixtureCollectionOptionsConfig<TDoc>): import("@tanstack/db").Collection<TDoc, string, import("@tanstack/db").UtilsRecord, never, TDoc> & import("@tanstack/db").NonSingleResult;
+//# sourceMappingURL=collection.d.ts.map

package/types/collection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAc,MAAM,cAAc,CAAC;AAGjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEzC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD;;;;GAIG;AACH,MAAM,WAAW,6BAA6B,CAC5C,KAAK,SAAS,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;IAExD,0DAA0D;IAC1D,IAAI,EAAE,UAAU,CAAC;IACjB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrE,oEAAoE;IACpE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,6BAA6B;IAC7B,OAAO,CAAC,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;IACvC,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,SAAS,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAC7F,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,6BAA6B,CAAC,IAAI,CAAC,GAC1C,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,CA4IhC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,SAAS,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAC5F,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,6BAA6B,CAAC,IAAI,CAAC,6IAG5C;AAED;;;GAGG;AACH,MAAM,WAAW,8BAA8B,CAC7C,KAAK,SAAS,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;IAExD,2CAA2C;IAC3C,QAAQ,EAAE,eAAe,CAAC;IAC1B,sCAAsC;IACtC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrE,8CAA8C;IAC9C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,6BAA6B;IAC7B,OAAO,CAAC,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;IACvC,0BAA0B;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,SAAS,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAC9F,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,8BAA8B,CAAC,IAAI,CAAC,GAC3C,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,CAgFhC;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,SAAS,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAC7F,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,8BAA8B,CAAC,IAAI,CAAC,6IAG7C"}

package/types/common/types.d.ts

@@ -0,0 +1,35 @@
+export type PrimitiveValue = string | number | boolean | null | undefined;
+export type FrappeDocValue = ChildTableRow[] | FrappeDocValue[] | PrimitiveValue | {
+    [key: string]: FrappeDocValue;
+};
+export interface ChildTableRow {
+    name: string;
+    doctype: string | null;
+    idx: number | null;
+    parent: string | null;
+    parentfield: string | null;
+    parenttype: string | null;
+    [key: string]: FrappeDocValue;
+}
+export interface FrappeDocBase {
+    creation?: string;
+    docstatus?: number;
+    doctype: string;
+    idx?: number;
+    modified?: string;
+    modified_by?: string;
+    name: string;
+    owner?: string;
+}
+/** Minimal constraint for document types - any object with name/doctype (e.g. FrappeTag, FrappeFile) */
+export type FrappeDocDataConstraint = object & {
+    name: string;
+    doctype: string;
+};
+/** Data can be any object with name/doctype; index signature relaxed for UI types like FrappeFile */
+export type FrappeDocData<Data extends FrappeDocDataConstraint = Record<string, FrappeDocValue> & {
+    name: string;
+    doctype: string;
+}> = Data & FrappeDocBase;
+export type FrappeDoc<Data extends FrappeDocData> = Data & FrappeDocBase;
+//# sourceMappingURL=types.d.ts.map

package/types/common/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/common/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;AAE1E,MAAM,MAAM,cAAc,GACtB,aAAa,EAAE,GACf,cAAc,EAAE,GAChB,cAAc,GACd;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAAA;CAAE,CAAC;AAEtC,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAAC;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wGAAwG;AACxG,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjF,qGAAqG;AACrG,MAAM,MAAM,aAAa,CACvB,IAAI,SAAS,uBAAuB,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,IACC,IAAI,GAAG,aAAa,CAAC;AAEzB,MAAM,MAAM,SAAS,CAAC,IAAI,SAAS,aAAa,IAAI,IAAI,GAAG,aAAa,CAAC"}

package/types/core/http.d.ts

@@ -0,0 +1,86 @@
+import { getCookie, setCookie, deleteCookie } from "@multiplatform.one/platform";
+import { HttpMethod } from "./types";
+import type { AuthConfig, RetryConfig } from "./types";
+export { getCookie, setCookie, deleteCookie };
+export type RequestBody = BodyInit | Record<string, unknown> | unknown[] | ArrayBufferView;
+export interface HttpResponse<T> {
+    _res: Response;
+    headers: Headers;
+    payload: T;
+    status: number;
+}
+export declare class HttpClient {
+    private readonly retryConfig;
+    private _language?;
+    /** Server-bootstrapped CSRF token for React Native cookie auth (see ensureNativeCsrfToken). */
+    private csrfToken?;
+    /** True once a native CSRF bootstrap attempt completed (even if it yielded no token). */
+    private csrfBootstrapDone;
+    /** In-flight CSRF bootstrap, deduped across concurrent mutating requests. */
+    private csrfBootstrap?;
+    private readonly baseURL;
+    private auth?;
+    constructor(baseURL: string, auth?: AuthConfig, retryConfig?: RetryConfig);
+    /** Set language preference for Accept-Language header on all requests. */
+    setLanguage(lang: string): void;
+    /** Get resolved language: explicit > cookie > undefined. */
+    getLanguage(): string | undefined;
+    /** Sync language preference to Frappe user profile (authenticated users). */
+    syncUserLanguage(lang: string, user?: string): Promise<void>;
+    /**
+     * React Native cookie-auth CSRF bootstrap.
+     *
+     * RN's fetch sends the OS cookie jar (so cookie-auth sessions work), but
+     * JS cannot READ those cookies — the platform `getCookie` shim is an
+     * in-memory map that never sees the `sid`/CSRF cookies — so mutating
+     * requests would 400 once the session has a CSRF token. Fetch the token
+     * from the server instead and cache it per client:
+     *
+     *   1. `GET /api/method/frappe.sessions.get_csrf_token` — whitelisted on
+     *      newer frappe versions; cheap JSON round-trip.
+     *   2. Fallback: `GET /app` and parse the `frappe.csrf_token = "…"` boot
+     *      script — works on every frappe (this repo's bench does NOT
+     *      whitelist the RPC above) and also generates the token server-side
+     *      when the session lacks one.
+     *
+     * Resolves undefined when neither source works (e.g. website-only session
+     * without desk access); requests then proceed without the header, which
+     * frappe accepts for sessions that have no CSRF token yet. The cache is
+     * dropped on auth change and on a 400 from a mutating request so a
+     * rotated session re-bootstraps.
+     */
+    private ensureNativeCsrfToken;
+    private fetchNativeCsrfToken;
+    private invalidateNativeCsrfToken;
+    private getAuthHeaders;
+    private shouldRetryError;
+    private getRetryDelay;
+    request<T>(method: HttpMethod, path: string, request: {
+        body?: RequestBody;
+        headers?: Record<string, string>;
+        /** Cancels the request (and any pending retry) when aborted. */
+        signal?: AbortSignal;
+    }): Promise<HttpResponse<T>>;
+    get<T>(path: string, params?: Record<string, unknown>, headers?: Record<string, string>, signal?: AbortSignal): Promise<HttpResponse<T>>;
+    post<T>(path: string, body?: RequestBody, headers?: Record<string, string>): Promise<HttpResponse<T>>;
+    put<T>(path: string, body?: RequestBody, headers?: Record<string, string>): Promise<HttpResponse<T>>;
+    delete<T>(path: string, body?: RequestBody, headers?: Record<string, string>): Promise<HttpResponse<T>>;
+    head(path: string, params?: Record<string, unknown>, headers?: Record<string, string>): Promise<HttpResponse<void>>;
+    getAuthConfig(): AuthConfig;
+    updateAuth(auth: AuthConfig): void;
+}
+/**
+ * Set cookies for SSR/Node environments where document.cookie is unavailable.
+ * Pass a cookie header string (e.g., from incoming request).
+ */
+export declare function setSSRCookies(cookieHeader: string | undefined): void;
+/**
+ * Clear SSR cookies (call at end of request lifecycle).
+ */
+export declare function clearSSRCookies(): void;
+/**
+ * Invalidate the cookie cache. No-op — retained for backwards compatibility.
+ * Cookie reads now delegate directly to the platform abstraction.
+ */
+export declare function invalidateCookieCache(): void;
+//# sourceMappingURL=http.d.ts.map

package/types/core/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/core/http.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAY,MAAM,6BAA6B,CAAC;AAE3F,OAAO,EAAe,UAAU,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEvD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC;AAoB9C,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,EAAE,GAAG,eAAe,CAAC;AAE3F,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,CAAC,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAE1C,OAAO,CAAC,SAAS,CAAC,CAAS;IAC3B,+FAA+F;IAC/F,OAAO,CAAC,SAAS,CAAC,CAAS;IAC3B,yFAAyF;IACzF,OAAO,CAAC,iBAAiB,CAAS;IAClC,6EAA6E;IAC7E,OAAO,CAAC,aAAa,CAAC,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,IAAI,CAAC,CAAa;gBAEd,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,EAAE,WAAW,CAAC,EAAE,WAAW;IAMzE,0EAA0E;IAC1E,WAAW,CAAC,IAAI,EAAE,MAAM;IAIxB,4DAA4D;IAC5D,WAAW,IAAI,MAAM,GAAG,SAAS;IAMjC,6EAA6E;IACvE,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUlE;;;;;;;;;;;;;;;;;;;;;OAqBG;YACW,qBAAqB;YAgBrB,oBAAoB;IAyBlC,OAAO,CAAC,yBAAyB;YAKnB,cAAc;IAQ5B,OAAO,CAAC,gBAAgB;IAiBxB,OAAO,CAAC,aAAa;IAQf,OAAO,CAAC,CAAC,EACb,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QACP,IAAI,CAAC,EAAE,WAAW,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACjC,gEAAgE;QAChE,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GACA,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAwJ3B,GAAG,CAAC,CAAC,EACH,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,MAAM,CAAC,EAAE,WAAW;IAMtB,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAI1E,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAIzE,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAI5E,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAKrF,aAAa,IAAI,UAAU;IAI3B,UAAU,CAAC,IAAI,EAAE,UAAU;CAM5B;AAeD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAsBpE;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAAG"}

package/types/core/types.d.ts

@@ -0,0 +1,74 @@
+import type { OrderBy } from "../sync/types";
+export declare enum AuthType {
+    Bearer = "Bearer",
+    Token = "token"
+}
+export interface AuthConfig {
+    /**
+     * Raw cookie string to attach to every request (used in SSR / Node.js
+     * where the browser cookie jar is not available).
+     *
+     * Example: `"sid=abc123; system_user=yes"`
+     */
+    cookie?: string;
+    sessionId?: string | (() => string | Promise<string>);
+    token?: string | (() => string | Promise<string>);
+    type?: AuthType;
+    useToken?: boolean;
+}
+export interface RetryConfig {
+    baseDelayMs?: number;
+    exponentialBackoff?: boolean;
+    maxDelayMs?: number;
+    maxRetries?: number;
+    retryOnNetworkError?: boolean;
+    retryStatusCodes?: number[];
+    shouldRetry?: (err: unknown, attempt: number) => boolean;
+}
+export type CustomEndpoints = {
+    createDoc?: string;
+    deleteDoc?: string;
+    backfill?: string;
+    updateDoc?: string;
+    /** Cursor-based pagination endpoint (frappe_live.api.get_list_with_cursor) */
+    getListWithCursor?: string;
+    /** Batch mutations endpoint (frappe_live.api.batch_mutations) */
+    batchMutations?: string;
+    /** CDC list_since endpoint (frappe_live.api.list_since) */
+    listSince?: string;
+};
+/**
+ * Configuration for frappe_live extension endpoints
+ */
+export interface FrappeLiveConfig {
+    /** Custom Frappe app name for extension endpoints (default: 'frappe_live') */
+    appName?: string;
+    /** Custom endpoints to override default frappe_live endpoints */
+    customEndpoints?: CustomEndpoints;
+}
+export declare enum HttpMethod {
+    Delete = "DELETE",
+    Get = "GET",
+    Head = "HEAD",
+    Post = "POST",
+    Put = "PUT"
+}
+export declare class FrappeError extends Error {
+    readonly status: number;
+    readonly data?: unknown;
+    constructor(message: string, status: number, data?: unknown);
+}
+export interface ListOptions {
+    asDict?: boolean;
+    cursor?: string;
+    fields?: readonly string[];
+    filters?: Array<[string, string, unknown]> | Record<string, unknown>;
+    groupBy?: string;
+    limit?: number;
+    limitStart?: number;
+    orFilters?: Array<[string, string, unknown]>;
+    orderBy?: OrderBy;
+    /** Cancels the underlying HTTP request when aborted (never serialized). */
+    signal?: AbortSignal;
+}
+//# sourceMappingURL=types.d.ts.map

package/types/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C,oBAAY,QAAQ;IAClB,MAAM,WAAW;IACjB,KAAK,UAAU;CAChB;AAED,MAAM,WAAW,UAAU;IACzB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IACtD,KAAK,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IAClD,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;CAC1D;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAED,oBAAY,UAAU;IACpB,MAAM,WAAW;IACjB,GAAG,QAAQ;IACX,IAAI,SAAS;IACb,IAAI,SAAS;IACb,GAAG,QAAQ;CACZ;AAED,qBAAa,WAAY,SAAQ,KAAK;IACpC,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,IAAI,CAAC,EAAE,OAAO,CAAC;gBACnB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;CAO5D;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC7C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB"}