@hotmeshio/long-tail 0.1.6 → 0.1.8

package/build/api/roles.d.ts

@@ -0,0 +1,88 @@
+import type { LTApiResult } from '../types/sdk';
+/**
+ * List all distinct role names in the system.
+ *
+ * @returns `{ status: 200, data: { roles: string[] } }` on success
+ */
+export declare function listRoles(): Promise<LTApiResult>;
+/**
+ * List all roles with their full details (member counts, escalation chains, etc.).
+ *
+ * @returns `{ status: 200, data: { roles: RoleDetail[] } }` on success
+ */
+export declare function listRolesWithDetails(): Promise<LTApiResult>;
+/**
+ * Create a new role. Requires admin privileges.
+ *
+ * The role name is trimmed, lowercased, and validated against the pattern
+ * `^[a-z][a-z0-9_-]*$` (must start with a letter, then lowercase alphanumerics,
+ * hyphens, or underscores).
+ *
+ * @param input.role — the role name to create
+ * @returns `{ status: 201, data: { role: string } }` on success
+ */
+export declare function createRole(input: {
+    role: string;
+}): Promise<LTApiResult>;
+/**
+ * Retrieve all escalation chains across all roles.
+ *
+ * @returns `{ status: 200, data: { chains: EscalationChain[] } }` on success
+ */
+export declare function getEscalationChains(): Promise<LTApiResult>;
+/**
+ * Add an escalation chain link from one role to another. Requires admin privileges.
+ *
+ * @param input.source_role — the role that escalates from
+ * @param input.target_role — the role that receives the escalation
+ * @returns `{ status: 201, data: { source_role, target_role } }` on success
+ */
+export declare function addEscalationChain(input: {
+    source_role: string;
+    target_role: string;
+}): Promise<LTApiResult>;
+/**
+ * Remove an escalation chain link between two roles. Requires admin privileges.
+ *
+ * @param input.source_role — the role that escalates from
+ * @param input.target_role — the role that receives the escalation
+ * @returns `{ status: 200, data: { removed: true } }` on success, or `{ status: 404 }` if not found
+ */
+export declare function removeEscalationChain(input: {
+    source_role: string;
+    target_role: string;
+}): Promise<LTApiResult>;
+/**
+ * Get all escalation target roles for a given source role.
+ *
+ * @param input.role — the source role to look up escalation targets for
+ * @returns `{ status: 200, data: { targets: string[] } }` on success
+ */
+export declare function getEscalationTargets(input: {
+    role: string;
+}): Promise<LTApiResult>;
+/**
+ * Replace all escalation targets for a role with a new set. Requires admin privileges.
+ *
+ * Removes all existing escalation links from the source role and creates new
+ * ones for each target in the provided array.
+ *
+ * @param input.role — the source role whose targets are being replaced
+ * @param input.targets — array of target role names to set as the new escalation targets
+ * @returns `{ status: 200, data: { role, targets } }` on success
+ */
+export declare function replaceEscalationTargets(input: {
+    role: string;
+    targets: string[];
+}): Promise<LTApiResult>;
+/**
+ * Delete a role from the system. Requires admin privileges.
+ *
+ * Returns 409 if the role cannot be deleted (e.g., still assigned to users).
+ *
+ * @param input.role — the role name to delete
+ * @returns `{ status: 200, data: { deleted: true } }` on success, or `{ status: 409 }` if deletion blocked
+ */
+export declare function deleteRole(input: {
+    role: string;
+}): Promise<LTApiResult>;

package/build/api/roles.js

@@ -0,0 +1,217 @@
+"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.listRoles = listRoles;
+exports.listRolesWithDetails = listRolesWithDetails;
+exports.createRole = createRole;
+exports.getEscalationChains = getEscalationChains;
+exports.addEscalationChain = addEscalationChain;
+exports.removeEscalationChain = removeEscalationChain;
+exports.getEscalationTargets = getEscalationTargets;
+exports.replaceEscalationTargets = replaceEscalationTargets;
+exports.deleteRole = deleteRole;
+const roleService = __importStar(require("../services/role"));
+/**
+ * List all distinct role names in the system.
+ *
+ * @returns `{ status: 200, data: { roles: string[] } }` on success
+ */
+async function listRoles() {
+    try {
+        const roles = await roleService.listDistinctRoles();
+        return { status: 200, data: { roles } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * List all roles with their full details (member counts, escalation chains, etc.).
+ *
+ * @returns `{ status: 200, data: { roles: RoleDetail[] } }` on success
+ */
+async function listRolesWithDetails() {
+    try {
+        const roles = await roleService.listRolesWithDetails();
+        return { status: 200, data: { roles } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Create a new role. Requires admin privileges.
+ *
+ * The role name is trimmed, lowercased, and validated against the pattern
+ * `^[a-z][a-z0-9_-]*$` (must start with a letter, then lowercase alphanumerics,
+ * hyphens, or underscores).
+ *
+ * @param input.role — the role name to create
+ * @returns `{ status: 201, data: { role: string } }` on success
+ */
+async function createRole(input) {
+    try {
+        if (!input.role || typeof input.role !== 'string' || !input.role.trim()) {
+            return { status: 400, error: 'role is required' };
+        }
+        const trimmed = input.role.trim().toLowerCase();
+        if (!/^[a-z][a-z0-9_-]*$/.test(trimmed)) {
+            return {
+                status: 400,
+                error: 'Role must start with a letter and contain only lowercase letters, numbers, hyphens, and underscores',
+            };
+        }
+        await roleService.createRole(trimmed);
+        return { status: 201, data: { role: trimmed } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Retrieve all escalation chains across all roles.
+ *
+ * @returns `{ status: 200, data: { chains: EscalationChain[] } }` on success
+ */
+async function getEscalationChains() {
+    try {
+        const chains = await roleService.getAllEscalationChains();
+        return { status: 200, data: { chains } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Add an escalation chain link from one role to another. Requires admin privileges.
+ *
+ * @param input.source_role — the role that escalates from
+ * @param input.target_role — the role that receives the escalation
+ * @returns `{ status: 201, data: { source_role, target_role } }` on success
+ */
+async function addEscalationChain(input) {
+    try {
+        if (!input.source_role || !input.target_role) {
+            return { status: 400, error: 'source_role and target_role are required' };
+        }
+        await roleService.addEscalationChain(input.source_role, input.target_role);
+        return {
+            status: 201,
+            data: { source_role: input.source_role, target_role: input.target_role },
+        };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Remove an escalation chain link between two roles. Requires admin privileges.
+ *
+ * @param input.source_role — the role that escalates from
+ * @param input.target_role — the role that receives the escalation
+ * @returns `{ status: 200, data: { removed: true } }` on success, or `{ status: 404 }` if not found
+ */
+async function removeEscalationChain(input) {
+    try {
+        if (!input.source_role || !input.target_role) {
+            return { status: 400, error: 'source_role and target_role are required' };
+        }
+        const removed = await roleService.removeEscalationChain(input.source_role, input.target_role);
+        if (!removed) {
+            return { status: 404, error: 'Chain entry not found' };
+        }
+        return { status: 200, data: { removed: true } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Get all escalation target roles for a given source role.
+ *
+ * @param input.role — the source role to look up escalation targets for
+ * @returns `{ status: 200, data: { targets: string[] } }` on success
+ */
+async function getEscalationTargets(input) {
+    try {
+        const targets = await roleService.getEscalationTargets(input.role);
+        return { status: 200, data: { targets } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Replace all escalation targets for a role with a new set. Requires admin privileges.
+ *
+ * Removes all existing escalation links from the source role and creates new
+ * ones for each target in the provided array.
+ *
+ * @param input.role — the source role whose targets are being replaced
+ * @param input.targets — array of target role names to set as the new escalation targets
+ * @returns `{ status: 200, data: { role, targets } }` on success
+ */
+async function replaceEscalationTargets(input) {
+    try {
+        if (!Array.isArray(input.targets)) {
+            return { status: 400, error: 'targets must be an array of strings' };
+        }
+        await roleService.replaceEscalationTargets(input.role, input.targets);
+        return { status: 200, data: { role: input.role, targets: input.targets } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Delete a role from the system. Requires admin privileges.
+ *
+ * Returns 409 if the role cannot be deleted (e.g., still assigned to users).
+ *
+ * @param input.role — the role name to delete
+ * @returns `{ status: 200, data: { deleted: true } }` on success, or `{ status: 409 }` if deletion blocked
+ */
+async function deleteRole(input) {
+    try {
+        const result = await roleService.deleteRole(input.role);
+        if (!result.deleted) {
+            return { status: 409, error: result.error || 'Cannot delete role' };
+        }
+        return { status: 200, data: { deleted: true } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}

package/build/api/settings.d.ts

@@ -0,0 +1,10 @@
+import type { LTApiResult } from '../types/sdk';
+/**
+ * Return platform settings for the current deployment.
+ *
+ * Includes telemetry configuration (trace URL), escalation claim duration
+ * options, and event transport details (socket.io, NATS, or none).
+ *
+ * @returns `{ status: 200, data: { telemetry, escalation, events } }`
+ */
+export declare function getSettings(): Promise<LTApiResult>;

package/build/api/settings.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSettings = getSettings;
+const telemetry_1 = require("../lib/telemetry");
+const events_1 = require("../lib/events");
+const nats_1 = require("../lib/events/nats");
+const socketio_1 = require("../lib/events/socketio");
+const defaults_1 = require("../modules/defaults");
+/**
+ * Return platform settings for the current deployment.
+ *
+ * Includes telemetry configuration (trace URL), escalation claim duration
+ * options, and event transport details (socket.io, NATS, or none).
+ *
+ * @returns `{ status: 200, data: { telemetry, escalation, events } }`
+ */
+async function getSettings() {
+    try {
+        const hasSocketIO = !!events_1.eventRegistry.getAdapter(socketio_1.SocketIOEventAdapter);
+        const hasNats = !!events_1.eventRegistry.getAdapter(nats_1.NatsEventAdapter);
+        const transport = hasSocketIO ? 'socketio' : hasNats ? 'nats' : 'none';
+        return {
+            status: 200,
+            data: {
+                telemetry: {
+                    traceUrl: telemetry_1.telemetryRegistry.traceUrl ?? null,
+                },
+                escalation: {
+                    claimDurations: defaults_1.CLAIM_DURATION_OPTIONS,
+                },
+                events: {
+                    transport,
+                    natsWsUrl: hasNats
+                        ? (process.env.VITE_NATS_WS_URL || process.env.NATS_WS_URL || null)
+                        : null,
+                },
+            },
+        };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}

package/build/api/tasks.d.ts

@@ -0,0 +1,70 @@
+import type { LTApiResult } from '../types/sdk';
+/**
+ * List tasks with optional filters.
+ *
+ * Tasks represent workflow executions tracked by the LT interceptor.
+ *
+ * @param input.status — filter by `pending` or `completed`
+ * @param input.lt_type — filter by interceptor classification
+ * @param input.workflow_type — filter by workflow function name
+ * @param input.workflow_id — filter by HotMesh workflow ID
+ * @param input.parent_workflow_id — filter by parent orchestrator ID
+ * @param input.origin_id — filter by root process origin ID
+ * @param input.limit — max results (default: 50)
+ * @param input.offset — pagination offset (default: 0)
+ * @returns `{ status: 200, data: { tasks, total } }`
+ */
+export declare function listTasks(input: {
+    status?: string;
+    lt_type?: string;
+    workflow_type?: string;
+    workflow_id?: string;
+    parent_workflow_id?: string;
+    origin_id?: string;
+    limit?: number;
+    offset?: number;
+}): Promise<LTApiResult>;
+/**
+ * Return aggregate process statistics.
+ *
+ * @param input.period — time window (`1h`, `24h`, `7d`, `30d`)
+ * @returns `{ status: 200, data: <process stats> }`
+ */
+export declare function getProcessStats(input: {
+    period?: string;
+}): Promise<LTApiResult>;
+/**
+ * List processes (grouped by origin_id) with optional filters.
+ *
+ * @param input.limit — max results (default: 50)
+ * @param input.offset — pagination offset
+ * @param input.workflow_type — filter by workflow type
+ * @param input.status — filter by status
+ * @param input.search — full-text search across process fields
+ * @returns `{ status: 200, data: { processes, total } }`
+ */
+export declare function listProcesses(input: {
+    limit?: number;
+    offset?: number;
+    workflow_type?: string;
+    status?: string;
+    search?: string;
+}): Promise<LTApiResult>;
+/**
+ * Get a single process with all its tasks and escalations.
+ *
+ * @param input.originId — root process origin ID
+ * @returns `{ status: 200, data: { origin_id, tasks, escalations } }`
+ */
+export declare function getProcess(input: {
+    originId: string;
+}): Promise<LTApiResult>;
+/**
+ * Get a single task by ID.
+ *
+ * @param input.id — task UUID
+ * @returns `{ status: 200, data: <task record> }` or 404
+ */
+export declare function getTask(input: {
+    id: string;
+}): Promise<LTApiResult>;

package/build/api/tasks.js

@@ -0,0 +1,139 @@
+"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.listTasks = listTasks;
+exports.getProcessStats = getProcessStats;
+exports.listProcesses = listProcesses;
+exports.getProcess = getProcess;
+exports.getTask = getTask;
+const taskService = __importStar(require("../services/task"));
+const escalationService = __importStar(require("../services/escalation"));
+/**
+ * List tasks with optional filters.
+ *
+ * Tasks represent workflow executions tracked by the LT interceptor.
+ *
+ * @param input.status — filter by `pending` or `completed`
+ * @param input.lt_type — filter by interceptor classification
+ * @param input.workflow_type — filter by workflow function name
+ * @param input.workflow_id — filter by HotMesh workflow ID
+ * @param input.parent_workflow_id — filter by parent orchestrator ID
+ * @param input.origin_id — filter by root process origin ID
+ * @param input.limit — max results (default: 50)
+ * @param input.offset — pagination offset (default: 0)
+ * @returns `{ status: 200, data: { tasks, total } }`
+ */
+async function listTasks(input) {
+    try {
+        const result = await taskService.listTasks(input);
+        return { status: 200, data: result };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Return aggregate process statistics.
+ *
+ * @param input.period — time window (`1h`, `24h`, `7d`, `30d`)
+ * @returns `{ status: 200, data: <process stats> }`
+ */
+async function getProcessStats(input) {
+    try {
+        const stats = await taskService.getProcessStats(input.period);
+        return { status: 200, data: stats };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * List processes (grouped by origin_id) with optional filters.
+ *
+ * @param input.limit — max results (default: 50)
+ * @param input.offset — pagination offset
+ * @param input.workflow_type — filter by workflow type
+ * @param input.status — filter by status
+ * @param input.search — full-text search across process fields
+ * @returns `{ status: 200, data: { processes, total } }`
+ */
+async function listProcesses(input) {
+    try {
+        const result = await taskService.listProcesses(input);
+        return { status: 200, data: result };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Get a single process with all its tasks and escalations.
+ *
+ * @param input.originId — root process origin ID
+ * @returns `{ status: 200, data: { origin_id, tasks, escalations } }`
+ */
+async function getProcess(input) {
+    try {
+        const [tasks, escalations] = await Promise.all([
+            taskService.getProcessTasks(input.originId),
+            escalationService.getEscalationsByOriginId(input.originId),
+        ]);
+        return {
+            status: 200,
+            data: { origin_id: input.originId, tasks, escalations },
+        };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Get a single task by ID.
+ *
+ * @param input.id — task UUID
+ * @returns `{ status: 200, data: <task record> }` or 404
+ */
+async function getTask(input) {
+    try {
+        const task = await taskService.getTask(input.id);
+        if (!task) {
+            return { status: 404, error: 'Task not found' };
+        }
+        return { status: 200, data: task };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}

package/build/api/users.d.ts

@@ -0,0 +1,115 @@
+import type { LTApiResult } from '../types/sdk';
+import type { LTRoleType } from '../types';
+/**
+ * List users with optional filters for role, role type, status, and pagination.
+ *
+ * @param input.role — filter by role name
+ * @param input.roleType — filter by role type (superadmin, admin, member)
+ * @param input.status — filter by user status
+ * @param input.limit — maximum number of users to return
+ * @param input.offset — number of users to skip for pagination
+ * @returns `{ status: 200, data: User[] }` on success
+ */
+export declare function listUsers(input: {
+    role?: string;
+    roleType?: LTRoleType;
+    status?: string;
+    limit?: number;
+    offset?: number;
+}): Promise<LTApiResult>;
+/**
+ * Retrieve a single user by ID.
+ *
+ * @param input.id — the user's unique identifier
+ * @returns `{ status: 200, data: User }` on success, or `{ status: 404 }` if not found
+ */
+export declare function getUser(input: {
+    id: string;
+}): Promise<LTApiResult>;
+/**
+ * Create a new user. Requires admin privileges.
+ *
+ * Validates that external_id is present and that any provided roles have valid
+ * names and types. Returns 409 if a user with the same external_id already exists.
+ *
+ * @param input.external_id — external system identifier (required)
+ * @param input.email — user's email address
+ * @param input.display_name — user's display name
+ * @param input.roles — initial role assignments, each with a role name and type (superadmin, admin, member)
+ * @param input.metadata — arbitrary key-value metadata to attach to the user
+ * @returns `{ status: 201, data: User }` on success, or `{ status: 409 }` on duplicate external_id
+ */
+export declare function createUser(input: {
+    external_id?: string;
+    email?: string;
+    display_name?: string;
+    roles?: {
+        role: string;
+        type: string;
+    }[];
+    metadata?: Record<string, any>;
+}): Promise<LTApiResult>;
+/**
+ * Update an existing user's profile fields. Requires admin privileges.
+ *
+ * Only the provided fields are updated; omitted fields remain unchanged.
+ *
+ * @param input.id — the user's unique identifier (required)
+ * @param input.email — new email address
+ * @param input.display_name — new display name
+ * @param input.status — new user status
+ * @param input.metadata — replacement metadata object
+ * @returns `{ status: 200, data: User }` on success, or `{ status: 404 }` if not found
+ */
+export declare function updateUser(input: {
+    id: string;
+    email?: string;
+    display_name?: string;
+    status?: string;
+    metadata?: Record<string, any>;
+}): Promise<LTApiResult>;
+/**
+ * Delete a user by ID. Requires admin privileges.
+ *
+ * @param input.id — the user's unique identifier
+ * @returns `{ status: 200, data: { deleted: true } }` on success, or `{ status: 404 }` if not found
+ */
+export declare function deleteUser(input: {
+    id: string;
+}): Promise<LTApiResult>;
+/**
+ * Retrieve all roles assigned to a user.
+ *
+ * @param input.id — the user's unique identifier
+ * @returns `{ status: 200, data: { roles: Role[] } }` on success
+ */
+export declare function getUserRoles(input: {
+    id: string;
+}): Promise<LTApiResult>;
+/**
+ * Assign a role to a user. Requires admin privileges.
+ *
+ * Validates that both role and type are provided and that the type is one of
+ * superadmin, admin, or member.
+ *
+ * @param input.id — the user's unique identifier
+ * @param input.role — the role name to assign
+ * @param input.type — the role type (superadmin, admin, or member)
+ * @returns `{ status: 201, data: UserRole }` on success
+ */
+export declare function addUserRole(input: {
+    id: string;
+    role: string;
+    type: string;
+}): Promise<LTApiResult>;
+/**
+ * Remove a role from a user. Requires admin privileges.
+ *
+ * @param input.id — the user's unique identifier
+ * @param input.role — the role name to remove
+ * @returns `{ status: 200, data: { removed: true } }` on success, or `{ status: 404 }` if role not found
+ */
+export declare function removeUserRole(input: {
+    id: string;
+    role: string;
+}): Promise<LTApiResult>;