@litusarchieve18/agricore-utils 1.0.11 → 1.0.13

package/dist/index.js

@@ -32,6 +32,8 @@ __export(index_exports, {
   CAT: () => CAT,
   Converter: () => Converter,
   CropCycleStatus: () => CropCycleStatus,
+  DOCUMENT_MENU_MAP: () => DOCUMENT_MENU_MAP,
+  DocumentType: () => DocumentType,
   ERROR_DICTIONARY: () => ERROR_DICTIONARY,
   EVERYONE: () => EVERYONE,
   EmitterType: () => EmitterType,
@@ -72,12 +74,14 @@ __export(index_exports, {
   assertCanWrite: () => assertCanWrite,
   assertTenantBoundary: () => assertTenantBoundary,
   buildRlsFilter: () => buildRlsFilter,
+  calculateFileMetadataMatch: () => calculateFileMetadataMatch,
   canRead: () => canRead,
   canWrite: () => canWrite,
   evaluateBaseAccess: () => evaluateBaseAccess,
   extractAppCode: () => extractAppCode,
   findSpecificOverride: () => findSpecificOverride,
   generateCanonicalId: () => generateCanonicalId,
+  generateDocumentPath: () => generateDocumentPath,
   generateInfrastructureFields: () => generateInfrastructureFields,
   getAcceptedMimeTypes: () => getAcceptedMimeTypes,
   getApproveAction: () => getApproveAction,
@@ -284,7 +288,7 @@ var Converter = {
   }
 };
 
-// src/index.ts
+// src/constants.ts
 var MOD = {
   OPERATIONS: "OPR",
   EQUIPMENT: "EQP",
@@ -298,7 +302,6 @@ var MOD = {
   ALERTS: "ALT",
   INFRA: "INF",
   SESSION: "SES"
-  // ← added: used in generateSessionContext but was missing from errorRegistry.js
 };
 var CAT = {
   SUBSCRIPTION: "1",
@@ -315,43 +318,6 @@ var ACT = {
   UPLOAD: "05"
 };
 var SENTINEL_UUID = "00000000-0000-0000-0000-000000000000";
-var AppError = class extends Error {
-  status;
-  appCode;
-  isOperational;
-  constructor(status, mod, cat, act, message) {
-    super(message);
-    this.status = status;
-    this.appCode = `${mod}-${status}-${cat}${act}`;
-    this.isOperational = true;
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
-};
-var ErrorFactory = {
-  unauthorized: (mod, msg = "Authentication required") => new AppError(401, mod, CAT.PERMISSION, ACT.GENERIC, msg),
-  forbidden: (mod, act, msg = "Access denied") => new AppError(403, mod, CAT.PERMISSION, act, msg),
-  badRequest: (mod, act, msg = "Bad request") => new AppError(400, mod, CAT.VALIDATION, act, msg),
-  notFound: (mod, act = ACT.GENERIC, msg = "Record not found") => new AppError(404, mod, CAT.VALIDATION, act, msg),
-  conflict: (mod, act, msg = "Record already exists") => new AppError(409, mod, CAT.INTEGRITY, act, msg),
-  integrity: (mod, act = ACT.GENERIC, msg = "Data integrity violation") => new AppError(409, mod, CAT.INTEGRITY, act, msg),
-  subscription: (mod, msg = "Module locked or subscription required") => new AppError(403, mod, CAT.SUBSCRIPTION, ACT.GENERIC, msg),
-  internal: (mod, msg = "Internal server error") => new AppError(500, mod, CAT.INTEGRITY, ACT.GENERIC, msg)
-};
-var handleAppErrorResponse = (error, mod = MOD.ADMIN) => {
-  if (error instanceof AppError && error.isOperational) {
-    return Response.json(
-      { error: { appCode: error.appCode, message: error.message } },
-      { status: error.status }
-    );
-  }
-  const e = error;
-  console.error(`[${mod}] UNEXPECTED ERROR:`, e?.message);
-  console.error(`[${mod}] STACK:`, e?.stack);
-  return Response.json(
-    { error: { appCode: `${mod}-500-000`, message: "An unexpected server error occurred. Please try again." } },
-    { status: 500 }
-  );
-};
 var MODULE_LABELS = {
   [MOD.OPERATIONS]: "Operations",
   [MOD.EQUIPMENT]: "Equipment & Fleet",
@@ -389,147 +355,6 @@ var ERROR_DICTIONARY = {
   "403": { title: "Edit Conflict", text: "This record was recently updated by someone else. Please refresh and try again." },
   "404": { title: "Record In Use", text: "This record cannot be deleted because it is referenced by other data." }
 };
-var FALLBACK = {
-  title: "Something Went Wrong",
-  text: "An unexpected error occurred. Please try again or contact your administrator."
-};
-var resolveAppError = (appCode) => {
-  if (!appCode || typeof appCode !== "string") {
-    return { ...FALLBACK, module: "UNK", moduleLabel: "Unknown", status: 500, catAct: "000", isSubscriptionIssue: false, isPermissionIssue: false };
-  }
-  const parts = appCode.split("-");
-  if (parts.length !== 3) {
-    return { ...FALLBACK, module: "UNK", moduleLabel: "Unknown", status: 500, catAct: "000", isSubscriptionIssue: false, isPermissionIssue: false };
-  }
-  const [mod, status, catAct] = parts;
-  const details = ERROR_DICTIONARY[catAct] || FALLBACK;
-  return {
-    title: details.title,
-    text: details.text,
-    module: mod,
-    moduleLabel: MODULE_LABELS[mod] || mod,
-    status: parseInt(status, 10),
-    catAct,
-    isSubscriptionIssue: catAct.startsWith("1"),
-    isPermissionIssue: catAct.startsWith("2")
-  };
-};
-var extractAppCode = (error) => {
-  const e = error;
-  return e?.response?.data?.error?.appCode ?? e?.data?.error?.appCode ?? null;
-};
-var resolveError = (error) => {
-  const appCode = extractAppCode(error);
-  if (appCode) return resolveAppError(appCode);
-  const e = error;
-  return { ...FALLBACK, module: "UNK", moduleLabel: "Unknown", status: e?.status || 500, catAct: "000", isSubscriptionIssue: false, isPermissionIssue: false };
-};
-function generateCanonicalId() {
-  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
-    return crypto.randomUUID();
-  }
-  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
-    const r = Math.random() * 16 | 0;
-    return (c === "x" ? r : r & 3 | 8).toString(16);
-  });
-}
-function generateInfrastructureFields(activeScope, availableScopes) {
-  if (!activeScope || !availableScopes?.length) {
-    throw ErrorFactory.unauthorized("[generateInfrastructureFields] Missing scope context.");
-  }
-  let companyId = null;
-  let legalEntityId = null;
-  let facilityId = null;
-  let pointer = activeScope;
-  while (pointer) {
-    if (pointer.type === "company") companyId = pointer.base44Id;
-    if (pointer.type === "legalEntity") legalEntityId = pointer.base44Id;
-    if (pointer.type === "facility") facilityId = pointer.base44Id;
-    const parentId = pointer.parentId ?? null;
-    pointer = parentId ? availableScopes.find((s) => s.base44Id === parentId) || null : null;
-  }
-  if (!companyId) {
-    throw ErrorFactory.unauthorized("[generateInfrastructureFields] Could not resolve companyId from scope tree.");
-  }
-  return {
-    canonicalId: crypto.randomUUID(),
-    companyId,
-    legalEntityId,
-    facilityId,
-    authScopeId: activeScope.authScopeId
-  };
-}
-function buildRlsFilter(session, extra = {}) {
-  return { ...extra, authScopeId: { $in: session.readScopes || [] } };
-}
-function canRead(session, authScopeId) {
-  return session.readScopes?.includes(authScopeId) ?? false;
-}
-function canWrite(session, authScopeId, resourcePath) {
-  const override = session.resourceOverrides?.[authScopeId]?.[resourcePath];
-  if (override === "WRITE") return true;
-  if (override === "NONE" || override === "READ") return false;
-  return session.writeScopes?.includes(authScopeId) ?? false;
-}
-function assertCanWrite(session, authScopeId, resourcePath) {
-  const override = session.resourceOverrides?.[authScopeId]?.[resourcePath];
-  if (override === "WRITE") return;
-  if (override === "NONE" || override === "READ") {
-    throw new AppError(
-      403,
-      MOD.SESSION,
-      CAT.PERMISSION,
-      ACT.GENERIC,
-      `You do not have write access to "${resourcePath}" in this scope.`
-    );
-  }
-  if (session.writeScopes?.includes(authScopeId)) return;
-  throw new AppError(
-    403,
-    MOD.SESSION,
-    CAT.PERMISSION,
-    ACT.GENERIC,
-    "You do not have permission to modify records in this scope."
-  );
-}
-function resolveAccess(session, activeScopeId, tabConfig) {
-  const resourcePath = tabConfig?.resourceId;
-  const overrides = session.resourceOverrides?.[activeScopeId] ?? {};
-  if (resourcePath) {
-    const segments = resourcePath.split(".");
-    for (let len = segments.length; len >= 1; len--) {
-      const path = segments.slice(0, len).join(".");
-      const override = overrides[path];
-      if (override === "NONE" || override === "READ" || override === "WRITE") return override;
-    }
-  }
-  const allowedRoles = tabConfig?.allowedRoles ?? [];
-  const requiredPrivileges = tabConfig?.requiredPrivileges ?? [];
-  const hasRestrictions = allowedRoles.length > 0 || requiredPrivileges.length > 0;
-  if (hasRestrictions) {
-    const role = session?.role ?? "";
-    const privileges = session?.privileges ?? [];
-    const passesRole = allowedRoles.length > 0 && allowedRoles.includes(role);
-    const passesPrivilege = requiredPrivileges.length > 0 && requiredPrivileges.some((p) => privileges.includes(p));
-    return passesRole || passesPrivilege ? "WRITE" : "NONE";
-  }
-  return "READ";
-}
-function resolveMenuVisibility(session, authScopeId, resourcePath) {
-  const override = session.resourceOverrides?.[authScopeId]?.[resourcePath];
-  if (override === "NONE") return "hidden";
-  if (override === "READ") return "read_only";
-  if (override === "WRITE") return "active";
-  if (session.writeScopes?.includes(authScopeId)) return "active";
-  if (session.readScopes?.includes(authScopeId)) return "read_only";
-  return "hidden";
-}
-function isTabVisible(session, activeScopeId, tabConfig) {
-  return resolveAccess(session, activeScopeId, tabConfig) !== "NONE";
-}
-function isTabWritable(session, activeScopeId, tabConfig) {
-  return resolveAccess(session, activeScopeId, tabConfig) === "WRITE";
-}
 var UserRole = {
   OWNER: "owner",
   MANAGER: "manager",
@@ -749,17 +574,6 @@ var FORM_REGISTRY = {
   // ── Audit & Compliance ───────────────────────────────────────────────────
   auditProjectForm: { label: "Audit Project", menuUrl: "/admin", module: "Audit & Compliance" }
 };
-function getFormMeta(componentId) {
-  return FORM_REGISTRY[componentId] ?? null;
-}
-function getFormsGroupedByModule() {
-  const groups = {};
-  for (const [id, meta] of Object.entries(FORM_REGISTRY)) {
-    if (!groups[meta.module]) groups[meta.module] = [];
-    groups[meta.module].push({ id, ...meta });
-  }
-  return groups;
-}
 var TASK_TYPE_REGISTRY = {
   INVOICE_OCR: {
     label: "Invoice / Receipt OCR",
@@ -794,20 +608,6 @@ var TASK_TYPE_REGISTRY = {
     approveAction: "ATTACH_REPORT_FILE"
   }
 };
-var getTaskTypeOptions = () => Object.entries(TASK_TYPE_REGISTRY).map(([value, config]) => ({
-  value,
-  label: config.label,
-  description: config.description,
-  mimeTypes: config.mimeTypes,
-  icon: config.icon
-}));
-var getAcceptedMimeTypes = (taskType) => {
-  const config = TASK_TYPE_REGISTRY[taskType];
-  return config ? config.mimeTypes.join(",") : "*/*";
-};
-var getApproveAction = (taskType) => {
-  return TASK_TYPE_REGISTRY[taskType]?.approveAction ?? null;
-};
 var RESOURCE_PATHS = {
   // ── Top-level menu sections ────────────────────────────────────────────────
   dashboard: "dashboard",
@@ -859,7 +659,6 @@ var AGRI_ONLY = [
 ];
 var RESOURCE_MODULE_MAP = {
   // ── Top-level menu sections ────────────────────────────────────────────────
-  // CORE features (accessible to everyone with an account)
   [RESOURCE_PATHS.dashboard]: [],
   [RESOURCE_PATHS.operations]: ALL_OPERATIONS,
   [RESOURCE_PATHS.equipment]: ALL_OPERATIONS,
@@ -914,17 +713,8 @@ var ROLE_SECTIONS_BY_KEY = {
 };
 var EVERYONE = Object.values(UserRole);
 var RESOURCE_REQUIREMENTS = {
-  [RESOURCE_PATHS.dashboard]: {
-    allowedRoles: EVERYONE
-  },
-  [RESOURCE_PATHS.operations]: {
-    allowedRoles: EVERYONE
-  },
-  // [RESOURCE_PATHS.equipment]: EVERYONE, 
-  // [RESOURCE_PATHS.safety]: ALL_OPERATIONS,
-  // [RESOURCE_PATHS.team]: ALL_OPERATIONS,
-  // [RESOURCE_PATHS.records]: ALL_OPERATIONS, 
-  // [RESOURCE_PATHS.adminSettings]: ALL_OPERATIONS,
+  [RESOURCE_PATHS.dashboard]: { allowedRoles: EVERYONE },
+  [RESOURCE_PATHS.operations]: { allowedRoles: EVERYONE },
   // ── Records & Reports ──────────────────────────────────────────────────────
   [RESOURCE_PATHS.documentHub]: {
     allowedRoles: [UserRole.OWNER, UserRole.MANAGER, UserRole.SUPERVISOR],
@@ -946,7 +736,6 @@ var RESOURCE_REQUIREMENTS = {
     allowedRoles: [UserRole.OWNER, UserRole.MANAGER, UserRole.SUPERVISOR],
     requiredPrivileges: [UserPrivilege.ADMIN, UserPrivilege.AUDIT_COMPLIANCE, UserPrivilege.FINANCE, UserPrivilege.HR]
   },
-  // [RESOURCE_PATHS.analytics]: ALL_OPERATIONS,
   // ── Admin Settings ─────────────────────────────────────────────────────────
   [RESOURCE_PATHS.adminUserRoster]: {
     allowedRoles: [UserRole.OWNER],
@@ -963,25 +752,258 @@ var RESOURCE_REQUIREMENTS = {
   [RESOURCE_PATHS.adminCompanySettings]: {
     allowedRoles: [UserRole.OWNER]
   }
-  //  // ── Operations ────────────────────────────────────────────────────────────
-  // [RESOURCE_PATHS.farmManagement]: [EnabledModule.FARM_MANAGEMENT],
-  // [RESOURCE_PATHS.packhouse]: [EnabledModule.PACKHOUSE],
-  // [RESOURCE_PATHS.accommodation]: [EnabledModule.ACCOMMODATION],
-  //  // ── Equipment & Fleet ──────────────────────────────────────────────────────
-  // [RESOURCE_PATHS.equipPreStart]: ALL_OPERATIONS,
-  // [RESOURCE_PATHS.equipMaintenance]: ALL_OPERATIONS,
-  // [RESOURCE_PATHS.equipFuelRegister]: ALL_OPERATIONS,
-  // [RESOURCE_PATHS.equipCalibration]: AGRI_ONLY,
-  // [RESOURCE_PATHS.equipFleet]: ALL_OPERATIONS,
-  //  // ── Safety, Quality & Compliance ──────────────────────────────────────────
-  // [RESOURCE_PATHS.safetyAuditing]: ALL_OPERATIONS,
-  // [RESOURCE_PATHS.safetyFood]: AGRI_ONLY,
-  // [RESOURCE_PATHS.safetyWhs]: ALL_OPERATIONS,
-  // [RESOURCE_PATHS.safetyCleaning]: ALL_OPERATIONS,
-  //  // ── Team & HR ──────────────────────────────────────────────────────────────
-  // [RESOURCE_PATHS.teamStaff]: ALL_OPERATIONS,
-  // [RESOURCE_PATHS.teamTraining]: ALL_OPERATIONS,
 };
+var DocumentType = /* @__PURE__ */ ((DocumentType2) => {
+  DocumentType2["SPRAY_RECORD"] = "SPRAY_RECORD";
+  DocumentType2["FERTIGATION_RECORD"] = "FERTIGATION_RECORD";
+  DocumentType2["FERTILIZER_RECORD"] = "FERTILIZER_RECORD";
+  DocumentType2["QA"] = "QA";
+  DocumentType2["CLEANING"] = "CLEANING";
+  DocumentType2["PEST"] = "PEST";
+  DocumentType2["EQUIPMENT_CALIBRATION_RECORD"] = "EQUIPMENT_CALIBRATION_RECORD";
+  DocumentType2["INVENTORY_CONSUMABLES"] = "INVENTORY_CONSUMABLES";
+  DocumentType2["INVENTORY_BOX_CARTON"] = "INVENTORY_BOX_CARTON";
+  DocumentType2["INVENTORY_CHEMICALS"] = "INVENTORY_CHEMICALS";
+  DocumentType2["STOCKTAKE"] = "STOCKTAKE";
+  DocumentType2["STOCKTAKE_MSDS"] = "STOCKTAKE_MSDS";
+  DocumentType2["MAPPING_FARM_MAPS"] = "MAPPING_FARM_MAPS";
+  DocumentType2["MAPPING_TRAFIC_MANAGEMENT"] = "MAPPING_TRAFIC_MANAGEMENT";
+  DocumentType2["MAPPING_EMERGENCY"] = "MAPPING_EMERGENCY";
+  DocumentType2["INCIDENT_REPORT"] = "INCIDENT_REPORT";
+  DocumentType2["TRAINING_RECORDS"] = "TRAINING_RECORDS";
+  DocumentType2["SOPS"] = "SOPS";
+  DocumentType2["RISK_ASSESSMENTS"] = "RISK_ASSESSMENTS";
+  DocumentType2["SERVICING_MAINTENANCE"] = "SERVICING_MAINTENANCE";
+  DocumentType2["SOIL_TEST"] = "SOIL_TEST";
+  DocumentType2["LEAF_TEST"] = "LEAF_TEST";
+  DocumentType2["WATER_TEST"] = "WATER_TEST";
+  DocumentType2["MRL_TESTING"] = "MRL_TESTING";
+  DocumentType2["HEAVY_METAL"] = "HEAVY_METAL";
+  DocumentType2["MICROBIAL"] = "MICROBIAL";
+  DocumentType2["HARVEST_LOG"] = "HARVEST_LOG";
+  DocumentType2["PACKHOUSE_INSPECTION"] = "PACKHOUSE_INSPECTION";
+  DocumentType2["TRAINING_CERTIFICATE"] = "TRAINING_CERTIFICATE";
+  DocumentType2["INVOICE"] = "INVOICE";
+  DocumentType2["LEGAL_CONTRACT"] = "LEGAL_CONTRACT";
+  DocumentType2["AUDIT_REPORT"] = "AUDIT_REPORT";
+  DocumentType2["SENSITIVE_IDENTITY"] = "SENSITIVE_IDENTITY";
+  return DocumentType2;
+})(DocumentType || {});
+var DOCUMENT_MENU_MAP = {
+  ["SPRAY_RECORD" /* SPRAY_RECORD */]: [RESOURCE_PATHS.farmManagement],
+  ["FERTIGATION_RECORD" /* FERTIGATION_RECORD */]: [RESOURCE_PATHS.farmManagement],
+  ["FERTILIZER_RECORD" /* FERTILIZER_RECORD */]: [RESOURCE_PATHS.farmManagement],
+  ["QA" /* QA */]: [RESOURCE_PATHS.safetyAuditing],
+  ["CLEANING" /* CLEANING */]: [RESOURCE_PATHS.safetyCleaning],
+  ["PEST" /* PEST */]: [RESOURCE_PATHS.farmManagement],
+  ["EQUIPMENT_CALIBRATION_RECORD" /* EQUIPMENT_CALIBRATION_RECORD */]: [RESOURCE_PATHS.equipCalibration],
+  ["SERVICING_MAINTENANCE" /* SERVICING_MAINTENANCE */]: [RESOURCE_PATHS.equipMaintenance],
+  ["INVENTORY_CONSUMABLES" /* INVENTORY_CONSUMABLES */]: [RESOURCE_PATHS.packhouse],
+  ["INVENTORY_BOX_CARTON" /* INVENTORY_BOX_CARTON */]: [RESOURCE_PATHS.packhouse],
+  ["INVENTORY_CHEMICALS" /* INVENTORY_CHEMICALS */]: [RESOURCE_PATHS.packhouse, RESOURCE_PATHS.farmManagement],
+  ["STOCKTAKE" /* STOCKTAKE */]: [RESOURCE_PATHS.packhouse],
+  ["STOCKTAKE_MSDS" /* STOCKTAKE_MSDS */]: [RESOURCE_PATHS.safetyWhs],
+  ["MAPPING_FARM_MAPS" /* MAPPING_FARM_MAPS */]: [RESOURCE_PATHS.adminBlueprintsSites],
+  ["MAPPING_TRAFIC_MANAGEMENT" /* MAPPING_TRAFIC_MANAGEMENT */]: [RESOURCE_PATHS.adminBlueprintsSites],
+  ["MAPPING_EMERGENCY" /* MAPPING_EMERGENCY */]: [RESOURCE_PATHS.adminBlueprintsSites],
+  ["INCIDENT_REPORT" /* INCIDENT_REPORT */]: [RESOURCE_PATHS.safetyWhs],
+  ["RISK_ASSESSMENTS" /* RISK_ASSESSMENTS */]: [RESOURCE_PATHS.safetyWhs],
+  ["TRAINING_RECORDS" /* TRAINING_RECORDS */]: [RESOURCE_PATHS.teamTraining],
+  ["TRAINING_CERTIFICATE" /* TRAINING_CERTIFICATE */]: [RESOURCE_PATHS.teamTraining],
+  ["SOPS" /* SOPS */]: [RESOURCE_PATHS.documentHubTemplates],
+  ["SOIL_TEST" /* SOIL_TEST */]: [RESOURCE_PATHS.farmManagement],
+  ["LEAF_TEST" /* LEAF_TEST */]: [RESOURCE_PATHS.farmManagement],
+  ["WATER_TEST" /* WATER_TEST */]: [RESOURCE_PATHS.farmManagement, RESOURCE_PATHS.safetyFood],
+  ["MRL_TESTING" /* MRL_TESTING */]: [RESOURCE_PATHS.safetyFood],
+  ["HEAVY_METAL" /* HEAVY_METAL */]: [RESOURCE_PATHS.safetyFood],
+  ["MICROBIAL" /* MICROBIAL */]: [RESOURCE_PATHS.safetyFood],
+  ["HARVEST_LOG" /* HARVEST_LOG */]: [RESOURCE_PATHS.farmManagement],
+  ["PACKHOUSE_INSPECTION" /* PACKHOUSE_INSPECTION */]: [RESOURCE_PATHS.packhouse],
+  ["INVOICE" /* INVOICE */]: [RESOURCE_PATHS.documentHub],
+  ["LEGAL_CONTRACT" /* LEGAL_CONTRACT */]: [RESOURCE_PATHS.documentHub],
+  ["AUDIT_REPORT" /* AUDIT_REPORT */]: [RESOURCE_PATHS.safetyAuditing, RESOURCE_PATHS.dashboard],
+  ["SENSITIVE_IDENTITY" /* SENSITIVE_IDENTITY */]: [RESOURCE_PATHS.adminUserRoster]
+};
+
+// src/index.ts
+var AppError = class extends Error {
+  status;
+  appCode;
+  isOperational;
+  constructor(status, mod, cat, act, message) {
+    super(message);
+    this.status = status;
+    this.appCode = `${mod}-${status}-${cat}${act}`;
+    this.isOperational = true;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var ErrorFactory = {
+  unauthorized: (mod, msg = "Authentication required") => new AppError(401, mod, CAT.PERMISSION, ACT.GENERIC, msg),
+  forbidden: (mod, act, msg = "Access denied") => new AppError(403, mod, CAT.PERMISSION, act, msg),
+  badRequest: (mod, act, msg = "Bad request") => new AppError(400, mod, CAT.VALIDATION, act, msg),
+  notFound: (mod, act = ACT.GENERIC, msg = "Record not found") => new AppError(404, mod, CAT.VALIDATION, act, msg),
+  conflict: (mod, act, msg = "Record already exists") => new AppError(409, mod, CAT.INTEGRITY, act, msg),
+  integrity: (mod, act = ACT.GENERIC, msg = "Data integrity violation") => new AppError(409, mod, CAT.INTEGRITY, act, msg),
+  subscription: (mod, msg = "Module locked or subscription required") => new AppError(403, mod, CAT.SUBSCRIPTION, ACT.GENERIC, msg),
+  internal: (mod, msg = "Internal server error") => new AppError(500, mod, CAT.INTEGRITY, ACT.GENERIC, msg)
+};
+var handleAppErrorResponse = (error, mod = MOD.ADMIN) => {
+  if (error instanceof AppError && error.isOperational) {
+    return Response.json(
+      { error: { appCode: error.appCode, message: error.message } },
+      { status: error.status }
+    );
+  }
+  const e = error;
+  console.error(`[${mod}] UNEXPECTED ERROR:`, e?.message);
+  console.error(`[${mod}] STACK:`, e?.stack);
+  return Response.json(
+    { error: { appCode: `${mod}-500-000`, message: "An unexpected server error occurred. Please try again." } },
+    { status: 500 }
+  );
+};
+var FALLBACK = {
+  title: "Something Went Wrong",
+  text: "An unexpected error occurred. Please try again or contact your administrator."
+};
+var resolveAppError = (appCode) => {
+  if (!appCode || typeof appCode !== "string") {
+    return { ...FALLBACK, module: "UNK", moduleLabel: "Unknown", status: 500, catAct: "000", isSubscriptionIssue: false, isPermissionIssue: false };
+  }
+  const parts = appCode.split("-");
+  if (parts.length !== 3) {
+    return { ...FALLBACK, module: "UNK", moduleLabel: "Unknown", status: 500, catAct: "000", isSubscriptionIssue: false, isPermissionIssue: false };
+  }
+  const [mod, status, catAct] = parts;
+  const details = ERROR_DICTIONARY[catAct] || FALLBACK;
+  return {
+    title: details.title,
+    text: details.text,
+    module: mod,
+    moduleLabel: MODULE_LABELS[mod] || mod,
+    status: parseInt(status, 10),
+    catAct,
+    isSubscriptionIssue: catAct.startsWith("1"),
+    isPermissionIssue: catAct.startsWith("2")
+  };
+};
+var extractAppCode = (error) => {
+  const e = error;
+  return e?.response?.data?.error?.appCode ?? e?.data?.error?.appCode ?? null;
+};
+var resolveError = (error) => {
+  const appCode = extractAppCode(error);
+  if (appCode) return resolveAppError(appCode);
+  const e = error;
+  return { ...FALLBACK, module: "UNK", moduleLabel: "Unknown", status: e?.status || 500, catAct: "000", isSubscriptionIssue: false, isPermissionIssue: false };
+};
+function generateCanonicalId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    return (c === "x" ? r : r & 3 | 8).toString(16);
+  });
+}
+function generateInfrastructureFields(activeScope, availableScopes) {
+  if (!activeScope || !availableScopes?.length) {
+    throw ErrorFactory.unauthorized("[generateInfrastructureFields] Missing scope context.");
+  }
+  let companyId = null;
+  let legalEntityId = null;
+  let facilityId = null;
+  let pointer = activeScope;
+  while (pointer) {
+    if (pointer.type === "company") companyId = pointer.base44Id;
+    if (pointer.type === "legalEntity") legalEntityId = pointer.base44Id;
+    if (pointer.type === "facility") facilityId = pointer.base44Id;
+    const parentId = pointer.parentId ?? null;
+    pointer = parentId ? availableScopes.find((s) => s.base44Id === parentId) || null : null;
+  }
+  if (!companyId) {
+    throw ErrorFactory.unauthorized("[generateInfrastructureFields] Could not resolve companyId from scope tree.");
+  }
+  return {
+    canonicalId: crypto.randomUUID(),
+    companyId,
+    legalEntityId,
+    facilityId,
+    authScopeId: activeScope.authScopeId
+  };
+}
+function buildRlsFilter(session, extra = {}) {
+  return { ...extra, authScopeId: { $in: session.readScopes || [] } };
+}
+function canRead(session, authScopeId) {
+  return session.readScopes?.includes(authScopeId) ?? false;
+}
+function canWrite(session, authScopeId, resourcePath) {
+  const override = session.resourceOverrides?.[authScopeId]?.[resourcePath];
+  if (override === "WRITE") return true;
+  if (override === "NONE" || override === "READ") return false;
+  return session.writeScopes?.includes(authScopeId) ?? false;
+}
+function assertCanWrite(session, authScopeId, resourcePath) {
+  const override = session.resourceOverrides?.[authScopeId]?.[resourcePath];
+  if (override === "WRITE") return;
+  if (override === "NONE" || override === "READ") {
+    throw new AppError(
+      403,
+      MOD.SESSION,
+      CAT.PERMISSION,
+      ACT.GENERIC,
+      `You do not have write access to "${resourcePath}" in this scope.`
+    );
+  }
+  if (session.writeScopes?.includes(authScopeId)) return;
+  throw new AppError(
+    403,
+    MOD.SESSION,
+    CAT.PERMISSION,
+    ACT.GENERIC,
+    "You do not have permission to modify records in this scope."
+  );
+}
+function resolveAccess(session, activeScopeId, tabConfig) {
+  const resourcePath = tabConfig?.resourceId;
+  const overrides = session.resourceOverrides?.[activeScopeId] ?? {};
+  if (resourcePath) {
+    const segments = resourcePath.split(".");
+    for (let len = segments.length; len >= 1; len--) {
+      const path = segments.slice(0, len).join(".");
+      const override = overrides[path];
+      if (override === "NONE" || override === "READ" || override === "WRITE") return override;
+    }
+  }
+  const allowedRoles = tabConfig?.allowedRoles ?? [];
+  const requiredPrivileges = tabConfig?.requiredPrivileges ?? [];
+  const hasRestrictions = allowedRoles.length > 0 || requiredPrivileges.length > 0;
+  if (hasRestrictions) {
+    const role = session?.role ?? "";
+    const privileges = session?.privileges ?? [];
+    const passesRole = allowedRoles.length > 0 && allowedRoles.includes(role);
+    const passesPrivilege = requiredPrivileges.length > 0 && requiredPrivileges.some((p) => privileges.includes(p));
+    return passesRole || passesPrivilege ? "WRITE" : "NONE";
+  }
+  return "READ";
+}
+function resolveMenuVisibility(session, authScopeId, resourcePath) {
+  const override = session.resourceOverrides?.[authScopeId]?.[resourcePath];
+  if (override === "NONE") return "hidden";
+  if (override === "READ") return "read_only";
+  if (override === "WRITE") return "active";
+  if (session.writeScopes?.includes(authScopeId)) return "active";
+  if (session.readScopes?.includes(authScopeId)) return "read_only";
+  return "hidden";
+}
+function isTabVisible(session, activeScopeId, tabConfig) {
+  return resolveAccess(session, activeScopeId, tabConfig) !== "NONE";
+}
+function isTabWritable(session, activeScopeId, tabConfig) {
+  return resolveAccess(session, activeScopeId, tabConfig) === "WRITE";
+}
 function evaluateBaseAccess(resourcePath, session, requirements = {}) {
   if (!session?.role) return "NONE";
   if (session.role === UserRole.OWNER) return "WRITE";
@@ -1058,6 +1080,68 @@ async function verifyAndExtractSession(token, secret) {
     throw ErrorFactory.unauthorized(MOD.SESSION, "UNAUTHORIZED: No secure session token provided.");
   }
 }
+function getFormMeta(componentId) {
+  return FORM_REGISTRY[componentId] ?? null;
+}
+function getFormsGroupedByModule() {
+  const groups = {};
+  for (const [id, meta] of Object.entries(FORM_REGISTRY)) {
+    if (!groups[meta.module]) groups[meta.module] = [];
+    groups[meta.module].push({ id, ...meta });
+  }
+  return groups;
+}
+var getTaskTypeOptions = () => Object.entries(TASK_TYPE_REGISTRY).map(([value, config]) => ({
+  value,
+  label: config.label,
+  description: config.description,
+  mimeTypes: config.mimeTypes,
+  icon: config.icon
+}));
+var getAcceptedMimeTypes = (taskType) => {
+  const config = TASK_TYPE_REGISTRY[taskType];
+  return config ? config.mimeTypes.join(",") : "*/*";
+};
+var getApproveAction = (taskType) => {
+  return TASK_TYPE_REGISTRY[taskType]?.approveAction ?? null;
+};
+function generateDocumentPath(params) {
+  const sanitizedName = params.siteName.replace(/[^a-z0-9]/gi, "_");
+  if (params.isStatic) {
+    return `${sanitizedName}/_CORE/${params.docType}`;
+  } else {
+    const folderYear = params.year || (/* @__PURE__ */ new Date()).getUTCFullYear();
+    const folderCrop = params.crop ? `/${params.crop.toUpperCase()}` : "";
+    return `${sanitizedName}/_SEASONAL/${folderYear}/${params.docType}${folderCrop}`;
+  }
+}
+function isValueMatch(fileValue, expectedValue) {
+  if (Array.isArray(expectedValue)) return expectedValue.includes(fileValue);
+  return fileValue === expectedValue;
+}
+function calculateFileMetadataMatch(criteria, fileMetadata, auditContext) {
+  for (const [key, expectedValue] of Object.entries(criteria.mustMatch)) {
+    if (!isValueMatch(fileMetadata[key], expectedValue)) return 0;
+  }
+  if (criteria.mustMatchContext) {
+    for (const field of criteria.mustMatchContext) {
+      const contextValue = auditContext[field];
+      if (contextValue === void 0) continue;
+      if (!isValueMatch(fileMetadata[field], contextValue)) return 0;
+    }
+  }
+  if (fileMetadata.isStatic === true) return 100;
+  if (!criteria.contextMatch || criteria.contextMatch.length === 0) return 100;
+  let matches = 0;
+  let validChecks = 0;
+  criteria.contextMatch.forEach((field) => {
+    const contextValue = auditContext[field];
+    if (contextValue === void 0) return;
+    validChecks++;
+    if (isValueMatch(fileMetadata[field], contextValue)) matches++;
+  });
+  return validChecks > 0 ? Math.round(matches / validChecks * 100) : 100;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ACCESS_RANK,
@@ -1072,6 +1156,8 @@ async function verifyAndExtractSession(token, secret) {
   CAT,
   Converter,
   CropCycleStatus,
+  DOCUMENT_MENU_MAP,
+  DocumentType,
   ERROR_DICTIONARY,
   EVERYONE,
   EmitterType,
@@ -1112,12 +1198,14 @@ async function verifyAndExtractSession(token, secret) {
   assertCanWrite,
   assertTenantBoundary,
   buildRlsFilter,
+  calculateFileMetadataMatch,
   canRead,
   canWrite,
   evaluateBaseAccess,
   extractAppCode,
   findSpecificOverride,
   generateCanonicalId,
+  generateDocumentPath,
   generateInfrastructureFields,
   getAcceptedMimeTypes,
   getApproveAction,