@aglyn/aglyn 1.0.0-beta.269 → 1.0.0-beta.271

package/src/lib/app-utils/org-role-grants.js

@@ -0,0 +1,193 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * WHAT EACH ORG ROLE MAY DO, AS DATA (AGL-243, AGL-3950).
+ *
+ * The core permission catalog and the core keys each org role holds when
+ * nothing refines it. `org-permissions.ts` builds the console's live
+ * catalog from these (adding the keys plugins declare, with their own role
+ * defaults), and the native apps read the same grants through the generated
+ * contracts, so a native gate (`hosts.create`, `data.manage`) answers as the
+ * console does for a member row that carries no `resolvedPermissions` stamp.
+ *
+ * `ORG_ROLE_GRANTS` in the contracts is this table with every plugin's
+ * declared catalog keys added (`assembleOrgRoleGrants`, run by
+ * `generate:native-contracts` over each plugin's declarations), which is
+ * exactly the set the console's `DEFAULT_ROLE_PERMISSIONS` holds once the
+ * plugins have registered.
+ *
+ * NO IMPORTS, on purpose: the native apps read it through the generated
+ * contracts.
+ */ /** The four org roles. */ import { _ as _extends } from "@swc/helpers/_/_extends";
+export const ORG_ROLE_NAMES = [
+    'owner',
+    'admin',
+    'editor',
+    'viewer'
+];
+/**
+ * The core keys, in display order for role editors. Every key here is
+ * enforced server-side (`apps/console/specs/org-permissions-are-enforced.spec.ts`).
+ */ export const CORE_ORG_PERMISSION_ENTRIES = [
+    {
+        key: 'org.settings',
+        label: 'Organization settings',
+        description: 'Rename the organization, change its slug, transfer it.'
+    },
+    {
+        key: 'org.auditLog',
+        label: 'Activity & audit log',
+        description: 'See the organization activity feed.'
+    },
+    {
+        key: 'billing.view',
+        label: 'View billing',
+        description: 'See the plan, usage meters, and invoices.'
+    },
+    {
+        key: 'billing.manage',
+        label: 'Manage billing',
+        description: 'Change plans, buy add-ons, update payment details.'
+    },
+    {
+        key: 'members.manage',
+        label: 'Manage members',
+        description: 'Invite, remove, and re-role organization members.'
+    },
+    {
+        key: 'hosts.create',
+        label: 'Create sites',
+        description: 'Create new sites in the organization.'
+    },
+    {
+        key: 'hosts.delete',
+        label: 'Delete sites',
+        description: 'Delete sites the member can access.'
+    },
+    {
+        key: 'data.manage',
+        label: 'Manage data',
+        description: 'Create, edit, and delete organization datasets.'
+    },
+    {
+        key: 'marketplace.publish',
+        label: 'Publish to marketplace',
+        description: 'Publish listings under the organization profile.'
+    },
+    {
+        key: 'plugins.install',
+        label: 'Install plugins',
+        description: 'Install or remove marketplace plugins.'
+    }
+];
+const CORE_KEYS = CORE_ORG_PERMISSION_ENTRIES.map((entry)=>entry.key);
+/**
+ * The core keys each org role holds when nothing refines it: owners and
+ * admins hold every core key (owner-only acts like deleting the
+ * organization stay role-checked, not permission-checked); editors work on
+ * content and see no money or roster controls; viewers read only.
+ */ export const CORE_ORG_ROLE_GRANTS = {
+    owner: CORE_KEYS,
+    admin: CORE_KEYS,
+    editor: [
+        'data.manage',
+        'marketplace.publish',
+        'plugins.install'
+    ],
+    viewer: []
+};
+/** The core's catalog and grants; the contracts' value adds the plugins' keys. */ export const ORG_ROLE_GRANTS = {
+    permissions: CORE_ORG_PERMISSION_ENTRIES.map((entry)=>_extends({}, entry)),
+    grants: {
+        owner: [
+            ...CORE_ORG_ROLE_GRANTS.owner
+        ],
+        admin: [
+            ...CORE_ORG_ROLE_GRANTS.admin
+        ],
+        editor: [
+            ...CORE_ORG_ROLE_GRANTS.editor
+        ],
+        viewer: [
+            ...CORE_ORG_ROLE_GRANTS.viewer
+        ]
+    }
+};
+/**
+ * The catalog with plugins' declared keys after the core ones, each role
+ * holding a declared key when its declaration's `roleDefaults` says so. A
+ * declaration naming a core key is refused, as the console's catalog refuses
+ * it: the core key keeps its meaning and defaults.
+ */ export function assembleOrgRoleGrants(core, declarations) {
+    const permissions = [
+        ...core.permissions
+    ];
+    const grants = Object.fromEntries(ORG_ROLE_NAMES.map((role)=>[
+            role,
+            [
+                ...core.grants[role]
+            ]
+        ]));
+    const taken = new Set(permissions.map((entry)=>entry.key));
+    for (const declaration of declarations){
+        if (!(declaration == null ? void 0 : declaration.key) || taken.has(declaration.key)) continue;
+        taken.add(declaration.key);
+        permissions.push(_extends({
+            key: declaration.key,
+            label: declaration.label,
+            description: declaration.description
+        }, declaration.pluginId ? {
+            pluginId: declaration.pluginId
+        } : {}));
+        for (const role of ORG_ROLE_NAMES){
+            var _declaration_roleDefaults;
+            if (((_declaration_roleDefaults = declaration.roleDefaults) == null ? void 0 : _declaration_roleDefaults[role]) === true) grants[role].push(declaration.key);
+        }
+    }
+    return {
+        permissions,
+        grants
+    };
+}
+/**
+ * A member's effective permissions, as the console's `resolveOrgPermissions`
+ * answers them: the role's defaults, then the custom role's explicit
+ * verdicts (when the member has one), then the member's own overrides,
+ * later layers winning key by key, over the catalog's keys only. A missing
+ * role reads as viewer; a role the catalog does not know holds nothing.
+ */ export function rolePermissions(catalog, role, customRole, overrides) {
+    var _catalog_grants_name;
+    const keys = catalog.permissions.map((entry)=>entry.key);
+    const name = role != null ? role : 'viewer';
+    const held = new Set((_catalog_grants_name = catalog.grants[name]) != null ? _catalog_grants_name : []);
+    const out = Object.fromEntries(keys.map((key)=>[
+            key,
+            held.has(key)
+        ]));
+    for (const layer of [
+        customRole,
+        overrides
+    ]){
+        const values = layer == null ? void 0 : layer.permissions;
+        if (!values) continue;
+        for (const key of keys){
+            if (typeof values[key] === 'boolean') out[key] = values[key];
+        }
+    }
+    return out;
+}
+
+//# sourceMappingURL=org-role-grants.js.map

package/src/lib/app-utils/org-role-grants.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/org-role-grants.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * WHAT EACH ORG ROLE MAY DO, AS DATA (AGL-243, AGL-3950).\n *\n * The core permission catalog and the core keys each org role holds when\n * nothing refines it. `org-permissions.ts` builds the console's live\n * catalog from these (adding the keys plugins declare, with their own role\n * defaults), and the native apps read the same grants through the generated\n * contracts, so a native gate (`hosts.create`, `data.manage`) answers as the\n * console does for a member row that carries no `resolvedPermissions` stamp.\n *\n * `ORG_ROLE_GRANTS` in the contracts is this table with every plugin's\n * declared catalog keys added (`assembleOrgRoleGrants`, run by\n * `generate:native-contracts` over each plugin's declarations), which is\n * exactly the set the console's `DEFAULT_ROLE_PERMISSIONS` holds once the\n * plugins have registered.\n *\n * NO IMPORTS, on purpose: the native apps read it through the generated\n * contracts.\n */\n\n/** The four org roles. */\nexport type OrgRoleName = 'owner' | 'admin' | 'editor' | 'viewer'\n\n/** One key of the org permission catalog. */\nexport interface OrgPermissionEntry {\n  key: string\n  label: string\n  description: string\n  /** The plugin that declared it; absent for a core key. */\n  pluginId?: string\n}\n\n/** The catalog and each role's default grants. */\nexport interface OrgRoleGrants {\n  /** Every key, in the order the role editor lists them. */\n  permissions: OrgPermissionEntry[]\n  /** The keys each role holds when no custom role or per-member override sets them. */\n  grants: Record<OrgRoleName, string[]>\n}\n\n/** A key a plugin declares into the catalog, as `PluginOrgPermissionDeclaration` carries it. */\nexport interface OrgPermissionDeclaration {\n  key: string\n  label: string\n  description: string\n  roleDefaults: Record<OrgRoleName, boolean>\n}\n\n/** A custom role (`orgs/{orgId}/roles/{roleId}`) or a member's overrides: explicit verdicts per key. */\nexport interface OrgPermissionLayer {\n  permissions?: Record<string, boolean>\n}\n\nexport const ORG_ROLE_NAMES: readonly OrgRoleName[] = ['owner', 'admin', 'editor', 'viewer']\n\n/**\n * The core keys, in display order for role editors. Every key here is\n * enforced server-side (`apps/console/specs/org-permissions-are-enforced.spec.ts`).\n */\nexport const CORE_ORG_PERMISSION_ENTRIES: readonly OrgPermissionEntry[] = [\n  {\n    key: 'org.settings',\n    label: 'Organization settings',\n    description: 'Rename the organization, change its slug, transfer it.',\n  },\n  {\n    key: 'org.auditLog',\n    label: 'Activity & audit log',\n    description: 'See the organization activity feed.',\n  },\n  {\n    key: 'billing.view',\n    label: 'View billing',\n    description: 'See the plan, usage meters, and invoices.',\n  },\n  {\n    key: 'billing.manage',\n    label: 'Manage billing',\n    description: 'Change plans, buy add-ons, update payment details.',\n  },\n  {\n    key: 'members.manage',\n    label: 'Manage members',\n    description: 'Invite, remove, and re-role organization members.',\n  },\n  {\n    key: 'hosts.create',\n    label: 'Create sites',\n    description: 'Create new sites in the organization.',\n  },\n  {\n    key: 'hosts.delete',\n    label: 'Delete sites',\n    description: 'Delete sites the member can access.',\n  },\n  {\n    key: 'data.manage',\n    label: 'Manage data',\n    description: 'Create, edit, and delete organization datasets.',\n  },\n  {\n    key: 'marketplace.publish',\n    label: 'Publish to marketplace',\n    description: 'Publish listings under the organization profile.',\n  },\n  {\n    key: 'plugins.install',\n    label: 'Install plugins',\n    description: 'Install or remove marketplace plugins.',\n  },\n]\n\nconst CORE_KEYS = CORE_ORG_PERMISSION_ENTRIES.map((entry) => entry.key)\n\n/**\n * The core keys each org role holds when nothing refines it: owners and\n * admins hold every core key (owner-only acts like deleting the\n * organization stay role-checked, not permission-checked); editors work on\n * content and see no money or roster controls; viewers read only.\n */\nexport const CORE_ORG_ROLE_GRANTS: Readonly<Record<OrgRoleName, readonly string[]>> = {\n  owner: CORE_KEYS,\n  admin: CORE_KEYS,\n  editor: ['data.manage', 'marketplace.publish', 'plugins.install'],\n  viewer: [],\n}\n\n/** The core's catalog and grants; the contracts' value adds the plugins' keys. */\nexport const ORG_ROLE_GRANTS: OrgRoleGrants = {\n  permissions: CORE_ORG_PERMISSION_ENTRIES.map((entry) => ({ ...entry })),\n  grants: {\n    owner: [...CORE_ORG_ROLE_GRANTS.owner],\n    admin: [...CORE_ORG_ROLE_GRANTS.admin],\n    editor: [...CORE_ORG_ROLE_GRANTS.editor],\n    viewer: [...CORE_ORG_ROLE_GRANTS.viewer],\n  },\n}\n\n/**\n * The catalog with plugins' declared keys after the core ones, each role\n * holding a declared key when its declaration's `roleDefaults` says so. A\n * declaration naming a core key is refused, as the console's catalog refuses\n * it: the core key keeps its meaning and defaults.\n */\nexport function assembleOrgRoleGrants(\n  core: OrgRoleGrants,\n  declarations: readonly (OrgPermissionDeclaration & { pluginId?: string })[],\n): OrgRoleGrants {\n  const permissions = [...core.permissions]\n  const grants = Object.fromEntries(ORG_ROLE_NAMES.map((role) => [role, [...core.grants[role]]])) as Record<\n    OrgRoleName,\n    string[]\n  >\n  const taken = new Set(permissions.map((entry) => entry.key))\n  for (const declaration of declarations) {\n    if (!declaration?.key || taken.has(declaration.key)) continue\n    taken.add(declaration.key)\n    permissions.push({\n      key: declaration.key,\n      label: declaration.label,\n      description: declaration.description,\n      ...(declaration.pluginId ? { pluginId: declaration.pluginId } : {}),\n    })\n    for (const role of ORG_ROLE_NAMES) {\n      if (declaration.roleDefaults?.[role] === true) grants[role].push(declaration.key)\n    }\n  }\n  return { permissions, grants }\n}\n\n/**\n * A member's effective permissions, as the console's `resolveOrgPermissions`\n * answers them: the role's defaults, then the custom role's explicit\n * verdicts (when the member has one), then the member's own overrides,\n * later layers winning key by key, over the catalog's keys only. A missing\n * role reads as viewer; a role the catalog does not know holds nothing.\n */\nexport function rolePermissions(\n  catalog: OrgRoleGrants,\n  role: string | null | undefined,\n  customRole?: OrgPermissionLayer | null,\n  overrides?: OrgPermissionLayer | null,\n): Record<string, boolean> {\n  const keys = catalog.permissions.map((entry) => entry.key)\n  const name = role ?? 'viewer'\n  const held = new Set((catalog.grants as Record<string, string[] | undefined>)[name] ?? [])\n  const out: Record<string, boolean> = Object.fromEntries(keys.map((key) => [key, held.has(key)]))\n  for (const layer of [customRole, overrides]) {\n    const values = layer?.permissions\n    if (!values) continue\n    for (const key of keys) {\n      if (typeof values[key] === 'boolean') out[key] = values[key]\n    }\n  }\n  return out\n}\n"],"names":["ORG_ROLE_NAMES","CORE_ORG_PERMISSION_ENTRIES","key","label","description","CORE_KEYS","map","entry","CORE_ORG_ROLE_GRANTS","owner","admin","editor","viewer","ORG_ROLE_GRANTS","permissions","grants","assembleOrgRoleGrants","core","declarations","Object","fromEntries","role","taken","Set","declaration","has","add","push","pluginId","roleDefaults","rolePermissions","catalog","customRole","overrides","keys","name","held","out","layer","values"],"mappings":"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"}

package/src/lib/app-utils/owner-approval-record.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * THE OWNER'S RECORDED YES (AGL-3959).
+ *
+ * Paid work beyond what a subscription includes is billed only after the
+ * owner agreed to it, and the owner never clicks anything in the console to
+ * agree: they say yes to a person — at the booth, on the phone, by text or by
+ * email — and STAFF record how and when. Saving the record emails the owner a
+ * confirmation, and that email is the written record.
+ *
+ * This module is the record's shape and its rules, with no Firestore and no
+ * product in it, so any staff surface that bills by an approval reads it the
+ * same way: Site Care's extra time first, and the flat-quoted project invoice
+ * (AGL-3970) after it. A correction never edits a record in place: it is a
+ * new record with `version` one higher, `corrected: true` and the reason, and
+ * the old one stays in the request's history.
+ */
+/** How the owner said yes. */
+export declare const OWNER_APPROVAL_CHANNELS: readonly ["in-person", "phone", "text", "email"];
+export type OwnerApprovalChannel = (typeof OWNER_APPROVAL_CHANNELS)[number];
+/** The channel as a sentence reads it: "by phone", "in person". */
+export declare const OWNER_APPROVAL_CHANNEL_WORDS: Readonly<Record<OwnerApprovalChannel, string>>;
+/** The channel as a picker labels it. */
+export declare const OWNER_APPROVAL_CHANNEL_LABELS: Readonly<Record<OwnerApprovalChannel, string>>;
+/** The longest approval an hourly record may carry, in hours. */
+export declare const OWNER_APPROVAL_MAX_HOURS = 40;
+/** The longest note or reason a record keeps. */
+export declare const OWNER_APPROVAL_NOTE_MAX = 500;
+/** One recorded yes. Written by staff, read by the close and the emails. */
+export interface OwnerApprovalRecord {
+    /** Whole hours the owner agreed to, at most. */
+    hours: number;
+    /** The published hourly rate the owner agreed to, in whole dollars. */
+    rateUsd: number;
+    channel: OwnerApprovalChannel;
+    /** When the owner said yes, epoch ms. */
+    approvedAtMs: number;
+    /** When staff recorded it, epoch ms. */
+    recordedAtMs: number;
+    recordedByUid: string;
+    recordedByEmail: string | null;
+    /** What the owner said yes to, in staff's words; optional. */
+    note: string | null;
+    /** 1 for the first record; each correction is one higher. */
+    version: number;
+    /** True on every record after the first. */
+    corrected: boolean;
+    /** Why it was corrected; required when `corrected`. */
+    correctionReason: string | null;
+}
+export type OwnerApprovalInputResult = {
+    ok: true;
+    record: OwnerApprovalRecord;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Reads what staff typed into a record, refusing anything the record cannot
+ * honestly say. `previous` is the record it corrects, when there is one: a
+ * correction needs a reason, and the reason is what the history and the
+ * re-sent confirmation say changed.
+ */
+export declare function readOwnerApprovalInput(raw: Readonly<Record<string, unknown>> | null | undefined, context: {
+    rateUsd: number;
+    nowMs: number;
+    by: {
+        uid: string;
+        email: string | null;
+    };
+    previous?: OwnerApprovalRecord | null;
+    /**
+     * The most hours the record may carry; `OWNER_APPROVAL_MAX_HOURS` unless
+     * the surface says otherwise. A flat-quoted project (AGL-3970) records
+     * the quote's own whole hours, which a redesign can take past a week.
+     */
+    maxHours?: number;
+}): OwnerApprovalInputResult;
+/** A stored record read back defensively, or null when it is not one. */
+export declare function readOwnerApprovalRecord(value: unknown): OwnerApprovalRecord | null;
+/** "2 hours", "1 hour". */
+export declare function describeHours(hours: number): string;
+/**
+ * The confirmation's one sentence, in the owner's words: what they agreed
+ * to, how and when.
+ */
+export declare function ownerApprovalSentence(record: Pick<OwnerApprovalRecord, 'hours' | 'rateUsd' | 'channel' | 'approvedAtMs'>, what: string, formatDate: (ms: number) => string): string;

package/src/lib/app-utils/owner-approval-record.js

@@ -0,0 +1,148 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * THE OWNER'S RECORDED YES (AGL-3959).
+ *
+ * Paid work beyond what a subscription includes is billed only after the
+ * owner agreed to it, and the owner never clicks anything in the console to
+ * agree: they say yes to a person — at the booth, on the phone, by text or by
+ * email — and STAFF record how and when. Saving the record emails the owner a
+ * confirmation, and that email is the written record.
+ *
+ * This module is the record's shape and its rules, with no Firestore and no
+ * product in it, so any staff surface that bills by an approval reads it the
+ * same way: Site Care's extra time first, and the flat-quoted project invoice
+ * (AGL-3970) after it. A correction never edits a record in place: it is a
+ * new record with `version` one higher, `corrected: true` and the reason, and
+ * the old one stays in the request's history.
+ */ /** How the owner said yes. */ export const OWNER_APPROVAL_CHANNELS = [
+    'in-person',
+    'phone',
+    'text',
+    'email'
+];
+/** The channel as a sentence reads it: "by phone", "in person". */ export const OWNER_APPROVAL_CHANNEL_WORDS = {
+    'in-person': 'in person',
+    phone: 'by phone',
+    text: 'by text message',
+    email: 'by email'
+};
+/** The channel as a picker labels it. */ export const OWNER_APPROVAL_CHANNEL_LABELS = {
+    'in-person': 'In person',
+    phone: 'Phone call',
+    text: 'Text message',
+    email: 'Email'
+};
+/** The longest approval an hourly record may carry, in hours. */ export const OWNER_APPROVAL_MAX_HOURS = 40;
+/** The longest note or reason a record keeps. */ export const OWNER_APPROVAL_NOTE_MAX = 500;
+/** A trimmed, bounded string, or null when blank. */ function cleanText(value, max) {
+    const text = typeof value === 'string' ? value.trim().slice(0, max) : '';
+    return text ? text : null;
+}
+/**
+ * Reads what staff typed into a record, refusing anything the record cannot
+ * honestly say. `previous` is the record it corrects, when there is one: a
+ * correction needs a reason, and the reason is what the history and the
+ * re-sent confirmation say changed.
+ */ export function readOwnerApprovalInput(raw, context) {
+    var _context_maxHours, _ref, _context_previous;
+    const hours = Number(raw == null ? void 0 : raw['hours']);
+    const maxHours = (_context_maxHours = context.maxHours) != null ? _context_maxHours : OWNER_APPROVAL_MAX_HOURS;
+    if (!Number.isInteger(hours) || hours < 1 || hours > maxHours) {
+        return {
+            ok: false,
+            error: `Enter the hours the owner approved, a whole number from 1 to ${maxHours}.`
+        };
+    }
+    const channel = String((_ref = raw == null ? void 0 : raw['channel']) != null ? _ref : '');
+    if (!OWNER_APPROVAL_CHANNELS.includes(channel)) {
+        return {
+            ok: false,
+            error: 'Choose how the owner said yes.'
+        };
+    }
+    const approvedAtMs = Number(raw == null ? void 0 : raw['approvedAtMs']);
+    if (!Number.isFinite(approvedAtMs) || approvedAtMs <= 0) {
+        return {
+            ok: false,
+            error: 'Enter when the owner said yes.'
+        };
+    }
+    // A minute of clock skew is allowed; a yes recorded for tomorrow is not one
+    // anybody has heard yet.
+    if (approvedAtMs > context.nowMs + 60000) {
+        return {
+            ok: false,
+            error: 'The owner’s yes cannot be in the future.'
+        };
+    }
+    const previous = (_context_previous = context.previous) != null ? _context_previous : null;
+    const correctionReason = cleanText(raw == null ? void 0 : raw['reason'], OWNER_APPROVAL_NOTE_MAX);
+    if (previous && !correctionReason) {
+        return {
+            ok: false,
+            error: 'Say why the approval is being corrected.'
+        };
+    }
+    return {
+        ok: true,
+        record: {
+            hours,
+            rateUsd: context.rateUsd,
+            channel,
+            approvedAtMs: Math.floor(approvedAtMs),
+            recordedAtMs: context.nowMs,
+            recordedByUid: context.by.uid,
+            recordedByEmail: context.by.email,
+            note: cleanText(raw == null ? void 0 : raw['note'], OWNER_APPROVAL_NOTE_MAX),
+            version: previous ? Math.max(1, Number(previous.version) || 1) + 1 : 1,
+            corrected: Boolean(previous),
+            correctionReason: previous ? correctionReason : null
+        }
+    };
+}
+/** A stored record read back defensively, or null when it is not one. */ export function readOwnerApprovalRecord(value) {
+    var _record_recordedByUid, _record_recordedByEmail, _record_note, _record_correctionReason;
+    if (!value || typeof value !== 'object') return null;
+    const record = value;
+    const hours = Number(record.hours);
+    if (!Number.isInteger(hours) || hours < 1) return null;
+    if (!OWNER_APPROVAL_CHANNELS.includes(record.channel)) return null;
+    return {
+        hours,
+        rateUsd: Number(record.rateUsd) || 0,
+        channel: record.channel,
+        approvedAtMs: Number(record.approvedAtMs) || 0,
+        recordedAtMs: Number(record.recordedAtMs) || 0,
+        recordedByUid: String((_record_recordedByUid = record.recordedByUid) != null ? _record_recordedByUid : ''),
+        recordedByEmail: (_record_recordedByEmail = record.recordedByEmail) != null ? _record_recordedByEmail : null,
+        note: (_record_note = record.note) != null ? _record_note : null,
+        version: Number(record.version) || 1,
+        corrected: record.corrected === true,
+        correctionReason: (_record_correctionReason = record.correctionReason) != null ? _record_correctionReason : null
+    };
+}
+/** "2 hours", "1 hour". */ export function describeHours(hours) {
+    return `${hours} ${hours === 1 ? 'hour' : 'hours'}`;
+}
+/**
+ * The confirmation's one sentence, in the owner's words: what they agreed
+ * to, how and when.
+ */ export function ownerApprovalSentence(record, what, formatDate) {
+    return `You approved up to ${describeHours(record.hours)} of extra time at ` + `$${record.rateUsd} an hour for “${what}”, ` + `${OWNER_APPROVAL_CHANNEL_WORDS[record.channel]} on ${formatDate(record.approvedAtMs)}.`;
+}
+
+//# sourceMappingURL=owner-approval-record.js.map

package/src/lib/app-utils/owner-approval-record.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/owner-approval-record.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * THE OWNER'S RECORDED YES (AGL-3959).\n *\n * Paid work beyond what a subscription includes is billed only after the\n * owner agreed to it, and the owner never clicks anything in the console to\n * agree: they say yes to a person — at the booth, on the phone, by text or by\n * email — and STAFF record how and when. Saving the record emails the owner a\n * confirmation, and that email is the written record.\n *\n * This module is the record's shape and its rules, with no Firestore and no\n * product in it, so any staff surface that bills by an approval reads it the\n * same way: Site Care's extra time first, and the flat-quoted project invoice\n * (AGL-3970) after it. A correction never edits a record in place: it is a\n * new record with `version` one higher, `corrected: true` and the reason, and\n * the old one stays in the request's history.\n */\n\n/** How the owner said yes. */\nexport const OWNER_APPROVAL_CHANNELS = ['in-person', 'phone', 'text', 'email'] as const\n\nexport type OwnerApprovalChannel = (typeof OWNER_APPROVAL_CHANNELS)[number]\n\n/** The channel as a sentence reads it: \"by phone\", \"in person\". */\nexport const OWNER_APPROVAL_CHANNEL_WORDS: Readonly<Record<OwnerApprovalChannel, string>> = {\n  'in-person': 'in person',\n  phone: 'by phone',\n  text: 'by text message',\n  email: 'by email',\n}\n\n/** The channel as a picker labels it. */\nexport const OWNER_APPROVAL_CHANNEL_LABELS: Readonly<Record<OwnerApprovalChannel, string>> = {\n  'in-person': 'In person',\n  phone: 'Phone call',\n  text: 'Text message',\n  email: 'Email',\n}\n\n/** The longest approval an hourly record may carry, in hours. */\nexport const OWNER_APPROVAL_MAX_HOURS = 40\n\n/** The longest note or reason a record keeps. */\nexport const OWNER_APPROVAL_NOTE_MAX = 500\n\n/** One recorded yes. Written by staff, read by the close and the emails. */\nexport interface OwnerApprovalRecord {\n  /** Whole hours the owner agreed to, at most. */\n  hours: number\n  /** The published hourly rate the owner agreed to, in whole dollars. */\n  rateUsd: number\n  channel: OwnerApprovalChannel\n  /** When the owner said yes, epoch ms. */\n  approvedAtMs: number\n  /** When staff recorded it, epoch ms. */\n  recordedAtMs: number\n  recordedByUid: string\n  recordedByEmail: string | null\n  /** What the owner said yes to, in staff's words; optional. */\n  note: string | null\n  /** 1 for the first record; each correction is one higher. */\n  version: number\n  /** True on every record after the first. */\n  corrected: boolean\n  /** Why it was corrected; required when `corrected`. */\n  correctionReason: string | null\n}\n\nexport type OwnerApprovalInputResult =\n  | { ok: true; record: OwnerApprovalRecord }\n  | { ok: false; error: string }\n\n/** A trimmed, bounded string, or null when blank. */\nfunction cleanText(value: unknown, max: number): string | null {\n  const text = typeof value === 'string' ? value.trim().slice(0, max) : ''\n  return text ? text : null\n}\n\n/**\n * Reads what staff typed into a record, refusing anything the record cannot\n * honestly say. `previous` is the record it corrects, when there is one: a\n * correction needs a reason, and the reason is what the history and the\n * re-sent confirmation say changed.\n */\nexport function readOwnerApprovalInput(\n  raw: Readonly<Record<string, unknown>> | null | undefined,\n  context: {\n    rateUsd: number\n    nowMs: number\n    by: { uid: string; email: string | null }\n    previous?: OwnerApprovalRecord | null\n    /**\n     * The most hours the record may carry; `OWNER_APPROVAL_MAX_HOURS` unless\n     * the surface says otherwise. A flat-quoted project (AGL-3970) records\n     * the quote's own whole hours, which a redesign can take past a week.\n     */\n    maxHours?: number\n  },\n): OwnerApprovalInputResult {\n  const hours = Number(raw?.['hours'])\n  const maxHours = context.maxHours ?? OWNER_APPROVAL_MAX_HOURS\n  if (!Number.isInteger(hours) || hours < 1 || hours > maxHours) {\n    return {\n      ok: false,\n      error: `Enter the hours the owner approved, a whole number from 1 to ${maxHours}.`,\n    }\n  }\n  const channel = String(raw?.['channel'] ?? '') as OwnerApprovalChannel\n  if (!OWNER_APPROVAL_CHANNELS.includes(channel)) {\n    return { ok: false, error: 'Choose how the owner said yes.' }\n  }\n  const approvedAtMs = Number(raw?.['approvedAtMs'])\n  if (!Number.isFinite(approvedAtMs) || approvedAtMs <= 0) {\n    return { ok: false, error: 'Enter when the owner said yes.' }\n  }\n  // A minute of clock skew is allowed; a yes recorded for tomorrow is not one\n  // anybody has heard yet.\n  if (approvedAtMs > context.nowMs + 60_000) {\n    return { ok: false, error: 'The owner’s yes cannot be in the future.' }\n  }\n  const previous = context.previous ?? null\n  const correctionReason = cleanText(raw?.['reason'], OWNER_APPROVAL_NOTE_MAX)\n  if (previous && !correctionReason) {\n    return { ok: false, error: 'Say why the approval is being corrected.' }\n  }\n  return {\n    ok: true,\n    record: {\n      hours,\n      rateUsd: context.rateUsd,\n      channel,\n      approvedAtMs: Math.floor(approvedAtMs),\n      recordedAtMs: context.nowMs,\n      recordedByUid: context.by.uid,\n      recordedByEmail: context.by.email,\n      note: cleanText(raw?.['note'], OWNER_APPROVAL_NOTE_MAX),\n      version: previous ? Math.max(1, Number(previous.version) || 1) + 1 : 1,\n      corrected: Boolean(previous),\n      correctionReason: previous ? correctionReason : null,\n    },\n  }\n}\n\n/** A stored record read back defensively, or null when it is not one. */\nexport function readOwnerApprovalRecord(value: unknown): OwnerApprovalRecord | null {\n  if (!value || typeof value !== 'object') return null\n  const record = value as Partial<OwnerApprovalRecord>\n  const hours = Number(record.hours)\n  if (!Number.isInteger(hours) || hours < 1) return null\n  if (!OWNER_APPROVAL_CHANNELS.includes(record.channel as OwnerApprovalChannel)) return null\n  return {\n    hours,\n    rateUsd: Number(record.rateUsd) || 0,\n    channel: record.channel as OwnerApprovalChannel,\n    approvedAtMs: Number(record.approvedAtMs) || 0,\n    recordedAtMs: Number(record.recordedAtMs) || 0,\n    recordedByUid: String(record.recordedByUid ?? ''),\n    recordedByEmail: record.recordedByEmail ?? null,\n    note: record.note ?? null,\n    version: Number(record.version) || 1,\n    corrected: record.corrected === true,\n    correctionReason: record.correctionReason ?? null,\n  }\n}\n\n/** \"2 hours\", \"1 hour\". */\nexport function describeHours(hours: number): string {\n  return `${hours} ${hours === 1 ? 'hour' : 'hours'}`\n}\n\n/**\n * The confirmation's one sentence, in the owner's words: what they agreed\n * to, how and when.\n */\nexport function ownerApprovalSentence(\n  record: Pick<OwnerApprovalRecord, 'hours' | 'rateUsd' | 'channel' | 'approvedAtMs'>,\n  what: string,\n  formatDate: (ms: number) => string,\n): string {\n  return (\n    `You approved up to ${describeHours(record.hours)} of extra time at ` +\n    `$${record.rateUsd} an hour for “${what}”, ` +\n    `${OWNER_APPROVAL_CHANNEL_WORDS[record.channel]} on ${formatDate(record.approvedAtMs)}.`\n  )\n}\n"],"names":["OWNER_APPROVAL_CHANNELS","OWNER_APPROVAL_CHANNEL_WORDS","phone","text","email","OWNER_APPROVAL_CHANNEL_LABELS","OWNER_APPROVAL_MAX_HOURS","OWNER_APPROVAL_NOTE_MAX","cleanText","value","max","trim","slice","readOwnerApprovalInput","raw","context","hours","Number","maxHours","isInteger","ok","error","channel","String","includes","approvedAtMs","isFinite","nowMs","previous","correctionReason","record","rateUsd","Math","floor","recordedAtMs","recordedByUid","by","uid","recordedByEmail","note","version","corrected","Boolean","readOwnerApprovalRecord","describeHours","ownerApprovalSentence","what","formatDate"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;CAeC,GAED,4BAA4B,GAC5B,OAAO,MAAMA,0BAA0B;IAAC;IAAa;IAAS;IAAQ;CAAQ,CAAS;AAIvF,iEAAiE,GACjE,OAAO,MAAMC,+BAA+E;IAC1F,aAAa;IACbC,OAAO;IACPC,MAAM;IACNC,OAAO;AACT,EAAC;AAED,uCAAuC,GACvC,OAAO,MAAMC,gCAAgF;IAC3F,aAAa;IACbH,OAAO;IACPC,MAAM;IACNC,OAAO;AACT,EAAC;AAED,+DAA+D,GAC/D,OAAO,MAAME,2BAA2B,GAAE;AAE1C,+CAA+C,GAC/C,OAAO,MAAMC,0BAA0B,IAAG;AA6B1C,mDAAmD,GACnD,SAASC,UAAUC,KAAc,EAAEC,GAAW;IAC5C,MAAMP,OAAO,OAAOM,UAAU,WAAWA,MAAME,IAAI,GAAGC,KAAK,CAAC,GAAGF,OAAO;IACtE,OAAOP,OAAOA,OAAO;AACvB;AAEA;;;;;CAKC,GACD,OAAO,SAASU,uBACdC,GAAyD,EACzDC,OAWC;QAGgBA,yBAoBAA;IArBjB,MAAMC,QAAQC,OAAOH,uBAAAA,GAAK,CAAC,QAAQ;IACnC,MAAMI,YAAWH,oBAAAA,QAAQG,QAAQ,YAAhBH,oBAAoBT;IACrC,IAAI,CAACW,OAAOE,SAAS,CAACH,UAAUA,QAAQ,KAAKA,QAAQE,UAAU;QAC7D,OAAO;YACLE,IAAI;YACJC,OAAO,CAAC,6DAA6D,EAAEH,SAAS,CAAC,CAAC;QACpF;IACF;IACA,MAAMI,UAAUC,eAAOT,uBAAAA,GAAK,CAAC,UAAU,mBAAI;IAC3C,IAAI,CAACd,wBAAwBwB,QAAQ,CAACF,UAAU;QAC9C,OAAO;YAAEF,IAAI;YAAOC,OAAO;QAAiC;IAC9D;IACA,MAAMI,eAAeR,OAAOH,uBAAAA,GAAK,CAAC,eAAe;IACjD,IAAI,CAACG,OAAOS,QAAQ,CAACD,iBAAiBA,gBAAgB,GAAG;QACvD,OAAO;YAAEL,IAAI;YAAOC,OAAO;QAAiC;IAC9D;IACA,4EAA4E;IAC5E,yBAAyB;IACzB,IAAII,eAAeV,QAAQY,KAAK,GAAG,OAAQ;QACzC,OAAO;YAAEP,IAAI;YAAOC,OAAO;QAA2C;IACxE;IACA,MAAMO,YAAWb,oBAAAA,QAAQa,QAAQ,YAAhBb,oBAAoB;IACrC,MAAMc,mBAAmBrB,UAAUM,uBAAAA,GAAK,CAAC,SAAS,EAAEP;IACpD,IAAIqB,YAAY,CAACC,kBAAkB;QACjC,OAAO;YAAET,IAAI;YAAOC,OAAO;QAA2C;IACxE;IACA,OAAO;QACLD,IAAI;QACJU,QAAQ;YACNd;YACAe,SAAShB,QAAQgB,OAAO;YACxBT;YACAG,cAAcO,KAAKC,KAAK,CAACR;YACzBS,cAAcnB,QAAQY,KAAK;YAC3BQ,eAAepB,QAAQqB,EAAE,CAACC,GAAG;YAC7BC,iBAAiBvB,QAAQqB,EAAE,CAAChC,KAAK;YACjCmC,MAAM/B,UAAUM,uBAAAA,GAAK,CAAC,OAAO,EAAEP;YAC/BiC,SAASZ,WAAWI,KAAKtB,GAAG,CAAC,GAAGO,OAAOW,SAASY,OAAO,KAAK,KAAK,IAAI;YACrEC,WAAWC,QAAQd;YACnBC,kBAAkBD,WAAWC,mBAAmB;QAClD;IACF;AACF;AAEA,uEAAuE,GACvE,OAAO,SAASc,wBAAwBlC,KAAc;QAY5BqB,uBACLA,yBACXA,cAGYA;IAhBpB,IAAI,CAACrB,SAAS,OAAOA,UAAU,UAAU,OAAO;IAChD,MAAMqB,SAASrB;IACf,MAAMO,QAAQC,OAAOa,OAAOd,KAAK;IACjC,IAAI,CAACC,OAAOE,SAAS,CAACH,UAAUA,QAAQ,GAAG,OAAO;IAClD,IAAI,CAAChB,wBAAwBwB,QAAQ,CAACM,OAAOR,OAAO,GAA2B,OAAO;IACtF,OAAO;QACLN;QACAe,SAASd,OAAOa,OAAOC,OAAO,KAAK;QACnCT,SAASQ,OAAOR,OAAO;QACvBG,cAAcR,OAAOa,OAAOL,YAAY,KAAK;QAC7CS,cAAcjB,OAAOa,OAAOI,YAAY,KAAK;QAC7CC,eAAeZ,QAAOO,wBAAAA,OAAOK,aAAa,YAApBL,wBAAwB;QAC9CQ,eAAe,GAAER,0BAAAA,OAAOQ,eAAe,YAAtBR,0BAA0B;QAC3CS,IAAI,GAAET,eAAAA,OAAOS,IAAI,YAAXT,eAAe;QACrBU,SAASvB,OAAOa,OAAOU,OAAO,KAAK;QACnCC,WAAWX,OAAOW,SAAS,KAAK;QAChCZ,gBAAgB,GAAEC,2BAAAA,OAAOD,gBAAgB,YAAvBC,2BAA2B;IAC/C;AACF;AAEA,yBAAyB,GACzB,OAAO,SAASc,cAAc5B,KAAa;IACzC,OAAO,GAAGA,MAAM,CAAC,EAAEA,UAAU,IAAI,SAAS,SAAS;AACrD;AAEA;;;CAGC,GACD,OAAO,SAAS6B,sBACdf,MAAmF,EACnFgB,IAAY,EACZC,UAAkC;IAElC,OACE,CAAC,mBAAmB,EAAEH,cAAcd,OAAOd,KAAK,EAAE,kBAAkB,CAAC,GACrE,CAAC,CAAC,EAAEc,OAAOC,OAAO,CAAC,cAAc,EAAEe,KAAK,GAAG,CAAC,GAC5C,GAAG7C,4BAA4B,CAAC6B,OAAOR,OAAO,CAAC,CAAC,IAAI,EAAEyB,WAAWjB,OAAOL,YAAY,EAAE,CAAC,CAAC;AAE5F"}