@hotmeshio/long-tail 0.1.6 → 0.1.8

package/build/api/users.js

@@ -0,0 +1,228 @@
+"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.listUsers = listUsers;
+exports.getUser = getUser;
+exports.createUser = createUser;
+exports.updateUser = updateUser;
+exports.deleteUser = deleteUser;
+exports.getUserRoles = getUserRoles;
+exports.addUserRole = addUserRole;
+exports.removeUserRole = removeUserRole;
+const userService = __importStar(require("../services/user"));
+/**
+ * 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
+ */
+async function listUsers(input) {
+    try {
+        const result = await userService.listUsers(input);
+        return { status: 200, data: result };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * 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
+ */
+async function getUser(input) {
+    try {
+        const user = await userService.getUser(input.id);
+        if (!user) {
+            return { status: 404, error: 'User not found' };
+        }
+        return { status: 200, data: user };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * 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
+ */
+async function createUser(input) {
+    try {
+        if (!input.external_id) {
+            return { status: 400, error: 'external_id is required' };
+        }
+        if (input.roles) {
+            for (const r of input.roles) {
+                if (!r.role || !r.type || !userService.isValidRoleType(r.type)) {
+                    return {
+                        status: 400,
+                        error: 'Each role must have a role name and type (superadmin, admin, member)',
+                    };
+                }
+            }
+        }
+        const user = await userService.createUser({
+            external_id: input.external_id,
+            email: input.email,
+            display_name: input.display_name,
+            roles: input.roles,
+            metadata: input.metadata,
+        });
+        return { status: 201, data: user };
+    }
+    catch (err) {
+        if (err.code === '23505') {
+            return { status: 409, error: 'User with this external_id already exists' };
+        }
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * 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
+ */
+async function updateUser(input) {
+    try {
+        const { id, ...fields } = input;
+        const user = await userService.updateUser(id, fields);
+        if (!user) {
+            return { status: 404, error: 'User not found' };
+        }
+        return { status: 200, data: user };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * 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
+ */
+async function deleteUser(input) {
+    try {
+        const deleted = await userService.deleteUser(input.id);
+        if (!deleted) {
+            return { status: 404, error: 'User not found' };
+        }
+        return { status: 200, data: { deleted: true } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Retrieve all roles assigned to a user.
+ *
+ * @param input.id — the user's unique identifier
+ * @returns `{ status: 200, data: { roles: Role[] } }` on success
+ */
+async function getUserRoles(input) {
+    try {
+        const roles = await userService.getUserRoles(input.id);
+        return { status: 200, data: { roles } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * 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
+ */
+async function addUserRole(input) {
+    try {
+        if (!input.role || !input.type) {
+            return { status: 400, error: 'role and type are required' };
+        }
+        if (!userService.isValidRoleType(input.type)) {
+            return { status: 400, error: 'type must be superadmin, admin, or member' };
+        }
+        const result = await userService.addUserRole(input.id, input.role, input.type);
+        return { status: 201, data: result };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * 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
+ */
+async function removeUserRole(input) {
+    try {
+        const removed = await userService.removeUserRole(input.id, input.role);
+        if (!removed) {
+            return { status: 404, error: 'Role not found' };
+        }
+        return { status: 200, data: { removed: true } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}

package/build/api/workflow-sets.d.ts

@@ -0,0 +1,77 @@
+import type { LTApiResult, LTApiAuth } from '../types/sdk';
+/**
+ * Create a new workflow set and kick off the LLM-powered planner.
+ *
+ * Persists the workflow set record, then starts an async planner workflow
+ * that generates the plan from the specification. Requires at least one
+ * LLM API key (OPENAI_API_KEY or ANTHROPIC_API_KEY) to be configured.
+ * Returns 409 if a workflow set with the same name already exists.
+ *
+ * @param input.name — unique name for the workflow set (required)
+ * @param input.description — optional description of the workflow set
+ * @param input.specification — free-text specification the planner uses to generate workflows (required)
+ * @param auth — authenticated user context; userId is forwarded to the planner
+ * @returns `{ status: 201, data: { ...set, source_workflow_id, planner_workflow_id } }` the created set with planner IDs
+ */
+export declare function createWorkflowSet(input: {
+    name: string;
+    description?: string;
+    specification: string;
+}, auth?: LTApiAuth): Promise<LTApiResult>;
+/**
+ * List workflow sets with optional filtering and pagination.
+ *
+ * @param input.status — filter by workflow set status
+ * @param input.search — free-text search term to match against set names or descriptions
+ * @param input.limit — maximum number of results to return
+ * @param input.offset — number of results to skip for pagination
+ * @returns `{ status: 200, data: WorkflowSet[] }` paginated list of workflow sets
+ */
+export declare function listWorkflowSets(input: {
+    status?: string;
+    search?: string;
+    limit?: number;
+    offset?: number;
+}): Promise<LTApiResult>;
+/**
+ * Retrieve a single workflow set by ID.
+ *
+ * @param input.id — unique identifier of the workflow set
+ * @returns `{ status: 200, data: WorkflowSet }` the workflow set record, or 404 if not found
+ */
+export declare function getWorkflowSet(input: {
+    id: string;
+}): Promise<LTApiResult>;
+/**
+ * Replace the plan and optional namespaces on a workflow set.
+ *
+ * @param input.id — unique identifier of the workflow set to update
+ * @param input.plan — array of plan entries (required, must be an array)
+ * @param input.namespaces — optional array of namespace definitions associated with the plan
+ * @returns `{ status: 200, data: WorkflowSet }` the updated workflow set, or 404 if not found
+ */
+export declare function updateWorkflowSetPlanApi(input: {
+    id: string;
+    plan: any[];
+    namespaces?: any[];
+}): Promise<LTApiResult>;
+/**
+ * Transition a workflow set from "planned" to "building" status.
+ *
+ * Returns 409 if the set is not currently in "planned" status.
+ *
+ * @param input.id — unique identifier of the workflow set to build
+ * @returns `{ status: 200, data: { status: 'building', id } }` confirmation the build has started
+ */
+export declare function buildWorkflowSet(input: {
+    id: string;
+}): Promise<LTApiResult>;
+/**
+ * Transition a workflow set to "deploying" status.
+ *
+ * @param input.id — unique identifier of the workflow set to deploy
+ * @returns `{ status: 200, data: { status: 'deploying', id } }` confirmation the deploy has started
+ */
+export declare function deployWorkflowSet(input: {
+    id: string;
+}): Promise<LTApiResult>;

package/build/api/workflow-sets.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWorkflowSet = createWorkflowSet;
+exports.listWorkflowSets = listWorkflowSets;
+exports.getWorkflowSet = getWorkflowSet;
+exports.updateWorkflowSetPlanApi = updateWorkflowSetPlanApi;
+exports.buildWorkflowSet = buildWorkflowSet;
+exports.deployWorkflowSet = deployWorkflowSet;
+const workflow_sets_1 = require("../services/workflow-sets");
+const insight_1 = require("../services/insight");
+/**
+ * Create a new workflow set and kick off the LLM-powered planner.
+ *
+ * Persists the workflow set record, then starts an async planner workflow
+ * that generates the plan from the specification. Requires at least one
+ * LLM API key (OPENAI_API_KEY or ANTHROPIC_API_KEY) to be configured.
+ * Returns 409 if a workflow set with the same name already exists.
+ *
+ * @param input.name — unique name for the workflow set (required)
+ * @param input.description — optional description of the workflow set
+ * @param input.specification — free-text specification the planner uses to generate workflows (required)
+ * @param auth — authenticated user context; userId is forwarded to the planner
+ * @returns `{ status: 201, data: { ...set, source_workflow_id, planner_workflow_id } }` the created set with planner IDs
+ */
+async function createWorkflowSet(input, auth) {
+    try {
+        if (!input.specification || typeof input.specification !== 'string') {
+            return { status: 400, error: 'specification is required' };
+        }
+        if (!input.name || typeof input.name !== 'string') {
+            return { status: 400, error: 'name is required' };
+        }
+        if (!process.env.OPENAI_API_KEY && !process.env.ANTHROPIC_API_KEY) {
+            return { status: 503, error: 'Workflow planner requires an LLM API key' };
+        }
+        const set = await (0, workflow_sets_1.createWorkflowSet)({
+            name: input.name,
+            description: input.description,
+            specification: input.specification,
+        });
+        const plannerResult = await (0, insight_1.startWorkflowPlanner)({
+            specification: input.specification,
+            setId: set.id,
+            wait: false,
+            userId: auth?.userId,
+        });
+        await (0, workflow_sets_1.updateWorkflowSetSourceWorkflow)(set.id, plannerResult.workflow_id);
+        return {
+            status: 201,
+            data: {
+                ...set,
+                source_workflow_id: plannerResult.workflow_id,
+                planner_workflow_id: plannerResult.workflow_id,
+            },
+        };
+    }
+    catch (err) {
+        if (err.code === '23505') {
+            return { status: 409, error: 'A workflow set with this name already exists' };
+        }
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * List workflow sets with optional filtering and pagination.
+ *
+ * @param input.status — filter by workflow set status
+ * @param input.search — free-text search term to match against set names or descriptions
+ * @param input.limit — maximum number of results to return
+ * @param input.offset — number of results to skip for pagination
+ * @returns `{ status: 200, data: WorkflowSet[] }` paginated list of workflow sets
+ */
+async function listWorkflowSets(input) {
+    try {
+        const result = await (0, workflow_sets_1.listWorkflowSets)({
+            status: input.status,
+            search: input.search,
+            limit: input.limit,
+            offset: input.offset,
+        });
+        return { status: 200, data: result };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Retrieve a single workflow set by ID.
+ *
+ * @param input.id — unique identifier of the workflow set
+ * @returns `{ status: 200, data: WorkflowSet }` the workflow set record, or 404 if not found
+ */
+async function getWorkflowSet(input) {
+    try {
+        const set = await (0, workflow_sets_1.getWorkflowSet)(input.id);
+        if (!set) {
+            return { status: 404, error: 'Workflow set not found' };
+        }
+        return { status: 200, data: set };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Replace the plan and optional namespaces on a workflow set.
+ *
+ * @param input.id — unique identifier of the workflow set to update
+ * @param input.plan — array of plan entries (required, must be an array)
+ * @param input.namespaces — optional array of namespace definitions associated with the plan
+ * @returns `{ status: 200, data: WorkflowSet }` the updated workflow set, or 404 if not found
+ */
+async function updateWorkflowSetPlanApi(input) {
+    try {
+        if (!Array.isArray(input.plan)) {
+            return { status: 400, error: 'plan must be an array' };
+        }
+        const updated = await (0, workflow_sets_1.updateWorkflowSetPlan)(input.id, input.plan, input.namespaces || []);
+        if (!updated) {
+            return { status: 404, error: 'Workflow set not found' };
+        }
+        return { status: 200, data: updated };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Transition a workflow set from "planned" to "building" status.
+ *
+ * Returns 409 if the set is not currently in "planned" status.
+ *
+ * @param input.id — unique identifier of the workflow set to build
+ * @returns `{ status: 200, data: { status: 'building', id } }` confirmation the build has started
+ */
+async function buildWorkflowSet(input) {
+    try {
+        const set = await (0, workflow_sets_1.getWorkflowSet)(input.id);
+        if (!set) {
+            return { status: 404, error: 'Workflow set not found' };
+        }
+        if (set.status !== 'planned') {
+            return { status: 409, error: `Cannot build set in '${set.status}' status` };
+        }
+        await (0, workflow_sets_1.updateWorkflowSetStatus)(input.id, 'building');
+        return { status: 200, data: { status: 'building', id: input.id } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Transition a workflow set to "deploying" status.
+ *
+ * @param input.id — unique identifier of the workflow set to deploy
+ * @returns `{ status: 200, data: { status: 'deploying', id } }` confirmation the deploy has started
+ */
+async function deployWorkflowSet(input) {
+    try {
+        const set = await (0, workflow_sets_1.getWorkflowSet)(input.id);
+        if (!set) {
+            return { status: 404, error: 'Workflow set not found' };
+        }
+        await (0, workflow_sets_1.updateWorkflowSetStatus)(input.id, 'deploying');
+        return { status: 200, data: { status: 'deploying', id: input.id } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}

package/build/api/workflows.d.ts

@@ -0,0 +1,158 @@
+import type { LTApiResult, LTApiAuth } from '../types/sdk';
+/**
+ * Start a workflow — proxy for `Durable.Client.workflow.start()`.
+ *
+ * Resolves the task queue, enforces auth/role constraints, builds the
+ * LTEnvelope with IAM context, and delegates to the Durable client.
+ * Any WorkflowOptions field (workflowId, expire, entity, namespace,
+ * search, signalIn, pending, etc.) can be passed via `options` and
+ * flows through to the Durable client unchanged.
+ *
+ * @see https://docs.hotmesh.io/types/types_durable.WorkflowOptions.html
+ */
+export declare function invokeWorkflow(input: {
+    type: string;
+    data?: Record<string, any>;
+    metadata?: Record<string, any>;
+    execute_as?: string;
+    /** Passthrough to Durable WorkflowOptions. */
+    options?: Record<string, any>;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Get the execution status of a workflow.
+ *
+ * Returns the HotMesh status code (0 = completed, 1 = running).
+ * Resolves the workflow handle via task record or worker registry.
+ *
+ * @param input.workflowId — HotMesh workflow ID
+ * @returns `{ status: 200, data: { workflowId, status } }` or 404
+ */
+export declare function getWorkflowStatus(input: {
+    workflowId: string;
+}): Promise<LTApiResult>;
+/**
+ * Get the result of a completed workflow.
+ *
+ * Returns 202 if the workflow is still running, 200 with the result
+ * payload when complete. Never blocks — always returns immediately.
+ *
+ * @param input.workflowId — HotMesh workflow ID
+ * @returns `{ status: 200, data: { workflowId, result } }` or 202 if running
+ */
+export declare function getWorkflowResult(input: {
+    workflowId: string;
+}): Promise<LTApiResult>;
+/**
+ * Terminate a running workflow.
+ *
+ * Interrupts the workflow execution immediately via HotMesh.
+ *
+ * @param input.workflowId — HotMesh workflow ID
+ * @returns `{ status: 200, data: { terminated: true, workflowId } }` or 404
+ */
+export declare function terminateWorkflow(input: {
+    workflowId: string;
+}): Promise<LTApiResult>;
+/**
+ * Export the full state of a workflow.
+ *
+ * Returns the serialized workflow state including all activity
+ * results, signals, and metadata.
+ *
+ * @param input.workflowId — HotMesh workflow ID
+ * @returns `{ status: 200, data: <exported state> }` or 404
+ */
+export declare function exportWorkflow(input: {
+    workflowId: string;
+}): Promise<LTApiResult>;
+/**
+ * List active workflow workers with their registration status.
+ *
+ * @param input.include_system — include system workflows (default: false)
+ * @returns `{ status: 200, data: { workers: [{ name, task_queue, registered, system }] } }`
+ */
+export declare function listWorkers(input: {
+    include_system?: boolean;
+}): Promise<LTApiResult>;
+/**
+ * Discover all known workflow types from workers, history, and config.
+ *
+ * Merges three sources: active in-memory workers, historical entities
+ * from the durable jobs table, and registered workflow configs. Returns
+ * a unified list with status flags for each type.
+ *
+ * @param input.include_system — include system workflows (default: false)
+ * @returns `{ status: 200, data: { workflows: [{ workflow_type, task_queue, registered, active, invocable, ... }] } }`
+ */
+export declare function listDiscoveredWorkflows(input: {
+    include_system?: boolean;
+}): Promise<LTApiResult>;
+/**
+ * List all cron-scheduled workflows and their active state.
+ *
+ * @returns `{ status: 200, data: { schedules: [{ workflow_type, cron_schedule, active, ... }] } }`
+ */
+export declare function getCronStatus(): Promise<LTApiResult>;
+/**
+ * List all registered workflow configurations.
+ *
+ * @returns `{ status: 200, data: { workflows: LTWorkflowConfig[] } }`
+ */
+export declare function listWorkflowConfigs(): Promise<LTApiResult>;
+/**
+ * Get a single workflow configuration by type.
+ *
+ * @param input.type — workflow type name (e.g. `"reviewContent"`)
+ * @returns `{ status: 200, data: <config> }` or 404
+ */
+export declare function getWorkflowConfig(input: {
+    type: string;
+}): Promise<LTApiResult>;
+/**
+ * Create or replace a workflow configuration.
+ *
+ * Invalidates the config cache and restarts the cron schedule if one
+ * is defined. Idempotent — safe to call repeatedly with the same input.
+ *
+ * @param input.type — workflow type name
+ * @param input.invocable — whether the workflow can be started via the API
+ * @param input.task_queue — HotMesh task queue
+ * @param input.default_role — default escalation role
+ * @param input.description — human-readable description
+ * @param input.execute_as — service account for proxy invocation
+ * @param input.roles — roles that can resolve escalations
+ * @param input.invocation_roles — roles that can invoke this workflow
+ * @param input.consumes — workflow types whose data this workflow consumes
+ * @param input.tool_tags — MCP tool tags for discovery
+ * @param input.envelope_schema — JSON Schema for envelope.data validation
+ * @param input.resolver_schema — JSON Schema for resolver payload validation
+ * @param input.cron_schedule — cron expression for scheduled execution
+ * @returns `{ status: 200, data: <saved config> }`
+ */
+export declare function upsertWorkflowConfig(input: {
+    type: string;
+    invocable?: boolean;
+    task_queue?: string | null;
+    default_role?: string;
+    description?: string | null;
+    execute_as?: string | null;
+    roles?: string[];
+    invocation_roles?: string[];
+    consumes?: string[];
+    tool_tags?: string[];
+    envelope_schema?: any;
+    resolver_schema?: any;
+    cron_schedule?: string | null;
+}): Promise<LTApiResult>;
+/**
+ * Delete a workflow configuration.
+ *
+ * Removes the config record and invalidates the cache. Active workers
+ * continue running — this only removes the config/interceptor binding.
+ *
+ * @param input.type — workflow type name
+ * @returns `{ status: 200, data: { deleted: true, workflow_type } }` or 404
+ */
+export declare function deleteWorkflowConfig(input: {
+    type: string;
+}): Promise<LTApiResult>;