@litusarchieve18/agricore-utils 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,470 @@
+type PermissionLevel = 'WRITE' | 'READ' | 'NONE';
+/**
+ * Deep map of scope IDs to resource paths and their permission levels.
+ * Example: { "uuid-123": { "farm.records": "WRITE" } }
+ */
+interface ResourceOverrides {
+    [scopeId: string]: Record<string, PermissionLevel>;
+}
+/**
+ * The canonical Session object used throughout the AgriCore ecosystem.
+ * All backend logic and frontend components should rely on THIS shape.
+ */
+interface AgriCoreSession {
+    userId: string;
+    companyId: string;
+    activeScopeId: string | null;
+    role: string;
+    privileges: string[];
+    enabledModules: string[];
+    readScopes: string[];
+    writeScopes: string[];
+    resourceOverrides: ResourceOverrides;
+}
+interface ResolvedError {
+    title: string;
+    text: string;
+    module: string;
+    moduleLabel: string;
+    status: number;
+    catAct: string;
+    isSubscriptionIssue: boolean;
+    isPermissionIssue: boolean;
+}
+interface AuthScopeFields {
+    facilityId?: string;
+    legalEntityId?: string;
+    companyId?: string;
+}
+interface TabConfig {
+    resourceId?: string;
+    allowedRoles?: string[];
+    requiredPrivileges?: string[];
+}
+interface FormMeta {
+    label: string;
+    menuUrl: string;
+    module: string;
+}
+interface TaskTypeConfig {
+    label: string;
+    targetEntity: string;
+    description: string;
+    mimeTypes: string[];
+    icon: string;
+    approveAction: string;
+}
+
+declare const AgriLogger: {
+    log(level: "INFO" | "WARN" | "ERROR", message: string, meta: any): void;
+};
+/**
+ * Automatically logs the start, end, duration, and errors of a function.
+ */
+declare function withAgriLogging<T extends (...args: any[]) => Promise<any>>(fn: T, functionName: string, session?: AgriCoreSession): T;
+
+declare const Validator: {
+    /** * 1. Email: The classic. Uses a standard RFC 5322 regex.
+     */
+    isEmail: (val: string) => boolean;
+    /** * 2. UUID v4: Critical for your canonicalId and authScopeId checks.
+     */
+    isUUID: (value: string | null | undefined) => boolean;
+    /** * 3. ISO Date String: Ensures dates are stored in UTC/ISO format.
+     */
+    isIsoDate: (val: string) => boolean;
+    isPositiveNumber: (value: number | null | undefined) => boolean;
+    /** * 4. Strong Password: Min 8 chars, 1 uppercase, 1 lowercase, 1 number, 1 special char.
+     */
+    isStrongPassword: (val: string) => boolean;
+    /** * 5. Phone Number (E.164): The international standard (e.g., +61400123456).
+     */
+    isE164Phone: (val: string) => boolean;
+    /** * 6. Range Checker: Useful for temperature sensors or quantity limits.
+     */
+    isInRange: (val: number, min: number, max: number) => boolean;
+    /** * 7. URL: Basic validation for external documentation links.
+     */
+    isValidUrl: (val: string) => boolean;
+    /** * 8. Slug: Useful for URL-friendly names (e.g. "sunset-farm-01").
+     */
+    isSlug: (val: string) => boolean;
+    isNotEmpty: (value: string | null | undefined) => boolean;
+    /** * 9. Is Non-Empty Array: Ensures you don't save an empty list of IDs.
+     */
+    hasItems: (val: any) => boolean;
+    /** * 10. Coordinates: Validate GPS Latitude/Longitude for Farm maps.
+     */
+    isValidCoordinate: (lat: number, lng: number) => boolean;
+};
+
+declare const Converter: {
+    /**
+     * Hectares to Acres
+     * Formula: $Acres = Hectares \times 2.47105$
+     */
+    haToAcre: (ha: number, precision?: number) => number;
+    /**
+     * Acres to Hectares
+     * Formula: $Hectares = Acres \div 2.47105$
+     */
+    acreToHa: (acre: number, precision?: number) => number;
+    /**
+     * Liters to US Gallons
+     * Formula: $Gallons = Liters \times 0.264172$
+     */
+    literToGal: (liters: number, precision?: number) => number;
+    /**
+     * US Gallons to Liters
+     * Formula: $Liters = Gallons \div 0.264172$
+     */
+    galToLiter: (gal: number, precision?: number) => number;
+    /**
+     * Kilograms to Pounds (useful for yield/harvest data)
+     */
+    kgToLbs: (kg: number, precision?: number) => number;
+};
+
+declare const MOD: {
+    readonly OPERATIONS: "OPR";
+    readonly EQUIPMENT: "EQP";
+    readonly PACKHOUSE: "PCK";
+    readonly FARM: "FRM";
+    readonly SAFETY: "SAF";
+    readonly TEAM_HR: "THR";
+    readonly RECORDS: "REC";
+    readonly ADMIN: "ADM";
+    readonly DOCUMENTS: "DOC";
+    readonly ALERTS: "ALT";
+    readonly INFRA: "INF";
+    readonly SESSION: "SES";
+};
+type ModCode = typeof MOD[keyof typeof MOD];
+declare const CAT: {
+    readonly SUBSCRIPTION: "1";
+    readonly PERMISSION: "2";
+    readonly VALIDATION: "3";
+    readonly INTEGRITY: "4";
+};
+declare const ACT: {
+    readonly GENERIC: "00";
+    readonly VIEW: "01";
+    readonly CREATE: "02";
+    readonly EDIT: "03";
+    readonly DELETE: "04";
+    readonly UPLOAD: "05";
+};
+declare const SENTINEL_UUID = "00000000-0000-0000-0000-000000000000";
+declare class AppError extends Error {
+    status: number;
+    appCode: string;
+    isOperational: boolean;
+    constructor(status: number, mod: string, cat: string, act: string, message: string);
+}
+declare const ErrorFactory: {
+    unauthorized: (mod: string, msg?: string) => AppError;
+    forbidden: (mod: string, act: string, msg?: string) => AppError;
+    badRequest: (mod: string, act: string, msg?: string) => AppError;
+    notFound: (mod: string, act?: "00", msg?: string) => AppError;
+    conflict: (mod: string, act: string, msg?: string) => AppError;
+    integrity: (mod: string, act?: "00", msg?: string) => AppError;
+    subscription: (mod: string, msg?: string) => AppError;
+    internal: (mod: string, msg?: string) => AppError;
+};
+declare const handleAppErrorResponse: (error: unknown, mod?: string) => Response;
+declare const MODULE_LABELS: Record<string, string>;
+declare const ERROR_DICTIONARY: Record<string, {
+    title: string;
+    text: string;
+}>;
+declare const resolveAppError: (appCode: string) => ResolvedError;
+declare const extractAppCode: (error: unknown) => string | null;
+declare const resolveError: (error: unknown) => ResolvedError;
+declare function generateCanonicalId(): string;
+/**
+ * Resolves authScopeId using the standard priority chain:
+ *   facilityId → legalEntityId → companyId → SENTINEL_UUID
+ *
+ * This matches the documented rule:
+ *   "Set to facilityId if available, else legalEntityId, else companyId."
+ */
+declare function resolveAuthScopeId(fields?: AuthScopeFields): string;
+declare function withSaveMiddleware<T extends Record<string, any>>(data: T): T & {
+    canonicalId: any;
+    authScopeId: any;
+};
+declare function buildRlsFilter(session: AgriCoreSession, extra?: Record<string, any>): {
+    authScopeId: {
+        $in: string[];
+    };
+};
+declare function canRead(session: AgriCoreSession, authScopeId: string): boolean;
+declare function canWrite(session: AgriCoreSession, authScopeId: string, resourcePath: string): boolean;
+/**
+ * Hard-throws if the user cannot write.
+ * Use this on the backend (inside Deno functions) to enforce server-side.
+ */
+declare function assertCanWrite(session: AgriCoreSession, authScopeId: string, resourcePath: string): void;
+/**
+ * Full resolution: DB override → static config fallback → public default.
+ * Returns 'NONE' | 'READ' | 'WRITE'.
+ */
+declare function resolveAccess(session: AgriCoreSession, activeScopeId: string, tabConfig: TabConfig): 'NONE' | 'READ' | 'WRITE';
+declare function resolveMenuVisibility(session: AgriCoreSession, authScopeId: string, resourcePath: string): 'hidden' | 'read_only' | 'active';
+declare function isTabVisible(session: AgriCoreSession, activeScopeId: string, tabConfig: TabConfig): boolean;
+declare function isTabWritable(session: AgriCoreSession, activeScopeId: string, tabConfig: TabConfig): boolean;
+declare const UserRole: {
+    readonly OWNER: "owner";
+    readonly MANAGER: "manager";
+    readonly SUPERVISOR: "supervisor";
+    readonly LEADING_HAND: "leadingHand";
+    readonly WORKER: "worker";
+};
+declare const UserPrivilege: {
+    readonly FINANCE: "finance";
+    readonly HR: "hr";
+    readonly MECHANIC: "mechanic";
+    readonly AUDIT_COMPLIANCE: "auditCompliance";
+    readonly ADMIN: "admin";
+};
+declare const AccessLevel: {
+    readonly NONE: "NONE";
+    readonly READ: "READ";
+    readonly WRITE: "WRITE";
+};
+declare const EnabledModule: {
+    readonly FARM_MANAGEMENT: "farm_management";
+    readonly PACKHOUSE: "packhouse";
+    readonly ACCOMMODATION: "accommodation";
+};
+declare const FacilityType: {
+    readonly FARM: "farm";
+    readonly PACKHOUSE: "packhouse";
+    readonly ACCOMMODATION: "accommodation";
+};
+declare const LinkedStatus: {
+    readonly NOT_LINKED: "not_linked";
+    readonly PENDING_LINK: "pending_link";
+    readonly LINKED: "linked";
+};
+declare const RelationshipType: {
+    readonly SUPPLIER: "supplier";
+    readonly CUSTOMER: "customer";
+    readonly BOTH: "both";
+};
+declare const ApprovalType: {
+    readonly ROLE: "role";
+    readonly PRIVILEGE: "privilege";
+    readonly SPECIFIC_USERS: "specific_users";
+};
+declare const TransactionType: {
+    readonly PURCHASE_ORDER: "purchase_order";
+    readonly SALES_ORDER: "sales_order";
+    readonly REPAIR: "repair";
+    readonly FUEL: "fuel";
+    readonly OTHER: "other";
+};
+declare const ApprovalStatus: {
+    readonly PENDING: "pending";
+    readonly APPROVED: "approved";
+    readonly REJECTED: "rejected";
+};
+declare const OrderStatus: {
+    readonly DRAFT: "draft";
+    readonly PENDING_FINANCE: "pending_finance";
+    readonly NEW: "new";
+    readonly ACKNOWLEDGED: "acknowledged";
+    readonly IN_PROGRESS: "in_progress";
+    readonly SHIPPED: "shipped";
+    readonly RECEIVED: "received";
+    readonly CANCELLED: "cancelled";
+};
+declare const NotificationMode: {
+    readonly INTERNAL: "internal";
+    readonly EXTERNAL_EMAIL: "external_email";
+    readonly NONE: "none";
+};
+declare const TaskType: {
+    readonly KML_PARSE: "KML_PARSE";
+    readonly INVOICE_OCR: "INVOICE_OCR";
+    readonly AUDIT_UPLOAD: "AUDIT_UPLOAD";
+    readonly REPORT_GEN: "REPORT_GEN";
+};
+declare const TaskStatus: {
+    readonly PENDING: "PENDING";
+    readonly PROCESSING: "PROCESSING";
+    readonly COMPLETED: "COMPLETED";
+    readonly FAILED: "FAILED";
+    readonly AWAITING_REVIEW: "AWAITING_REVIEW";
+    readonly VERIFIED: "VERIFIED";
+    readonly REJECTED: "REJECTED";
+};
+declare const MimeType: {
+    readonly KML: "application/vnd.google-earth.kml+xml";
+    readonly KMZ: "application/vnd.google-earth.kmz";
+    readonly PDF: "application/pdf";
+    readonly XLSX: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+    readonly XLS: "application/vnd.ms-excel";
+    readonly JPEG: "image/jpeg";
+    readonly PNG: "image/png";
+};
+declare const TargetEntityType: {
+    readonly FARM: "FARM";
+    readonly ZONE: "ZONE";
+    readonly BLOCK: "BLOCK";
+    readonly FUEL_SITE: "FUEL_SITE";
+    readonly WORKSHOP: "WORKSHOP";
+    readonly AUTO: "AUTO";
+};
+declare const AuditType: {
+    readonly FRESHCARE: "Freshcare";
+    readonly HACCP: "HACCP";
+    readonly WHS: "WHS";
+    readonly CUSTOM: "Custom";
+};
+declare const AuditStatus: {
+    readonly DRAFT: "DRAFT";
+    readonly IN_REVIEW: "IN_REVIEW";
+    readonly FINALIZED: "FINALIZED";
+};
+declare const SoilTexture: {
+    readonly SAND: "SAND";
+    readonly LOAMY_SAND: "LOAMY_SAND";
+    readonly SANDY_LOAM: "SANDY_LOAM";
+    readonly LOAM: "LOAM";
+    readonly SILT_LOAM: "SILT_LOAM";
+    readonly SILT: "SILT";
+    readonly SANDY_CLAY_LOAM: "SANDY_CLAY_LOAM";
+    readonly CLAY_LOAM: "CLAY_LOAM";
+    readonly SILTY_CLAY_LOAM: "SILTY_CLAY_LOAM";
+    readonly SANDY_CLAY: "SANDY_CLAY";
+    readonly SILTY_CLAY: "SILTY_CLAY";
+    readonly CLAY: "CLAY";
+};
+declare const MicroclimateZone: {
+    readonly STANDARD: "STANDARD";
+    readonly FROST_POCKET: "FROST_POCKET";
+    readonly WIND_CORRIDOR: "WIND_CORRIDOR";
+    readonly EXPOSED_RIDGE: "EXPOSED_RIDGE";
+    readonly HEAT_TRAP: "HEAT_TRAP";
+    readonly RIPARIAN: "RIPARIAN";
+};
+declare const PlantingMethod: {
+    readonly SQUARE: "SQUARE";
+    readonly RECTANGULAR: "RECTANGULAR";
+    readonly HEXAGONAL: "HEXAGONAL";
+    readonly QUINCUNX: "QUINCUNX";
+    readonly CONTOUR: "CONTOUR";
+};
+declare const RowOrientation: {
+    readonly NORTH_SOUTH: "NORTH_SOUTH";
+    readonly EAST_WEST: "EAST_WEST";
+    readonly NORTHEAST_SOUTHWEST: "NORTHEAST_SOUTHWEST";
+    readonly NORTHWEST_SOUTHEAST: "NORTHWEST_SOUTHEAST";
+};
+declare const EmitterType: {
+    readonly SURFACE_DRIP: "SURFACE_DRIP";
+    readonly SUBSURFACE_DRIP: "SUBSURFACE_DRIP";
+    readonly MICRO_SPRINKLER: "MICRO_SPRINKLER";
+    readonly JET_SPRAY: "JET_SPRAY";
+    readonly INLINE_DRIPPER: "INLINE_DRIPPER";
+    readonly PRESSURE_COMPENSATED: "PRESSURE_COMPENSATED";
+};
+declare const TrellisType: {
+    readonly NONE: "NONE";
+    readonly VERTICAL_AXIS: "VERTICAL_AXIS";
+    readonly TWO_D_PLANE: "2D_PLANE";
+    readonly V_TRELLIS: "V_TRELLIS";
+    readonly T_BAR: "T_BAR";
+    readonly PERGOLA: "PERGOLA";
+    readonly Y_TRELLIS: "Y_TRELLIS";
+};
+declare const NettingType: {
+    readonly NONE: "NONE";
+    readonly OVERHEAD_HAIL: "OVERHEAD_HAIL";
+    readonly SIDE_BIRD: "SIDE_BIRD";
+    readonly FULL_EXCLUSION: "FULL_EXCLUSION";
+    readonly SHADE_30: "SHADE_30";
+    readonly SHADE_50: "SHADE_50";
+    readonly CROSS_OVER: "CROSS_OVER";
+};
+declare const HarvestMethod: {
+    readonly HAND: "HAND";
+    readonly MACHINE: "MACHINE";
+};
+declare const VigorRating: {
+    readonly VERY_LOW: "VERY_LOW";
+    readonly LOW: "LOW";
+    readonly MODERATE: "MODERATE";
+    readonly HIGH: "HIGH";
+    readonly VERY_HIGH: "VERY_HIGH";
+};
+declare const CropCycleStatus: {
+    readonly NEW: "NEW";
+    readonly CONFIRMED: "CONFIRMED";
+    readonly ACTIVE: "ACTIVE";
+    readonly COMPLETED: "COMPLETED";
+};
+declare const WaterSource: {
+    readonly BORE_WELL: "BORE_WELL";
+    readonly RIVER_STREAM: "RIVER_STREAM";
+    readonly ON_FARM_DAM: "ON_FARM_DAM";
+    readonly IRRIGATION_SCHEME: "IRRIGATION_SCHEME";
+    readonly MUNICIPAL: "MUNICIPAL";
+    readonly RECLAIMED_WASTE: "RECLAIMED_WASTE";
+    readonly RAINWATER: "RAINWATER";
+};
+declare const PhysicalState: {
+    readonly LIQUID: "LIQUID";
+    readonly GAS: "GAS";
+};
+declare const FORM_REGISTRY: Record<string, FormMeta>;
+declare function getFormMeta(componentId: string): FormMeta | null;
+declare function getFormsGroupedByModule(): Record<string, Array<{
+    id: string;
+} & FormMeta>>;
+declare const TASK_TYPE_REGISTRY: Record<string, TaskTypeConfig>;
+declare const getTaskTypeOptions: () => {
+    value: string;
+    label: string;
+    description: string;
+    mimeTypes: string[];
+    icon: string;
+}[];
+declare const getAcceptedMimeTypes: (taskType: string) => string;
+declare const getApproveAction: (taskType: string) => string | null;
+declare const RESOURCE_PATHS: {
+    dashboard: string;
+    operations: string;
+    equipment: string;
+    safety: string;
+    team: string;
+    records: string;
+    adminSettings: string;
+    documentHub: string;
+    documentHubTemplates: string;
+    documentHubFolder: string;
+    documentHubExtraction: string;
+    documentHubQueue: string;
+    analytics: string;
+    adminUserRoster: string;
+    adminRolesPermissions: string;
+    adminBlueprintsSites: string;
+    adminCompanySettings: string;
+    farmManagement: string;
+    packhouse: string;
+    accommodation: string;
+    equipPreStart: string;
+    equipMaintenance: string;
+    equipFuelRegister: string;
+    equipCalibration: string;
+    equipFleet: string;
+    safetyAuditing: string;
+    safetyFood: string;
+    safetyWhs: string;
+    safetyCleaning: string;
+    teamStaff: string;
+    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 };