@multiplatform.one/backoffice 6.4.3 → 6.6.0

package/src/form/fetchFrom.ts

@@ -0,0 +1,111 @@
+/**
+ * fetch_from client-side preview — desk parity with
+ * frappe/public/js/frappe/form/script_manager.js (`setup_add_fetch`) and
+ * controls/link.js (`validate_link_and_fetch`):
+ *
+ * - A field participates when `fetch_from` is "<link_field>.<source_field>"
+ *   AND (its fieldtype is in the scalar set desk registers, or it is
+ *   read_only / is_virtual).
+ * - When the link field changes to a value, desk calls
+ *   `frappe.client.validate_link` with the source columns and writes the
+ *   returned values onto the targets; clearing the link clears the targets.
+ * - `fetch_if_empty` targets keep a non-empty existing value (server
+ *   semantics; desk leaves such fields editable — see
+ *   `read_only_because_of_fetch_from`, base_input.js:56-66).
+ *
+ * The server remains authoritative: this is a preview so the user sees the
+ * fetched values before save.
+ */
+
+import type { DocFieldMeta } from "../shared/useDoctypeMeta";
+
+/** Fieldtypes desk registers for client-side fetch (script_manager.js:196-215). */
+const FETCHABLE_FIELDTYPES = new Set([
+  "Data",
+  "Read Only",
+  "Text",
+  "Small Text",
+  "Currency",
+  "Check",
+  "Text Editor",
+  "Attach Image",
+  "Code",
+  "Link",
+  "Float",
+  "Int",
+  "Date",
+  "Datetime",
+  "Select",
+  "Duration",
+  "Time",
+]);
+
+export interface FetchRule {
+  /** Field to populate. */
+  target: string;
+  /** Column on the linked doc to read. */
+  source: string;
+  /** Only fill when the target is currently empty; never lock the field. */
+  fetchIfEmpty: boolean;
+}
+
+/** Map of link fieldname → fetch rules hanging off that link. */
+export type FetchMap = Map<string, FetchRule[]>;
+
+export function buildFetchMap(fields: DocFieldMeta[]): FetchMap {
+  const map: FetchMap = new Map();
+  for (const field of fields) {
+    const fetchFrom = typeof field.fetch_from === "string" ? field.fetch_from : "";
+    if (!fetchFrom || !fetchFrom.includes(".")) continue;
+    const eligible =
+      FETCHABLE_FIELDTYPES.has(field.fieldtype) ||
+      !!field.read_only ||
+      !!(field as { is_virtual?: 0 | 1 }).is_virtual;
+    if (!eligible) continue;
+    const [linkField, ...rest] = fetchFrom.split(".");
+    const source = rest.join(".");
+    if (!linkField || !source) continue;
+    const rules = map.get(linkField) ?? [];
+    rules.push({
+      target: field.fieldname,
+      source,
+      fetchIfEmpty: !!field.fetch_if_empty,
+    });
+    map.set(linkField, rules);
+  }
+  return map;
+}
+
+function isEmpty(value: unknown): boolean {
+  return value === undefined || value === null || value === "";
+}
+
+/**
+ * Values to patch onto the doc after the linked doc's columns arrive.
+ * `fetched` is empty when the link was cleared — desk then blanks the
+ * targets; `fetch_if_empty` targets holding a value are left alone in both
+ * directions (they belong to the user until the server reconciles).
+ */
+export function applyFetchedValues(
+  rules: FetchRule[],
+  fetched: Record<string, unknown>,
+  currentDoc: Record<string, unknown>,
+): Record<string, unknown> {
+  const patch: Record<string, unknown> = {};
+  for (const rule of rules) {
+    if (rule.fetchIfEmpty && !isEmpty(currentDoc[rule.target])) continue;
+    patch[rule.target] = fetched[rule.source] ?? "";
+  }
+  return patch;
+}
+
+/**
+ * Desk's `read_only_because_of_fetch_from`: a fetch target without
+ * `fetch_if_empty` renders read-only while its source link holds a value.
+ */
+export function isFetchLocked(field: DocFieldMeta, doc: Record<string, unknown>): boolean {
+  const fetchFrom = typeof field.fetch_from === "string" ? field.fetch_from : "";
+  if (!fetchFrom || !fetchFrom.includes(".") || field.fetch_if_empty) return false;
+  const linkField = fetchFrom.split(".")[0];
+  return !isEmpty(doc[linkField]);
+}

package/src/form/fieldPermissions.spec.ts

@@ -0,0 +1,61 @@
+/**
+ * fieldPermissions — permlevel matrix parity with desk perm.js
+ * get_role_permissions / get_field_display_status.
+ */
+import { describe, expect, it } from "vitest";
+import { buildPermLevelMatrix, canReadLevel, canWriteLevel } from "./fieldPermissions";
+
+const userDoctypePerms = [
+  { role: "System Manager", permlevel: 0, read: 1 as const, write: 1 as const },
+  { role: "System Manager", permlevel: 1, read: 1 as const, write: 1 as const },
+  { role: "Desk User", permlevel: 0, read: 0 as const, write: 0 as const },
+];
+
+describe("buildPermLevelMatrix", () => {
+  it("unions rights across the user's matching roles", () => {
+    const matrix = buildPermLevelMatrix(
+      [
+        { role: "Blogger", permlevel: 1, read: 1 as const, write: 0 as const },
+        { role: "Website Manager", permlevel: 1, read: 1 as const, write: 1 as const },
+      ],
+      ["Blogger", "Website Manager"],
+    );
+    expect(matrix?.[1]).toEqual({ read: true, write: true });
+  });
+
+  it("ignores rows for roles the user does not hold (User doctype shape)", () => {
+    const matrix = buildPermLevelMatrix(userDoctypePerms, ["Desk User"]);
+    expect(matrix?.[1]).toBeUndefined();
+    expect(canReadLevel(matrix, 1)).toBe(false);
+    expect(canWriteLevel(matrix, 1)).toBe(false);
+  });
+
+  it("returns undefined without roles or permission rows (fallback signal)", () => {
+    expect(buildPermLevelMatrix(userDoctypePerms, undefined)).toBeUndefined();
+    expect(buildPermLevelMatrix([], ["System Manager"])).toBeUndefined();
+    expect(buildPermLevelMatrix(undefined, ["System Manager"])).toBeUndefined();
+  });
+});
+
+describe("canReadLevel / canWriteLevel", () => {
+  const matrix = buildPermLevelMatrix(userDoctypePerms, ["System Manager"]);
+
+  it("level 0 defers to doc-level perms (always true here)", () => {
+    expect(canReadLevel(matrix, 0)).toBe(true);
+    expect(canWriteLevel(matrix, 0)).toBe(true);
+    expect(canReadLevel(undefined, 0)).toBe(true);
+    expect(canWriteLevel(undefined, 0)).toBe(true);
+  });
+
+  it("higher levels resolve from the matrix", () => {
+    expect(canReadLevel(matrix, 1)).toBe(true);
+    expect(canWriteLevel(matrix, 1)).toBe(true);
+    // Level with no rows at all → hidden (desk fills gaps with {}).
+    expect(canReadLevel(matrix, 2)).toBe(false);
+  });
+
+  it("without a matrix: visible but read-only above level 0 (coarse fallback)", () => {
+    expect(canReadLevel(undefined, 1)).toBe(true);
+    expect(canWriteLevel(undefined, 1)).toBe(false);
+  });
+});

package/src/form/fieldPermissions.ts

@@ -0,0 +1,68 @@
+/**
+ * Field-level permission matrix — desk parity with
+ * frappe/public/js/frappe/model/perm.js (`get_role_permissions` +
+ * `get_field_display_status`):
+ *
+ *   perm[level] = OR of meta.permissions rows whose role the session user
+ *   holds. A field at permlevel L then resolves to:
+ *     - no read at L  → hidden   ("None")
+ *     - read, no write → read-only ("Read")
+ *     - write          → editable ("Write", subject to the other rules)
+ *
+ * Levels that appear on fields but have no granting rows resolve to
+ * {read: false} — desk hides those fields (gap-filled `{}` in perm.js:153).
+ * When the caller has no role list (fixtures, roles RPC unavailable) the
+ * matrix is undefined and formLayout falls back to the conservative
+ * "permlevel > 0 → read-only" rule (never hides, never unlocks).
+ */
+
+import type { DocPermissionRule } from "../shared/useDoctypeMeta";
+
+export interface LevelPerm {
+  read: boolean;
+  write: boolean;
+}
+
+/** Sparse array indexed by permlevel; missing entries mean "no rights". */
+export type PermLevelMatrix = LevelPerm[];
+
+export function buildPermLevelMatrix(
+  permissions: DocPermissionRule[] | undefined,
+  userRoles: string[] | undefined,
+): PermLevelMatrix | undefined {
+  if (!userRoles || !permissions || permissions.length === 0) return undefined;
+  const roles = new Set(userRoles);
+  const matrix: PermLevelMatrix = [];
+  for (const rule of permissions) {
+    if (!rule.role || !roles.has(rule.role)) continue;
+    const level = Number(rule.permlevel ?? 0) || 0;
+    const current = (matrix[level] ??= { read: false, write: false });
+    // if_owner rows are unioned in like desk's get_role_permissions — the
+    // owner check itself is enforced server-side (and via docinfo at level 0).
+    if (rule.read) current.read = true;
+    if (rule.write) current.write = true;
+  }
+  return matrix;
+}
+
+/**
+ * Read access at a permlevel. Level 0 is implied by having the doc at all
+ * (docinfo/doc-level perms govern it — including share/if_owner grants the
+ * role matrix can't see), so only higher levels consult the matrix.
+ */
+export function canReadLevel(matrix: PermLevelMatrix | undefined, permlevel: number): boolean {
+  if (!permlevel) return true;
+  if (!matrix) return true; // caller falls back to the coarse read-only rule
+  return !!matrix[permlevel]?.read;
+}
+
+/**
+ * Write access at a permlevel. Level 0 defers to the doc-level write flag
+ * (formReadOnly); higher levels require a granting role row — without a
+ * matrix the coarse fallback keeps them read-only (desk-safe direction).
+ */
+export function canWriteLevel(matrix: PermLevelMatrix | undefined, permlevel: number): boolean {
+  if (!permlevel) return true;
+  if (!matrix) return false;
+  return !!matrix[permlevel]?.write;
+}

package/src/form/formActions.ts

@@ -0,0 +1,281 @@
+/**
+ * Desk form RPC helpers — thin wrappers over the whitelisted methods the
+ * stock desk form view calls. Every payload here was probed against a live
+ * bench (frappe v15) before implementation:
+ *
+ *   frappe.desk.form.assign_to.add        {doctype, name, assign_to: [..], description?}
+ *   frappe.desk.form.assign_to.remove     {doctype, name, assign_to: "user"}
+ *   frappe.desk.form.utils.add_comment    {reference_doctype, reference_name, content,
+ *                                          comment_email, comment_by}
+ *   frappe.desk.doctype.tag.tag.add_tag   {tag, dt, dn}
+ *   frappe.desk.doctype.tag.tag.remove_tag{tag, dt, dn}
+ *   frappe.desk.like.toggle_like          {doctype, name, add: "Yes"|"No"}
+ *   frappe.desk.form.document_follow.follow_document / unfollow_document
+ *                                         {doctype, doc_name, user}
+ *   frappe.model.rename_doc.update_document_title
+ *                                         {doctype, docname, name, merge: 0} → new name
+ *                                         (what desk calls — syncs the title field too)
+ *   frappe.client.submit                  {doc} (full doc incl. modified — OCC enforced)
+ *   frappe.client.cancel                  {doctype, name}
+ *   frappe.client.get_count               {doctype, filters}
+ *   frappe.client.validate_link           {doctype, docname, fields: [..]} →
+ *                                         {name, <field>: value} (fetch_from preview)
+ *   frappe.core.doctype.communication.email.make
+ *                                         {doctype, name, recipients, subject, content,
+ *                                          send_email: 1}
+ *   frappe.desk.form.utils.remove_attach  {fid, dt, dn}
+ */
+
+import { HttpClient, FileModule, type AuthConfig } from "@multiplatform.one/frappe";
+import type { FixtureProvider } from "@multiplatform.one/frappe";
+
+/**
+ * Connection shape shared by every form loader/action — structurally
+ * compatible with frappe-ui's FrappeConfig and the frappe package's
+ * UseFrappeCollectionConfig (function tokens included).
+ */
+export interface FrappeConnection {
+  baseURL: string;
+  socketPort?: number;
+  auth?: {
+    useToken?: boolean;
+    token?: string | (() => string | Promise<string>);
+    type?: string;
+  };
+  // biome-ignore lint: matches FrappeConfig.syncOptions
+  syncOptions?: any;
+  fixtures?: FixtureProvider;
+}
+
+export function createHttpClient(connection: FrappeConnection): HttpClient {
+  const auth: AuthConfig | undefined = connection.auth
+    ? {
+        useToken: connection.auth.useToken,
+        token: connection.auth.token,
+        type: connection.auth.type as AuthConfig["type"],
+      }
+    : undefined;
+  return new HttpClient(connection.baseURL, auth);
+}
+
+async function post<T = unknown>(
+  http: HttpClient,
+  method: string,
+  body: Record<string, unknown>,
+): Promise<T | undefined> {
+  const response = await http.post<{ message?: T }>(`/api/method/${method}`, body);
+  return response.payload?.message;
+}
+
+// ---------------------------------------------------------------------------
+// Assignments
+// ---------------------------------------------------------------------------
+
+export function addAssignment(
+  http: HttpClient,
+  doctype: string,
+  name: string,
+  users: string[],
+  description?: string,
+) {
+  return post(http, "frappe.desk.form.assign_to.add", {
+    doctype,
+    name,
+    assign_to: users,
+    description: description || undefined,
+  });
+}
+
+export function removeAssignment(http: HttpClient, doctype: string, name: string, user: string) {
+  return post(http, "frappe.desk.form.assign_to.remove", { doctype, name, assign_to: user });
+}
+
+// ---------------------------------------------------------------------------
+// Comments
+// ---------------------------------------------------------------------------
+
+export function addComment(
+  http: HttpClient,
+  args: {
+    doctype: string;
+    name: string;
+    content: string;
+    commentEmail: string;
+    commentBy?: string;
+  },
+) {
+  return post(http, "frappe.desk.form.utils.add_comment", {
+    reference_doctype: args.doctype,
+    reference_name: args.name,
+    content: args.content,
+    comment_email: args.commentEmail,
+    comment_by: args.commentBy ?? args.commentEmail,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Tags
+// ---------------------------------------------------------------------------
+
+export function addTag(http: HttpClient, doctype: string, name: string, tag: string) {
+  return post(http, "frappe.desk.doctype.tag.tag.add_tag", { tag, dt: doctype, dn: name });
+}
+
+export function removeTag(http: HttpClient, doctype: string, name: string, tag: string) {
+  return post(http, "frappe.desk.doctype.tag.tag.remove_tag", { tag, dt: doctype, dn: name });
+}
+
+// ---------------------------------------------------------------------------
+// Like / Follow
+// ---------------------------------------------------------------------------
+
+export function toggleLike(http: HttpClient, doctype: string, name: string, add: boolean) {
+  return post(http, "frappe.desk.like.toggle_like", {
+    doctype,
+    name,
+    add: add ? "Yes" : "No",
+  });
+}
+
+export function followDocument(http: HttpClient, doctype: string, name: string, user: string) {
+  return post(http, "frappe.desk.form.document_follow.follow_document", {
+    doctype,
+    doc_name: name,
+    user,
+  });
+}
+
+export function unfollowDocument(http: HttpClient, doctype: string, name: string, user: string) {
+  return post(http, "frappe.desk.form.document_follow.unfollow_document", {
+    doctype,
+    doc_name: name,
+    user,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Document lifecycle
+// ---------------------------------------------------------------------------
+
+/**
+ * Rename a document; resolves with the new name. Uses desk's own
+ * `update_document_title` (handles title-field sync; the bare
+ * `frappe.rename_doc` does not). Pass a `title` argument instead of `name`
+ * to retitle without renaming — not needed here yet.
+ */
+export async function renameDoc(
+  http: HttpClient,
+  doctype: string,
+  oldName: string,
+  newName: string,
+): Promise<string> {
+  const result = await post<string>(http, "frappe.model.rename_doc.update_document_title", {
+    doctype,
+    docname: oldName,
+    name: newName,
+    merge: 0,
+  });
+  return result ?? newName;
+}
+
+/** Submit a saved draft (docstatus 0 → 1). Requires the current full doc for OCC. */
+export function submitDoc(http: HttpClient, doc: Record<string, unknown>) {
+  return post<Record<string, unknown>>(http, "frappe.client.submit", { doc });
+}
+
+/** Cancel a submitted doc (docstatus 1 → 2). */
+export function cancelDoc(http: HttpClient, doctype: string, name: string) {
+  return post<Record<string, unknown>>(http, "frappe.client.cancel", { doctype, name });
+}
+
+/** Direct REST insert — returns the created doc (with its server-issued name). */
+export async function insertDoc(
+  http: HttpClient,
+  doctype: string,
+  values: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  const response = await http.post<{ data?: Record<string, unknown> }>(
+    `/api/resource/${encodeURIComponent(doctype)}`,
+    values,
+  );
+  const data = response.payload?.data;
+  if (!data) throw new Error(`Insert into ${doctype} returned no document`);
+  return data;
+}
+
+/**
+ * Validate a link value and fetch columns off the linked doc in one call —
+ * what desk's Link control uses to drive fetch_from previews. Resolves with
+ * `{name, <field>: value, ...}`; rejects when the target doc is missing.
+ */
+export async function validateLink(
+  http: HttpClient,
+  doctype: string,
+  docname: string,
+  fields: string[],
+): Promise<Record<string, unknown>> {
+  const result = await post<Record<string, unknown>>(http, "frappe.client.validate_link", {
+    doctype,
+    docname,
+    fields,
+  });
+  return result ?? {};
+}
+
+// ---------------------------------------------------------------------------
+// Misc
+// ---------------------------------------------------------------------------
+
+export async function getCount(
+  http: HttpClient,
+  doctype: string,
+  filters: Record<string, unknown>,
+): Promise<number> {
+  const response = await http.get<{ message?: number }>("/api/method/frappe.client.get_count", {
+    doctype,
+    filters: JSON.stringify(filters),
+  });
+  return response.payload?.message ?? 0;
+}
+
+let cachedUser: string | undefined;
+export async function getLoggedUser(http: HttpClient): Promise<string> {
+  if (cachedUser) return cachedUser;
+  const response = await http.get<{ message?: string }>("/api/method/frappe.auth.get_logged_user");
+  cachedUser = response.payload?.message ?? "Guest";
+  return cachedUser;
+}
+
+export function removeAttachment(http: HttpClient, fileId: string, doctype: string, name: string) {
+  return post(http, "frappe.desk.form.utils.remove_attach", { fid: fileId, dt: doctype, dn: name });
+}
+
+export function uploadAttachment(
+  http: HttpClient,
+  file: File | Blob,
+  doctype: string,
+  name: string,
+): Promise<unknown> {
+  const files = new FileModule(http);
+  return files.uploadFile(file, { doctype, docname: name });
+}
+
+export function sendEmail(
+  http: HttpClient,
+  args: {
+    doctype: string;
+    name: string;
+    recipients: string;
+    subject: string;
+    content: string;
+  },
+) {
+  return post(http, "frappe.core.doctype.communication.email.make", {
+    doctype: args.doctype,
+    name: args.name,
+    recipients: args.recipients,
+    subject: args.subject,
+    content: args.content,
+    send_email: 1,
+  });
+}