@hotmeshio/long-tail 0.22.0 → 0.22.2

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

@@ -0,0 +1,68 @@
+"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.resolveSubject = resolveSubject;
+exports.claimedByOther = claimedByOther;
+const scanCodeService = __importStar(require("../../services/scan-code"));
+const escalationService = __importStar(require("../../services/escalation"));
+const userService = __importStar(require("../../services/user"));
+const uuid_1 = require("../../lib/uuid");
+const helpers_1 = require("../escalations/helpers");
+const types_1 = require("../../types");
+async function resolveSubject(ref, schemes, stationAuth) {
+    if (!ref)
+        return null;
+    if (typeof ref.code !== 'string' || !(0, uuid_1.isUuid)(ref.escalationId))
+        return { ok: false };
+    const parsed = scanCodeService.parseScanCode(ref.code, schemes);
+    if (!parsed.ok || parsed.scheme.kind !== types_1.SCAN_SCHEME_KINDS.ACTION)
+        return { ok: false };
+    const row = await escalationService.getEscalation(ref.escalationId);
+    if (!row || row.status !== 'pending')
+        return { ok: false };
+    if (await (0, helpers_1.assertReadAccess)(stationAuth.userId, row))
+        return { ok: false };
+    if (row.metadata?.[parsed.scheme.target_facet] !== parsed.parsed.target) {
+        return { ok: false };
+    }
+    return { ok: true, subject: { row, parsed: parsed.parsed, scheme: parsed.scheme, code: ref.code } };
+}
+/** Who holds a live claim on the row, when that is someone other than `actorId`. */
+async function claimedByOther(row, actorId) {
+    if (!row.assigned_to || !(0, types_1.isEffectivelyClaimed)(row) || row.assigned_to === actorId)
+        return null;
+    const user = await userService.getUser(row.assigned_to);
+    return { id: row.assigned_to, displayName: user?.display_name || user?.external_id || 'another associate' };
+}

package/build/api/scan-codes/verb-accumulate.d.ts

@@ -0,0 +1,24 @@
+import { type ScanExecuteResponse, type ScanStep } from '../../types';
+import type { LTApiResult } from '../../types/sdk';
+import { type StepContext } from './context';
+/**
+ * Adds the scanned item to an accumulator. Two modes, one atomic write:
+ *
+ * - Item-locate (`params.accumulate.containerFacet`): the scan locates the
+ *   item's own pending row through the scheme facet, reads the container
+ *   facet value it carries, and adds the target to the container that shares
+ *   it, writing the item row as the reciprocal in the same statement. An
+ *   item with no row, or no container facet, falls through. An item whose
+ *   container has closed and whose successor has not parked yet answers
+ *   `no_open_container` with the item row, so the station can say "scan
+ *   again" instead of showing the item with no hint.
+ * - Container-locate (no `containerFacet`): the scan locates the container
+ *   by the scheme facet and adds `params.itemKey` (template).
+ *
+ * Templates may read `{claim.<facet>}` (the actor's live claim) and, in item
+ * mode, `{item.<facet>}` (the located row); an unresolvable token falls
+ * through. The write is the SDK's guarded statement; the locate only picks
+ * ids. A container already holding the item answers conflict, never a
+ * second add.
+ */
+export declare function accumulateStep(step: ScanStep, ctx: StepContext): Promise<LTApiResult<ScanExecuteResponse> | null>;

package/build/api/scan-codes/verb-accumulate.js

@@ -0,0 +1,147 @@
+"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.accumulateStep = accumulateStep;
+const scanCodeService = __importStar(require("../../services/scan-code"));
+const accumulate_1 = require("../escalations/accumulate");
+const types_1 = require("../../types");
+const context_1 = require("./context");
+const grant_1 = require("./grant");
+const locate_1 = require("./locate");
+const verbs_subject_1 = require("./verbs-subject");
+/**
+ * Adds the scanned item to an accumulator. Two modes, one atomic write:
+ *
+ * - Item-locate (`params.accumulate.containerFacet`): the scan locates the
+ *   item's own pending row through the scheme facet, reads the container
+ *   facet value it carries, and adds the target to the container that shares
+ *   it, writing the item row as the reciprocal in the same statement. An
+ *   item with no row, or no container facet, falls through. An item whose
+ *   container has closed and whose successor has not parked yet answers
+ *   `no_open_container` with the item row, so the station can say "scan
+ *   again" instead of showing the item with no hint.
+ * - Container-locate (no `containerFacet`): the scan locates the container
+ *   by the scheme facet and adds `params.itemKey` (template).
+ *
+ * Templates may read `{claim.<facet>}` (the actor's live claim) and, in item
+ * mode, `{item.<facet>}` (the located row); an unresolvable token falls
+ * through. The write is the SDK's guarded statement; the locate only picks
+ * ids. A container already holding the item answers conflict, never a
+ * second add.
+ */
+async function accumulateStep(step, ctx) {
+    const options = step.params?.accumulate;
+    if (options?.from === 'subject')
+        return (0, verbs_subject_1.accumulateFromSubject)(step, ctx);
+    if (options?.into === 'subject')
+        return (0, verbs_subject_1.accumulateIntoSubject)(step, ctx);
+    let item;
+    if (options?.containerFacet) {
+        const located = await (0, locate_1.locateForStep)(step, ctx, 1);
+        item = located?.escalations[0];
+        if (!item)
+            return null;
+    }
+    const rendered = await (0, context_1.templated)(step, ctx, (tpl) => ({
+        payload: step.params?.resolverPayload
+            ? scanCodeService.interpolateScanTemplate(step.params.resolverPayload, tpl)
+            : undefined,
+        metadata: { ...(0, context_1.interpolatedMetadata)(step, ctx, tpl), ...(0, context_1.provenance)(ctx) },
+        itemKey: options?.containerFacet
+            ? ctx.parsed.target
+            : scanCodeService.interpolateScanTemplate(step.params.itemKey, tpl),
+    }), item);
+    if (rendered === null)
+        return null;
+    let request;
+    let container;
+    if (options?.containerFacet && item) {
+        const containerValue = item.metadata?.[options.containerFacet];
+        if (containerValue === undefined || containerValue === null || containerValue === '')
+            return null;
+        container = { facet: options.containerFacet, value: String(containerValue) };
+        request = {
+            key: container.facet,
+            value: container.value,
+            itemKey: rendered.itemKey,
+            payload: rendered.payload,
+            metadata: rendered.metadata,
+            restrictRoles: options.container?.roles ?? options.containerRoles,
+            container: options.container
+                ? { types: options.container.types, subtypes: options.container.subtypes, facets: options.container.facets }
+                : undefined,
+            ...(options.reciprocal === false ? {} : { reciprocal: { id: item.id } }),
+        };
+    }
+    else {
+        request = {
+            key: ctx.scheme.target_facet,
+            value: ctx.parsed.target,
+            itemKey: rendered.itemKey,
+            payload: rendered.payload,
+            metadata: rendered.metadata,
+            restrictRoles: step.query?.roles,
+        };
+    }
+    const notPrimed = await (0, grant_1.spendGrant)(ctx);
+    if (notPrimed)
+        return notPrimed;
+    const result = await (0, accumulate_1.accumulateItemByMetadata)(request, ctx.auth);
+    if (result.status === 404) {
+        if (!container || !item)
+            return null;
+        return {
+            status: 200,
+            data: {
+                outcome: types_1.SCAN_OUTCOMES.NO_OPEN_CONTAINER,
+                verb: step.verb,
+                escalation: item,
+                container,
+                fallback: ctx.rule.fallback,
+                error: `No open container carries ${container.facet} = ${container.value}`,
+            },
+        };
+    }
+    if (result.status === 403)
+        return (0, context_1.forbidden)(result.error);
+    if (result.status === 409)
+        return (0, context_1.conflict)(result.error);
+    if (result.status === 400 || result.status === 422)
+        return (0, context_1.refused)(result.error ?? 'the item was not accepted');
+    if (result.status !== 200)
+        return result;
+    const escalation = result.data.escalationId ? { id: result.data.escalationId, ...result.data } : undefined;
+    return (0, context_1.executed)(escalation, step);
+}

package/build/api/scan-codes/verb-fill.d.ts

@@ -0,0 +1,6 @@
+import { type ScanExecuteResponse, type ScanStep } from '../../types';
+import type { LTApiResult } from '../../types/sdk';
+import { type StepContext } from './context';
+type ScanResult = LTApiResult<ScanExecuteResponse>;
+export declare function fillStep(step: ScanStep, ctx: StepContext): Promise<ScanResult | null>;
+export {};

package/build/api/scan-codes/verb-fill.js

@@ -0,0 +1,152 @@
+"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.fillStep = fillStep;
+const scanCodeService = __importStar(require("../../services/scan-code"));
+const escalationService = __importStar(require("../../services/escalation"));
+const resolve_batch_1 = require("../escalations/resolve-batch");
+const escalation_1 = require("../../types/escalation");
+const types_1 = require("../../types");
+const context_1 = require("./context");
+const grant_1 = require("./grant");
+const locate_1 = require("./locate");
+const subject_1 = require("./subject");
+const STOCK_UNEXPECTED = 'Not one of the items expected here.';
+function readBatch(row) {
+    const meta = (row.metadata ?? {});
+    const pending = meta[escalation_1.ESCALATION_BATCH_KEYS.PENDING];
+    const keys = meta[escalation_1.ESCALATION_BATCH_KEYS.KEYS];
+    if (!Array.isArray(pending))
+        return null;
+    return { pending: pending.map(String), keys: Array.isArray(keys) ? keys.map(String) : pending.map(String) };
+}
+/** The code a batch key names, without its ordinal suffix. */
+function codeOf(key, separator) {
+    const at = key.lastIndexOf(separator);
+    return at > 0 && /^[0-9]+$/.test(key.slice(at + 1)) ? key.slice(0, at) : key;
+}
+function keysFor(keys, target, separator) {
+    return keys.filter((k) => codeOf(k, separator) === target);
+}
+function progress(batch, filledNow) {
+    const remaining = Math.max(0, batch.pending.length - filledNow);
+    return { filled: batch.keys.length - remaining, total: batch.keys.length, remaining };
+}
+async function fillStep(step, ctx) {
+    const options = step.params.fill;
+    const separator = options.separator ?? types_1.SCAN_FILL_SEPARATOR_DEFAULT;
+    // 1. The batch row: the held subject, or the row the scan names
+    const row = options.into === 'subject'
+        ? ctx.subject.row
+        : (await (0, locate_1.locateForStep)(step, ctx, 1))?.escalations[0];
+    if (!row)
+        return null;
+    if (options.into === 'subject' && step.subject?.claimedByOther !== 'allow') {
+        const other = await (0, subject_1.claimedByOther)(row, ctx.auth.userId);
+        if (other)
+            return (0, context_1.refused)(`Claimed by **${other.displayName}**.`);
+    }
+    const batch = readBatch(row);
+    if (!batch)
+        return (0, context_1.conflict)('the held row is not a batch');
+    // 2. Which open slot this scan fills, or why none
+    const tpl = {
+        ...(0, context_1.templateContext)(ctx),
+        fill: {
+            pending: [...new Set(batch.pending.map((k) => codeOf(k, separator)))],
+            total: batch.keys.length,
+            filled: batch.keys.length - batch.pending.length,
+        },
+    };
+    const candidates = keysFor(batch.pending, ctx.parsed.target, separator);
+    if (candidates.length === 0) {
+        const declared = keysFor(batch.keys, ctx.parsed.target, separator);
+        const markdown = declared.length
+            ? `All ${declared.length} of these are already checked off.`
+            : scanCodeService.renderScanCopy(step.refuse?.markdown ?? STOCK_UNEXPECTED, tpl);
+        return (0, context_1.refused)(markdown, {
+            refusal: { markdown, expected: tpl.fill.pending },
+            progress: progress(batch, 0),
+        });
+    }
+    // 3. Spend the badge, then fill; a slot taken since the read moves to the next
+    let payload;
+    try {
+        payload = scanCodeService.interpolateScanTemplate(options.payload ?? { scannedCode: '{scan.code}' }, tpl);
+    }
+    catch (err) {
+        if (err instanceof scanCodeService.ScanTemplateError)
+            return null;
+        throw err;
+    }
+    const notPrimed = (await (0, grant_1.identityGate)(step, ctx)) ?? (await (0, grant_1.spendGrant)(ctx));
+    if (notPrimed)
+        return notPrimed;
+    for (const itemKey of candidates) {
+        const result = await (0, resolve_batch_1.resolveBatchItem)({
+            id: row.id, itemKey, resolverPayload: payload, metadata: (0, context_1.provenance)(ctx),
+        }, ctx.auth);
+        if (result.status === 200) {
+            const data = result.data;
+            const done = data.outcome === 'completed';
+            const filled = progress(batch, batch.pending.length - (done ? 0 : (data.remaining ?? 0)));
+            return (0, context_1.withDone)({
+                status: 200,
+                data: {
+                    outcome: types_1.SCAN_OUTCOMES.EXECUTED,
+                    verb: step.verb,
+                    escalation: { id: row.id, ...data },
+                    progress: filled,
+                    ...(done ? { clearSubject: true } : {}),
+                },
+            }, step, { ...tpl, fill: { ...tpl.fill, ...filled } });
+        }
+        const outcome = result.data?.outcome;
+        if (outcome === 'duplicate-item')
+            continue;
+        if (result.status === 403)
+            return (0, context_1.forbidden)(result.error);
+        if (result.status === 404)
+            return null;
+        if (outcome?.startsWith('already-'))
+            return (0, context_1.refused)('This one is already complete.', { clearSubject: true });
+        return (0, context_1.refused)(result.error ?? STOCK_UNEXPECTED);
+    }
+    const fresh = await escalationService.getEscalation(row.id);
+    const after = fresh ? readBatch(fresh) : null;
+    return (0, context_1.refused)(`All ${keysFor(batch.keys, ctx.parsed.target, separator).length} of these are already checked off.`, {
+        ...(after ? { progress: progress(after, 0) } : {}),
+    });
+}

package/build/api/scan-codes/verbs-subject.d.ts

@@ -0,0 +1,14 @@
+import { type LTEscalationRecord, type ScanExecuteResponse, type ScanStep } from '../../types';
+import type { LTApiResult } from '../../types/sdk';
+import { type StepContext } from './context';
+type ScanResult = LTApiResult<ScanExecuteResponse>;
+/**
+ * The pre-write guard. Returns the refusal when the pairing is wrong, null
+ * when it holds (or the step declares no match).
+ */
+export declare function matchGuard(step: ScanStep, ctx: StepContext, container?: LTEscalationRecord): ScanResult | null;
+/** The subject joins the scanned container; the subject's row is the reciprocal. */
+export declare function accumulateFromSubject(step: ScanStep, ctx: StepContext): Promise<ScanResult | null>;
+/** The subject's own row collects the scanned code. */
+export declare function accumulateIntoSubject(step: ScanStep, ctx: StepContext): Promise<ScanResult | null>;
+export {};