@litusarchieve18/agricore-utils 1.0.10 → 1.0.12

package/README.md

@@ -65,6 +65,8 @@ The universal vocabulary of the AgriCore platform, ensuring type-safety across a
 🔐 Security & Access Control
 The library now includes a centralized logic layer to enforce granular permissions across all AgriCore services.
 
+---------------------------------------------------------------------
+
 evaluateBaseAccess: Automatically determines a user's base permission level (NONE, READ, or WRITE) for a specific resource path (e.g., records.financials). It respects the OWNER role "God Mode" bypass and uses ROLE_SECTIONS_BY_KEY to provide sensible defaults for different app sections.
 
 Access Ranking (resolveEffectiveAccess): Implements an additive permission model. By ranking levels (NONE < READ < WRITE), it allows the system to compare base permissions against specific user overrides and resolve the highest authorized access level.
@@ -92,6 +94,8 @@ const recordToSave = {
 
 To completely eliminate database bottlenecks and solve serverless rate-limiting, AgriCore has migrated to a state-of-the-art, "Zero-DB" authorization architecture. By decoupling our security rules from the database SDK, our backend API endpoints now resolve complex multi-tenant boundaries and granular role-based access controls in roughly 1 millisecond.
 
+---------------------------------------------------------------------
+
 Key Features of the New Security Engine:
 
 One-Time Session Generation: On login, the backend dynamically aggregates a user's full hierarchical profile—including role assignments, availableScopes (Company > Legal Entity > Facility), and granular resourceOverrides—into a single, cryptographically signed JSON Web Token (JWT).
@@ -102,6 +106,56 @@ Smart Frontend Interceptor: A centralized React hook (useApiClient) acts as an a
 
 Instant Context Switching: Because the JWT securely holds the user's entire "VIP List" of permitted scopes, users can instantly switch between farms, legal entities, and facilities in the frontend global dropdown without triggering a new authentication handshake or database query.
 
+---------------------------------------------------------------------
+
+This Document Management Engine provides a standardized, compliant, and migration-ready architecture for handling agricultural records. It ensures that files are stored predictably and matched against audit requirements with high precision.
+
+Document Management & Compliance Engine
+This module handles the lifecycle of file assets, from standardized naming and path generation to intelligent metadata matching for compliance audits.
+
+1. Standardized Taxonomy (DocumentType)
+The DocumentType enum serves as the single source of truth for the AgriCore document ecosystem. It categorizes every record—from SPRAY_RECORD to MAPPING_FARM_MAPS—ensuring that the database remains searchable and consistent across different farms and legal entities.
+
+2. Smart Routing (generateDocumentPath)
+This function enforces the "Core vs. Seasonal" storage architecture. It ensures that permanent files (Fixed Assets) and crop-cycle files (Working Assets) are physically and logically separated:
+
+Static Assets (isStatic: true): Routed to {SiteName}/_CORE/{DocumentType}.
+
+Seasonal Assets: Routed to a strict temporal hierarchy: {SiteName}/_SEASONAL/{Year}/{DocumentType}/{Crop}.
+
+3. Intelligence Engine (calculateFileMetadataMatch)
+A 3-tier matching algorithm used to automatically suggest evidence for audit questions. It evaluates the relevance of a file based on three layers:
+
+Static Hard Fails: Strict equality checks for properties like documentType.
+
+Dynamic Hard Fails (mustMatchContext): Ensures files belong to the correct boundaries (e.g., siteId array inclusion) based on the current AuditHeader.
+
+Soft Relevance Scoring (contextMatch): Calculates a percentage score based on environmental tags like seasonId or crop, allowing the UI to surface the "best matches" first.
+
+Quick Example
+TypeScript
+// 1. Generate a path for a seasonal spray record
+const path = generateDocumentPath({
+  siteName: "North Farm",
+  docType: DocumentType.SPRAY_RECORD,
+  year: 2026,
+  crop: "Mango"
+}); 
+// Output: North_Farm/_SEASONAL/2026/SPRAY_RECORD/MANGO
+
+// 2. Score a file against an audit requirement
+const score = calculateFileMetadataMatch(
+  { 
+    mustMatch: { documentType: "SPRAY_RECORD" },
+    mustMatchContext: ["siteId"], // Hard fail if wrong farm
+    contextMatch: ["seasonId"]    // Soft score for season relevance
+  },
+  file.metadata,
+  auditHeader.context
+);
+
+============================================================================
+
 🛠️ Development & Publishing Guide
 Zero Dependencies
 To keep the package ultra-lightweight (~30KB), this library has zero runtime dependencies. All build tools (tsup, typescript) are strictly kept in devDependencies, and the package.json uses the "files": ["dist"] array to ensure only compiled code is uploaded.
@@ -129,6 +183,10 @@ Run the publish command:
 Bash
 npm publish --access public
 📝 Version History
+V1.0.12 — add some functionality to add a file tag
+
+V1.0.11 — add userName and userEmail to AgriCoreSession
+
 V1.0.10 — add an explicit exports map
 
 V1.0.9 — added jwt function

package/dist/index.d.mts

@@ -23,6 +23,8 @@ interface ResourceOverrides {
  */
 interface AgriCoreSession {
     userId: string;
+    userName: string;
+    userEmail: string;
     companyId: string;
     activeScopeId: string | null;
     companyConfig: CompanyConfig;
@@ -518,5 +520,57 @@ targets: {
     expectedScopeType?: 'company' | 'legalEntity' | 'facility';
 }): Promise<boolean>;
 declare function verifyAndExtractSession(token: string, secret: string): Promise<AgriCoreSession>;
+declare enum DocumentType {
+    SPRAY_RECORD = "SPRAY_RECORD",
+    FERTIGATION_RECORD = "FERTIGATION_RECORD",
+    FERTILIZER_RECORD = "FERTILIZER_RECORD",
+    QA = "QA",
+    CLEANING = "CLEANING",
+    PEST = "PEST",
+    EQUIPMENT_CALIBRATION_RECORD = "EQUIPMENT_CALIBRATION_RECORD",
+    INVENTORY_CONSUMABLES = "INVENTORY_CONSUMABLES",
+    INVENTORY_BOX_CARTON = "INVENTORY_BOX_CARTON",
+    INVENTORY_CHEMICALS = "INVENTORY_CHEMICALS",
+    STOCKTAKE = "STOCKTAKE",
+    STOCKTAKE_MSDS = "STOCKTAKE_MSDS",
+    MAPPING_FARM_MAPS = "MAPPING_FARM_MAPS",
+    MAPPING_TRAFIC_MANAGEMENT = "MAPPING_TRAFIC_MANAGEMENT",
+    MAPPING_EMERGENCY = "MAPPING_EMERGENCY",
+    INCIDENT_REPORT = "INCIDENT_REPORT",
+    TRAINING_RECORDS = "TRAINING_RECORDS",
+    SOPS = "SOPS",
+    RISK_ASSESSMENTS = "RISK_ASSESSMENTS",
+    SERVICING_MAINTENANCE = "SERVICING_MAINTENANCE",
+    SOIL_TEST = "SOIL_TEST",
+    LEAF_TEST = "LEAF_TEST",
+    WATER_TEST = "WATER_TEST",
+    MRL_TESTING = "MRL_TESTING",
+    HEAVY_METAL = "HEAVY_METAL",
+    MICROBIAL = "MICROBIAL",
+    HARVEST_LOG = "HARVEST_LOG",
+    PACKHOUSE_INSPECTION = "PACKHOUSE_INSPECTION",
+    TRAINING_CERTIFICATE = "TRAINING_CERTIFICATE",
+    INVOICE = "INVOICE",
+    LEGAL_CONTRACT = "LEGAL_CONTRACT",
+    AUDIT_REPORT = "AUDIT_REPORT",
+    SENSITIVE_IDENTITY = "SENSITIVE_IDENTITY"
+}
+/**
+ * Generates a full folder path matching strict business requirements.
+ * Static:  {SiteName}/_CORE/{DocumentType}
+ * Dynamic: {SiteName}/_SEASONAL/{Year}/{DocumentType}/{Crop}
+ */
+declare function generateDocumentPath(params: {
+    siteName: string;
+    docType: DocumentType;
+    isStatic?: boolean;
+    year?: number | string;
+    crop?: string;
+}): string;
+declare function calculateFileMetadataMatch(criteria: {
+    mustMatch: Record<string, any>;
+    mustMatchContext?: string[];
+    contextMatch?: string[];
+}, fileMetadata: Record<string, any>, auditContext: Record<string, any>): number;
 
-export { ACCESS_RANK, ACT, AccessLevel, type AccessLevelType, type AgriCoreSession, AgriLogger, AppError, ApprovalStatus, ApprovalType, AuditStatus, AuditType, type AuthScopeFields, type AvailableScope, CAT, type CompanyConfig, Converter, CropCycleStatus, ERROR_DICTIONARY, EVERYONE, EmitterType, EnabledModule, ErrorFactory, FORM_REGISTRY, FacilityType, type FormMeta, HarvestMethod, type InfrastructureFields, LinkedStatus, MOD, MODULE_LABELS, MicroclimateZone, MimeType, type ModCode, NettingType, NotificationMode, OrderStatus, type PermissionLevel, PhysicalState, PlantingMethod, RESOURCE_MODULE_MAP, RESOURCE_PATHS, RESOURCE_REQUIREMENTS, ROLE_SECTIONS_BY_KEY, RelationshipType, type ResolvedError, type ResourceOverrides, type ResourceRequirement, RowOrientation, SENTINEL_UUID, type ScopeType, SoilTexture, TASK_TYPE_REGISTRY, type TabConfig, TargetEntityType, TaskStatus, TaskType, type TaskTypeConfig, TransactionType, TrellisType, UserPrivilege, UserRole, type UserRoleType, Validator, VigorRating, WaterSource, assertCanWrite, assertTenantBoundary, buildRlsFilter, canRead, canWrite, evaluateBaseAccess, extractAppCode, findSpecificOverride, generateCanonicalId, generateInfrastructureFields, getAcceptedMimeTypes, getApproveAction, getFormMeta, getFormsGroupedByModule, getTaskTypeOptions, handleAppErrorResponse, isTabVisible, isTabWritable, resolveAccess, resolveAppError, resolveEffectiveAccess, resolveError, resolveMenuVisibility, verifyAndExtractSession, withAgriLogging };
+export { ACCESS_RANK, ACT, AccessLevel, type AccessLevelType, type AgriCoreSession, AgriLogger, AppError, ApprovalStatus, ApprovalType, AuditStatus, AuditType, type AuthScopeFields, type AvailableScope, CAT, type CompanyConfig, Converter, CropCycleStatus, DocumentType, ERROR_DICTIONARY, EVERYONE, EmitterType, EnabledModule, ErrorFactory, FORM_REGISTRY, FacilityType, type FormMeta, HarvestMethod, type InfrastructureFields, LinkedStatus, MOD, MODULE_LABELS, MicroclimateZone, MimeType, type ModCode, NettingType, NotificationMode, OrderStatus, type PermissionLevel, PhysicalState, PlantingMethod, RESOURCE_MODULE_MAP, RESOURCE_PATHS, RESOURCE_REQUIREMENTS, ROLE_SECTIONS_BY_KEY, RelationshipType, type ResolvedError, type ResourceOverrides, type ResourceRequirement, RowOrientation, SENTINEL_UUID, type ScopeType, SoilTexture, TASK_TYPE_REGISTRY, type TabConfig, TargetEntityType, TaskStatus, TaskType, type TaskTypeConfig, TransactionType, TrellisType, UserPrivilege, UserRole, type UserRoleType, Validator, VigorRating, WaterSource, assertCanWrite, assertTenantBoundary, buildRlsFilter, calculateFileMetadataMatch, canRead, canWrite, evaluateBaseAccess, extractAppCode, findSpecificOverride, generateCanonicalId, generateDocumentPath, generateInfrastructureFields, getAcceptedMimeTypes, getApproveAction, getFormMeta, getFormsGroupedByModule, getTaskTypeOptions, handleAppErrorResponse, isTabVisible, isTabWritable, resolveAccess, resolveAppError, resolveEffectiveAccess, resolveError, resolveMenuVisibility, verifyAndExtractSession, withAgriLogging };

package/dist/index.d.ts

@@ -23,6 +23,8 @@ interface ResourceOverrides {
  */
 interface AgriCoreSession {
     userId: string;
+    userName: string;
+    userEmail: string;
     companyId: string;
     activeScopeId: string | null;
     companyConfig: CompanyConfig;
@@ -518,5 +520,57 @@ targets: {
     expectedScopeType?: 'company' | 'legalEntity' | 'facility';
 }): Promise<boolean>;
 declare function verifyAndExtractSession(token: string, secret: string): Promise<AgriCoreSession>;
+declare enum DocumentType {
+    SPRAY_RECORD = "SPRAY_RECORD",
+    FERTIGATION_RECORD = "FERTIGATION_RECORD",
+    FERTILIZER_RECORD = "FERTILIZER_RECORD",
+    QA = "QA",
+    CLEANING = "CLEANING",
+    PEST = "PEST",
+    EQUIPMENT_CALIBRATION_RECORD = "EQUIPMENT_CALIBRATION_RECORD",
+    INVENTORY_CONSUMABLES = "INVENTORY_CONSUMABLES",
+    INVENTORY_BOX_CARTON = "INVENTORY_BOX_CARTON",
+    INVENTORY_CHEMICALS = "INVENTORY_CHEMICALS",
+    STOCKTAKE = "STOCKTAKE",
+    STOCKTAKE_MSDS = "STOCKTAKE_MSDS",
+    MAPPING_FARM_MAPS = "MAPPING_FARM_MAPS",
+    MAPPING_TRAFIC_MANAGEMENT = "MAPPING_TRAFIC_MANAGEMENT",
+    MAPPING_EMERGENCY = "MAPPING_EMERGENCY",
+    INCIDENT_REPORT = "INCIDENT_REPORT",
+    TRAINING_RECORDS = "TRAINING_RECORDS",
+    SOPS = "SOPS",
+    RISK_ASSESSMENTS = "RISK_ASSESSMENTS",
+    SERVICING_MAINTENANCE = "SERVICING_MAINTENANCE",
+    SOIL_TEST = "SOIL_TEST",
+    LEAF_TEST = "LEAF_TEST",
+    WATER_TEST = "WATER_TEST",
+    MRL_TESTING = "MRL_TESTING",
+    HEAVY_METAL = "HEAVY_METAL",
+    MICROBIAL = "MICROBIAL",
+    HARVEST_LOG = "HARVEST_LOG",
+    PACKHOUSE_INSPECTION = "PACKHOUSE_INSPECTION",
+    TRAINING_CERTIFICATE = "TRAINING_CERTIFICATE",
+    INVOICE = "INVOICE",
+    LEGAL_CONTRACT = "LEGAL_CONTRACT",
+    AUDIT_REPORT = "AUDIT_REPORT",
+    SENSITIVE_IDENTITY = "SENSITIVE_IDENTITY"
+}
+/**
+ * Generates a full folder path matching strict business requirements.
+ * Static:  {SiteName}/_CORE/{DocumentType}
+ * Dynamic: {SiteName}/_SEASONAL/{Year}/{DocumentType}/{Crop}
+ */
+declare function generateDocumentPath(params: {
+    siteName: string;
+    docType: DocumentType;
+    isStatic?: boolean;
+    year?: number | string;
+    crop?: string;
+}): string;
+declare function calculateFileMetadataMatch(criteria: {
+    mustMatch: Record<string, any>;
+    mustMatchContext?: string[];
+    contextMatch?: string[];
+}, fileMetadata: Record<string, any>, auditContext: Record<string, any>): number;
 
-export { ACCESS_RANK, ACT, AccessLevel, type AccessLevelType, type AgriCoreSession, AgriLogger, AppError, ApprovalStatus, ApprovalType, AuditStatus, AuditType, type AuthScopeFields, type AvailableScope, CAT, type CompanyConfig, Converter, CropCycleStatus, ERROR_DICTIONARY, EVERYONE, EmitterType, EnabledModule, ErrorFactory, FORM_REGISTRY, FacilityType, type FormMeta, HarvestMethod, type InfrastructureFields, LinkedStatus, MOD, MODULE_LABELS, MicroclimateZone, MimeType, type ModCode, NettingType, NotificationMode, OrderStatus, type PermissionLevel, PhysicalState, PlantingMethod, RESOURCE_MODULE_MAP, RESOURCE_PATHS, RESOURCE_REQUIREMENTS, ROLE_SECTIONS_BY_KEY, RelationshipType, type ResolvedError, type ResourceOverrides, type ResourceRequirement, RowOrientation, SENTINEL_UUID, type ScopeType, SoilTexture, TASK_TYPE_REGISTRY, type TabConfig, TargetEntityType, TaskStatus, TaskType, type TaskTypeConfig, TransactionType, TrellisType, UserPrivilege, UserRole, type UserRoleType, Validator, VigorRating, WaterSource, assertCanWrite, assertTenantBoundary, buildRlsFilter, canRead, canWrite, evaluateBaseAccess, extractAppCode, findSpecificOverride, generateCanonicalId, generateInfrastructureFields, getAcceptedMimeTypes, getApproveAction, getFormMeta, getFormsGroupedByModule, getTaskTypeOptions, handleAppErrorResponse, isTabVisible, isTabWritable, resolveAccess, resolveAppError, resolveEffectiveAccess, resolveError, resolveMenuVisibility, verifyAndExtractSession, withAgriLogging };
+export { ACCESS_RANK, ACT, AccessLevel, type AccessLevelType, type AgriCoreSession, AgriLogger, AppError, ApprovalStatus, ApprovalType, AuditStatus, AuditType, type AuthScopeFields, type AvailableScope, CAT, type CompanyConfig, Converter, CropCycleStatus, DocumentType, ERROR_DICTIONARY, EVERYONE, EmitterType, EnabledModule, ErrorFactory, FORM_REGISTRY, FacilityType, type FormMeta, HarvestMethod, type InfrastructureFields, LinkedStatus, MOD, MODULE_LABELS, MicroclimateZone, MimeType, type ModCode, NettingType, NotificationMode, OrderStatus, type PermissionLevel, PhysicalState, PlantingMethod, RESOURCE_MODULE_MAP, RESOURCE_PATHS, RESOURCE_REQUIREMENTS, ROLE_SECTIONS_BY_KEY, RelationshipType, type ResolvedError, type ResourceOverrides, type ResourceRequirement, RowOrientation, SENTINEL_UUID, type ScopeType, SoilTexture, TASK_TYPE_REGISTRY, type TabConfig, TargetEntityType, TaskStatus, TaskType, type TaskTypeConfig, TransactionType, TrellisType, UserPrivilege, UserRole, type UserRoleType, Validator, VigorRating, WaterSource, assertCanWrite, assertTenantBoundary, buildRlsFilter, calculateFileMetadataMatch, canRead, canWrite, evaluateBaseAccess, extractAppCode, findSpecificOverride, generateCanonicalId, generateDocumentPath, generateInfrastructureFields, getAcceptedMimeTypes, getApproveAction, getFormMeta, getFormsGroupedByModule, getTaskTypeOptions, handleAppErrorResponse, isTabVisible, isTabWritable, resolveAccess, resolveAppError, resolveEffectiveAccess, resolveError, resolveMenuVisibility, verifyAndExtractSession, withAgriLogging };

package/dist/index.js

@@ -32,6 +32,7 @@ __export(index_exports, {
   CAT: () => CAT,
   Converter: () => Converter,
   CropCycleStatus: () => CropCycleStatus,
+  DocumentType: () => DocumentType,
   ERROR_DICTIONARY: () => ERROR_DICTIONARY,
   EVERYONE: () => EVERYONE,
   EmitterType: () => EmitterType,
@@ -72,12 +73,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,
@@ -1058,6 +1061,79 @@ async function verifyAndExtractSession(token, secret) {
     throw ErrorFactory.unauthorized(MOD.SESSION, "UNAUTHORIZED: No secure session token provided.");
   }
 }
+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 || {});
+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 +1148,7 @@ async function verifyAndExtractSession(token, secret) {
   CAT,
   Converter,
   CropCycleStatus,
+  DocumentType,
   ERROR_DICTIONARY,
   EVERYONE,
   EmitterType,
@@ -1112,12 +1189,14 @@ async function verifyAndExtractSession(token, secret) {
   assertCanWrite,
   assertTenantBoundary,
   buildRlsFilter,
+  calculateFileMetadataMatch,
   canRead,
   canWrite,
   evaluateBaseAccess,
   extractAppCode,
   findSpecificOverride,
   generateCanonicalId,
+  generateDocumentPath,
   generateInfrastructureFields,
   getAcceptedMimeTypes,
   getApproveAction,

package/dist/index.mjs

@@ -961,6 +961,79 @@ async function verifyAndExtractSession(token, secret) {
     throw ErrorFactory.unauthorized(MOD.SESSION, "UNAUTHORIZED: No secure session token provided.");
   }
 }
+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 || {});
+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;
+}
 export {
   ACCESS_RANK,
   ACT,
@@ -974,6 +1047,7 @@ export {
   CAT,
   Converter,
   CropCycleStatus,
+  DocumentType,
   ERROR_DICTIONARY,
   EVERYONE,
   EmitterType,
@@ -1014,12 +1088,14 @@ export {
   assertCanWrite,
   assertTenantBoundary,
   buildRlsFilter,
+  calculateFileMetadataMatch,
   canRead,
   canWrite,
   evaluateBaseAccess,
   extractAppCode,
   findSpecificOverride,
   generateCanonicalId,
+  generateDocumentPath,
   generateInfrastructureFields,
   getAcceptedMimeTypes,
   getApproveAction,

package/package.json

@@ -1,37 +1,37 @@
-{
-  "name": "@litusarchieve18/agricore-utils",
-  "version": "1.0.10",
-  "description": "Canonical Backend Utility Library for AgriCore",
-  "main": "./dist/index.js",
-  "module": "./dist/index.mjs",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js",
-      "default": "./dist/index.mjs"
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "agricore",
-    "utils",
-    "backend"
-  ],
-  "author": "Vincent",
-  "license": "ISC",
-  "devDependencies": {
-    "tsup": "^8.0.0",
-    "typescript": "^5.0.0"
-  },
-  "dependencies": {
-    "jose": "^6.2.2"
-  }
-}
+{
+  "name": "@litusarchieve18/agricore-utils",
+  "version": "1.0.12",
+  "description": "Canonical Backend Utility Library for AgriCore",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "agricore",
+    "utils",
+    "backend"
+  ],
+  "author": "Vincent",
+  "license": "ISC",
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "jose": "^6.2.2"
+  }
+}