@multiplatform.one/frappe 6.1.0 → 6.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/frappe",
-  "version": "6.1.0",
+  "version": "6.3.0",
   "description": "frappe client for multiplatform.one ecosystem",
   "keywords": [
     "auth",
@@ -19,37 +19,40 @@
   "author": "BitSpur",
   "repository": {
     "type": "git",
-    "url": "https://gitlab.com/bitspur/multiplatform.one/multiplatform.one"
+    "url": "git+https://gitlab.com/bitspur/frappe/multiplatform.one.git",
+    "directory": "public/frappe"
   },
   "source": "src/index.ts",
   "files": [
     "dist",
     "src",
-    "types"
+    "types",
+    "!types/.tsbuildinfo"
   ],
   "sideEffects": false,
   "main": "src/index.ts",
   "module": "src/index.ts",
-  "types": "src/index.ts",
+  "types": "types/index.d.ts",
   "exports": {
     "./package.json": "./package.json",
     ".": {
       "source": "./src/index.ts",
       "react-native": {
+        "types": "./types/index.d.ts",
         "import": "./dist/esm/index.native.js",
         "require": "./dist/cjs/index.native.js",
         "default": "./dist/esm/index.native.js"
       },
-      "types": "./src/index.ts",
-      "import": "./dist/esm/index.js",
-      "require": "./dist/cjs/index.js",
-      "default": "./dist/cjs/index.js"
+      "types": "./types/index.d.ts",
+      "import": "./dist/esm/index.mjs",
+      "require": "./dist/cjs/index.cjs",
+      "default": "./dist/cjs/index.cjs"
     },
     "./devtools": {
       "source": "./src/devtools/index.ts",
-      "types": "./src/devtools/index.ts",
-      "import": "./dist/esm/devtools/index.js",
-      "require": "./dist/cjs/devtools/index.js",
+      "types": "./types/devtools/index.d.ts",
+      "import": "./dist/esm/devtools/index.mjs",
+      "require": "./dist/cjs/devtools/index.cjs",
       "default": "./src/devtools/index.ts"
     }
   },
@@ -63,7 +66,7 @@
     "@tanstack/react-pacer": "0.22.0",
     "broadcast-channel": "^7.3.0",
     "socket.io-client": "^4.8.3",
-    "@multiplatform.one/store": "6.1.0"
+    "@multiplatform.one/store": "6.3.0"
   },
   "devDependencies": {
     "@tamagui/build": "2.0.0-rc.41",
@@ -76,13 +79,13 @@
     "react": "19.2.5",
     "typescript": "~5.9.3",
     "vitest": "^4.1.5",
-    "@multiplatform.one/config": "6.1.0",
-    "@multiplatform.one/test-utils": "6.1.0",
-    "@multiplatform.one/platform": "6.1.0"
+    "@multiplatform.one/config": "6.3.0",
+    "@multiplatform.one/platform": "6.3.0",
+    "@multiplatform.one/test-utils": "6.3.0"
   },
   "peerDependencies": {
     "react": "^19.1.0",
-    "@multiplatform.one/platform": "^6.1.0"
+    "@multiplatform.one/platform": "^6.3.0"
   },
   "engines": {
     "node": ">=6.0.0"
@@ -90,7 +93,7 @@
   "module:jsx": "dist/jsx",
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "build": "rm -rf dist types 2>/dev/null && tamagui-build --ts-project ./tsconfig.build.json",
+    "build": "rm -rf dist types 2>/dev/null && tamagui-build --ts-project ./tsconfig.build.json --exclude '\\.spec\\.|\\.test\\.|\\.stories\\.'",
     "test": "vitest run"
   }
 }

package/src/auth.ts

@@ -1,7 +1,11 @@
 import type { HttpClient } from "./core/http";
 
 export class AuthModule {
-  constructor(private readonly http: HttpClient) {}
+  private readonly http: HttpClient;
+
+  constructor(http: HttpClient) {
+    this.http = http;
+  }
 
   async loginWithUsernamePassword(input: { username: string; password: string }) {
     return this.http.post("/api/method/login", {

package/src/call.ts

@@ -1,7 +1,11 @@
 import type { HttpClient } from "./core/http";
 
 export class CallModule {
-  constructor(private readonly http: HttpClient) {}
+  private readonly http: HttpClient;
+
+  constructor(http: HttpClient) {
+    this.http = http;
+  }
 
   get<T>(method: string, params?: Record<string, any>) {
     return this.http.get<T>(`/api/method/${method}`, params);

package/src/collection.spec.ts

@@ -198,6 +198,61 @@ describe("frappeCollectionOptions", () => {
     // Cleanup
     if (typeof cleanup === "function") cleanup();
   });
+
+  it("calls onSyncError when the initial subscription fetch fails", async () => {
+    const error = new Error("PermissionError: not permitted");
+    (mockSync.subscribe as ReturnType<typeof vi.fn>).mockRejectedValueOnce(error);
+    const onSyncError = vi.fn();
+    const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    const options = frappeCollectionOptions<TestDoc>("Task", {
+      sync: mockSync,
+      onSyncError,
+    });
+
+    const markReady = vi.fn();
+    const syncFn = options.sync!.sync;
+    const cleanup = syncFn({
+      begin: vi.fn(),
+      write: vi.fn(),
+      commit: vi.fn(),
+      markReady,
+      truncate: vi.fn(),
+      collection: {} as any,
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    expect(onSyncError).toHaveBeenCalledWith(error);
+    // Collection still marks ready so consumers are never stuck loading
+    expect(markReady).toHaveBeenCalled();
+
+    consoleError.mockRestore();
+    if (typeof cleanup === "function") cleanup();
+  });
+
+  it("does not call onSyncError on a successful initial sync", async () => {
+    const onSyncError = vi.fn();
+    const options = frappeCollectionOptions<TestDoc>("Task", {
+      sync: mockSync,
+      onSyncError,
+    });
+
+    const syncFn = options.sync!.sync;
+    const cleanup = syncFn({
+      begin: vi.fn(),
+      write: vi.fn(),
+      commit: vi.fn(),
+      markReady: vi.fn(),
+      truncate: vi.fn(),
+      collection: {} as any,
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    expect(onSyncError).not.toHaveBeenCalled();
+    if (typeof cleanup === "function") cleanup();
+  });
 });
 
 describe("createFrappeCollection", () => {

package/src/collection.ts

@@ -26,6 +26,12 @@ export interface FrappeCollectionOptionsConfig<
   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;
 }
 
 /**
@@ -53,7 +59,7 @@ export function frappeCollectionOptions<TDoc extends object & { name: string; do
   doctype: string,
   config: FrappeCollectionOptionsConfig<TDoc>,
 ): CollectionConfig<TDoc, string> {
-  const { sync: syncModule, fields, filters, orderBy, limit } = config;
+  const { sync: syncModule, fields, filters, orderBy, limit, onSyncError } = config;
 
   const syncFn: SyncConfig<TDoc, string>["sync"] = (params) => {
     const { begin, write, commit, markReady } = params;
@@ -61,6 +67,12 @@ export function frappeCollectionOptions<TDoc extends object & { name: string; do
     let subscriptionId: string | undefined;
     let storeUnsubscribe: (() => void) | undefined;
     let lastKnownNames = new Set<string>();
+    // Set when the collection is cleaned up while the initial subscribe is
+    // still in flight. Without it the continuation would orphan a live
+    // SyncModule subscription (nothing left to unsubscribe it) and the
+    // trailing markReady() would throw on the cleaned-up collection
+    // (invalid "cleaned-up" → "ready" status transition).
+    let cancelled = false;
 
     async function initSync() {
       try {
@@ -74,6 +86,10 @@ export function frappeCollectionOptions<TDoc extends object & { name: string; do
         };
 
         const result = await syncModule.subscribe<TDoc>(query);
+        if (cancelled) {
+          syncModule.unsubscribe(result.subscriptionId);
+          return;
+        }
         subscriptionId = result.subscriptionId;
 
         // Seed initial data from the subscription
@@ -119,9 +135,11 @@ export function frappeCollectionOptions<TDoc extends object & { name: string; do
           lastKnownNames = currentNames;
         });
       } catch (error) {
+        if (cancelled) return;
         console.error(`[frappe-collection] Initial sync failed for ${doctype}:`, error);
+        onSyncError?.(error);
       } finally {
-        markReady();
+        if (!cancelled) markReady();
       }
     }
 
@@ -129,6 +147,7 @@ export function frappeCollectionOptions<TDoc extends object & { name: string; do
 
     // Return cleanup function
     return () => {
+      cancelled = true;
       if (storeUnsubscribe) {
         storeUnsubscribe();
         storeUnsubscribe = undefined;
@@ -250,6 +269,12 @@ export function fixtureCollectionOptions<TDoc extends object & { name: string; d
   const syncFn: SyncConfig<TDoc, string>["sync"] = (params) => {
     const { begin, write, commit, markReady } = params;
 
+    // Same guard as the SyncModule-backed syncFn above: cleanup while the
+    // fixture fetch is in flight must skip the trailing writes + markReady()
+    // — markReady() on a cleaned-up collection throws (invalid
+    // "cleaned-up" → "ready" status transition) as an unhandled rejection.
+    let cancelled = false;
+
     async function initSync() {
       try {
         const orderByForFixture =
@@ -267,6 +292,7 @@ export function fixtureCollectionOptions<TDoc extends object & { name: string; d
           limit,
         });
 
+        if (cancelled) return;
         if (docs.length > 0) {
           begin();
           for (const doc of docs) {
@@ -276,15 +302,18 @@ export function fixtureCollectionOptions<TDoc extends object & { name: string; d
           commit();
         }
       } catch (error) {
+        if (cancelled) return;
         console.error(`[frappe-collection] Fixture sync failed for ${doctype}:`, error);
       } finally {
-        markReady();
+        if (!cancelled) markReady();
       }
     }
 
     initSync();
 
-    return () => {};
+    return () => {
+      cancelled = true;
+    };
   };
 
   return {

package/src/core/http.spec.ts

@@ -544,6 +544,72 @@ describe("HttpClient", () => {
     });
   });
 
+  describe("abort", () => {
+    it("passes the AbortSignal through to fetch", async () => {
+      const mockRes = {
+        ok: true,
+        headers: new Headers({ "Content-Type": "application/json" }),
+        status: 200,
+        json: async () => ({ success: true }),
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      const controller = new AbortController();
+      await client.request(HttpMethod.Get, "/test", { signal: controller.signal });
+      expect(fetch).toHaveBeenCalledWith(
+        `${baseURL}/test`,
+        expect.objectContaining({ signal: controller.signal }),
+      );
+    });
+
+    it("get() forwards the signal", async () => {
+      const mockRes = {
+        ok: true,
+        headers: new Headers({ "Content-Type": "application/json" }),
+        status: 200,
+        json: async () => ({ success: true }),
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      const controller = new AbortController();
+      await client.get("/test", { a: 1 }, undefined, controller.signal);
+      expect(fetch).toHaveBeenCalledWith(
+        `${baseURL}/test?a=1`,
+        expect.objectContaining({ signal: controller.signal }),
+      );
+    });
+
+    it("rejects without retrying when the request is aborted", async () => {
+      // retryOnNetworkError would normally re-issue a rejected fetch — an
+      // abort is a deliberate cancellation and must bypass the retry loop.
+      const retryClient = new HttpClient(baseURL, undefined, {
+        maxRetries: 3,
+        baseDelayMs: 1,
+        retryOnNetworkError: true,
+      });
+      const controller = new AbortController();
+      global.fetch = vi.fn().mockImplementation(async () => {
+        controller.abort();
+        throw new DOMException("The operation was aborted.", "AbortError");
+      });
+      await expect(
+        retryClient.request(HttpMethod.Get, "/test", { signal: controller.signal }),
+      ).rejects.toThrow(/aborted/i);
+      expect(fetch).toHaveBeenCalledTimes(1);
+    });
+
+    it("does not retry an AbortError even without a signal reference", async () => {
+      const retryClient = new HttpClient(baseURL, undefined, {
+        maxRetries: 3,
+        baseDelayMs: 1,
+        retryOnNetworkError: true,
+      });
+      global.fetch = vi
+        .fn()
+        .mockRejectedValue(new DOMException("The operation was aborted.", "AbortError"));
+      await expect(retryClient.request(HttpMethod.Get, "/test", {})).rejects.toThrow(/aborted/i);
+      expect(fetch).toHaveBeenCalledTimes(1);
+    });
+  });
+
   describe("convenience methods", () => {
     beforeEach(() => {
       const mockRes = {

package/src/core/http.ts

@@ -1,4 +1,4 @@
-import { getCookie, setCookie, deleteCookie } from "@multiplatform.one/platform";
+import { getCookie, setCookie, deleteCookie, isNative } from "@multiplatform.one/platform";
 import { isBrowser } from "../util";
 import { FrappeError, HttpMethod } from "./types";
 import type { AuthConfig, RetryConfig } from "./types";
@@ -13,6 +13,16 @@ const defaultRetryConfig: RetryConfig = {
   retryOnNetworkError: true,
   retryStatusCodes: [408, 429, 500, 502, 503, 504],
 };
+
+/**
+ * An aborted request is a deliberate caller cancellation, not a transient
+ * network failure — it must bypass the retry loop entirely (retrying would
+ * re-issue a request the caller explicitly gave up on).
+ */
+function isAbortError(err: unknown, signal?: AbortSignal): boolean {
+  if (signal?.aborted) return true;
+  return err instanceof Error && err.name === "AbortError";
+}
 export type RequestBody = BodyInit | Record<string, unknown> | unknown[] | ArrayBufferView;
 
 export interface HttpResponse<T> {
@@ -26,12 +36,18 @@ export class HttpClient {
   private readonly retryConfig: RetryConfig;
   // Language preference for Accept-Language header (used in SSR / React Native)
   private _language?: string;
+  /** Server-bootstrapped CSRF token for React Native cookie auth (see ensureNativeCsrfToken). */
+  private csrfToken?: string;
+  /** True once a native CSRF bootstrap attempt completed (even if it yielded no token). */
+  private csrfBootstrapDone = false;
+  /** In-flight CSRF bootstrap, deduped across concurrent mutating requests. */
+  private csrfBootstrap?: Promise<void>;
+  private readonly baseURL: string;
+  private auth?: AuthConfig;
 
-  constructor(
-    private readonly baseURL: string,
-    private auth?: AuthConfig,
-    retryConfig?: RetryConfig,
-  ) {
+  constructor(baseURL: string, auth?: AuthConfig, retryConfig?: RetryConfig) {
+    this.baseURL = baseURL;
+    this.auth = auth;
     this.retryConfig = { ...defaultRetryConfig, ...retryConfig };
   }
 
@@ -58,6 +74,74 @@ export class HttpClient {
     });
   }
 
+  /**
+   * 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 async ensureNativeCsrfToken(): Promise<string | undefined> {
+    if (this.csrfBootstrapDone) return this.csrfToken;
+    if (!this.csrfBootstrap) {
+      this.csrfBootstrap = this.fetchNativeCsrfToken()
+        .then((token) => {
+          this.csrfToken = token;
+          this.csrfBootstrapDone = true;
+        })
+        .finally(() => {
+          this.csrfBootstrap = undefined;
+        });
+    }
+    await this.csrfBootstrap;
+    return this.csrfToken;
+  }
+
+  private async fetchNativeCsrfToken(): Promise<string | undefined> {
+    try {
+      const rpcUrl = new URL("/api/method/frappe.sessions.get_csrf_token", this.baseURL).toString();
+      const res = await fetch(rpcUrl, { method: "GET", credentials: "include" });
+      if (res.ok) {
+        const payload = (await res.json()) as { message?: unknown };
+        if (typeof payload?.message === "string" && payload.message) return payload.message;
+      }
+    } catch {
+      // Fall through to the HTML fallback.
+    }
+    try {
+      const appUrl = new URL("/app", this.baseURL).toString();
+      const res = await fetch(appUrl, { method: "GET", credentials: "include" });
+      if (res.ok) {
+        const html = await res.text();
+        const match = html.match(/frappe\.csrf_token\s*=\s*"([^"]+)"/);
+        if (match?.[1]) return match[1];
+      }
+    } catch {
+      // No token available — proceed without the header.
+    }
+    return undefined;
+  }
+
+  private invalidateNativeCsrfToken(): void {
+    this.csrfToken = undefined;
+    this.csrfBootstrapDone = false;
+  }
+
   private async getAuthHeaders(): Promise<Record<string, string>> {
     if (!this.auth?.useToken) return {};
     const raw = typeof this.auth.token === "function" ? await this.auth.token() : this.auth?.token;
@@ -97,6 +181,8 @@ export class HttpClient {
     request: {
       body?: RequestBody;
       headers?: Record<string, string>;
+      /** Cancels the request (and any pending retry) when aborted. */
+      signal?: AbortSignal;
     },
   ): Promise<HttpResponse<T>> {
     const url = new URL(path, this.baseURL).toString();
@@ -177,8 +263,12 @@ export class HttpClient {
       headers.set("Accept-Language", lang);
     }
     if (!this.auth?.useToken && isBrowser() && method !== HttpMethod.Get) {
-      const csrf =
+      let csrf =
         getCookie("frappe-csrf-token") || getCookie("csrf_token") || globalThis.frappe?.csrf_token;
+      // React Native cannot read the OS cookie jar — bootstrap the token
+      // from the server before the first mutating request (native only;
+      // web keeps the cookie-read path above unchanged).
+      if (!csrf && isNative) csrf = await this.ensureNativeCsrfToken();
       if (csrf) headers.set("X-Frappe-CSRF-Token", csrf);
     }
     const makeRequest = (): Promise<Response> => {
@@ -187,6 +277,7 @@ export class HttpClient {
         headers,
         credentials: this.auth?.useToken ? "omit" : "include",
         body,
+        signal: request?.signal,
       });
     };
     let lastError: unknown;
@@ -203,6 +294,12 @@ export class HttpClient {
             (payload && (payload.message || payload.exc || payload._server_messages)) ||
             res.statusText;
           const err = new FrappeError(message, res.status, payload);
+          // Native cookie-auth: a 400 on a mutating request may be frappe's
+          // CSRFTokenError from a rotated session — drop the cached token so
+          // the next mutation re-bootstraps.
+          if (isNative && res.status === 400 && !this.auth?.useToken && method !== HttpMethod.Get) {
+            this.invalidateNativeCsrfToken();
+          }
           if (this.shouldRetryError(err, attempt)) {
             lastError = err;
             attempt++;
@@ -224,6 +321,7 @@ export class HttpClient {
           _res: res,
         };
       } catch (err) {
+        if (isAbortError(err, request?.signal)) throw err;
         if (this.shouldRetryError(err, attempt)) {
           lastError = err;
           attempt++;
@@ -238,9 +336,14 @@ export class HttpClient {
     throw lastError;
   }
 
-  get<T>(path: string, params?: Record<string, unknown>, headers?: Record<string, string>) {
+  get<T>(
+    path: string,
+    params?: Record<string, unknown>,
+    headers?: Record<string, string>,
+    signal?: AbortSignal,
+  ) {
     const qs = params ? `?${new URLSearchParams(normalizeParams(params)).toString()}` : "";
-    return this.request<T>(HttpMethod.Get, `${path}${qs}`, { headers });
+    return this.request<T>(HttpMethod.Get, `${path}${qs}`, { headers, signal });
   }
 
   post<T>(path: string, body?: RequestBody, headers?: Record<string, string>) {
@@ -266,6 +369,9 @@ export class HttpClient {
 
   updateAuth(auth: AuthConfig) {
     this.auth = auth;
+    // Auth change usually means session change — the cached native CSRF
+    // token belongs to the old session.
+    this.invalidateNativeCsrfToken();
   }
 }