@multiplatform.one/frappe 6.0.4 → 6.3.0

package/src/doctype.ts

@@ -129,9 +129,9 @@ export interface DocTypeMeta {
 export interface LinkSearchResult {
   /** The document name (ID) */
   value: string;
-  /** The display label (title_field value, or name) */
+  /** The display label (server `label` when the doctype shows its title in links, else the name) */
   label: string;
-  /** Optional description from additional search fields */
+  /** Ranked description from the server (title field / matched context), like stock Frappe */
   description?: string;
 }
 
@@ -139,12 +139,26 @@ export interface LinkSearchResult {
 export interface LinkSearchOptions {
   /** Search query text */
   query?: string;
-  /** Fields to search across (defaults to title_field + "name") */
+  /**
+   * Restrict matching to one field (maps to `search_link`'s `searchfield`).
+   * Extra entries are ignored — the server owns multi-field ranking now.
+   */
   searchFields?: string[];
-  /** Additional Frappe filters */
+  /** Additional Frappe filters (server-side, on top of the doctype's link query) */
   filters?: Record<string, unknown> | Array<[string, string, unknown]>;
-  /** Maximum results (default 20) */
+  /** Maximum results / `page_length` (default 20) */
   limit?: number;
+  /**
+   * Fetch the first page when the query is empty (stock Frappe behavior on
+   * focus). Default false: empty query returns no results and no request.
+   */
+  allowEmptyQuery?: boolean;
+  /** Gate searching entirely (e.g. only while the picker is open). Default true. */
+  enabled?: boolean;
+  /** Debounce before hitting the server, in ms (default 300) */
+  debounceMs?: number;
+  /** Doctype of the form the link sits on (server `reference_doctype`, feeds link queries) */
+  referenceDoctype?: string;
 }
 
 /** A navigation suggestion from DocType search */
@@ -166,6 +180,9 @@ const metaCache = new Map<string, DocTypeMeta>();
 
 /** Cache for the full list of DocTypes, keyed by baseURL */
 const docTypeListCache = new Map<string, DocTypeListItem[]>();
+// In-flight DocType-list fetch per baseURL: the desk mounts two consumers
+// (Awesomebar + DeskSidebar) simultaneously and they must share one request.
+const docTypeListFetches = new Map<string, Promise<DocTypeListItem[]>>();
 
 interface DocTypeListItem {
   name: string;
@@ -294,6 +311,8 @@ export function parseDependsOn(expression?: string): (doc: Record<string, unknow
  * 3. `Column Break` → start a new column within the current section.
  * 4. `Tab Break` → start a new section with `tab: true`.
  * 5. All other fields → add to the current column (skip hidden fields).
+ * 6. Drop empty leading sections (see below) so meta that begins with a
+ *    Section Break doesn't produce an empty card before the first real one.
  *
  * @param fields - Flat list of DocType fields, ordered by field_order or position
  * @returns Structured layout tree of sections and columns
@@ -336,6 +355,15 @@ export function parseFormLayout(fields: DocTypeField[]): FormSection[] {
     }
   }
 
+  // Skip empty leading sections: a doctype whose first field is a Section
+  // Break (or whose leading fields are all hidden) otherwise keeps the
+  // implicit fieldless first section, which renders as an empty card before
+  // the first real section. Keep one section for a fieldless doctype so
+  // consumers always receive at least one.
+  while (sections.length > 1 && sections[0].columns.every((col) => col.fields.length === 0)) {
+    sections.shift();
+  }
+
   return sections;
 }
 
@@ -594,16 +622,25 @@ export function useDocTypeMeta(
 // Hook: useLinkSearch
 // ---------------------------------------------------------------------------
 
+/** Raw item shape returned by `frappe.desk.search.search_link` (v13: `results`, v14+: `message`). */
+interface RawSearchLinkItem {
+  value?: string;
+  label?: string;
+  description?: string;
+}
+
 /**
- * Debounced search for Link field suggestions.
+ * Debounced backend search for Link field suggestions — the same server
+ * search stock Frappe's link control uses.
  *
- * Auto-configures the `title_field` from DocType metadata when `searchFields`
- * is not explicitly provided. Calls `GET /api/method/frappe.client.get_list`
- * with a 300ms debounce.
+ * Calls `GET /api/method/frappe.desk.search.search_link` (doctype + txt +
+ * filters + page_length) with a 300ms debounce, returning the server's
+ * ranked `{value, description, label?}` pairs. The endpoint enforces
+ * permissions and the doctype's link/`get_query` conditions server-side.
  *
  * @param config - Frappe connection config, or undefined to disable
  * @param doctype - The target DocType to search within
- * @param options - Search options (query, searchFields, filters, limit)
+ * @param options - Search options (query, filters, limit, enabled, allowEmptyQuery, debounceMs)
  * @returns `{ results, isLoading, error }`
  *
  * @example
@@ -637,19 +674,20 @@ export function useLinkSearch(
   const searchFields = options?.searchFields;
   const filters = options?.filters;
   const limit = options?.limit ?? 20;
+  const allowEmptyQuery = options?.allowEmptyQuery ?? false;
+  const enabled = options?.enabled ?? true;
+  const debounceMs = options?.debounceMs ?? 300;
+  const referenceDoctype = options?.referenceDoctype;
 
   const [results, setResults] = useState<LinkSearchResult[]>([]);
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<Error | null>(null);
 
-  // Get meta for auto-configuring title_field
-  const { meta } = useDocTypeMeta(config, doctype);
-
   const httpRef = useHttpClientRef(config);
 
   useEffect(() => {
     const http = httpRef.current;
-    if (!http || !query) {
+    if (!http || !doctype || !enabled || (!query && !allowEmptyQuery)) {
       setResults([]);
       setIsLoading(false);
       setError(null);
@@ -662,34 +700,32 @@ export function useLinkSearch(
 
     const timer = setTimeout(async () => {
       try {
-        const titleField = meta?.title_field || "name";
-        const effectiveSearchFields =
-          searchFields ?? (titleField !== "name" ? [titleField, "name"] : ["name"]);
-
-        // Build or_filters for searching across multiple fields
-        const orFilters = effectiveSearchFields.map((f) => [f, "like", `%${query}%`]);
-        const requestFields = [...new Set(["name", titleField, ...effectiveSearchFields])];
-
         const params: Record<string, unknown> = {
           doctype,
-          fields: requestFields,
-          or_filters: orFilters,
-          limit_page_length: limit,
+          txt: query,
+          page_length: limit,
         };
         if (filters) params.filters = filters;
+        if (searchFields?.[0]) params.searchfield = searchFields[0];
+        if (referenceDoctype) params.reference_doctype = referenceDoctype;
 
         const response = await http.get<{
-          message?: Record<string, unknown>[];
-        }>("/api/method/frappe.client.get_list", params);
+          message?: RawSearchLinkItem[];
+          results?: RawSearchLinkItem[];
+        }>("/api/method/frappe.desk.search.search_link", params);
 
         if (cancelled) return;
 
-        const docs = response.payload?.message ?? [];
+        // v14+ responds under `message`; v13 used `results`.
+        const items = response.payload?.message ?? response.payload?.results ?? [];
         setResults(
-          docs.map((doc) => ({
-            value: String(doc.name ?? ""),
-            label: String(doc[titleField] ?? doc.name ?? ""),
-            description: undefined,
+          items.map((item) => ({
+            value: String(item.value ?? ""),
+            label: String(item.label ?? item.value ?? ""),
+            description:
+              item.description === null || item.description === undefined
+                ? undefined
+                : String(item.description),
           })),
         );
       } catch (err) {
@@ -699,17 +735,110 @@ export function useLinkSearch(
       } finally {
         if (!cancelled) setIsLoading(false);
       }
-    }, 300);
+    }, debounceMs);
 
     return () => {
       cancelled = true;
       clearTimeout(timer);
     };
-  }, [query, doctype, meta?.title_field, searchFields, filters, limit]);
+  }, [
+    query,
+    doctype,
+    searchFields,
+    filters,
+    limit,
+    allowEmptyQuery,
+    enabled,
+    debounceMs,
+    referenceDoctype,
+  ]);
 
   return { results, isLoading, error };
 }
 
+// ---------------------------------------------------------------------------
+// Hook: useLinkTitle
+// ---------------------------------------------------------------------------
+
+/** Cache for link display titles, keyed by "{baseURL}:{doctype}:{name}" */
+const linkTitleCache = new Map<string, string>();
+
+/**
+ * Fetch the display title for an existing Link value (foreign key) — what
+ * stock Frappe does on form load so a saved link shows its label before any
+ * search has run.
+ *
+ * Calls `frappe.desk.search.get_link_title`, which resolves the doctype's
+ * `title_field` server-side (returns the plain name when the doctype does
+ * not show titles in links). Results are cached per session; failures fall
+ * back to the raw name so the field never renders empty.
+ *
+ * @param config - Frappe connection config, or undefined to disable
+ * @param doctype - The Link's target DocType
+ * @param name - The linked document name (current field value)
+ * @returns `{ title, isLoading }` — `title` is undefined while nothing is known
+ */
+export function useLinkTitle(
+  config: FrappeConnectionConfig | undefined,
+  doctype: string,
+  name: string | undefined,
+): { title: string | undefined; isLoading: boolean } {
+  const cacheKey = config && doctype && name ? `${config.baseURL}:${doctype}:${name}` : "";
+  const [title, setTitle] = useState<string | undefined>(() =>
+    cacheKey ? linkTitleCache.get(cacheKey) : undefined,
+  );
+  const [isLoading, setIsLoading] = useState(false);
+
+  const httpRef = useHttpClientRef(config);
+
+  useEffect(() => {
+    if (!cacheKey || !name) {
+      setTitle(undefined);
+      setIsLoading(false);
+      return;
+    }
+
+    const cached = linkTitleCache.get(cacheKey);
+    if (cached !== undefined) {
+      setTitle(cached);
+      setIsLoading(false);
+      return;
+    }
+
+    const http = httpRef.current;
+    if (!http) return;
+
+    let cancelled = false;
+    setIsLoading(true);
+
+    (async () => {
+      try {
+        const response = await http.get<{ message?: string }>(
+          "/api/method/frappe.desk.search.get_link_title",
+          { doctype, docname: name },
+        );
+        if (cancelled) return;
+        const message = response.payload?.message;
+        const resolved = message === null || message === undefined ? name : String(message);
+        linkTitleCache.set(cacheKey, resolved);
+        setTitle(resolved);
+      } catch {
+        if (cancelled) return;
+        // Honest fallback: the name itself is always a truthful display value.
+        setTitle(name);
+      } finally {
+        if (!cancelled) setIsLoading(false);
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [cacheKey, doctype, name]);
+
+  return { title, isLoading };
+}
+
 // ---------------------------------------------------------------------------
 // Hook: useDocTypeSearch
 // ---------------------------------------------------------------------------
@@ -752,16 +881,16 @@ export function useDocTypeSearch(
   const [error, setError] = useState<Error | null>(null);
 
   const httpRef = useHttpClientRef(config);
+  const cacheKey = config?.baseURL ?? "";
 
   useEffect(() => {
-    if (!config) {
+    if (!cacheKey) {
       setAllDocTypes([]);
       setIsLoading(false);
       return;
     }
 
-    const key = config.baseURL;
-    const cached = docTypeListCache.get(key);
+    const cached = docTypeListCache.get(cacheKey);
     if (cached) {
       setAllDocTypes(cached);
       return;
@@ -774,32 +903,53 @@ export function useDocTypeSearch(
     setIsLoading(true);
     setError(null);
 
-    (async () => {
-      try {
-        const response = await http.get<{
+    // Share one in-flight fetch per baseURL (Awesomebar + DeskSidebar mount
+    // together). A failed fetch clears its entry so a later mount can retry;
+    // the stable cacheKey dep below keeps that from looping.
+    let fetchPromise = docTypeListFetches.get(cacheKey);
+    if (!fetchPromise) {
+      fetchPromise = http
+        .get<{
           data?: DocTypeListItem[];
         }>("/api/resource/DocType", {
           limit_page_length: 0,
-          fields: ["name", "module", "title"],
+          // DocType has no `title` column; requesting it makes Frappe reject
+          // the whole query ("Field not permitted in query: title")
+          fields: ["name", "module"],
+        })
+        .then((response) => {
+          const list = response.payload?.data ?? [];
+          docTypeListCache.set(cacheKey, list);
+          return list;
+        })
+        .finally(() => {
+          docTypeListFetches.delete(cacheKey);
         });
+      docTypeListFetches.set(cacheKey, fetchPromise);
+    }
 
-        if (cancelled) return;
-
-        const list = response.payload?.data ?? [];
-        docTypeListCache.set(key, list);
-        setAllDocTypes(list);
-      } catch (err) {
-        if (cancelled) return;
-        setError(err instanceof Error ? err : new Error(String(err)));
-      } finally {
+    fetchPromise
+      .then((list) => {
+        if (!cancelled) setAllDocTypes(list);
+      })
+      .catch((err) => {
+        if (!cancelled) setError(err instanceof Error ? err : new Error(String(err)));
+      })
+      .finally(() => {
         if (!cancelled) setIsLoading(false);
-      }
-    })();
+      });
 
     return () => {
       cancelled = true;
     };
-  }, [config]);
+    // Depend on the stable string `cacheKey` (baseURL), NOT the `config`
+    // object — both desk callers allocate a fresh config every render.
+    // Keying on object identity re-runs this effect per render and, when
+    // the request fails (a Guest hitting the permission-gated DocType list
+    // → 403, which never populates `docTypeListCache`), spins into an
+    // infinite refetch loop that hammers the bench. Same fix as
+    // useDocTypeMeta above.
+  }, [cacheKey]);
 
   // Filter locally for instant results
   const results = useMemo<DocTypeSearchResult[]>(() => {

package/src/file.ts

@@ -10,7 +10,11 @@ export type UploadArgs = {
 };
 
 export class FileModule {
-  constructor(private readonly http: HttpClient) {}
+  private readonly http: HttpClient;
+
+  constructor(http: HttpClient) {
+    this.http = http;
+  }
 
   uploadFile(
     file: File | Blob,

package/src/fixtureDb.ts

@@ -8,13 +8,18 @@
  */
 
 import type { FrappeDoc, FrappeDocData } from "./common/types";
+import { FrappeError } from "./core/types";
 import type { ListOptions } from "./core/types";
 import type { BackfillArgs, BackfillResponse } from "./db";
 import type { FixtureProvider } from "./fixtures";
 import type { OrderBy } from "./sync/types";
 
 export class FixtureDbModule {
-  constructor(private readonly fixtures: FixtureProvider) {}
+  private readonly fixtures: FixtureProvider;
+
+  constructor(fixtures: FixtureProvider) {
+    this.fixtures = fixtures;
+  }
 
   getAppName(): string | undefined {
     return undefined;
@@ -37,7 +42,13 @@ export class FixtureDbModule {
     name: string,
   ): Promise<FrappeDoc<Data>> {
     const doc = await this.fixtures.getDoc<Data>(doctype, name);
-    if (!doc) throw new Error(`Document ${doctype}/${name} not found`);
+    // Mirror the live DbModule contract: a missing document surfaces as a
+    // 404-status FrappeError (what /api/resource/<dt>/<name> returns), so
+    // callers that treat 404 as not-found (e.g. the single-doc subscription
+    // path) behave identically in fixture mode. A bare Error here read as a
+    // SYNC FAILURE upstream and turned every missing-doc fixture story into
+    // a failing-fetch loop.
+    if (!doc) throw new FrappeError(`Document ${doctype}/${name} not found`, 404);
     return { ...doc, doctype, name } as FrappeDoc<Data>;
   }
 

package/src/frappeApp.ts

@@ -50,16 +50,10 @@ export class FrappeApp {
     this._call = new CallModule(this.http);
     this._file = new FileModule(this.http);
 
-    // Configure RealtimeModule with proper Socket.IO settings
+    // Configure RealtimeModule with the same credentials HTTP uses (token and/or sessionId).
     const realtimeConfig: RealtimeConfig = {
       baseURL,
-      auth: auth.useToken
-        ? {
-            useToken: auth.useToken,
-            token: auth.token,
-            type: auth.type,
-          }
-        : undefined,
+      auth: toRealtimeAuth(auth),
       ...auth.realtimeOptions,
     };
     this._realtime = new RealtimeModule(realtimeConfig);
@@ -110,16 +104,21 @@ export class FrappeApp {
 
   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({});
-    }
+    await this._realtime.updateAuth(toRealtimeAuth(auth) ?? {});
   }
 }
+
+/** Map FrappeApp auth into the subset RealtimeModule understands. */
+function toRealtimeAuth(auth: FrappeConfig): AuthConfig | undefined {
+  const hasToken = !!(auth.useToken && auth.token);
+  const hasSession = !!auth.sessionId;
+  const hasCookie = !!auth.cookie;
+  if (!hasToken && !hasSession && !hasCookie) return undefined;
+  return {
+    useToken: auth.useToken,
+    token: auth.token,
+    type: auth.type,
+    sessionId: auth.sessionId,
+    cookie: auth.cookie,
+  };
+}