@hotmeshio/long-tail 0.1.7 → 0.1.8

package/build/api/escalations.d.ts

@@ -1,4 +1,51 @@
 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;
@@ -11,6 +58,23 @@ export declare function listEscalations(input: {
     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;
@@ -21,49 +85,186 @@ export declare function listAvailableEscalations(input: {
     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>;

package/build/api/escalations.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEscalation = createEscalation;
 exports.listEscalations = listEscalations;
 exports.listAvailableEscalations = listAvailableEscalations;
 exports.listDistinctTypes = listDistinctTypes;
@@ -97,7 +98,88 @@ function publishBulkClaimEvents(ids, assignedTo) {
         });
     }
 }
+// ── Create ────────────────────────────────────────────────────────────────
+/**
+ * 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> }`
+ */
+async function createEscalation(input, auth) {
+    try {
+        const { type, role } = input;
+        if (!type || typeof type !== 'string') {
+            return { status: 400, error: 'type is required' };
+        }
+        if (!role || typeof role !== 'string') {
+            return { status: 400, error: 'role is required' };
+        }
+        // RBAC: caller must hold the target role or be superadmin
+        const isSuperAdminUser = await userService.isSuperAdmin(auth.userId);
+        if (!isSuperAdminUser) {
+            const userHasRole = await userService.hasRole(auth.userId, role);
+            if (!userHasRole) {
+                return { status: 403, error: `You must hold the "${role}" role or be a superadmin to create escalations for it` };
+            }
+        }
+        const escalation = await escalationService.createEscalation({
+            type,
+            subtype: input.subtype ?? type,
+            description: input.description,
+            priority: input.priority,
+            role,
+            envelope: input.envelope ?? '{}',
+            metadata: input.metadata,
+            escalation_payload: input.escalation_payload,
+        });
+        (0, publish_1.publishEscalationEvent)({
+            type: 'escalation.created',
+            source: 'api',
+            workflowId: '',
+            workflowName: '',
+            taskQueue: '',
+            escalationId: escalation.id,
+            status: 'pending',
+            data: { type: input.type, role },
+        });
+        return { status: 201, data: escalation };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
 // ── List routes ────────────────────────────────────────────────────────────
+/**
+ * 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 } }`
+ */
 async function listEscalations(input, auth) {
     try {
         const visibleRoles = await getVisibleRoles(auth.userId);
@@ -123,6 +205,23 @@ async function listEscalations(input, auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * 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 } }`
+ */
 async function listAvailableEscalations(input, auth) {
     try {
         const visibleRoles = await getVisibleRoles(auth.userId);
@@ -146,6 +245,11 @@ async function listAvailableEscalations(input, auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * List all distinct escalation type values.
+ *
+ * @returns `{ status: 200, data: { types: string[] } }`
+ */
 async function listDistinctTypes() {
     try {
         const types = await escalationService.listDistinctTypes();
@@ -155,6 +259,13 @@ async function listDistinctTypes() {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * 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 } }`
+ */
 async function getEscalationStats(input, auth) {
     try {
         const visibleRoles = await getVisibleRoles(auth.userId);
@@ -179,6 +290,15 @@ async function getEscalationStats(input, auth) {
     }
 }
 // ── Single-escalation routes ───────────────────────────────────────────────
+/**
+ * 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
+ */
 async function getEscalation(input, auth) {
     try {
         const escalation = await escalationService.getEscalation(input.id);
@@ -198,6 +318,12 @@ async function getEscalation(input, auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * List all escalations for a given workflow ID.
+ *
+ * @param input.workflowId — HotMesh workflow ID
+ * @returns `{ status: 200, data: { escalations } }`
+ */
 async function getEscalationsByWorkflowId(input) {
     try {
         const escalations = await escalationService.getEscalationsByWorkflowId(input.workflowId);
@@ -207,6 +333,17 @@ async function getEscalationsByWorkflowId(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * 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
+ */
 async function escalateToRole(input, auth) {
     try {
         const { id, targetRole } = input;
@@ -234,6 +371,18 @@ async function escalateToRole(input, auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * 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
+ */
 async function claimEscalation(input, auth) {
     try {
         const { id, durationMinutes } = input;
@@ -271,6 +420,16 @@ async function claimEscalation(input, auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * 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
+ */
 async function releaseEscalation(input, auth) {
     try {
         const result = await escalationService.releaseEscalation(input.id, auth.userId);
@@ -294,6 +453,14 @@ async function releaseEscalation(input, auth) {
     }
 }
 // ── Bulk routes ────────────────────────────────────────────────────────────
+/**
+ * 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 } }`
+ */
 async function releaseExpiredClaims() {
     try {
         const released = await escalationService.releaseExpiredClaims();
@@ -303,6 +470,14 @@ async function releaseExpiredClaims() {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * 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 } }`
+ */
 async function updatePriority(input, auth) {
     try {
         const { ids, priority } = input;
@@ -322,6 +497,14 @@ async function updatePriority(input, auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * 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 } }`
+ */
 async function bulkClaim(input, auth) {
     try {
         const { ids, durationMinutes } = input;
@@ -340,6 +523,18 @@ async function bulkClaim(input, auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * 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 } }`
+ */
 async function bulkAssign(input, auth) {
     try {
         const { ids, targetUserId, durationMinutes } = input;
@@ -372,6 +567,14 @@ async function bulkAssign(input, auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * 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 } }`
+ */
 async function bulkEscalate(input, auth) {
     try {
         const { ids, targetRole } = input;
@@ -391,6 +594,17 @@ async function bulkEscalate(input, auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * 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 } }`
+ */
 async function bulkTriage(input, auth) {
     try {
         const { ids, hint } = input;
@@ -414,6 +628,28 @@ async function bulkTriage(input, auth) {
     }
 }
 // ── Resolve route ──────────────────────────────────────────────────────────
+/**
+ * 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)
+ */
 async function resolveEscalation(input, auth) {
     try {
         const { id, resolverPayload } = input;

package/build/api/exports.d.ts

@@ -1,6 +1,19 @@
 import type { LTApiResult } from '../types/sdk';
 import type { LTExportField } from '../types';
 import type { ExportMode } from '@hotmeshio/hotmesh/build/types/exporter';
+/**
+ * List export jobs with optional filtering, sorting, and pagination.
+ *
+ * @param input.limit — maximum number of jobs to return
+ * @param input.offset — number of jobs to skip for pagination
+ * @param input.entity — filter by entity/workflow type
+ * @param input.search — free-text search across job fields
+ * @param input.status — filter by job status
+ * @param input.sort_by — field name to sort results by
+ * @param input.order — sort direction (asc or desc)
+ * @param input.registered — filter by registration status
+ * @returns `{ status: 200, data: { jobs, total, ... } }` on success
+ */
 export declare function listJobs(input: {
     limit?: number;
     offset?: number;
@@ -11,12 +24,39 @@ export declare function listJobs(input: {
     order?: string;
     registered?: string;
 }): Promise<LTApiResult>;
+/**
+ * Export the stored state (hash data) of a workflow.
+ *
+ * Resolves the workflow handle from its ID, then exports its state fields.
+ * Fields can be filtered via allow/block lists. Returns 404 if the workflow
+ * cannot be found or its data has expired.
+ *
+ * @param input.workflowId — the workflow's unique identifier
+ * @param input.allow — whitelist of field names to include in the export
+ * @param input.block — blacklist of field names to exclude from the export
+ * @param input.values — when true, include field values (not just field names)
+ * @returns `{ status: 200, data: ExportedState }` on success
+ */
 export declare function exportWorkflowState(input: {
     workflowId: string;
     allow?: LTExportField[];
     block?: LTExportField[];
     values?: boolean;
 }): Promise<LTApiResult>;
+/**
+ * Export the full execution tree of a workflow.
+ *
+ * Resolves the workflow handle, then exports its execution graph including
+ * activity inputs and results. Returns 404 if the workflow cannot be found
+ * or its data has expired.
+ *
+ * @param input.workflowId — the workflow's unique identifier
+ * @param input.excludeSystem — when true, omit system-generated activities from the export
+ * @param input.omitResults — when true, exclude activity result payloads
+ * @param input.mode — export mode controlling output format (e.g., tree, flat)
+ * @param input.maxDepth — maximum depth to traverse in the execution tree
+ * @returns `{ status: 200, data: ExecutionExport }` on success
+ */
 export declare function exportWorkflowExecution(input: {
     workflowId: string;
     excludeSystem?: boolean;
@@ -24,9 +64,27 @@ export declare function exportWorkflowExecution(input: {
     mode?: ExportMode;
     maxDepth?: number;
 }): Promise<LTApiResult>;
+/**
+ * Get the current status of a workflow (e.g., running, completed, failed).
+ *
+ * Resolves the workflow handle, then queries its status. Returns 404 if the
+ * workflow cannot be found or its data has expired.
+ *
+ * @param input.workflowId — the workflow's unique identifier
+ * @returns `{ status: 200, data: WorkflowStatus }` on success
+ */
 export declare function getWorkflowStatus(input: {
     workflowId: string;
 }): Promise<LTApiResult>;
+/**
+ * Get the current state data of a workflow.
+ *
+ * Resolves the workflow handle, then retrieves its full state. Returns 404
+ * if the workflow cannot be found or its data has expired.
+ *
+ * @param input.workflowId — the workflow's unique identifier
+ * @returns `{ status: 200, data: WorkflowState }` on success
+ */
 export declare function getWorkflowState(input: {
     workflowId: string;
 }): Promise<LTApiResult>;