@reekon-tools/boldr-utils 1.20.3 → 1.21.1

package/dist/exports.d.ts

@@ -1,4 +1,4 @@
-export { evaluateFormula, createFormulaScope, createEnhancedFormulaScope, clearFormulaCache, type EnhancedMapping, type FormulaDefinition, type FormulaEvaluationOptions, } from './formulas/evaluateFormula.js';
+export { evaluateFormula, createFormulaScope, createEnhancedFormulaScope, clearFormulaCache, micrometersToUnitNumber, type EnhancedMapping, type FormulaDefinition, type FormulaEvaluationOptions, } from './formulas/evaluateFormula.js';
 export { calculateFormula } from './formulas/calculateFormula.js';
 export { convertMicrometers } from './utils/micrometersToUnit.js';
 export { parseMeasurement } from './utils/parseMeasurement.js';
@@ -9,6 +9,7 @@ export * from './types/annotation.js';
 export { getToleranceColor, calculateDeviationPercentage, isWithinTolerance, generateToleranceGradient, createDefaultToleranceThresholds, DEFAULT_TOLERANCE_COLORS, type ToleranceThreshold, type ToleranceConfig, } from './utils/tolerance.js';
 export { GeneralColors, SecondaryColors, FormColors, TileColors, FormulaColors, YellowColors, RedColors, GreenColors, tailwindColors, } from './theme/colors.js';
 export { DEFAULT_GROUP_INDEX, isDefaultGroup, findDefaultGroup, isFormGroupCompleted, } from './utils/groups.js';
+export { ROLE_RANK, EMPTY_GRANTS, normalizeRole, roleAtLeast, effectiveRole, canView, canEdit, canManage, canManageOrg, isGuest, groupGrants, resolveAccess, type MaybeRole, type GroupedGrants, type ResolvedAccess, } from './utils/permissions.js';
 export { ALL_EXPORT_CATEGORIES, ALL_EXPORT_MEASUREMENT_DATA_FIELDS, ALL_EXPORT_OBJECT_TYPES, DEFAULT_EXPORT_CONFIG, EXPORT_EVERYTHING_CONFIG, normalizeExportConfig, type ExportCategory, type ExportConfig, type ExportImageFormat, type ExportMeasurementDataField, type ExportMeasurementFilter, type ExportObjectType, } from './export/config.js';
 export { classifyFileForExport } from './export/objectKinds.js';
 export { buildJobCsv, escapeCSVField, hyperlinkCell, type BuildJobCsvInput, type ExportObjectRow, type ExportScope, } from './export/buildJobCsv.js';

package/dist/exports.js

@@ -2,7 +2,7 @@
 // platform-specific `AnnotationCanvas` wrapper lives here. The two index
 // files (index.ts, index.native.ts) re-export from this and add their own
 // AnnotationCanvas import.
-export { evaluateFormula, createFormulaScope, createEnhancedFormulaScope, clearFormulaCache, } from './formulas/evaluateFormula.js';
+export { evaluateFormula, createFormulaScope, createEnhancedFormulaScope, clearFormulaCache, micrometersToUnitNumber, } from './formulas/evaluateFormula.js';
 export { calculateFormula } from './formulas/calculateFormula.js';
 export { convertMicrometers } from './utils/micrometersToUnit.js';
 export { parseMeasurement } from './utils/parseMeasurement.js';
@@ -14,6 +14,9 @@ export { getToleranceColor, calculateDeviationPercentage, isWithinTolerance, gen
 // Shared color palette (canonical source for both apps' brand colors).
 export { GeneralColors, SecondaryColors, FormColors, TileColors, FormulaColors, YellowColors, RedColors, GreenColors, tailwindColors, } from './theme/colors.js';
 export { DEFAULT_GROUP_INDEX, isDefaultGroup, findDefaultGroup, isFormGroupCompleted, } from './utils/groups.js';
+// Three-level access (organization → project → job) role arithmetic. Keep in
+// step with rock-pro-backend/firestore.rules.
+export { ROLE_RANK, EMPTY_GRANTS, normalizeRole, roleAtLeast, effectiveRole, canView, canEdit, canManage, canManageOrg, isGuest, groupGrants, resolveAccess, } from './utils/permissions.js';
 // Configurable job CSV export, shared by rock-pro-app and rock-desktop so
 // both platforms emit identical files.
 export { ALL_EXPORT_CATEGORIES, ALL_EXPORT_MEASUREMENT_DATA_FIELDS, ALL_EXPORT_OBJECT_TYPES, DEFAULT_EXPORT_CONFIG, EXPORT_EVERYTHING_CONFIG, normalizeExportConfig, } from './export/config.js';

package/dist/formulas/calculateFormula.d.ts

@@ -1,2 +1,2 @@
 import { ColumnConfig, DecimalTolerance, FractionalTolerance, Formula, Measurement, Units } from '../types/firestore.js';
-export declare const calculateFormula: (formula: Formula, formulas: Formula[], columns: Record<string, string>, tableConfig: ColumnConfig[], measurements: Measurement[], unit: Units, fractionalTolerance: FractionalTolerance, decimalTolerance: DecimalTolerance) => string | number | null;
+export declare const calculateFormula: (formula: Formula, formulas: Formula[], columns: Record<string, string>, tableConfig: ColumnConfig[], measurements: Measurement[], unit: Units, _fractionalTolerance?: FractionalTolerance, _decimalTolerance?: DecimalTolerance) => string | number | null;

package/dist/formulas/calculateFormula.js

@@ -1,25 +1,9 @@
 import { ColumnType, } from '../types/firestore.js';
-import { evaluateFormula } from './evaluateFormula.js';
-import { convertMicrometers } from '../utils/micrometersToUnit.js';
-function parseMixedNumber(str) {
-    const parts = str.trim().split(' ');
-    let whole = 0;
-    let fraction = 0;
-    if (parts.length === 2) {
-        whole = parseFloat(parts[0]);
-        const [num, den] = parts[1].split('/').map(Number);
-        fraction = num / den;
-    }
-    else if (parts[0].includes('/')) {
-        const [num, den] = parts[0].split('/').map(Number);
-        fraction = num / den;
-    }
-    else {
-        whole = parseFloat(parts[0]);
-    }
-    return whole + fraction;
-}
-export const calculateFormula = (formula, formulas, columns, tableConfig, measurements, unit, fractionalTolerance, decimalTolerance) => {
+import { evaluateFormula, micrometersToUnitNumber, } from './evaluateFormula.js';
+export const calculateFormula = (formula, formulas, columns, tableConfig, measurements, unit, 
+// Unused since measurement values stopped round-tripping through the display
+// string — kept so the 8-arg call sites in the apps don't break.
+_fractionalTolerance, _decimalTolerance) => {
     // Convert Firestore Map to plain object if necessary
     let variableToColumnMap = {};
     if (formula.variableToColumnMap) {
@@ -45,8 +29,11 @@ export const calculateFormula = (formula, formulas, columns, tableConfig, measur
             const measurement = measurements.find((m) => m.id === measurementId);
             if (!measurement)
                 continue;
-            const { value, unit: displayUnit } = convertMicrometers(measurement.value, unit, fractionalTolerance, decimalTolerance);
-            valueMap[columnId] = parseMixedNumber(value);
+            // Straight um -> display-unit number. The old path rendered the display
+            // STRING (convertMicrometers) and re-parsed it, which rounded the value
+            // to the display tolerance and returned NaN / dropped the inches for the
+            // composite feet-inches formats (`5' 3 1/2"`).
+            valueMap[columnId] = micrometersToUnitNumber(measurement.value, unit);
         }
         else if (column.type === ColumnType.Angle) {
             const measurement = measurements.find((m) => m.id === measurementId);

package/dist/formulas/evaluateFormula.d.ts

@@ -17,6 +17,16 @@ export interface FormulaEvaluationOptions {
     formulas?: FormulaDefinition[];
     scope?: Record<string, number>;
 }
+export declare function normalizeUnitForMathJS(unit: Units | string): string;
+/**
+ * Convert a stored micrometer value to the number the formula scope expects
+ * for `unit` — the same conversion nested-formula results go through. This is
+ * the ONLY sanctioned way to put a measurement into a valueMap: converting via
+ * the display STRING (convertMicrometers + a string parser) both rounds the
+ * value to the display tolerance and falls apart on composite formats like
+ * `5' 3 1/2"`.
+ */
+export declare function micrometersToUnitNumber(micrometers: number, unit: Units): number;
 export declare function evaluateFormula({ expression, mappings, valueMap, unit, formulas, scope, }: FormulaEvaluationOptions): number | string | null;
 export declare function createFormulaScope({ mappings, valueMap, unit, }: {
     mappings: Record<string, string>;

package/dist/formulas/evaluateFormula.js

@@ -7,7 +7,7 @@ const compile = math.compile.bind(math);
 const mathUnit = math.unit.bind(math);
 // Cache for evaluated formulas to improve performance
 const formulaCache = new Map();
-function normalizeUnitForMathJS(unit) {
+export function normalizeUnitForMathJS(unit) {
     switch (unit) {
         case Units.Centimeters:
         case 'cm':
@@ -30,6 +30,17 @@ function normalizeUnitForMathJS(unit) {
             return 'mm'; // fallback
     }
 }
+/**
+ * Convert a stored micrometer value to the number the formula scope expects
+ * for `unit` — the same conversion nested-formula results go through. This is
+ * the ONLY sanctioned way to put a measurement into a valueMap: converting via
+ * the display STRING (convertMicrometers + a string parser) both rounds the
+ * value to the display tolerance and falls apart on composite formats like
+ * `5' 3 1/2"`.
+ */
+export function micrometersToUnitNumber(micrometers, unit) {
+    return mathUnit(micrometers, 'um').toNumber(normalizeUnitForMathJS(unit));
+}
 // Normalize mapping to EnhancedMapping format
 function normalizeMapping(mapping) {
     if (typeof mapping === 'string') {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export * from './exports.js';
-export { evaluateFormula, createFormulaScope, createEnhancedFormulaScope, clearFormulaCache, type EnhancedMapping, type FormulaDefinition, type FormulaEvaluationOptions, } from './formulas/evaluateFormula.js';
+export { evaluateFormula, createFormulaScope, createEnhancedFormulaScope, clearFormulaCache, micrometersToUnitNumber, type EnhancedMapping, type FormulaDefinition, type FormulaEvaluationOptions, } from './formulas/evaluateFormula.js';
 export { calculateFormula } from './formulas/calculateFormula.js';
 export { convertMicrometers } from './utils/micrometersToUnit.js';
 export { parseMeasurement } from './utils/parseMeasurement.js';

package/dist/index.js

@@ -3,7 +3,7 @@
 // WithSkiaWeb. Metro/RN consumers resolve `index.native.ts` instead via
 // the `react-native` condition in package.json `exports`.
 export * from './exports.js';
-export { evaluateFormula, createFormulaScope, createEnhancedFormulaScope, clearFormulaCache, } from './formulas/evaluateFormula.js';
+export { evaluateFormula, createFormulaScope, createEnhancedFormulaScope, clearFormulaCache, micrometersToUnitNumber, } from './formulas/evaluateFormula.js';
 export { calculateFormula } from './formulas/calculateFormula.js';
 export { convertMicrometers } from './utils/micrometersToUnit.js';
 export { parseMeasurement } from './utils/parseMeasurement.js';

package/dist/server.d.ts

@@ -1,4 +1,4 @@
-export { evaluateFormula, createFormulaScope, createEnhancedFormulaScope, clearFormulaCache, type EnhancedMapping, type FormulaDefinition, type FormulaEvaluationOptions, } from './formulas/evaluateFormula.js';
+export { evaluateFormula, createFormulaScope, createEnhancedFormulaScope, clearFormulaCache, micrometersToUnitNumber, type EnhancedMapping, type FormulaDefinition, type FormulaEvaluationOptions, } from './formulas/evaluateFormula.js';
 export { calculateFormula } from './formulas/calculateFormula.js';
 export { convertMicrometers } from './utils/micrometersToUnit.js';
 export { parseMeasurement } from './utils/parseMeasurement.js';
@@ -7,6 +7,7 @@ export * from './types/layout.js';
 export * from './types/annotation.js';
 export { getToleranceColor, getToleranceSecondaryColor, calculateDeviationPercentage, isWithinTolerance, generateToleranceGradient, createDefaultToleranceThresholds, DEFAULT_TOLERANCE_COLORS, DEFAULT_TOLERANCE_SECONDARY_COLORS, type ToleranceThreshold, type ToleranceConfig, } from './utils/tolerance.js';
 export { DEFAULT_GROUP_INDEX, isDefaultGroup, findDefaultGroup, isFormGroupCompleted, } from './utils/groups.js';
+export { ROLE_RANK, EMPTY_GRANTS, normalizeRole, roleAtLeast, effectiveRole, canView, canEdit, canManage, canManageOrg, isGuest, groupGrants, resolveAccess, type MaybeRole, type GroupedGrants, type ResolvedAccess, } from './utils/permissions.js';
 export { ALL_EXPORT_CATEGORIES, ALL_EXPORT_MEASUREMENT_DATA_FIELDS, ALL_EXPORT_OBJECT_TYPES, DEFAULT_EXPORT_CONFIG, EXPORT_EVERYTHING_CONFIG, normalizeExportConfig, type ExportCategory, type ExportConfig, type ExportImageFormat, type ExportMeasurementDataField, type ExportMeasurementFilter, type ExportObjectType, } from './export/config.js';
 export { classifyFileForExport } from './export/objectKinds.js';
 export { buildJobCsv, escapeCSVField, hyperlinkCell, type BuildJobCsvInput, type ExportObjectRow, type ExportScope, } from './export/buildJobCsv.js';

package/dist/server.js

@@ -3,7 +3,7 @@
 // root barrel, whose module graph statically pulls in `react` and
 // `@shopify/react-native-skia`. Only modules with no React/Skia anywhere
 // in their import graph may be re-exported from this file.
-export { evaluateFormula, createFormulaScope, createEnhancedFormulaScope, clearFormulaCache, } from './formulas/evaluateFormula.js';
+export { evaluateFormula, createFormulaScope, createEnhancedFormulaScope, clearFormulaCache, micrometersToUnitNumber, } from './formulas/evaluateFormula.js';
 export { calculateFormula } from './formulas/calculateFormula.js';
 export { convertMicrometers } from './utils/micrometersToUnit.js';
 export { parseMeasurement } from './utils/parseMeasurement.js';
@@ -12,6 +12,7 @@ export * from './types/layout.js';
 export * from './types/annotation.js';
 export { getToleranceColor, getToleranceSecondaryColor, calculateDeviationPercentage, isWithinTolerance, generateToleranceGradient, createDefaultToleranceThresholds, DEFAULT_TOLERANCE_COLORS, DEFAULT_TOLERANCE_SECONDARY_COLORS, } from './utils/tolerance.js';
 export { DEFAULT_GROUP_INDEX, isDefaultGroup, findDefaultGroup, isFormGroupCompleted, } from './utils/groups.js';
+export { ROLE_RANK, EMPTY_GRANTS, normalizeRole, roleAtLeast, effectiveRole, canView, canEdit, canManage, canManageOrg, isGuest, groupGrants, resolveAccess, } from './utils/permissions.js';
 export { ALL_EXPORT_CATEGORIES, ALL_EXPORT_MEASUREMENT_DATA_FIELDS, ALL_EXPORT_OBJECT_TYPES, DEFAULT_EXPORT_CONFIG, EXPORT_EVERYTHING_CONFIG, normalizeExportConfig, } from './export/config.js';
 export { classifyFileForExport } from './export/objectKinds.js';
 export { buildJobCsv, escapeCSVField, hyperlinkCell, } from './export/buildJobCsv.js';

package/dist/types/firestore.d.ts

@@ -21,7 +21,60 @@ export declare enum OrganizationRole {
     Admin = "admin",
     Full = "member",
     Contributor = "contributor",
-    Viewer = "viewer"
+    Viewer = "viewer",
+    /**
+     * Synthetic org membership for users invited to a single project or job.
+     * Grants read of the org doc and its supporting library (templates, labels,
+     * formulas, miter variants, print logos) and nothing under `projects/`.
+     * Server-written only; never offered in an org role picker. The same word
+     * is used for the project-level marker an `AccessGrant` carries when a user
+     * has job access but no project access — "may read this container's doc,
+     * nothing inside it".
+     */
+    Guest = "guest"
+}
+/** Roles an org admin may assign in Team settings. Excludes Guest. */
+export declare const ASSIGNABLE_ORG_ROLES: readonly OrganizationRole[];
+/**
+ * Roles grantable on a single project or job. Same wire values as the org
+ * roles minus Admin (admin is org management, not data access).
+ */
+export type ScopedRole = OrganizationRole.Full | OrganizationRole.Contributor | OrganizationRole.Viewer;
+export declare const SCOPED_ROLES: readonly ScopedRole[];
+/**
+ * What the sharing UIs offer. Contributor is deliberately absent (Figma
+ * 1028-47443 / 746-37130 show Full and Viewer); add it here to enable it —
+ * rules and types already accept it.
+ */
+export declare const ACCESS_ROLE_OPTIONS: readonly {
+    label: string;
+    value: ScopedRole;
+}[];
+/** Role stored on an `AccessGrant`: a scoped role, or the project-level guest marker. */
+export type AccessRole = ScopedRole | OrganizationRole.Guest;
+export type AccessScope = 'project' | 'job';
+/**
+ * A per-user grant on a project or a job. Lives at
+ *   organizations/{orgId}/projects/{projectId}/access/{uid}            (scope 'project')
+ *   organizations/{orgId}/projects/{projectId}/jobs/{jobId}/access/{uid} (scope 'job')
+ * Doc id == uid. Written only by Cloud Functions. Discovered by the client
+ * with `collectionGroup('access').where('userId', '==', uid)`.
+ */
+export interface AccessGrant extends FirestoreDoc {
+    userId: string;
+    organizationId: string;
+    projectId: string;
+    jobId?: string;
+    scope: AccessScope;
+    role: AccessRole;
+    email: string;
+    firstName: string;
+    lastName: string;
+    grantedBy: {
+        userId: string;
+        email: string;
+    };
+    grantedAt: Date;
 }
 export declare enum InvitationStatus {
     Pending = "pending",
@@ -49,6 +102,16 @@ export interface Invitation extends FirestoreDoc, Timestamps {
     organizationId: string;
     role: OrganizationRole;
     status: InvitationStatus;
+    /**
+     * Present on project/job invites (`kind === 'access'`); absent on org
+     * invites. `projectName` / `jobName` are denormalized for email and UI
+     * copy only — never authoritative.
+     */
+    kind?: 'organization' | 'access';
+    projectId?: string;
+    jobId?: string;
+    projectName?: string;
+    jobName?: string;
 }
 export interface OrganizationMember extends FirestoreDoc {
     email: string;

package/dist/types/firestore.js

@@ -4,7 +4,38 @@ export var OrganizationRole;
     OrganizationRole["Full"] = "member";
     OrganizationRole["Contributor"] = "contributor";
     OrganizationRole["Viewer"] = "viewer";
+    /**
+     * Synthetic org membership for users invited to a single project or job.
+     * Grants read of the org doc and its supporting library (templates, labels,
+     * formulas, miter variants, print logos) and nothing under `projects/`.
+     * Server-written only; never offered in an org role picker. The same word
+     * is used for the project-level marker an `AccessGrant` carries when a user
+     * has job access but no project access — "may read this container's doc,
+     * nothing inside it".
+     */
+    OrganizationRole["Guest"] = "guest";
 })(OrganizationRole || (OrganizationRole = {}));
+/** Roles an org admin may assign in Team settings. Excludes Guest. */
+export const ASSIGNABLE_ORG_ROLES = [
+    OrganizationRole.Admin,
+    OrganizationRole.Full,
+    OrganizationRole.Contributor,
+    OrganizationRole.Viewer,
+];
+export const SCOPED_ROLES = [
+    OrganizationRole.Full,
+    OrganizationRole.Contributor,
+    OrganizationRole.Viewer,
+];
+/**
+ * What the sharing UIs offer. Contributor is deliberately absent (Figma
+ * 1028-47443 / 746-37130 show Full and Viewer); add it here to enable it —
+ * rules and types already accept it.
+ */
+export const ACCESS_ROLE_OPTIONS = [
+    { label: 'Full', value: OrganizationRole.Full },
+    { label: 'Viewer', value: OrganizationRole.Viewer },
+];
 export var InvitationStatus;
 (function (InvitationStatus) {
     InvitationStatus["Pending"] = "pending";

package/dist/utils/permissions.d.ts

@@ -0,0 +1,63 @@
+import { OrganizationRole, type AccessGrant, type ScopedRole } from '../types/firestore.js';
+/** A role as it may arrive from Firestore: possibly legacy, possibly missing. */
+export type MaybeRole = OrganizationRole | string | null | undefined;
+export declare const ROLE_RANK: Readonly<Record<OrganizationRole, number>>;
+/**
+ * Maps a stored role string to the enum. Founder member docs written by early
+ * `cloneDemoOrganization` carry the legacy value `'creator'`, which the Cloud
+ * Functions treat as admin; normalise it the same way. Unknown values → null.
+ */
+export declare function normalizeRole(role: MaybeRole): OrganizationRole | null;
+export declare function roleAtLeast(role: MaybeRole, min: OrganizationRole): boolean;
+/**
+ * Highest role wins across the levels that enclose a document. Pass only the
+ * levels that apply: `effectiveRole(org)` for org-level resources,
+ * `effectiveRole(org, project)` for a project, `effectiveRole(org, project,
+ * job)` for anything under a job. Guest at any level is ignored. Returns null
+ * when the user holds no data-bearing role.
+ */
+export declare function effectiveRole(orgRole: MaybeRole, projectRole?: MaybeRole, jobRole?: MaybeRole): OrganizationRole | null;
+/** Viewer or better. */
+export declare const canView: (role: MaybeRole) => boolean;
+/** Contributor or better — may update existing documents. */
+export declare const canEdit: (role: MaybeRole) => boolean;
+/** Full or better — may create/delete children and manage sharing. */
+export declare const canManage: (role: MaybeRole) => boolean;
+/** Org admin — team management, org settings, deleting the org. */
+export declare const canManageOrg: (orgRole: MaybeRole) => boolean;
+export declare const isGuest: (orgRole: MaybeRole) => boolean;
+/**
+ * The grants a user holds inside ONE organization, indexed for O(1) lookup.
+ * `guestProjectIds` are projects the user may read the doc of (because they
+ * hold a job grant inside) but has no project-level role on.
+ */
+export interface GroupedGrants {
+    projectRoles: Readonly<Record<string, ScopedRole>>;
+    jobRolesByProject: Readonly<Record<string, Readonly<Record<string, ScopedRole>>>>;
+    guestProjectIds: readonly string[];
+}
+export declare const EMPTY_GRANTS: GroupedGrants;
+/**
+ * Groups the raw docs from `collectionGroup('access')` for one org. Grants for
+ * other orgs are ignored, so callers may pass the whole snapshot. A project
+ * grant with role `guest` is a marker, recorded in `guestProjectIds` only.
+ */
+export declare function groupGrants(grants: readonly Pick<AccessGrant, 'organizationId' | 'projectId' | 'jobId' | 'scope' | 'role'>[], orgId: string): GroupedGrants;
+export interface ResolvedAccess {
+    /** Effective (highest-wins) role, or null when the user has no access. */
+    role: OrganizationRole | null;
+    canView: boolean;
+    canEdit: boolean;
+    canManage: boolean;
+    /**
+     * True when the user may read the project DOCUMENT itself (org viewer+,
+     * a project role, or the guest marker). Distinct from `canView`, which
+     * covers the project's contents.
+     */
+    canReadProjectDoc: boolean;
+}
+/**
+ * Resolves what a user may do at a project or a job. Mirrors the rules:
+ *   canViewProject/Job, canContributeProject/Job, canEditProject/Job.
+ */
+export declare function resolveAccess(orgRole: MaybeRole, grants: GroupedGrants, projectId: string, jobId?: string | null): ResolvedAccess;

package/dist/utils/permissions.js

@@ -0,0 +1,131 @@
+// Role arithmetic shared by both clients and the backend. Pure: no React, no
+// Firebase, no Skia — this module is re-exported from `server.ts`.
+//
+// Three levels of access exist (organization → project → job). A user's
+// effective role on any document is the HIGHEST of the roles they hold at the
+// levels enclosing it; lower-level grants are additive and never restrict.
+// `Guest` (org role, or the project-level marker on an AccessGrant) ranks
+// below Viewer and contributes nothing to the effective role — it exists so
+// the container document itself is readable.
+//
+// The Firestore rules in rock-pro-backend/firestore.rules encode the same
+// tiers; keep the two in step:
+//   view   = Viewer+       (rules: canView*)
+//   edit   = Contributor+  (rules: canContribute*)
+//   manage = Full+         (rules: canEdit* / canManage*)
+import { OrganizationRole, } from '../types/firestore.js';
+export const ROLE_RANK = {
+    [OrganizationRole.Guest]: 0,
+    [OrganizationRole.Viewer]: 1,
+    [OrganizationRole.Contributor]: 2,
+    [OrganizationRole.Full]: 3,
+    [OrganizationRole.Admin]: 4,
+};
+const KNOWN_ROLES = new Set(Object.values(OrganizationRole));
+/**
+ * Maps a stored role string to the enum. Founder member docs written by early
+ * `cloneDemoOrganization` carry the legacy value `'creator'`, which the Cloud
+ * Functions treat as admin; normalise it the same way. Unknown values → null.
+ */
+export function normalizeRole(role) {
+    if (role == null)
+        return null;
+    if (role === 'creator')
+        return OrganizationRole.Admin;
+    return KNOWN_ROLES.has(role) ? role : null;
+}
+export function roleAtLeast(role, min) {
+    const r = normalizeRole(role);
+    return r != null && ROLE_RANK[r] >= ROLE_RANK[min];
+}
+/**
+ * Highest role wins across the levels that enclose a document. Pass only the
+ * levels that apply: `effectiveRole(org)` for org-level resources,
+ * `effectiveRole(org, project)` for a project, `effectiveRole(org, project,
+ * job)` for anything under a job. Guest at any level is ignored. Returns null
+ * when the user holds no data-bearing role.
+ */
+export function effectiveRole(orgRole, projectRole, jobRole) {
+    let best = null;
+    for (const raw of [orgRole, projectRole, jobRole]) {
+        const r = normalizeRole(raw);
+        if (r == null || r === OrganizationRole.Guest)
+            continue;
+        if (best == null || ROLE_RANK[r] > ROLE_RANK[best])
+            best = r;
+    }
+    return best;
+}
+/** Viewer or better. */
+export const canView = (role) => roleAtLeast(role, OrganizationRole.Viewer);
+/** Contributor or better — may update existing documents. */
+export const canEdit = (role) => roleAtLeast(role, OrganizationRole.Contributor);
+/** Full or better — may create/delete children and manage sharing. */
+export const canManage = (role) => roleAtLeast(role, OrganizationRole.Full);
+/** Org admin — team management, org settings, deleting the org. */
+export const canManageOrg = (orgRole) => roleAtLeast(orgRole, OrganizationRole.Admin);
+export const isGuest = (orgRole) => normalizeRole(orgRole) === OrganizationRole.Guest;
+export const EMPTY_GRANTS = Object.freeze({
+    projectRoles: Object.freeze({}),
+    jobRolesByProject: Object.freeze({}),
+    guestProjectIds: Object.freeze([]),
+});
+function isScopedRole(role) {
+    const r = normalizeRole(role);
+    return (r === OrganizationRole.Full ||
+        r === OrganizationRole.Contributor ||
+        r === OrganizationRole.Viewer);
+}
+/**
+ * Groups the raw docs from `collectionGroup('access')` for one org. Grants for
+ * other orgs are ignored, so callers may pass the whole snapshot. A project
+ * grant with role `guest` is a marker, recorded in `guestProjectIds` only.
+ */
+export function groupGrants(grants, orgId) {
+    var _a;
+    const projectRoles = {};
+    const jobRolesByProject = {};
+    const guest = new Set();
+    for (const g of grants) {
+        if (g.organizationId !== orgId)
+            continue;
+        if (g.scope === 'job') {
+            if (!g.jobId || !isScopedRole(g.role))
+                continue;
+            (jobRolesByProject[_a = g.projectId] ?? (jobRolesByProject[_a] = {}))[g.jobId] = g.role;
+        }
+        else if (g.scope === 'project') {
+            if (isScopedRole(g.role))
+                projectRoles[g.projectId] = g.role;
+            else if (normalizeRole(g.role) === OrganizationRole.Guest)
+                guest.add(g.projectId);
+        }
+    }
+    // A real project role supersedes a stale marker.
+    for (const id of Object.keys(projectRoles))
+        guest.delete(id);
+    return {
+        projectRoles,
+        jobRolesByProject,
+        guestProjectIds: [...guest].sort(),
+    };
+}
+/**
+ * Resolves what a user may do at a project or a job. Mirrors the rules:
+ *   canViewProject/Job, canContributeProject/Job, canEditProject/Job.
+ */
+export function resolveAccess(orgRole, grants, projectId, jobId) {
+    const projectRole = grants.projectRoles[projectId];
+    const jobRole = jobId
+        ? grants.jobRolesByProject[projectId]?.[jobId]
+        : undefined;
+    const role = effectiveRole(orgRole, projectRole, jobId ? jobRole : undefined);
+    return {
+        role,
+        canView: canView(role),
+        canEdit: canEdit(role),
+        canManage: canManage(role),
+        canReadProjectDoc: canView(effectiveRole(orgRole, projectRole)) ||
+            grants.guestProjectIds.includes(projectId),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reekon-tools/boldr-utils",
-  "version": "1.20.3",
+  "version": "1.21.1",
   "description": "Shared utilities for formulas and measurement conversion used in Reekon apps",
   "author": "REEKON Tools",
   "license": "MIT",