@hotmeshio/long-tail 0.1.6 → 0.1.8

package/build/api/controlplane.js

@@ -0,0 +1,158 @@
+"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.listApps = listApps;
+exports.rollCall = rollCall;
+exports.applyThrottle = applyThrottle;
+exports.getStreamStats = getStreamStats;
+exports.subscribeMesh = subscribeMesh;
+const controlplane = __importStar(require("../services/controlplane"));
+const events_1 = require("../lib/events");
+/**
+ * List all registered application namespaces.
+ *
+ * @returns `{ status: 200, data: { apps } }` array of known app identifiers
+ */
+async function listApps() {
+    try {
+        const apps = await controlplane.listApps();
+        return { status: 200, data: { apps } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Query active worker profiles for an application.
+ *
+ * Sends a roll-call request to the mesh and collects responses from
+ * all running workers within the optional delay window.
+ *
+ * @param input.appId — application namespace to query (defaults to 'durable')
+ * @param input.delay — milliseconds to wait for worker responses before returning
+ * @returns `{ status: 200, data: { profiles } }` array of worker profile objects
+ */
+async function rollCall(input) {
+    try {
+        const appId = input.appId || 'durable';
+        const profiles = await controlplane.rollCall(appId, input.delay);
+        return { status: 200, data: { profiles } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Apply a throttle rate to workflow execution.
+ *
+ * Sets the throttle value for a specific topic or workflow within an app
+ * namespace. Also publishes a synthetic `mesh.throttle` event so the
+ * dashboard event stream reflects the change.
+ *
+ * @param input.appId — application namespace (defaults to 'durable')
+ * @param input.throttle — throttle value to apply (required, must be a number)
+ * @param input.topic — optional topic to scope the throttle to
+ * @param input.guid — optional workflow GUID to scope the throttle to
+ * @returns `{ status: 200, data: { success } }` boolean indicating the throttle was applied
+ */
+async function applyThrottle(input) {
+    try {
+        const appId = input.appId || 'durable';
+        if (typeof input.throttle !== 'number') {
+            return { status: 400, error: 'throttle (number) is required' };
+        }
+        const result = await controlplane.applyThrottle(appId, {
+            throttle: input.throttle,
+            topic: input.topic,
+            guid: input.guid,
+        });
+        // Publish a synthetic event so the dashboard event stream sees it
+        const throttleEvent = {
+            type: 'mesh.throttle',
+            source: 'controlplane',
+            workflowId: input.guid || '',
+            workflowName: '',
+            taskQueue: appId,
+            data: { throttle: input.throttle, topic: input.topic, guid: input.guid, appId },
+            timestamp: new Date().toISOString(),
+        };
+        events_1.eventRegistry.publish(throttleEvent).catch(() => { });
+        return { status: 200, data: { success: result } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Retrieve stream statistics for an application.
+ *
+ * Returns throughput and backlog metrics for Redis streams backing the
+ * given app namespace over the specified time window.
+ *
+ * @param input.app_id — application namespace (defaults to 'durable')
+ * @param input.duration — time window for stats aggregation, e.g. '1h', '30m' (defaults to '1h')
+ * @param input.stream — optional specific stream name to filter results
+ * @returns `{ status: 200, data: { ... } }` stream statistics object
+ */
+async function getStreamStats(input) {
+    try {
+        const schema = input.app_id || 'durable';
+        const duration = input.duration || '1h';
+        const stats = await controlplane.getStreamStats(schema, duration, input.stream);
+        return { status: 200, data: stats };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Subscribe to mesh events for an application.
+ *
+ * Establishes a subscription to the event stream of the given app
+ * namespace so that mesh events are captured and forwarded.
+ *
+ * @param input.appId — application namespace to subscribe to (defaults to 'durable')
+ * @returns `{ status: 200, data: { subscribed, appId } }` confirmation with the subscribed app ID
+ */
+async function subscribeMesh(input) {
+    try {
+        const appId = input.appId || 'durable';
+        await controlplane.subscribeMesh(appId);
+        return { status: 200, data: { subscribed: true, appId } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}

package/build/api/dba.d.ts

@@ -0,0 +1,42 @@
+import type { LTApiResult } from '../types/sdk';
+/**
+ * Prune stale HotMesh data from Redis.
+ *
+ * Selectively removes completed jobs, stream entries, engine/worker
+ * streams, and search attributes. Delegates to the HotMesh DBA service.
+ *
+ * @param input.expire — Redis TTL expression for pruned keys
+ * @param input.jobs — prune completed job hashes
+ * @param input.streams — prune activity streams
+ * @param input.engineStreams — prune engine consumer streams
+ * @param input.engineStreamsExpire — TTL for engine stream entries
+ * @param input.workerStreams — prune worker consumer streams
+ * @param input.workerStreamsExpire — TTL for worker stream entries
+ * @param input.attributes — prune FT.SEARCH attributes
+ * @param input.entities — limit pruning to these entity types
+ * @param input.pruneTransient — include transient keys
+ * @param input.keepHmark — preserve hmark keys
+ * @returns `{ status: 200, data: <prune result summary> }`
+ */
+export declare function prune(input: {
+    expire?: string;
+    jobs?: boolean;
+    streams?: boolean;
+    engineStreams?: boolean;
+    engineStreamsExpire?: string;
+    workerStreams?: boolean;
+    workerStreamsExpire?: string;
+    attributes?: boolean;
+    entities?: string[];
+    pruneTransient?: boolean;
+    keepHmark?: boolean;
+}): Promise<LTApiResult>;
+/**
+ * Deploy (or redeploy) all HotMesh workflow schemas.
+ *
+ * Triggers a full schema deployment across all registered entities,
+ * updating the Redis execution graph. Safe to call repeatedly.
+ *
+ * @returns `{ status: 200, data: { ok: true } }`
+ */
+export declare function deploy(): Promise<LTApiResult>;

package/build/api/dba.js

@@ -0,0 +1,95 @@
+"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.prune = prune;
+exports.deploy = deploy;
+const dbaService = __importStar(require("../services/dba"));
+/**
+ * Prune stale HotMesh data from Redis.
+ *
+ * Selectively removes completed jobs, stream entries, engine/worker
+ * streams, and search attributes. Delegates to the HotMesh DBA service.
+ *
+ * @param input.expire — Redis TTL expression for pruned keys
+ * @param input.jobs — prune completed job hashes
+ * @param input.streams — prune activity streams
+ * @param input.engineStreams — prune engine consumer streams
+ * @param input.engineStreamsExpire — TTL for engine stream entries
+ * @param input.workerStreams — prune worker consumer streams
+ * @param input.workerStreamsExpire — TTL for worker stream entries
+ * @param input.attributes — prune FT.SEARCH attributes
+ * @param input.entities — limit pruning to these entity types
+ * @param input.pruneTransient — include transient keys
+ * @param input.keepHmark — preserve hmark keys
+ * @returns `{ status: 200, data: <prune result summary> }`
+ */
+async function prune(input) {
+    try {
+        const result = await dbaService.prune({
+            expire: input.expire,
+            jobs: input.jobs,
+            streams: input.streams,
+            engineStreams: input.engineStreams,
+            engineStreamsExpire: input.engineStreamsExpire,
+            workerStreams: input.workerStreams,
+            workerStreamsExpire: input.workerStreamsExpire,
+            attributes: input.attributes,
+            entities: input.entities,
+            pruneTransient: input.pruneTransient,
+            keepHmark: input.keepHmark,
+        });
+        return { status: 200, data: result };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Deploy (or redeploy) all HotMesh workflow schemas.
+ *
+ * Triggers a full schema deployment across all registered entities,
+ * updating the Redis execution graph. Safe to call repeatedly.
+ *
+ * @returns `{ status: 200, data: { ok: true } }`
+ */
+async function deploy() {
+    try {
+        await dbaService.deploy();
+        return { status: 200, data: { ok: true } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}

package/build/api/escalations.d.ts

@@ -0,0 +1,271 @@
+import type { LTApiResult, LTApiAuth } from '../types/sdk';
+/**
+ * Create a standalone escalation (not tied to a workflow).
+ *
+ * Useful for manual work items, support tickets, or approval requests
+ * that originate outside the durable workflow engine. The caller must
+ * hold the target role or be a superadmin.
+ *
+ * @param input.type — escalation category (e.g. `"support"`, `"approval"`)
+ * @param input.subtype — subcategory for finer routing
+ * @param input.role — role responsible for resolving this escalation
+ * @param input.description — human-readable summary
+ * @param input.priority — 1 (critical) through 4 (low), default 2
+ * @param input.envelope — serialized context for the resolver
+ * @param input.metadata — arbitrary key-value data (e.g. signal_routing)
+ * @param input.escalation_payload — serialized payload for the resolver UI
+ * @param auth — authenticated user context (must hold target role or be superadmin)
+ * @returns `{ status: 201, data: <escalation record> }`
+ */
+export declare function createEscalation(input: {
+    type: string;
+    subtype?: string;
+    role: string;
+    description?: string;
+    priority?: number;
+    envelope?: string;
+    metadata?: Record<string, any>;
+    escalation_payload?: string;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * List escalations with optional filters.
+ *
+ * Results are scoped to the authenticated user's roles unless the user
+ * is a superadmin (who sees all roles).
+ *
+ * @param input.status — filter by `pending`, `resolved`, or `cancelled`
+ * @param input.role — filter by assigned role
+ * @param input.type — filter by workflow type
+ * @param input.subtype — filter by subtype
+ * @param input.assigned_to — filter by assigned user ID
+ * @param input.priority — filter by priority (1–4)
+ * @param input.limit — max results (default: 50)
+ * @param input.offset — pagination offset
+ * @param input.sort_by — column to sort by (e.g. `created_at`, `priority`)
+ * @param input.order — `asc` or `desc`
+ * @param auth — authenticated user context (required for role scoping)
+ * @returns `{ status: 200, data: { escalations, total } }`
+ */
+export declare function listEscalations(input: {
+    status?: string;
+    role?: string;
+    type?: string;
+    subtype?: string;
+    assigned_to?: string;
+    priority?: number;
+    limit?: number;
+    offset?: number;
+    sort_by?: string;
+    order?: string;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * List escalations available for claim (pending and not actively claimed).
+ *
+ * Similar to `listEscalations` but excludes escalations with active claims.
+ * Scoped to the authenticated user's roles.
+ *
+ * @param input.role — filter by role
+ * @param input.type — filter by workflow type
+ * @param input.subtype — filter by subtype
+ * @param input.priority — filter by priority (1–4)
+ * @param input.limit — max results (default: 50)
+ * @param input.offset — pagination offset
+ * @param input.sort_by — column to sort by
+ * @param input.order — `asc` or `desc`
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { escalations, total } }`
+ */
+export declare function listAvailableEscalations(input: {
+    role?: string;
+    type?: string;
+    subtype?: string;
+    priority?: number;
+    limit?: number;
+    offset?: number;
+    sort_by?: string;
+    order?: string;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * List all distinct escalation type values.
+ *
+ * @returns `{ status: 200, data: { types: string[] } }`
+ */
+export declare function listDistinctTypes(): Promise<LTApiResult>;
+/**
+ * Get aggregate escalation statistics scoped to the user's roles.
+ *
+ * @param input.period — time window (`1h`, `24h`, `7d`, `30d`)
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { pending, claimed, created, resolved, by_role, by_type } }`
+ */
+export declare function getEscalationStats(input: {
+    period?: string;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Get a single escalation by ID.
+ *
+ * Non-superadmin users must hold the escalation's assigned role.
+ *
+ * @param input.id — escalation UUID
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: <escalation record> }` or 403/404
+ */
+export declare function getEscalation(input: {
+    id: string;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * List all escalations for a given workflow ID.
+ *
+ * @param input.workflowId — HotMesh workflow ID
+ * @returns `{ status: 200, data: { escalations } }`
+ */
+export declare function getEscalationsByWorkflowId(input: {
+    workflowId: string;
+}): Promise<LTApiResult>;
+/**
+ * Route a pending escalation to a different role.
+ *
+ * The user must be authorized to escalate from the current role to the
+ * target role (checked via escalation chain configuration).
+ *
+ * @param input.id — escalation UUID
+ * @param input.targetRole — destination role
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: <updated escalation> }` or 403/404/409
+ */
+export declare function escalateToRole(input: {
+    id: string;
+    targetRole: string;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Claim a pending escalation for the authenticated user.
+ *
+ * Sets `assigned_to` and `assigned_until` on the escalation (soft lock).
+ * Non-superadmin users must hold the escalation's role. Publishes a
+ * `escalation.claimed` event.
+ *
+ * @param input.id — escalation UUID
+ * @param input.durationMinutes — claim duration (default: 30)
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { escalation, isExtension } }` or 403/404/409
+ */
+export declare function claimEscalation(input: {
+    id: string;
+    durationMinutes?: number;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Release a claimed escalation back to the pool.
+ *
+ * Only the user who holds the claim can release it. Publishes a
+ * `escalation.released` event.
+ *
+ * @param input.id — escalation UUID
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { escalation } }` or 409
+ */
+export declare function releaseEscalation(input: {
+    id: string;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Release all escalation claims past their `assigned_until` deadline.
+ *
+ * Typically called on a maintenance schedule. Returns the count of
+ * released claims.
+ *
+ * @returns `{ status: 200, data: { released: number } }`
+ */
+export declare function releaseExpiredClaims(): Promise<LTApiResult>;
+/**
+ * Update priority for one or more escalations.
+ *
+ * @param input.ids — array of escalation UUIDs
+ * @param input.priority — new priority (1=critical, 2=high, 3=medium, 4=low)
+ * @param auth — authenticated user context (admin or role-holder required)
+ * @returns `{ status: 200, data: { updated: number } }`
+ */
+export declare function updatePriority(input: {
+    ids: string[];
+    priority: number;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Claim multiple escalations at once for the authenticated user.
+ *
+ * @param input.ids — array of escalation UUIDs
+ * @param input.durationMinutes — claim duration (default: 30)
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { claimed, skipped } }`
+ */
+export declare function bulkClaim(input: {
+    ids: string[];
+    durationMinutes?: number;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Assign multiple escalations to a specific user.
+ *
+ * Non-superadmin callers must verify the target user holds each
+ * escalation's role. Publishes claim events for assigned items.
+ *
+ * @param input.ids — array of escalation UUIDs
+ * @param input.targetUserId — user to assign to
+ * @param input.durationMinutes — assignment duration (default: 30)
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { assigned, skipped } }`
+ */
+export declare function bulkAssign(input: {
+    ids: string[];
+    targetUserId: string;
+    durationMinutes?: number;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Route multiple escalations to a different role.
+ *
+ * @param input.ids — array of escalation UUIDs
+ * @param input.targetRole — destination role
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { updated: number } }`
+ */
+export declare function bulkEscalate(input: {
+    ids: string[];
+    targetRole: string;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Trigger AI triage for multiple escalations.
+ *
+ * Resolves each escalation and starts a triage workflow that uses MCP
+ * tools to analyze and potentially auto-resolve the issue.
+ *
+ * @param input.ids — array of escalation UUIDs
+ * @param input.hint — optional natural-language guidance for the triage AI
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { triaged, workflows } }`
+ */
+export declare function bulkTriage(input: {
+    ids: string[];
+    hint?: string;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Resolve a pending escalation with a human-provided payload.
+ *
+ * Handles two resolution paths:
+ * 1. **Signal-routed** — if the escalation has `signal_routing` metadata,
+ *    the resolver payload is sent directly to the paused workflow via
+ *    `handle.signal()`. Supports both Durable and YAML engines.
+ * 2. **Re-run** — the original workflow is re-started with the resolver
+ *    payload injected into `envelope.resolver`. The interceptor detects
+ *    the re-run and skips to the resolution branch.
+ *
+ * Password fields in the resolver payload are replaced with ephemeral
+ * tokens (15-minute TTL) so plaintext never enters the signal store.
+ *
+ * Supports optional escalation strategy execution after resolution.
+ *
+ * @param input.id — escalation UUID
+ * @param input.resolverPayload — human decision data
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { signaled, escalationId, workflowId } }` (signal path)
+ *          or `{ status: 200, data: { workflowId, resumed, escalationId } }` (re-run path)
+ */
+export declare function resolveEscalation(input: {
+    id: string;
+    resolverPayload: Record<string, any>;
+}, auth: LTApiAuth): Promise<LTApiResult>;