@litusarchieve18/agricore-utils 1.0.1 → 1.0.2

package/README.md

@@ -0,0 +1,103 @@
+# @litusarchieve18/agricore-utils
+
+The Canonical Backend Utility Library for the **AgriCore** ecosystem. 
+
+This library provides the foundational "plumbing" for the AgriCore backend, including standardized error handling, data middleware, domain enums, and the core security session contracts. It is specifically optimized to be framework-agnostic and lightweight, with native support for the **Base44 / Deno** deployment environment.
+
+## 📦 Installation
+
+Because Base44 Deno functions require module resolution at runtime without private authentication headers, this package is published to the **public NPM registry**.
+
+### For Node.js Environments
+```bash
+npm install @litusarchieve18/agricore-utils
+
+For Base44 / Deno Environments
+You do not need a .npmrc or GITHUB_TOKEN to use this library in Base44. Import it directly using the npm: protocol:
+import { AgriLogger, AppError, MOD } from 'npm:@litusarchieve18/agricore-utils@^1.0.2';
+
+🏗️ Core Architecture & Features
+This library is designed with the "Adapter Pattern" in mind. It defines strict contracts (AgriCoreSession) so that your business logic remains completely isolated from the underlying Base44 database infrastructure.
+
+1. The AgriCore Session (v2)
+The universal contract for authenticated users. The v2 upgrade includes injected UI-ready navigation data (availableScopes) and tenant configurations to prevent unnecessary frontend API calls.
+
+TypeScript
+import { AgriCoreSession } from 'npm:@litusarchieve18/agricore-utils@^1.0.2';
+
+// Example of the v2 structure:
+const session: AgriCoreSession = {
+  userId: "69e1a1...",
+  companyId: "69e6a3...",
+  activeScopeId: "660216...",
+  companyConfig: { isMultiEntity: true },
+  role: "owner",
+  privileges: ["finance", "hr", "auditCompliance", "admin"],
+  enabledModules: ["farm_management", "packhouse"],
+  readScopes: ["..."],
+  writeScopes: ["..."],
+  availableScopes: [
+    { authScopeId: "...", type: "company", name: "Acme Corp", parentId: null }
+  ],
+  resourceOverrides: { /* ... */ }
+}
+2. Security Pillars & Middleware
+Pure functions that enforce Row Level Security (RLS) and standardized data preparation without requiring direct database access.
+
+assertCanWrite(session, targetScopeId)
+
+buildRlsFilter(session)
+
+withSaveMiddleware(data)
+
+generateCanonicalId()
+
+3. Error Registry & Handling
+Standardized error tracking using Module (MOD), Category (CAT), and Action (ACT) constants.
+
+AppError class
+
+ErrorFactory
+
+4. Domain Enums
+The universal vocabulary of the AgriCore platform, ensuring type-safety across all microservices (e.g., UserRole, UserPrivilege, AccessLevel, FacilityType, NotificationMode, TaskStatus, RESOURCE_PATHS).
+
+🛠️ 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.
+
+Building Locally
+This project uses tsup for rapid, zero-config bundling into both CommonJS and ES Modules.
+
+Bash
+npm run build
+The "No-PIN" Publishing Workflow (NPM 2FA Workaround)
+Due to NPM's deprecation of CLI TOTP apps and Windows Security (Passkey) loop issues, publishing updates requires a Granular Access Token with 2FA Bypass.
+
+To publish a new version:
+
+Bump the "version" in package.json.
+
+Ensure you have your granular token in a local (git-ignored) .npmrc file:
+
+Ini, TOML
+//registry.npmjs.org/:_authToken=npm_YOUR_GRANULAR_TOKEN
+(Note: This token MUST be generated from the NPM website with the "Bypass Two-Factor Authentication" checkbox enabled for the @litusarchieve18 scope).
+
+Run the publish command:
+
+Bash
+npm publish --access public
+📝 Version History
+v1.0.2 — Breaking Change: Upgraded AgriCoreSession interface. Added companyConfig and UI-ready availableScopes arrays to support the frontend hierarchy dropdown without secondary API calls.
+
+v1.0.1 — Migrated package from private GitHub Registry to public NPM Registry for Base44/Deno compatibility. Removed baseUrl from tsconfig.json for NodeNext compatibility. Cleaned build artifacts from dependencies.
+
+v1.0.0 — Initial release. Core logging, error factory, and validation utilities.
+
+
+### Analyst Notes on the Process:
+This README captures the entire technical journey we just completed:
+1. It explains **how** to import the code into Base44 using the `npm:` prefix.
+2. It highlights the **Adapter pattern** and the **v2 Session Object** so future developers know *why* the data is shaped that way.
+3. Most importantly, it documents the exact **Publishing Workflow** and the **2FA bypas

package/dist/index.d.mts

@@ -1,4 +1,14 @@
 type PermissionLevel = 'WRITE' | 'READ' | 'NONE';
+type ScopeType = 'company' | 'legalEntity' | 'facility';
+interface AvailableScope {
+    authScopeId: string;
+    type: ScopeType;
+    name: string;
+    parentId: string | null;
+}
+interface CompanyConfig {
+    isMultiEntity: boolean;
+}
 /**
  * Deep map of scope IDs to resource paths and their permission levels.
  * Example: { "uuid-123": { "farm.records": "WRITE" } }
@@ -14,11 +24,13 @@ interface AgriCoreSession {
     userId: string;
     companyId: string;
     activeScopeId: string | null;
+    companyConfig: CompanyConfig;
     role: string;
     privileges: string[];
     enabledModules: string[];
     readScopes: string[];
     writeScopes: string[];
+    availableScopes: AvailableScope[];
     resourceOverrides: ResourceOverrides;
 }
 interface ResolvedError {
@@ -312,8 +324,7 @@ declare const TargetEntityType: {
     readonly FARM: "FARM";
     readonly ZONE: "ZONE";
     readonly BLOCK: "BLOCK";
-    readonly FUEL_SITE: "FUEL_SITE";
-    readonly WORKSHOP: "WORKSHOP";
+    readonly INFRASTRUCTURE: "INFRASTRUCTURE";
     readonly AUTO: "AUTO";
 };
 declare const AuditType: {
@@ -467,4 +478,4 @@ declare const RESOURCE_PATHS: {
     teamTraining: string;
 };
 
-export { ACT, AccessLevel, type AgriCoreSession, AgriLogger, AppError, ApprovalStatus, ApprovalType, AuditStatus, AuditType, type AuthScopeFields, CAT, Converter, CropCycleStatus, ERROR_DICTIONARY, EmitterType, EnabledModule, ErrorFactory, FORM_REGISTRY, FacilityType, type FormMeta, HarvestMethod, LinkedStatus, MOD, MODULE_LABELS, MicroclimateZone, MimeType, type ModCode, NettingType, NotificationMode, OrderStatus, type PermissionLevel, PhysicalState, PlantingMethod, RESOURCE_PATHS, RelationshipType, type ResolvedError, type ResourceOverrides, RowOrientation, SENTINEL_UUID, SoilTexture, TASK_TYPE_REGISTRY, type TabConfig, TargetEntityType, TaskStatus, TaskType, type TaskTypeConfig, TransactionType, TrellisType, UserPrivilege, UserRole, Validator, VigorRating, WaterSource, assertCanWrite, buildRlsFilter, canRead, canWrite, extractAppCode, generateCanonicalId, getAcceptedMimeTypes, getApproveAction, getFormMeta, getFormsGroupedByModule, getTaskTypeOptions, handleAppErrorResponse, isTabVisible, isTabWritable, resolveAccess, resolveAppError, resolveAuthScopeId, resolveError, resolveMenuVisibility, withAgriLogging, withSaveMiddleware };
+export { ACT, AccessLevel, type AgriCoreSession, AgriLogger, AppError, ApprovalStatus, ApprovalType, AuditStatus, AuditType, type AuthScopeFields, type AvailableScope, CAT, type CompanyConfig, Converter, CropCycleStatus, ERROR_DICTIONARY, EmitterType, EnabledModule, ErrorFactory, FORM_REGISTRY, FacilityType, type FormMeta, HarvestMethod, LinkedStatus, MOD, MODULE_LABELS, MicroclimateZone, MimeType, type ModCode, NettingType, NotificationMode, OrderStatus, type PermissionLevel, PhysicalState, PlantingMethod, RESOURCE_PATHS, RelationshipType, type ResolvedError, type ResourceOverrides, RowOrientation, SENTINEL_UUID, type ScopeType, SoilTexture, TASK_TYPE_REGISTRY, type TabConfig, TargetEntityType, TaskStatus, TaskType, type TaskTypeConfig, TransactionType, TrellisType, UserPrivilege, UserRole, Validator, VigorRating, WaterSource, assertCanWrite, buildRlsFilter, canRead, canWrite, extractAppCode, generateCanonicalId, getAcceptedMimeTypes, getApproveAction, getFormMeta, getFormsGroupedByModule, getTaskTypeOptions, handleAppErrorResponse, isTabVisible, isTabWritable, resolveAccess, resolveAppError, resolveAuthScopeId, resolveError, resolveMenuVisibility, withAgriLogging, withSaveMiddleware };

package/dist/index.d.ts

@@ -1,4 +1,14 @@
 type PermissionLevel = 'WRITE' | 'READ' | 'NONE';
+type ScopeType = 'company' | 'legalEntity' | 'facility';
+interface AvailableScope {
+    authScopeId: string;
+    type: ScopeType;
+    name: string;
+    parentId: string | null;
+}
+interface CompanyConfig {
+    isMultiEntity: boolean;
+}
 /**
  * Deep map of scope IDs to resource paths and their permission levels.
  * Example: { "uuid-123": { "farm.records": "WRITE" } }
@@ -14,11 +24,13 @@ interface AgriCoreSession {
     userId: string;
     companyId: string;
     activeScopeId: string | null;
+    companyConfig: CompanyConfig;
     role: string;
     privileges: string[];
     enabledModules: string[];
     readScopes: string[];
     writeScopes: string[];
+    availableScopes: AvailableScope[];
     resourceOverrides: ResourceOverrides;
 }
 interface ResolvedError {
@@ -312,8 +324,7 @@ declare const TargetEntityType: {
     readonly FARM: "FARM";
     readonly ZONE: "ZONE";
     readonly BLOCK: "BLOCK";
-    readonly FUEL_SITE: "FUEL_SITE";
-    readonly WORKSHOP: "WORKSHOP";
+    readonly INFRASTRUCTURE: "INFRASTRUCTURE";
     readonly AUTO: "AUTO";
 };
 declare const AuditType: {
@@ -467,4 +478,4 @@ declare const RESOURCE_PATHS: {
     teamTraining: string;
 };
 
-export { ACT, AccessLevel, type AgriCoreSession, AgriLogger, AppError, ApprovalStatus, ApprovalType, AuditStatus, AuditType, type AuthScopeFields, CAT, Converter, CropCycleStatus, ERROR_DICTIONARY, EmitterType, EnabledModule, ErrorFactory, FORM_REGISTRY, FacilityType, type FormMeta, HarvestMethod, LinkedStatus, MOD, MODULE_LABELS, MicroclimateZone, MimeType, type ModCode, NettingType, NotificationMode, OrderStatus, type PermissionLevel, PhysicalState, PlantingMethod, RESOURCE_PATHS, RelationshipType, type ResolvedError, type ResourceOverrides, RowOrientation, SENTINEL_UUID, SoilTexture, TASK_TYPE_REGISTRY, type TabConfig, TargetEntityType, TaskStatus, TaskType, type TaskTypeConfig, TransactionType, TrellisType, UserPrivilege, UserRole, Validator, VigorRating, WaterSource, assertCanWrite, buildRlsFilter, canRead, canWrite, extractAppCode, generateCanonicalId, getAcceptedMimeTypes, getApproveAction, getFormMeta, getFormsGroupedByModule, getTaskTypeOptions, handleAppErrorResponse, isTabVisible, isTabWritable, resolveAccess, resolveAppError, resolveAuthScopeId, resolveError, resolveMenuVisibility, withAgriLogging, withSaveMiddleware };
+export { ACT, AccessLevel, type AgriCoreSession, AgriLogger, AppError, ApprovalStatus, ApprovalType, AuditStatus, AuditType, type AuthScopeFields, type AvailableScope, CAT, type CompanyConfig, Converter, CropCycleStatus, ERROR_DICTIONARY, EmitterType, EnabledModule, ErrorFactory, FORM_REGISTRY, FacilityType, type FormMeta, HarvestMethod, LinkedStatus, MOD, MODULE_LABELS, MicroclimateZone, MimeType, type ModCode, NettingType, NotificationMode, OrderStatus, type PermissionLevel, PhysicalState, PlantingMethod, RESOURCE_PATHS, RelationshipType, type ResolvedError, type ResourceOverrides, RowOrientation, SENTINEL_UUID, type ScopeType, SoilTexture, TASK_TYPE_REGISTRY, type TabConfig, TargetEntityType, TaskStatus, TaskType, type TaskTypeConfig, TransactionType, TrellisType, UserPrivilege, UserRole, Validator, VigorRating, WaterSource, assertCanWrite, buildRlsFilter, canRead, canWrite, extractAppCode, generateCanonicalId, getAcceptedMimeTypes, getApproveAction, getFormMeta, getFormsGroupedByModule, getTaskTypeOptions, handleAppErrorResponse, isTabVisible, isTabWritable, resolveAccess, resolveAppError, resolveAuthScopeId, resolveError, resolveMenuVisibility, withAgriLogging, withSaveMiddleware };

package/dist/index.js

@@ -604,8 +604,7 @@ var TargetEntityType = {
   FARM: "FARM",
   ZONE: "ZONE",
   BLOCK: "BLOCK",
-  FUEL_SITE: "FUEL_SITE",
-  WORKSHOP: "WORKSHOP",
+  INFRASTRUCTURE: "INFRASTRUCTURE",
   AUTO: "AUTO"
 };
 var AuditType = {

package/dist/index.mjs

@@ -514,8 +514,7 @@ var TargetEntityType = {
   FARM: "FARM",
   ZONE: "ZONE",
   BLOCK: "BLOCK",
-  FUEL_SITE: "FUEL_SITE",
-  WORKSHOP: "WORKSHOP",
+  INFRASTRUCTURE: "INFRASTRUCTURE",
   AUTO: "AUTO"
 };
 var AuditType = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litusarchieve18/agricore-utils",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Canonical Backend Utility Library for AgriCore",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",