@multiplatform.one/frappe 6.0.0

package/src/frappeApp.ts

@@ -0,0 +1,125 @@
+import { AuthModule } from "./auth";
+import { CallModule } from "./call";
+import { HttpClient } from "./core/http";
+import type { AuthConfig, CustomEndpoints, FrappeLiveConfig } from "./core/types";
+import { DbModule } from "./db";
+import { FileModule } from "./file";
+import { type RealtimeConfig, RealtimeModule } from "./realtime";
+import { SyncModule } from "./sync/index";
+
+export type FrappeConfig = AuthConfig & {
+  sessionId?: string;
+  credentials?: RequestCredentials;
+  realtimeOptions?: Partial<RealtimeConfig>;
+  /** Configuration for frappe_live extension endpoints */
+  frappeLive?: FrappeLiveConfig;
+  /**
+   * Raw cookie string forwarded on every HTTP request.
+   * Use this in SSR / Node.js where the browser cookie jar is unavailable.
+   *
+   * @example `"sid=abc123; system_user=yes"`
+   */
+  cookie?: string;
+};
+
+/**
+ * Main entry point for Frappe SDK
+ * Orchestrates all modules and provides unified API
+ */
+export class FrappeApp {
+  private http: HttpClient;
+  private _db: DbModule;
+  private _auth: AuthModule;
+  private _call: CallModule;
+  private _file: FileModule;
+  private _realtime: RealtimeModule;
+  private _sync: SyncModule;
+
+  constructor(baseURL: string, auth: FrappeConfig = {}, customEndpoints: CustomEndpoints = {}) {
+    this.http = new HttpClient(baseURL, auth);
+    // Merge constructor customEndpoints with auth.frappeLive (frappeLive wins on overlap)
+    const frappeLiveConfig: FrappeLiveConfig = {
+      appName: auth.frappeLive?.appName,
+      customEndpoints: {
+        ...customEndpoints,
+        ...auth.frappeLive?.customEndpoints,
+      },
+    };
+    this._db = new DbModule(this.http, frappeLiveConfig);
+    this._auth = new AuthModule(this.http);
+    this._call = new CallModule(this.http);
+    this._file = new FileModule(this.http);
+
+    // Configure RealtimeModule with proper Socket.IO settings
+    const realtimeConfig: RealtimeConfig = {
+      baseURL,
+      auth: auth.useToken
+        ? {
+            useToken: auth.useToken,
+            token: auth.token,
+            type: auth.type,
+          }
+        : undefined,
+      ...auth.realtimeOptions,
+    };
+    this._realtime = new RealtimeModule(realtimeConfig);
+
+    // Initialize sync module with default options
+    this._sync = new SyncModule(this._db, this._realtime, {
+      pageSize: 20,
+      persistKey: "frappe-sync",
+      onMutationError: (info) => {
+        console.error("Mutation error:", info);
+      },
+      onConflict: (info) => {
+        console.warn("Conflict detected:", info);
+      },
+    });
+  }
+
+  // Module accessors
+  db() {
+    return this._db;
+  }
+  auth() {
+    return this._auth;
+  }
+  call() {
+    return this._call;
+  }
+  file() {
+    return this._file;
+  }
+  realtime() {
+    return this._realtime;
+  }
+  sync() {
+    return this._sync;
+  }
+
+  // Cleanup
+  async dispose() {
+    this._realtime.disconnect();
+    await this._sync.dispose();
+  }
+
+  // Config management
+  getConfig(): FrappeConfig {
+    return this.http.getAuthConfig() as FrappeConfig;
+  }
+
+  async updateAuth(auth: FrappeConfig) {
+    this.http.updateAuth(auth);
+
+    // Update realtime auth with new configuration
+    if (auth.useToken && auth.token) {
+      await this._realtime.updateAuth({
+        useToken: auth.useToken,
+        token: auth.token,
+        type: auth.type,
+      });
+    } else {
+      await this._realtime.updateAuth({});
+    }
+  }
+}

package/src/frappeReact.spec.ts

@@ -0,0 +1,505 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { act, renderHook, waitFor } from "@testing-library/react";
+
+const {
+  mockSubscribe,
+  mockUnsubscribe,
+  mockGetDocsForSubscription,
+  mockGetPageInfo,
+  mockGetNextBatch,
+  mockSubscribeStore,
+} = vi.hoisted(() => ({
+  mockSubscribe: vi.fn(),
+  mockUnsubscribe: vi.fn(),
+  mockGetDocsForSubscription: vi.fn(),
+  mockGetPageInfo: vi.fn(),
+  mockGetNextBatch: vi.fn(),
+  mockSubscribeStore: vi.fn(),
+}));
+
+vi.mock("./sync", () => ({
+  SyncModule: class {
+    subscribe = mockSubscribe;
+    unsubscribe = mockUnsubscribe;
+    getDocsForSubscription = mockGetDocsForSubscription;
+    getPageInfo = mockGetPageInfo;
+    getNextBatch = mockGetNextBatch;
+    subscribeStore = mockSubscribeStore;
+  },
+}));
+
+vi.mock("./realtime", () => ({ RealtimeModule: class {} }));
+vi.mock("./core/http", () => ({ HttpClient: class {} }));
+vi.mock("./db", () => ({ DbModule: class {} }));
+const { mockCreateFrappeCollection, mockIsBrowser } = vi.hoisted(() => ({
+  mockCreateFrappeCollection: vi.fn(),
+  mockIsBrowser: vi.fn(() => true),
+}));
+
+vi.mock("./collection", () => ({ createFrappeCollection: mockCreateFrappeCollection }));
+vi.mock("./util", () => ({ isBrowser: mockIsBrowser }));
+vi.mock("./fixtureDb", () => ({ FixtureDbModule: class {} }));
+
+import { isBrowser } from "./util";
+import type { UseFrappeCollectionConfig, UseFrappeInfiniteListConfig } from "./frappeReact";
+import {
+  __getActiveSyncModule,
+  useFrappeCollection,
+  useFrappeInfiniteList,
+  useInfiniteScroll,
+} from "./frappeReact";
+
+interface TestDoc {
+  name: string;
+  doctype: string;
+  title: string;
+}
+
+const testDocs: TestDoc[] = [
+  { name: "doc-1", doctype: "Task", title: "Task 1" },
+  { name: "doc-2", doctype: "Task", title: "Task 2" },
+  { name: "doc-3", doctype: "Task", title: "Task 3" },
+];
+
+describe("useFrappeInfiniteList", () => {
+  let storeListener: (() => void) | undefined;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    storeListener = undefined;
+
+    mockSubscribe.mockResolvedValue({
+      subscriptionId: "sub-1",
+      rows: testDocs,
+      checkpoint: "2024-01-01T12:00:00",
+    });
+    mockGetDocsForSubscription.mockReturnValue(testDocs);
+    mockGetPageInfo.mockReturnValue({ hasMore: true, currentPage: 1 });
+    mockGetNextBatch.mockResolvedValue(testDocs);
+    mockSubscribeStore.mockImplementation((listener: () => void) => {
+      storeListener = listener;
+      return vi.fn();
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  const defaultConfig: UseFrappeInfiniteListConfig<TestDoc> = {
+    config: { baseURL: "http://test.local" },
+    doctype: "Task",
+    fields: ["name", "title"],
+    pageSize: 20,
+  };
+
+  it("should subscribe with progressive: true on mount", async () => {
+    const { result } = renderHook(() => useFrappeInfiniteList(defaultConfig));
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(mockSubscribe).toHaveBeenCalledWith(
+      expect.objectContaining({
+        doctype: "Task",
+        progressive: true,
+        limit: 20,
+      }),
+    );
+  });
+
+  it("should populate items after subscription resolves", async () => {
+    const { result } = renderHook(() => useFrappeInfiniteList(defaultConfig));
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.items).toHaveLength(3);
+    expect(result.current.items[0].name).toBe("doc-1");
+    expect(result.current.hasMore).toBe(true);
+  });
+
+  it("should set error state on subscribe failure", async () => {
+    mockSubscribe.mockRejectedValueOnce(new Error("Network error"));
+
+    const { result } = renderHook(() => useFrappeInfiniteList(defaultConfig));
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.error).toBeInstanceOf(Error);
+    expect(result.current.error!.message).toBe("Network error");
+    expect(result.current.items).toHaveLength(0);
+  });
+
+  it("should call getNextBatch on loadMore", async () => {
+    const { result } = renderHook(() => useFrappeInfiniteList(defaultConfig));
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    await act(async () => {
+      await result.current.loadMore();
+    });
+
+    expect(mockGetNextBatch).toHaveBeenCalledWith("sub-1", "doc-3", 20);
+  });
+
+  it("should not loadMore when hasMore is false", async () => {
+    mockGetPageInfo.mockReturnValue({ hasMore: false, currentPage: 1 });
+
+    const { result } = renderHook(() => useFrappeInfiniteList(defaultConfig));
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    await act(async () => {
+      await result.current.loadMore();
+    });
+
+    expect(mockGetNextBatch).not.toHaveBeenCalled();
+  });
+
+  it("should unsubscribe on unmount", async () => {
+    const { result, unmount } = renderHook(() => useFrappeInfiniteList(defaultConfig));
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    unmount();
+
+    expect(mockUnsubscribe).toHaveBeenCalledWith("sub-1");
+  });
+
+  it("should update items when store listener fires", async () => {
+    const { result } = renderHook(() => useFrappeInfiniteList(defaultConfig));
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    const updatedDocs = [...testDocs, { name: "doc-4", doctype: "Task", title: "Task 4" }];
+    mockGetDocsForSubscription.mockReturnValue(updatedDocs);
+    mockGetPageInfo.mockReturnValue({ hasMore: false, currentPage: 1 });
+
+    act(() => {
+      storeListener?.();
+    });
+
+    expect(result.current.items).toHaveLength(4);
+    expect(result.current.hasMore).toBe(false);
+  });
+
+  it("should apply transform to items", async () => {
+    const config: UseFrappeInfiniteListConfig<TestDoc> = {
+      ...defaultConfig,
+      transform: (doc) => ({ ...doc, title: doc.title.toUpperCase() }),
+    };
+
+    const { result } = renderHook(() => useFrappeInfiniteList(config));
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.items[0].title).toBe("TASK 1");
+  });
+
+  it("should refresh by re-subscribing", async () => {
+    const { result } = renderHook(() => useFrappeInfiniteList(defaultConfig));
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    mockSubscribe.mockResolvedValueOnce({
+      subscriptionId: "sub-2",
+      rows: [testDocs[0]],
+      checkpoint: "2024-01-02T12:00:00",
+    });
+    mockGetDocsForSubscription.mockReturnValue([testDocs[0]]);
+
+    await act(async () => {
+      await result.current.refresh();
+    });
+
+    expect(mockUnsubscribe).toHaveBeenCalledWith("sub-1");
+    expect(mockSubscribe).toHaveBeenCalledTimes(2);
+  });
+
+  it("should return loading state while subscribing", () => {
+    mockSubscribe.mockReturnValue(new Promise(() => {})); // never resolves
+
+    const { result } = renderHook(() => useFrappeInfiniteList(defaultConfig));
+
+    expect(result.current.isLoading).toBe(true);
+    expect(result.current.items).toHaveLength(0);
+  });
+
+  it("should not subscribe when config is undefined", () => {
+    const config: UseFrappeInfiniteListConfig<TestDoc> = {
+      ...defaultConfig,
+      config: undefined,
+    };
+
+    renderHook(() => useFrappeInfiniteList(config));
+
+    expect(mockSubscribe).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// useFrappeCollection
+// ---------------------------------------------------------------------------
+
+describe("useFrappeCollection", () => {
+  // Use a counter so each test gets a unique baseURL — avoids syncModuleCache hits
+  let testNum = 0;
+  const mockCollection = { id: "mock-collection" } as any;
+
+  beforeEach(() => {
+    testNum++;
+    vi.clearAllMocks();
+    mockIsBrowser.mockReturnValue(true);
+    mockCreateFrappeCollection.mockReturnValue(mockCollection);
+  });
+
+  afterEach(() => {
+    mockIsBrowser.mockReturnValue(true);
+  });
+
+  it("returns undefined when config is undefined", () => {
+    const { result } = renderHook(() => useFrappeCollection(undefined, "Task"));
+    expect(result.current).toBeUndefined();
+  });
+
+  it("returns undefined during SSR (isBrowser returns false)", () => {
+    mockIsBrowser.mockReturnValue(false);
+    const config: UseFrappeCollectionConfig = { baseURL: `https://ssr-${testNum}.example.com` };
+    const { result } = renderHook(() => useFrappeCollection(config, "Task"));
+    expect(result.current).toBeUndefined();
+    expect(mockCreateFrappeCollection).not.toHaveBeenCalled();
+  });
+
+  it("creates a collection in a browser environment", () => {
+    const config: UseFrappeCollectionConfig = { baseURL: `https://browser-${testNum}.example.com` };
+    const { result } = renderHook(() => useFrappeCollection(config, "Pokemon"));
+    expect(mockCreateFrappeCollection).toHaveBeenCalledWith(
+      "Pokemon",
+      expect.objectContaining({ sync: expect.any(Object) }),
+    );
+    expect(result.current).toBe(mockCollection);
+  });
+
+  it("returns the same collection instance on re-render (stable ref)", () => {
+    const config: UseFrappeCollectionConfig = { baseURL: `https://stable-${testNum}.example.com` };
+    const { result, rerender } = renderHook(() => useFrappeCollection(config, "Task"));
+    const first = result.current;
+    rerender();
+    rerender();
+    expect(result.current).toBe(first);
+    expect(mockCreateFrappeCollection).toHaveBeenCalledTimes(1);
+  });
+
+  it("creates a new collection when baseURL changes", () => {
+    const mockCollection2 = { id: "mock-collection-2" } as any;
+    mockCreateFrappeCollection
+      .mockReturnValueOnce(mockCollection)
+      .mockReturnValueOnce(mockCollection2);
+
+    const { result, rerender } = renderHook(
+      ({ baseURL }: { baseURL: string }) => useFrappeCollection({ baseURL }, "Task"),
+      { initialProps: { baseURL: `https://change-a-${testNum}.example.com` } },
+    );
+
+    const first = result.current;
+    rerender({ baseURL: `https://change-b-${testNum}.example.com` });
+
+    expect(result.current).not.toBe(first);
+    expect(mockCreateFrappeCollection).toHaveBeenCalledTimes(2);
+  });
+
+  it("clears the collection when config becomes undefined", () => {
+    const config: UseFrappeCollectionConfig = { baseURL: `https://clear-${testNum}.example.com` };
+    const { result, rerender } = renderHook(
+      ({ cfg }: { cfg: UseFrappeCollectionConfig | undefined }) => useFrappeCollection(cfg, "Task"),
+      { initialProps: { cfg: config as UseFrappeCollectionConfig | undefined } },
+    );
+
+    expect(result.current).toBeDefined();
+    rerender({ cfg: undefined });
+    expect(result.current).toBeUndefined();
+  });
+
+  it("__getActiveSyncModule returns a SyncModule after a collection is created", () => {
+    const config: UseFrappeCollectionConfig = { baseURL: `https://active-${testNum}.example.com` };
+    renderHook(() => useFrappeCollection(config, "Task"));
+    const active = __getActiveSyncModule();
+    expect(active).toBeDefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// useInfiniteScroll
+// ---------------------------------------------------------------------------
+
+describe("useInfiniteScroll", () => {
+  let ioInstances: Array<{
+    observe: ReturnType<typeof vi.fn>;
+    disconnect: ReturnType<typeof vi.fn>;
+    cb: IntersectionObserverCallback;
+  }>;
+
+  function installMockIO() {
+    ioInstances = [];
+    const MockIO = function (this: any, cb: IntersectionObserverCallback) {
+      const instance = { observe: vi.fn(), disconnect: vi.fn(), cb };
+      ioInstances.push(instance);
+      this.observe = instance.observe;
+      this.disconnect = instance.disconnect;
+    } as unknown as typeof IntersectionObserver;
+    vi.stubGlobal("IntersectionObserver", MockIO);
+  }
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+  });
+
+  it("returns correct initial state", () => {
+    const { result } = renderHook(() =>
+      useInfiniteScroll({ hasMore: true, isLoading: false, onLoadMore: vi.fn() }),
+    );
+    expect(result.current.isVisible).toBe(false);
+    expect(result.current.isLoadingMore).toBe(false);
+    expect(typeof result.current.sentinelRef).toBe("function");
+  });
+
+  it("does not create IntersectionObserver when enabled=false", async () => {
+    installMockIO();
+
+    const el = document.createElement("div");
+    const { result } = renderHook(() =>
+      useInfiniteScroll({ hasMore: true, isLoading: false, onLoadMore: vi.fn(), enabled: false }),
+    );
+
+    await act(async () => {
+      result.current.sentinelRef(el);
+    });
+
+    expect(ioInstances).toHaveLength(0);
+  });
+
+  it("creates IntersectionObserver and observes element when enabled and sentinel is set", async () => {
+    installMockIO();
+
+    const el = document.createElement("div");
+    const { result, rerender } = renderHook(
+      ({ enabled }: { enabled: boolean }) =>
+        useInfiniteScroll({ hasMore: true, isLoading: false, onLoadMore: vi.fn(), enabled }),
+      { initialProps: { enabled: false } },
+    );
+
+    await act(async () => {
+      result.current.sentinelRef(el);
+    });
+    await act(async () => {
+      rerender({ enabled: true });
+    });
+
+    expect(ioInstances).toHaveLength(1);
+    expect(ioInstances[0].observe).toHaveBeenCalledWith(el);
+  });
+
+  it("calls onLoadMore when intersection fires with hasMore=true", async () => {
+    installMockIO();
+    const onLoadMore = vi.fn().mockResolvedValue(undefined);
+
+    const el = document.createElement("div");
+    const { result, rerender } = renderHook(
+      ({ enabled }: { enabled: boolean }) =>
+        useInfiniteScroll({
+          hasMore: true,
+          isLoading: false,
+          onLoadMore,
+          debounceMs: 0,
+          enabled,
+        }),
+      { initialProps: { enabled: false } },
+    );
+
+    await act(async () => {
+      result.current.sentinelRef(el);
+    });
+    await act(async () => {
+      rerender({ enabled: true });
+    });
+
+    expect(ioInstances).toHaveLength(1);
+
+    await act(async () => {
+      ioInstances[0].cb(
+        [{ isIntersecting: true } as IntersectionObserverEntry],
+        {} as IntersectionObserver,
+      );
+    });
+    await act(async () => {
+      vi.runAllTimers();
+    });
+
+    expect(onLoadMore).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not call onLoadMore when hasMore=false", async () => {
+    installMockIO();
+    const onLoadMore = vi.fn();
+
+    const el = document.createElement("div");
+    const { result, rerender } = renderHook(
+      ({ enabled }: { enabled: boolean }) =>
+        useInfiniteScroll({
+          hasMore: false,
+          isLoading: false,
+          onLoadMore,
+          debounceMs: 0,
+          enabled,
+        }),
+      { initialProps: { enabled: false } },
+    );
+
+    await act(async () => {
+      result.current.sentinelRef(el);
+    });
+    await act(async () => {
+      rerender({ enabled: true });
+    });
+
+    if (ioInstances.length > 0) {
+      await act(async () => {
+        ioInstances[0].cb(
+          [{ isIntersecting: true } as IntersectionObserverEntry],
+          {} as IntersectionObserver,
+        );
+      });
+    }
+    await act(async () => {
+      vi.runAllTimers();
+    });
+
+    expect(onLoadMore).not.toHaveBeenCalled();
+  });
+
+  it("disconnects IntersectionObserver on unmount", async () => {
+    installMockIO();
+
+    const el = document.createElement("div");
+    const { result, rerender, unmount } = renderHook(
+      ({ enabled }: { enabled: boolean }) =>
+        useInfiniteScroll({ hasMore: true, isLoading: false, onLoadMore: vi.fn(), enabled }),
+      { initialProps: { enabled: false } },
+    );
+
+    await act(async () => {
+      result.current.sentinelRef(el);
+    });
+    await act(async () => {
+      rerender({ enabled: true });
+    });
+
+    unmount();
+    expect(ioInstances[0].disconnect).toHaveBeenCalled();
+  });
+});