@hotmeshio/long-tail 0.10.14 → 0.11.0

package/build/api/escalations/analytics.d.ts

@@ -0,0 +1,6 @@
+import type { LTApiAuth, LTApiResult } from '../../types/sdk';
+import type { AggregateByFacetsInput, TimelineByFacetInput } from '../../types';
+/** Grouped membership/dwell aggregate over the escalation intervals. */
+export declare function aggregateByFacets(input: AggregateByFacetsInput, auth: LTApiAuth): Promise<LTApiResult>;
+/** One entity's ordered interval sequence (gap-preserving). */
+export declare function timelineByFacet(input: TimelineByFacetInput, auth: LTApiAuth): Promise<LTApiResult>;

package/build/api/escalations/analytics.js

@@ -0,0 +1,123 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aggregateByFacets = aggregateByFacets;
+exports.timelineByFacet = timelineByFacet;
+const escalationService = __importStar(require("../../services/escalation"));
+const escalation_1 = require("../../services/escalation");
+const userService = __importStar(require("../../services/user"));
+const features_1 = require("../../modules/features");
+// ── Escalation analytics surface (public) ────────────────────────────────────
+//
+// Grouped/temporal reads over the pond (membership, dwell, timeline). Reads
+// only, but reads that AGGREGATE other operators' items — so the gate is the
+// same broad scope the faceted search uses (read_all per requested role), with
+// one extension: these queries may span roles. A caller must hold read_all on
+// EVERY role in the filter; a filter with no role scope is inherently
+// cross-role and requires a global principal (superadmin / admin). Results are
+// principal-independent once the gate passes, which is what makes the
+// service-layer cache shareable.
+//
+// publicPaceBoard carve-out (mirrors GET /station-metrics, list.ts): with the
+// flag on, any authenticated caller may run aggregates whose group keys are
+// COLUMNS only — those emit counts/seconds, the exact data class the Pace
+// Board already exposes to every login. A groupBy.facets grouping emits facet
+// VALUES (entity ids) as group keys and always takes the strict gate, as does
+// timelineByFacet (an entity's movement history is item-level disclosure).
+async function callerMayReadPonds(userId, roles) {
+    if (await userService.hasGlobalEscalationAccess(userId))
+        return true;
+    if (!roles.length)
+        return false; // whole-pond / cross-role ⇒ global only
+    for (const role of roles) {
+        const scope = await userService.getRoleScope(userId, role);
+        if (scope?.read !== 'all')
+            return false;
+    }
+    return true;
+}
+async function effectiveRoles(query) {
+    // `entity` scopes to its derived system — the gate covers the same roles the
+    // query will actually touch. Resolution throws AnalyticsInputError (→ 400)
+    // for unknown keys, before any scope decision.
+    if (query?.entity) {
+        return (await escalationService.resolveEntitySystem(query.entity)).map((s) => s.role);
+    }
+    if (query?.role)
+        return [query.role];
+    if (query?.roles?.length)
+        return query.roles;
+    return [];
+}
+function deniedMessage(roles) {
+    return roles.length
+        ? `You must hold ${roles.map((r) => `"${r}"`).join(', ')} with full (read_all) scope or be a superadmin`
+        : 'Analytics without a role filter spans every pond — a global (superadmin/admin) principal is required';
+}
+function failure(err) {
+    if (err instanceof escalation_1.AnalyticsInputError)
+        return { status: 400, error: err.message };
+    return { status: 500, error: err.message };
+}
+/** Grouped membership/dwell aggregate over the escalation intervals. */
+async function aggregateByFacets(input, auth) {
+    try {
+        const roles = await effectiveRoles(input?.query);
+        const countsOnly = !input?.groupBy?.facets?.length;
+        const publiclyReadable = countsOnly && (0, features_1.getFeatureFlags)().publicPaceBoard;
+        if (!publiclyReadable && !(await callerMayReadPonds(auth.userId, roles))) {
+            return { status: 403, error: deniedMessage(roles) };
+        }
+        const data = await escalationService.aggregateByFacets(input);
+        return { status: 200, data };
+    }
+    catch (err) {
+        return failure(err);
+    }
+}
+/** One entity's ordered interval sequence (gap-preserving). */
+async function timelineByFacet(input, auth) {
+    try {
+        const roles = await effectiveRoles(input?.query);
+        if (!(await callerMayReadPonds(auth.userId, roles))) {
+            return { status: 403, error: deniedMessage(roles) };
+        }
+        const data = await escalationService.timelineByFacet(input);
+        return { status: 200, data };
+    }
+    catch (err) {
+        return failure(err);
+    }
+}

package/build/api/escalations/index.d.ts

@@ -7,3 +7,4 @@ export { resolveEscalation, resolveBySignalKey, resolveByIds, resolveAllOrNone }
 export { findByMetadata, claimByMetadata, resolveByMetadata } from './metadata';
 export { cancelSingleEscalation, bulkCancel } from './cancel';
 export { searchByFacets, claimGroups, claimByFacets } from './facets';
+export { aggregateByFacets, timelineByFacet } from './analytics';

package/build/api/escalations/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.claimByFacets = exports.claimGroups = exports.searchByFacets = exports.bulkCancel = exports.cancelSingleEscalation = exports.resolveByMetadata = exports.claimByMetadata = exports.findByMetadata = exports.resolveAllOrNone = exports.resolveByIds = exports.resolveBySignalKey = exports.resolveEscalation = exports.bulkTriage = exports.bulkEscalate = exports.bulkAssign = exports.bulkClaim = exports.updatePriority = exports.releaseExpiredClaims = exports.releaseEscalation = exports.claimEscalation = exports.escalateToRole = exports.getEscalationsByWorkflowId = exports.getEscalation = exports.getStationMetrics = exports.getEscalationStats = exports.listFacetKeys = exports.listDistinctTypes = exports.listAvailableEscalations = exports.listEscalations = exports.createEscalation = void 0;
+exports.timelineByFacet = exports.aggregateByFacets = exports.claimByFacets = exports.claimGroups = exports.searchByFacets = exports.bulkCancel = exports.cancelSingleEscalation = exports.resolveByMetadata = exports.claimByMetadata = exports.findByMetadata = exports.resolveAllOrNone = exports.resolveByIds = exports.resolveBySignalKey = exports.resolveEscalation = exports.bulkTriage = exports.bulkEscalate = exports.bulkAssign = exports.bulkClaim = exports.updatePriority = exports.releaseExpiredClaims = exports.releaseEscalation = exports.claimEscalation = exports.escalateToRole = exports.getEscalationsByWorkflowId = exports.getEscalation = exports.getStationMetrics = exports.getEscalationStats = exports.listFacetKeys = exports.listDistinctTypes = exports.listAvailableEscalations = exports.listEscalations = exports.createEscalation = void 0;
 var create_1 = require("./create");
 Object.defineProperty(exports, "createEscalation", { enumerable: true, get: function () { return create_1.createEscalation; } });
 var list_1 = require("./list");
@@ -40,3 +40,6 @@ var facets_1 = require("./facets");
 Object.defineProperty(exports, "searchByFacets", { enumerable: true, get: function () { return facets_1.searchByFacets; } });
 Object.defineProperty(exports, "claimGroups", { enumerable: true, get: function () { return facets_1.claimGroups; } });
 Object.defineProperty(exports, "claimByFacets", { enumerable: true, get: function () { return facets_1.claimByFacets; } });
+var analytics_1 = require("./analytics");
+Object.defineProperty(exports, "aggregateByFacets", { enumerable: true, get: function () { return analytics_1.aggregateByFacets; } });
+Object.defineProperty(exports, "timelineByFacet", { enumerable: true, get: function () { return analytics_1.timelineByFacet; } });

package/build/api/roles.d.ts

@@ -106,6 +106,10 @@ export declare function updateRole(input: {
     priority_threshold_minutes?: number | null;
     /** Escalation metadata key holding the age origin (ISO 8601 UTC timestamp). Falls back to created_at. */
     priority_facet?: string | null;
+    /** Escalation metadata key identifying the entity that moves through this role (e.g. serialNumber). */
+    entity_facet?: string | null;
+    /** How this role names the entity's states: 'role' (the station is the state) or 'subtype'. Null resets to 'role'. */
+    entity_state_source?: 'role' | 'subtype' | null;
     /** Turn server-side resolver schema validation on/off for this role. */
     enforce_schema?: boolean;
     /** Replace the upstream-input set (omitted = preserve; null or [] = clear). */

package/build/api/roles.js

@@ -222,6 +222,12 @@ async function updateRole(input) {
         if (input.priority_facet != null && (typeof input.priority_facet !== 'string' || !facet_sql_1.FACET_KEY.test(input.priority_facet))) {
             return { status: 400, error: 'priority_facet must be a metadata key (letters, numbers, underscores) or null' };
         }
+        if (input.entity_facet != null && (typeof input.entity_facet !== 'string' || !facet_sql_1.FACET_KEY.test(input.entity_facet))) {
+            return { status: 400, error: 'entity_facet must be a metadata key (letters, numbers, underscores) or null' };
+        }
+        if (input.entity_state_source != null && input.entity_state_source !== 'role' && input.entity_state_source !== 'subtype') {
+            return { status: 400, error: "entity_state_source must be 'role', 'subtype', or null" };
+        }
         if (input.ops_visible !== undefined && typeof input.ops_visible !== 'boolean') {
             return { status: 400, error: 'ops_visible must be a boolean' };
         }
@@ -272,6 +278,8 @@ async function updateRole(input) {
             worker_count: input.worker_count,
             priority_threshold_minutes: input.priority_threshold_minutes,
             priority_facet: input.priority_facet,
+            entity_facet: input.entity_facet,
+            entity_state_source: input.entity_state_source,
             enforce_schema: input.enforce_schema,
             upstream_roles: input.upstream_roles,
             change_summary: input.change_summary,

package/build/api/scan-codes/choice.d.ts

@@ -0,0 +1,11 @@
+import { type ScanChoiceExecuteRequest, type ScanExecuteResponse } from '../../types';
+import type { LTApiAuth, LTApiResult } from '../../types/sdk';
+/**
+ * Execute one presented choice. The request is a POINTER — scheme/category/
+ * step/choice indices plus the escalation id the screen showed — and a
+ * pointer is never authority: the choice is re-read from live config, the
+ * row is re-located under the step's query, the identity gate re-applies,
+ * and the verb runs through the same atomic executors a direct scan uses
+ * (so a lost race is a structured CONFLICT, exactly as on double-scan).
+ */
+export declare function executeScanChoice(input: ScanChoiceExecuteRequest, auth: LTApiAuth): Promise<LTApiResult<ScanExecuteResponse>>;

package/build/api/scan-codes/choice.js

@@ -0,0 +1,136 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeScanChoice = executeScanChoice;
+const scanCodeService = __importStar(require("../../services/scan-code"));
+const escalationService = __importStar(require("../../services/escalation"));
+const types_1 = require("../../types");
+const identity_1 = require("./identity");
+const context_1 = require("./context");
+const locate_1 = require("./locate");
+const verbs_1 = require("./verbs");
+/**
+ * Execute one presented choice. The request is a POINTER — scheme/category/
+ * step/choice indices plus the escalation id the screen showed — and a
+ * pointer is never authority: the choice is re-read from live config, the
+ * row is re-located under the step's query, the identity gate re-applies,
+ * and the verb runs through the same atomic executors a direct scan uses
+ * (so a lost race is a structured CONFLICT, exactly as on double-scan).
+ */
+async function executeScanChoice(input, auth) {
+    try {
+        if (!Number.isInteger(input?.schemeVersion) || typeof input?.category !== 'string'
+            || !Number.isInteger(input?.stepIndex) || !Number.isInteger(input?.choiceIndex)
+            || !input?.escalationId) {
+            return { status: 400, error: 'schemeVersion, category, stepIndex, choiceIndex, and escalationId are required' };
+        }
+        // 1. The pointer resolves against LIVE config — an edit between render
+        // and tap is a structured miss, never a stale execution.
+        const scheme = await scanCodeService.getScanScheme(input.schemeVersion);
+        const rule = await scanCodeService.getScanRule(input.schemeVersion, input.category);
+        const step = rule?.steps?.[input.stepIndex];
+        const choice = step?.choices?.[input.choiceIndex];
+        if (!scheme || !scheme.enabled || scheme.kind !== types_1.SCAN_SCHEME_KINDS.ACTION
+            || !rule || !rule.enabled || step?.verb !== types_1.SCAN_VERBS.PRESENT || !choice) {
+            return {
+                status: 200,
+                data: { outcome: types_1.SCAN_OUTCOMES.UNCONFIGURED, error: 'the presented choice is no longer configured' },
+            };
+        }
+        // 2. The acting grant, exchanged before anything reads or writes.
+        let effectiveAuth = auth;
+        let acting = false;
+        if (input.actingToken) {
+            const resolved = await (0, identity_1.resolveActingAuth)(input.actingToken);
+            if (!resolved.ok) {
+                return {
+                    status: 200,
+                    data: { outcome: types_1.SCAN_OUTCOMES.NOT_PRIMED, notPrimed: rule.notPrimed, error: resolved.error },
+                };
+            }
+            effectiveAuth = resolved.auth;
+            acting = true;
+        }
+        // 3. The row anchors the target: the scheme's facet on the escalation the
+        // screen presented. A missing binding is loud misconfiguration.
+        const row = await escalationService.getEscalation(input.escalationId);
+        const target = row?.metadata?.[scheme.target_facet];
+        if (!row || typeof target !== 'string' || !target) {
+            return {
+                status: 200,
+                data: { outcome: types_1.SCAN_OUTCOMES.UNCONFIGURED, error: `escalation does not carry the scheme facet "${scheme.target_facet}"` },
+            };
+        }
+        const ctx = {
+            scheme,
+            rule,
+            parsed: { version: scheme.version, category: rule.category, target },
+            scannedAt: new Date().toISOString(),
+            auth: effectiveAuth,
+            stationAuth: auth,
+            acting,
+        };
+        // 4. The identity gate, per the choice.
+        if (choice.requireActingIdentity && !(await (0, identity_1.actingIdentitySatisfied)(step, ctx))) {
+            return decorate((0, context_1.notPrimed)(ctx), ctx, input);
+        }
+        // 5. The row must still match the step's query — the reality the screen
+        // showed. A row that moved on (resolved, claimed away, re-routed) is the
+        // same double-actor race a second scan loses.
+        const located = await (0, locate_1.locateForStep)(step, ctx, 2);
+        if (!located || !located.escalations.some((e) => e.id === input.escalationId)) {
+            return decorate((0, context_1.conflict)('the item is no longer in the presented state'), ctx, input);
+        }
+        // 6. Dispatch through the same atomic executors a direct scan uses.
+        const synthesized = { query: step.query, verb: choice.verb, params: choice.params };
+        const result = await (0, verbs_1.dispatchChoiceVerb)(synthesized, ctx, located.escalations[0]);
+        return decorate(result, ctx, input);
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/** Stamp the rule + pointer identity onto the outcome, mirroring execute. */
+function decorate(result, ctx, input) {
+    if (result.data && typeof result.data === 'object' && 'outcome' in result.data) {
+        result.data = {
+            ...result.data,
+            parsed: ctx.parsed,
+            rule: { schemeVersion: ctx.rule.scheme_version, category: ctx.rule.category, name: ctx.rule.name },
+            stepIndex: input.stepIndex,
+        };
+    }
+    return result;
+}

package/build/api/scan-codes/context.d.ts

@@ -0,0 +1,24 @@
+import * as scanCodeService from '../../services/scan-code';
+import { type LTEscalationRecord, type ParsedScanCode, type ScanExecuteResponse, type ScanRule, type ScanScheme, type ScanStep } from '../../types';
+import type { LTApiAuth, LTApiResult } from '../../types/sdk';
+/** Everything a step executor needs about the scan that reached it. */
+export interface StepContext {
+    scheme: ScanScheme;
+    rule: ScanRule;
+    parsed: ParsedScanCode;
+    scannedAt: string;
+    /** The effective actor — the acting (badged) user when a grant rode the request. */
+    auth: LTApiAuth;
+    /** The authenticated principal (the device on a station deployment). */
+    stationAuth: LTApiAuth;
+    /** True when `auth` came from an acting-identity grant. */
+    acting: boolean;
+}
+export declare function targetFilter(step: ScanStep, ctx: StepContext): Record<string, any>;
+export declare function templateContext(ctx: StepContext): scanCodeService.ScanTemplateContext;
+export declare function provenance(ctx: StepContext): Record<string, any>;
+export declare function interpolatedMetadata(step: ScanStep, ctx: StepContext): Record<string, any>;
+export declare function executed(escalation: LTEscalationRecord | Record<string, any> | undefined, step: Pick<ScanStep, 'verb'>): LTApiResult<ScanExecuteResponse>;
+export declare function forbidden(error?: string): LTApiResult<ScanExecuteResponse>;
+export declare function conflict(error?: string): LTApiResult<ScanExecuteResponse>;
+export declare function notPrimed(ctx: StepContext): LTApiResult<ScanExecuteResponse>;

package/build/api/scan-codes/context.js

@@ -0,0 +1,86 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.targetFilter = targetFilter;
+exports.templateContext = templateContext;
+exports.provenance = provenance;
+exports.interpolatedMetadata = interpolatedMetadata;
+exports.executed = executed;
+exports.forbidden = forbidden;
+exports.conflict = conflict;
+exports.notPrimed = notPrimed;
+const scanCodeService = __importStar(require("../../services/scan-code"));
+const types_1 = require("../../types");
+function targetFilter(step, ctx) {
+    return { [ctx.scheme.target_facet]: ctx.parsed.target, ...(step.query?.facets ?? {}) };
+}
+function templateContext(ctx) {
+    return { target: ctx.parsed.target, category: ctx.parsed.category, scannedAt: ctx.scannedAt };
+}
+function provenance(ctx) {
+    return {
+        [types_1.SCAN_PROVENANCE_KEYS.SCHEME]: ctx.scheme.version,
+        [types_1.SCAN_PROVENANCE_KEYS.CATEGORY]: ctx.parsed.category,
+        [types_1.SCAN_PROVENANCE_KEYS.ACTION_NAME]: ctx.rule.name,
+        [types_1.SCAN_PROVENANCE_KEYS.SCANNED_AT]: ctx.scannedAt,
+        // Under an acting identity the mutation attributes to the person; the
+        // device where it happened is the other half of the audit pair.
+        ...(ctx.acting ? { [types_1.SCAN_PROVENANCE_KEYS.STATION]: ctx.stationAuth.userId } : {}),
+    };
+}
+function interpolatedMetadata(step, ctx) {
+    return step.params?.metadata
+        ? scanCodeService.interpolateScanTemplate(step.params.metadata, templateContext(ctx))
+        : {};
+}
+function executed(escalation, step) {
+    return { status: 200, data: { outcome: types_1.SCAN_OUTCOMES.EXECUTED, verb: step.verb, escalation } };
+}
+function forbidden(error) {
+    return { status: 200, data: { outcome: types_1.SCAN_OUTCOMES.FORBIDDEN, error } };
+}
+function conflict(error) {
+    return { status: 200, data: { outcome: types_1.SCAN_OUTCOMES.CONFLICT, error } };
+}
+function notPrimed(ctx) {
+    return {
+        status: 200,
+        data: {
+            outcome: types_1.SCAN_OUTCOMES.NOT_PRIMED,
+            notPrimed: ctx.rule.notPrimed,
+            error: 'an acting identity is required — scan your badge',
+        },
+    };
+}

package/build/api/scan-codes/execute.d.ts

@@ -1,5 +1,6 @@
 import { type ScanExecuteRequest, type ScanExecuteResponse } from '../../types';
 import type { LTApiAuth, LTApiResult } from '../../types/sdk';
+export type { StepContext } from './context';
 /**
  * Execute a raw scan code: parse → load the rule → walk its steps in order.
  * The first step whose condition matches performs its verb and answers; a