@multiplatform.one/frappe 7.10.0 → 7.15.0

package/src/doctype.ts

@@ -5,95 +5,160 @@
  * documents, and searching across DocTypes for navigation (Awesomebar).
  */
 
+import { getCookie } from "@multiplatform.one/platform";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { HttpClient } from "./core/http";
-import type { AuthConfig } from "./core/types";
+import { FrappeError, type AuthConfig } from "./core/types";
 import type { FrappeConnectionConfig } from "./pacer";
 
 // ---------------------------------------------------------------------------
 // Type Definitions
 // ---------------------------------------------------------------------------
 
-/** All Frappe field type strings */
-export type FrappeFieldType =
-  | "Autocomplete"
-  | "Attach"
-  | "Attach Image"
-  | "Barcode"
-  | "Button"
-  | "Check"
-  | "Code"
-  | "Color"
-  | "Column Break"
-  | "Currency"
-  | "Data"
-  | "Date"
-  | "Datetime"
-  | "Duration"
-  | "Dynamic Link"
-  | "Float"
-  | "Geolocation"
-  | "HTML"
-  | "HTML Editor"
-  | "Heading"
-  | "Icon"
-  | "Image"
-  | "Int"
-  | "JSON"
-  | "Link"
-  | "Long Text"
-  | "Markdown Editor"
-  | "Password"
-  | "Percent"
-  | "Phone"
-  | "Rating"
-  | "Read Only"
-  | "Section Break"
-  | "Select"
-  | "Signature"
-  | "Small Text"
-  | "Tab Break"
-  | "Table"
-  | "Table MultiSelect"
-  | "Text"
-  | "Text Editor"
-  | "Time";
-
-/** Normalized DocType field descriptor */
+/**
+ * Every fieldtype a Frappe bench serves: the options of `DocField.fieldtype`.
+ */
+export const stockFieldTypes = [
+  "Autocomplete",
+  "Attach",
+  "Attach Image",
+  "Barcode",
+  "Button",
+  "Check",
+  "Code",
+  "Color",
+  "Column Break",
+  "Currency",
+  "Data",
+  "Date",
+  "Datetime",
+  "Duration",
+  "Dynamic Link",
+  "Float",
+  "Fold",
+  "Geolocation",
+  "HTML",
+  "HTML Editor",
+  "Heading",
+  "Icon",
+  "Image",
+  "Int",
+  "JSON",
+  "Link",
+  "Long Text",
+  "Markdown Editor",
+  "Password",
+  "Percent",
+  "Phone",
+  "Rating",
+  "Read Only",
+  "Section Break",
+  "Select",
+  "Signature",
+  "Small Text",
+  "Tab Break",
+  "Table",
+  "Table MultiSelect",
+  "Text",
+  "Text Editor",
+  "Time",
+] as const;
+
+/**
+ * Fieldtypes no bench serves. frappe-ui's field registry renders them for
+ * hand-written meta, so they belong to the union: the registry must never
+ * accept a fieldtype the meta model forbids (MPO-15).
+ */
+export const customFieldTypes = [
+  "Date Range",
+  "Mention",
+  "OTP",
+  "Progress",
+  "Radio",
+  "Slider",
+  "Switch",
+  "Toggle Group",
+] as const;
+
+/** Every fieldtype a `DocTypeField` may carry, and all `registerField` accepts. */
+export const frappeFieldTypes = [...stockFieldTypes, ...customFieldTypes] as const;
+
+export type FrappeFieldType = (typeof frappeFieldTypes)[number];
+
+/**
+ * One DocField row as `frappe.desk.form.load.getdoctype` sends it. This is
+ * the only field model: the desk form engine, the list surfaces and
+ * `useDocTypeMeta` all read it. Flags stay the server's `0 | 1`, and the
+ * index signature carries the keys no surface reads yet.
+ */
 export interface DocTypeField {
   fieldname: string;
   fieldtype: FrappeFieldType;
   label?: string;
   /** Link target DocType, Select options, or Table child DocType */
   options?: string;
-  reqd?: boolean;
-  unique?: boolean;
-  default?: string;
+  reqd?: 0 | 1;
+  unique?: 0 | 1;
+  hidden?: 0 | 1;
+  read_only?: 0 | 1;
+  bold?: 0 | 1;
+  in_list_view?: 0 | 1;
+  in_standard_filter?: 0 | 1;
+  in_global_search?: 0 | 1;
+  allow_in_quick_entry?: 0 | 1;
+  allow_on_submit?: 0 | 1;
+  no_copy?: 0 | 1;
+  set_only_once?: 0 | 1;
+  report_hide?: 0 | 1;
+  /** For Section Break fields: whether the section is collapsible */
+  collapsible?: 0 | 1;
+  collapsible_depends_on?: string;
   /** Conditional visibility expression (e.g. `eval:doc.status=="Active"`) */
   depends_on?: string;
-  read_only?: boolean;
-  hidden?: boolean;
-  in_list_view?: boolean;
-  in_standard_filter?: boolean;
-  description?: string;
+  mandatory_depends_on?: string;
+  read_only_depends_on?: string;
+  fetch_from?: string;
+  fetch_if_empty?: 0 | 1;
+  permlevel?: number;
   length?: number;
-  precision?: number;
+  precision?: string | number;
+  default?: string;
+  description?: string;
   /** For Link fields: comma-separated search fields */
   search_fields?: string;
-  /** For Section Break fields: whether the section is collapsible */
-  collapsible?: boolean;
+  idx?: number;
+  [key: string]: unknown;
 }
 
-/** DocType permission entry */
+/** Role permission row from the DocType meta. */
 export interface DocTypePermission {
-  role: string;
-  read?: boolean;
-  write?: boolean;
-  create?: boolean;
-  delete?: boolean;
-  submit?: boolean;
-  cancel?: boolean;
-  amend?: boolean;
+  role?: string;
+  permlevel?: number;
+  read?: 0 | 1;
+  write?: 0 | 1;
+  create?: 0 | 1;
+  delete?: 0 | 1;
+  submit?: 0 | 1;
+  cancel?: 0 | 1;
+  amend?: 0 | 1;
+  print?: 0 | 1;
+  email?: 0 | 1;
+  share?: 0 | 1;
+  if_owner?: 0 | 1;
+  [key: string]: unknown;
+}
+
+/** DocType Link child row (Connections tab). Probed: `group` arrives null when unset. */
+export interface DocTypeLink {
+  name?: string;
+  link_doctype: string;
+  link_fieldname: string;
+  group?: string | null;
+  hidden?: 0 | 1;
+  is_child_table?: 0 | 1;
+  parent_doctype?: string;
+  table_fieldname?: string;
+  [key: string]: unknown;
 }
 
 /** A column in a form section, containing an ordered list of fields */
@@ -110,20 +175,48 @@ export interface FormSection {
   columns: FormColumn[];
 }
 
-/** Normalized DocType metadata */
+/** DocType meta as `frappe.desk.form.load.getdoctype` sends it (loose: the server is the source of truth). */
 export interface DocTypeMeta {
+  doctype?: string;
   name: string;
-  module: string;
+  module?: string;
+  issingle?: 0 | 1;
+  istable?: 0 | 1;
+  is_submittable?: 0 | 1;
+  is_tree?: 0 | 1;
+  /** Desk treeview_settings asset (`{doctype}_tree.js`) — gates Tree. */
+  __tree_js?: string;
+  /** Desk calendar_settings asset (`{doctype}_calendar.js`) — gates Calendar. */
+  __calendar_js?: string;
+  is_virtual?: 0 | 1;
+  editable_grid?: 0 | 1;
+  track_changes?: 0 | 1;
+  quick_entry?: 0 | 1;
+  autoname?: string;
+  naming_rule?: string;
+  allow_rename?: 0 | 1;
+  allow_copy?: 0 | 1;
+  read_only?: 0 | 1;
+  in_create?: 0 | 1;
+  hide_toolbar?: 0 | 1;
+  max_attachments?: number;
   title_field?: string;
   image_field?: string;
-  is_tree?: boolean;
-  sort_field: string;
-  sort_order: string;
-  /** Flat list of all fields (ordered by field_order or position) */
+  search_fields?: string;
+  sort_field?: string;
+  sort_order?: string;
+  icon?: string;
+  document_type?: string;
+  /** May arrive as a JSON string or an already-parsed array. */
+  field_order?: string[] | string;
+  /** Flat list of all fields (`useDocTypeMeta` orders them by `field_order`) */
   fields: DocTypeField[];
-  /** Parsed layout tree from Section Break / Column Break / Tab Break fields */
-  sections: FormSection[];
-  permissions: DocTypePermission[];
+  permissions?: DocTypePermission[];
+  links?: DocTypeLink[];
+  states?: Array<{ title?: string; color?: string } & Record<string, unknown>>;
+  /** Layout tree parsed from the break fields. `useDocTypeMeta` fills it; a raw getdoctype doc has none. */
+  sections?: FormSection[];
+  [key: string]: unknown;
 }
 
 /** A search result for a Link field */
@@ -191,54 +284,6 @@ interface DocTypeListItem {
   title?: string;
 }
 
-// ---------------------------------------------------------------------------
-// Raw API response types (internal)
-// ---------------------------------------------------------------------------
-
-interface RawDocTypeResponse {
-  name: string;
-  module: string;
-  title_field?: string;
-  image_field?: string;
-  is_tree?: number;
-  sort_field?: string;
-  sort_order?: string;
-  field_order?: string[] | string;
-  fields: RawFieldResponse[];
-  permissions?: RawPermissionResponse[];
-}
-
-interface RawFieldResponse {
-  fieldname: string;
-  fieldtype: string;
-  label?: string;
-  options?: string;
-  reqd?: number;
-  unique?: number;
-  default?: string;
-  depends_on?: string;
-  read_only?: number;
-  hidden?: number;
-  in_list_view?: number;
-  in_standard_filter?: number;
-  description?: string;
-  length?: number;
-  precision?: number;
-  search_fields?: string;
-  collapsible?: number;
-}
-
-interface RawPermissionResponse {
-  role: string;
-  read?: number;
-  write?: number;
-  create?: number;
-  delete?: number;
-  submit?: number;
-  cancel?: number;
-  amend?: number;
-}
-
 // ---------------------------------------------------------------------------
 // Utility: parseDependsOn
 // ---------------------------------------------------------------------------
@@ -328,7 +373,7 @@ export function parseFormLayout(fields: DocTypeField[]): FormSection[] {
       case "Section Break":
         currentSection = {
           label: field.label,
-          collapsible: field.collapsible,
+          collapsible: !!field.collapsible,
           columns: [{ fields: [] }],
         };
         sections.push(currentSection);
@@ -384,39 +429,18 @@ function createHttpClient(config: FrappeConnectionConfig): HttpClient | undefine
   return new HttpClient(config.baseURL, authConfig);
 }
 
-function parseRawField(raw: RawFieldResponse): DocTypeField {
-  return {
-    fieldname: raw.fieldname,
-    fieldtype: raw.fieldtype as FrappeFieldType,
-    label: raw.label,
-    options: raw.options,
-    reqd: !!raw.reqd,
-    unique: !!raw.unique,
-    default: raw.default,
-    depends_on: raw.depends_on,
-    read_only: !!raw.read_only,
-    hidden: !!raw.hidden,
-    in_list_view: !!raw.in_list_view,
-    in_standard_filter: !!raw.in_standard_filter,
-    description: raw.description,
-    length: raw.length,
-    precision: raw.precision,
-    search_fields: raw.search_fields,
-    collapsible: !!raw.collapsible,
-  };
-}
-
-function parseRawPermission(raw: RawPermissionResponse): DocTypePermission {
-  return {
-    role: raw.role,
-    read: !!raw.read,
-    write: !!raw.write,
-    create: !!raw.create,
-    delete: !!raw.delete,
-    submit: !!raw.submit,
-    cancel: !!raw.cancel,
-    amend: !!raw.amend,
-  };
+/**
+ * True when requests on this connection reach Frappe as Guest: it names a
+ * token source, the source resolves empty (signed out), and no Frappe desk
+ * session cookie names a user. A cookie-only connection names no token
+ * source, so it is never judged here.
+ */
+async function connectsAsGuest(auth: FrappeConnectionConfig["auth"]): Promise<boolean> {
+  if (!auth?.useToken || !auth.token) return false;
+  const token = typeof auth.token === "function" ? await auth.token() : auth.token;
+  if (token) return false;
+  const user = getCookie("user_id");
+  return !user || user === "Guest";
 }
 
 function orderFields(fields: DocTypeField[], fieldOrder: string[]): DocTypeField[] {
@@ -442,8 +466,8 @@ function orderFields(fields: DocTypeField[], fieldOrder: string[]): DocTypeField
   return ordered;
 }
 
-function parseRawDocTypeMeta(raw: RawDocTypeResponse): DocTypeMeta {
-  const fields = raw.fields.map(parseRawField);
+function parseRawDocTypeMeta(raw: DocTypeMeta): DocTypeMeta {
+  const fields = raw.fields.map((field) => ({ ...field }));
 
   // field_order may be a JSON string or an already-parsed array
   let fieldOrder: string[] | undefined;
@@ -458,20 +482,14 @@ function parseRawDocTypeMeta(raw: RawDocTypeResponse): DocTypeMeta {
   }
 
   const orderedFields = fieldOrder ? orderFields(fields, fieldOrder) : fields;
-  const permissions = (raw.permissions ?? []).map(parseRawPermission);
-  const sections = parseFormLayout(orderedFields);
 
   return {
-    name: raw.name,
-    module: raw.module,
-    title_field: raw.title_field,
-    image_field: raw.image_field,
-    is_tree: !!raw.is_tree,
+    ...raw,
     sort_field: raw.sort_field || "modified",
     sort_order: raw.sort_order || "DESC",
     fields: orderedFields,
-    sections,
-    permissions,
+    permissions: raw.permissions ?? [],
+    sections: parseFormLayout(orderedFields),
   };
 }
 
@@ -533,6 +551,10 @@ function useHttpClientRef(
  * where the RPC is not registered. When `config.fixtures` carries a "DocType"
  * entry for the doctype it is used instead and no request is made.
  *
+ * Neither route is open to Guest. A signed-out connection (its token source
+ * resolves empty and no desk session cookie names a user) gets a 403
+ * `FrappeError` without a request, so callers keep their Guest fallbacks.
+ *
  * Responses are cached per-session in memory keyed by `{baseURL}:{doctype}`.
  * The `refetch` function clears the cache entry and forces a fresh fetch.
  *
@@ -545,7 +567,7 @@ function useHttpClientRef(
  * function PokemonForm() {
  *   const { meta, isLoading } = useDocTypeMeta(config, "Pokemon");
  *   if (isLoading) return <Spinner />;
- *   return meta?.sections.map(section => (
+ *   return meta?.sections?.map(section => (
  *     <FormSection key={section.label} section={section} />
  *   ));
  * }
@@ -613,7 +635,7 @@ export function useDocTypeMeta(
         // backoffice meta loader uses. Providers that stub only documents fall
         // through to the network below.
         const fromFixtures = config.fixtures
-          ? ((await config.fixtures.getDoc("DocType", doctype)) as RawDocTypeResponse | null)
+          ? ((await config.fixtures.getDoc("DocType", doctype)) as DocTypeMeta | null)
           : null;
         if (cancelled) return;
 
@@ -628,13 +650,20 @@ export function useDocTypeMeta(
             );
           }
 
+          // Both routes below are closed to Guest, so a signed-out reader
+          // gets the 403 without the request (MPO-322).
+          if (await connectsAsGuest(config.auth)) {
+            if (cancelled) return;
+            throw new FrappeError(`Sign in to load the ${doctype} schema`, 403);
+          }
+
           // `getdoctype` is the whitelisted RPC the Desk itself loads form
           // metadata with, and every logged-in user may call it. Reading
           // `/api/resource/DocType/<name>` instead asks for the DocType
           // *document*, which only System Manager holds read permission on, so
           // ordinary users got a 403 PermissionError — and Frappe's
           // developer-mode traceback rendered into the UI instead of a form.
-          const response = await http.get<{ docs?: RawDocTypeResponse[] }>(
+          const response = await http.get<{ docs?: DocTypeMeta[] }>(
             "/api/method/frappe.desk.form.load.getdoctype",
             { doctype },
           );
@@ -650,7 +679,7 @@ export function useDocTypeMeta(
             // above unregistered, so it answers with no `docs`. The document
             // route still serves meta there, and such a site's API clients are
             // typically System Managers, who may read it.
-            const rest = await http.get<{ data?: RawDocTypeResponse }>(
+            const rest = await http.get<{ data?: DocTypeMeta }>(
               `/api/resource/DocType/${encodeURIComponent(doctype)}`,
             );
 

package/src/fixtures.ts

@@ -234,6 +234,7 @@ export class InMemoryFixtureProvider implements FixtureProvider {
     doc: TDoc,
     fields: readonly string[],
   ): Partial<TDoc> {
+    if (fields.includes("*")) return { ...doc };
     const projected: any = {};
     for (const field of fields) {
       if (field in doc) {

package/src/frappeReact.catchUp.spec.tsx

@@ -0,0 +1,105 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { afterEach, expect, it, vi } from "vitest";
+import { getFrappeSyncModule, useFrappeCatchUp, useFrappePendingMutations } from "./frappeReact";
+import { Operation, Status } from "./sync/types";
+import { InMemoryFixtureProvider } from "./fixtures";
+import type { SyncModule } from "./sync";
+import type { UseFrappeCollectionConfig } from "./frappeReact";
+
+const modules = new Set<SyncModule>();
+function moduleFor(config: UseFrappeCollectionConfig) {
+  const sync = getFrappeSyncModule(config)!;
+  expect(sync).toBeDefined();
+  modules.add(sync);
+  return sync;
+}
+afterEach(async () => {
+  for (const sync of modules) await sync.dispose();
+  modules.clear();
+  vi.unstubAllGlobals();
+});
+
+it.each([false, true])(
+  "separates effective options in the shared cache, fixtures=%s",
+  (fixture) => {
+    const config = fixture
+      ? { fixtures: new InMemoryFixtureProvider({}) }
+      : { baseURL: "https://cache-options.test", realtime: false };
+    const defaultSync = moduleFor(config);
+    expect(moduleFor({ ...config, syncOptions: { catchUpStrategy: "cdc", cdcInterval: 0 } })).toBe(
+      defaultSync,
+    );
+    const snapshot = moduleFor({ ...config, syncOptions: { catchUpStrategy: "snapshot" } });
+    expect(snapshot).not.toBe(defaultSync);
+    expect(moduleFor({ ...config, syncOptions: { catchUpStrategy: "snapshot" } })).toBe(snapshot);
+    expect(moduleFor({ ...config, syncOptions: { cdcInterval: 1000 } })).not.toBe(defaultSync);
+  },
+);
+
+it("follows the selected module, retains failure state during retry and does not retry on render", async () => {
+  const transport = vi.fn(async () => Response.json({ data: [{ name: "a", doctype: "Task" }] }));
+  vi.stubGlobal("fetch", transport);
+  const cdc = { baseURL: "https://hook-options.test", realtime: false };
+  const snapshot = { ...cdc, syncOptions: { catchUpStrategy: "snapshot" as const } };
+  const first = moduleFor(cdc);
+  const second = moduleFor(snapshot);
+  await first.subscribe({ doctype: "Task" });
+  await second.subscribe({ doctype: "Task" });
+  const view = renderHook(({ config }) => useFrappeCatchUp(config), {
+    initialProps: { config: cdc as UseFrappeCollectionConfig | undefined },
+  });
+  transport.mockImplementation(async () =>
+    Response.json({ message: "unavailable" }, { status: 404 }),
+  );
+  await act(async () => {
+    await view.result.current.retry();
+  });
+  expect(view.result.current).toMatchObject({
+    refreshing: false,
+    stale: true,
+    error: { status: 404 },
+  });
+  const calls = transport.mock.calls.length;
+  view.rerender({ config: { ...cdc } });
+  expect(transport).toHaveBeenCalledTimes(calls);
+  view.rerender({ config: snapshot });
+  await waitFor(() => expect(view.result.current.stale).toBe(false));
+  transport.mockImplementation(async () => Response.json({ data: [] }));
+  await act(async () => {
+    await view.result.current.retry();
+  });
+  expect(view.result.current.error).toBeNull();
+  expect(second.__debug().subscriptions[0].docCount).toBe(0);
+  expect(first.__debug().subscriptions[0].docCount).toBe(1);
+  view.rerender({ config: undefined });
+  expect(await view.result.current.retry()).toEqual({
+    refreshing: false,
+    stale: false,
+    error: null,
+  });
+  view.unmount();
+});
+
+it("drops the previous module's mutation notice when changed options select an empty ledger", () => {
+  const config = { fixtures: new InMemoryFixtureProvider({}) };
+  const next = { ...config, syncOptions: { catchUpStrategy: "snapshot" as const } };
+  vi.spyOn(moduleFor(config), "getMutationEntries").mockReturnValue([
+    {
+      id: "old",
+      operation: Operation.Update,
+      doctype: "Task",
+      status: Status.Failed,
+      createdAt: 1,
+      retryCount: 0,
+      error: "old module failure",
+    },
+  ]);
+  moduleFor(next);
+  const view = renderHook(({ connection }) => useFrappePendingMutations(connection), {
+    initialProps: { connection: config as UseFrappeCollectionConfig },
+  });
+  expect(view.result.current.failed.map((entry) => entry.id)).toEqual(["old"]);
+  view.rerender({ connection: next });
+  expect(view.result.current.entries).toEqual([]);
+  view.unmount();
+});