@hotmeshio/long-tail 0.1.6 → 0.1.8

package/docs/api/sdk/controlplane.md

@@ -0,0 +1,103 @@
+# lt.controlplane
+
+Manage the HotMesh control plane: application discovery, worker health, throttling, and stream statistics.
+
+## listApps
+
+List all registered application namespaces.
+
+```typescript
+const result = await lt.controlplane.listApps();
+```
+
+**Parameters:** None
+
+**Returns:** `LTApiResult<{ apps: string[] }>`
+
+**Auth:** Not required
+
+---
+
+## rollCall
+
+Query active worker profiles for an application. Sends a roll-call request to the mesh and collects responses within the delay window.
+
+```typescript
+const result = await lt.controlplane.rollCall({ appId: 'durable', delay: 2000 });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `appId` | `string` | No | Application namespace to query (defaults to `'durable'`) |
+| `delay` | `number` | No | Milliseconds to wait for worker responses before returning |
+
+**Returns:** `LTApiResult<{ profiles: object[] }>`
+
+**Auth:** Not required
+
+---
+
+## throttle
+
+Apply a throttle rate to workflow execution. Also publishes a synthetic `mesh.throttle` event to the dashboard event stream.
+
+```typescript
+const result = await lt.controlplane.throttle({ throttle: 50, topic: 'my-topic' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `throttle` | `number` | Yes | Throttle value to apply |
+| `appId` | `string` | No | Application namespace (defaults to `'durable'`) |
+| `topic` | `string` | No | Topic to scope the throttle to |
+| `guid` | `string` | No | Workflow GUID to scope the throttle to |
+
+**Returns:** `LTApiResult<{ success: boolean }>`
+
+**Auth:** Not required
+
+---
+
+## getStreamStats
+
+Retrieve stream statistics (throughput, backlog) for an application over a time window.
+
+```typescript
+const result = await lt.controlplane.getStreamStats({ app_id: 'durable', duration: '30m' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `app_id` | `string` | No | Application namespace (defaults to `'durable'`) |
+| `duration` | `string` | No | Time window for stats aggregation, e.g. `'1h'`, `'30m'` (defaults to `'1h'`) |
+| `stream` | `string` | No | Specific stream name to filter results |
+
+**Returns:** `LTApiResult<StreamStats>`
+
+**Auth:** Not required
+
+---
+
+## subscribe
+
+Subscribe to mesh events for an application so they are captured and forwarded.
+
+```typescript
+const result = await lt.controlplane.subscribe({ appId: 'durable' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `appId` | `string` | No | Application namespace to subscribe to (defaults to `'durable'`) |
+
+**Returns:** `LTApiResult<{ subscribed: true, appId: string }>`
+
+**Auth:** Not required

package/docs/api/sdk/dba.md

@@ -0,0 +1,52 @@
+# lt.dba
+
+Database administration: prune stale data and deploy workflow schemas.
+
+## prune
+
+Prune stale HotMesh data from Redis. Selectively removes completed jobs, stream entries, engine/worker streams, and search attributes.
+
+```typescript
+const result = await lt.dba.prune({
+  jobs: true,
+  streams: true,
+  expire: '7 days',
+  entities: ['order', 'invoice'],
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `expire` | `string` | No | Redis TTL expression for pruned keys |
+| `jobs` | `boolean` | No | Prune completed job hashes |
+| `streams` | `boolean` | No | Prune activity streams |
+| `engineStreams` | `boolean` | No | Prune engine consumer streams |
+| `engineStreamsExpire` | `string` | No | TTL for engine stream entries |
+| `workerStreams` | `boolean` | No | Prune worker consumer streams |
+| `workerStreamsExpire` | `string` | No | TTL for worker stream entries |
+| `attributes` | `boolean` | No | Prune FT.SEARCH attributes |
+| `entities` | `string[]` | No | Limit pruning to these entity types |
+| `pruneTransient` | `boolean` | No | Include transient keys |
+| `keepHmark` | `boolean` | No | Preserve hmark keys |
+
+**Returns:** `LTApiResult<PruneResult>`
+
+**Auth:** Not required
+
+---
+
+## deploy
+
+Deploy (or redeploy) all HotMesh workflow schemas. Updates the Redis execution graph across all registered entities. Safe to call repeatedly.
+
+```typescript
+const result = await lt.dba.deploy();
+```
+
+**Parameters:** None
+
+**Returns:** `LTApiResult<{ ok: true }>`
+
+**Auth:** Not required

package/docs/api/sdk/escalations.md

@@ -0,0 +1,374 @@
+# lt.escalations
+
+Manage human-in-the-loop escalations -- list, claim, resolve, and bulk-operate on workflow escalations.
+
+## list
+
+List escalations with optional filters, scoped to the authenticated user's roles.
+
+```typescript
+const result = await lt.escalations.list({
+  status: 'pending',
+  role: 'reviewer',
+  limit: 25,
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `status` | `string` | No | Filter by `pending`, `resolved`, or `cancelled` |
+| `role` | `string` | No | Filter by assigned role |
+| `type` | `string` | No | Filter by workflow type |
+| `subtype` | `string` | No | Filter by subtype |
+| `assigned_to` | `string` | No | Filter by assigned user ID |
+| `priority` | `number` | No | Filter by priority (1--4) |
+| `limit` | `number` | No | Max results (default: 50) |
+| `offset` | `number` | No | Pagination offset |
+| `sort_by` | `string` | No | Column to sort by (e.g. `created_at`, `priority`) |
+| `order` | `string` | No | `asc` or `desc` |
+
+**Returns:** `LTApiResult<{ escalations, total }>`
+
+**Auth:** Required
+
+---
+
+## listAvailable
+
+List escalations available for claim (pending and not actively claimed).
+
+```typescript
+const result = await lt.escalations.listAvailable({
+  role: 'reviewer',
+  limit: 10,
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `role` | `string` | No | Filter by role |
+| `type` | `string` | No | Filter by workflow type |
+| `subtype` | `string` | No | Filter by subtype |
+| `priority` | `number` | No | Filter by priority (1--4) |
+| `limit` | `number` | No | Max results (default: 50) |
+| `offset` | `number` | No | Pagination offset |
+| `sort_by` | `string` | No | Column to sort by |
+| `order` | `string` | No | `asc` or `desc` |
+
+**Returns:** `LTApiResult<{ escalations, total }>`
+
+**Auth:** Required
+
+---
+
+## listTypes
+
+List all distinct escalation type values.
+
+```typescript
+const result = await lt.escalations.listTypes();
+```
+
+**Parameters:** None (pass `{}` or `undefined`).
+
+**Returns:** `LTApiResult<{ types: string[] }>`
+
+**Auth:** Not required
+
+---
+
+## getStats
+
+Get aggregate escalation statistics scoped to the user's roles.
+
+```typescript
+const result = await lt.escalations.getStats({ period: '24h' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `period` | `string` | No | Time window (`1h`, `24h`, `7d`, `30d`) |
+
+**Returns:** `LTApiResult<{ pending, claimed, created, resolved, by_role, by_type }>`
+
+**Auth:** Required
+
+---
+
+## get
+
+Get a single escalation by ID.
+
+```typescript
+const result = await lt.escalations.get({ id: 'esc_123' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | Escalation UUID |
+
+**Returns:** `LTApiResult<Escalation>` -- returns 403 if user lacks the role, 404 if not found.
+
+**Auth:** Required
+
+---
+
+## getByWorkflowId
+
+List all escalations for a given workflow ID.
+
+```typescript
+const result = await lt.escalations.getByWorkflowId({ workflowId: 'wf_abc' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `workflowId` | `string` | Yes | HotMesh workflow ID |
+
+**Returns:** `LTApiResult<{ escalations }>`
+
+**Auth:** Not required
+
+---
+
+## escalate
+
+Route a pending escalation to a different role.
+
+```typescript
+const result = await lt.escalations.escalate({
+  id: 'esc_123',
+  targetRole: 'senior-reviewer',
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | Escalation UUID |
+| `targetRole` | `string` | Yes | Destination role |
+
+**Returns:** `LTApiResult<Escalation>` -- returns 403 if not authorized, 404 if not found, 409 if not pending.
+
+**Auth:** Required
+
+---
+
+## claim
+
+Claim a pending escalation for the authenticated user.
+
+```typescript
+const result = await lt.escalations.claim({
+  id: 'esc_123',
+  durationMinutes: 60,
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | Escalation UUID |
+| `durationMinutes` | `number` | No | Claim duration (default: 30) |
+
+**Returns:** `LTApiResult<{ escalation, isExtension }>` -- returns 403 if user lacks the role, 404 if not found, 409 if not available.
+
+**Auth:** Required
+
+---
+
+## release
+
+Release a claimed escalation back to the pool.
+
+```typescript
+const result = await lt.escalations.release({ id: 'esc_123' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | Escalation UUID |
+
+**Returns:** `LTApiResult<{ escalation }>` -- returns 409 if not claimed by the caller.
+
+**Auth:** Required
+
+---
+
+## resolve
+
+Resolve a pending escalation with a human-provided payload.
+
+Supports two resolution paths: signal-routed (sends payload to a paused workflow) and re-run (restarts the workflow with resolver data injected). Password fields are replaced with ephemeral tokens.
+
+```typescript
+const result = await lt.escalations.resolve({
+  id: 'esc_123',
+  resolverPayload: { approved: true, comment: 'Looks good' },
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | Escalation UUID |
+| `resolverPayload` | `Record<string, any>` | Yes | Human decision data |
+
+**Returns:** `LTApiResult<{ signaled, escalationId, workflowId }>` (signal path) or `LTApiResult<{ started, escalationId, workflowId }>` (re-run path) -- returns 404 if not found, 409 if not pending.
+
+**Auth:** Required
+
+---
+
+## releaseExpired
+
+Release all escalation claims past their `assigned_until` deadline.
+
+```typescript
+const result = await lt.escalations.releaseExpired();
+```
+
+**Parameters:** None (pass `{}` or `undefined`).
+
+**Returns:** `LTApiResult<{ released: number }>`
+
+**Auth:** Not required
+
+---
+
+## updatePriority
+
+Update priority for one or more escalations.
+
+```typescript
+const result = await lt.escalations.updatePriority({
+  ids: ['esc_1', 'esc_2'],
+  priority: 1,
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `ids` | `string[]` | Yes | Array of escalation UUIDs |
+| `priority` | `number` | Yes | New priority (1=critical, 2=high, 3=medium, 4=low) |
+
+**Returns:** `LTApiResult<{ updated: number }>`
+
+**Auth:** Required
+
+---
+
+## bulkClaim
+
+Claim multiple escalations at once for the authenticated user.
+
+```typescript
+const result = await lt.escalations.bulkClaim({
+  ids: ['esc_1', 'esc_2'],
+  durationMinutes: 60,
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `ids` | `string[]` | Yes | Array of escalation UUIDs |
+| `durationMinutes` | `number` | No | Claim duration (default: 30) |
+
+**Returns:** `LTApiResult<{ claimed, skipped }>`
+
+**Auth:** Required
+
+---
+
+## bulkAssign
+
+Assign multiple escalations to a specific user.
+
+```typescript
+const result = await lt.escalations.bulkAssign({
+  ids: ['esc_1', 'esc_2'],
+  targetUserId: 'user_456',
+  durationMinutes: 60,
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `ids` | `string[]` | Yes | Array of escalation UUIDs |
+| `targetUserId` | `string` | Yes | User to assign to |
+| `durationMinutes` | `number` | No | Assignment duration (default: 30) |
+
+**Returns:** `LTApiResult<{ assigned, skipped }>`
+
+**Auth:** Required
+
+---
+
+## bulkEscalate
+
+Route multiple escalations to a different role.
+
+```typescript
+const result = await lt.escalations.bulkEscalate({
+  ids: ['esc_1', 'esc_2'],
+  targetRole: 'senior-reviewer',
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `ids` | `string[]` | Yes | Array of escalation UUIDs |
+| `targetRole` | `string` | Yes | Destination role |
+
+**Returns:** `LTApiResult<{ updated: number }>`
+
+**Auth:** Required
+
+---
+
+## bulkTriage
+
+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.
+
+```typescript
+const result = await lt.escalations.bulkTriage({
+  ids: ['esc_1', 'esc_2'],
+  hint: 'Check if the content violates policy section 3.2',
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `ids` | `string[]` | Yes | Array of escalation UUIDs |
+| `hint` | `string` | No | Natural-language guidance for the triage AI |
+
+**Returns:** `LTApiResult<{ triaged, workflows }>`
+
+**Auth:** Required

package/docs/api/sdk/events.md

@@ -0,0 +1,68 @@
+# lt.events
+
+Subscribe to real-time Long Tail events via in-process callbacks.
+
+## on
+
+Subscribe to events by type pattern. Returns an unsubscribe function.
+
+```typescript
+// Exact event type
+const unsub = lt.events.on('escalation.claimed', (event) => {
+  console.log('claimed:', event.escalationId);
+});
+
+// Category wildcard — all task events
+const unsub2 = lt.events.on('task.*', (event) => {
+  console.log('task event:', event.type);
+});
+
+// Global wildcard — every event
+const unsub3 = lt.events.on('*', (event) => {
+  console.log(event.type, event.workflowId);
+});
+
+// Unsubscribe when done
+unsub();
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `pattern` | `LTEventType \| '*' \| string` | Yes | Event type to match |
+| `callback` | `(event: LTEvent) => void` | Yes | Handler invoked for each matching event |
+
+**Pattern matching:**
+
+| Pattern | Matches |
+|---------|---------|
+| `'task.created'` | Exact match on `task.created` only |
+| `'task.*'` | All events starting with `task.` (e.g. `task.created`, `task.completed`, `task.failed`) |
+| `'*'` | Every event |
+
+**Returns:** `() => void` -- call the returned function to unsubscribe.
+
+**Auth:** Not required
+
+---
+
+### LTEventType values
+
+`task.created`, `task.started`, `task.completed`, `task.escalated`, `task.failed`, `escalation.created`, `escalation.resolved`, `escalation.claimed`, `escalation.released`, `workflow.started`, `workflow.completed`, `workflow.failed`, `activity.started`, `activity.completed`, `activity.failed`, `milestone`
+
+### LTEvent fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `LTEventType \| string` | Event classification |
+| `source` | `string` | Origin: `'interceptor'`, `'orchestrator'`, or `'activity'` |
+| `workflowId` | `string` | The workflow instance that produced this event |
+| `workflowName` | `string` | The workflow function name |
+| `taskQueue` | `string` | The task queue the workflow ran on |
+| `taskId` | `string?` | The task ID (present when orchestrated) |
+| `escalationId` | `string?` | The escalation ID (present for escalation events) |
+| `originId` | `string?` | Root process lineage |
+| `status` | `string?` | Task or workflow status after this event |
+| `data` | `Record<string, unknown>?` | Event-specific payload |
+| `timestamp` | `string` | ISO 8601 timestamp |

package/docs/api/sdk/exports.md

@@ -0,0 +1,124 @@
+# lt.exports
+
+Export workflow state, execution trees, and job metadata.
+
+## listJobs
+
+List export jobs with optional filtering, sorting, and pagination.
+
+```typescript
+const result = await lt.exports.listJobs({ limit: 25, offset: 0, status: 'completed' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `limit` | `number` | No | Maximum number of jobs to return |
+| `offset` | `number` | No | Number of jobs to skip for pagination |
+| `entity` | `string` | No | Filter by entity/workflow type |
+| `search` | `string` | No | Free-text search across job fields |
+| `status` | `string` | No | Filter by job status |
+| `sort_by` | `string` | No | Field name to sort results by |
+| `order` | `string` | No | Sort direction (`asc` or `desc`) |
+| `registered` | `string` | No | Filter by registration status |
+
+**Returns:** `LTApiResult<{ jobs, total, ... }>`
+
+**Auth:** Not required
+
+---
+
+## exportState
+
+Export the stored state (hash data) of a workflow. Fields can be filtered via allow/block lists.
+
+```typescript
+const result = await lt.exports.exportState({
+  workflowId: 'wf_abc123',
+  allow: ['data', 'status'],
+  values: true,
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `workflowId` | `string` | Yes | The workflow's unique identifier |
+| `allow` | `LTExportField[]` | No | Whitelist of field names to include |
+| `block` | `LTExportField[]` | No | Blacklist of field names to exclude |
+| `values` | `boolean` | No | When true, include field values (not just names) |
+
+`LTExportField` is one of: `'data'`, `'state'`, `'status'`, `'timeline'`, `'transitions'`
+
+**Returns:** `LTApiResult<ExportedState>` -- returns 404 if the workflow is not found or data has expired.
+
+**Auth:** Not required
+
+---
+
+## exportExecution
+
+Export the full execution tree of a workflow, including activity inputs and results.
+
+```typescript
+const result = await lt.exports.exportExecution({
+  workflowId: 'wf_abc123',
+  excludeSystem: true,
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `workflowId` | `string` | Yes | The workflow's unique identifier |
+| `excludeSystem` | `boolean` | No | Omit system-generated activities from the export |
+| `omitResults` | `boolean` | No | Exclude activity result payloads |
+| `mode` | `ExportMode` | No | Export mode controlling output format (e.g., tree, flat) |
+| `maxDepth` | `number` | No | Maximum depth to traverse in the execution tree |
+
+**Returns:** `LTApiResult<ExecutionExport>` -- returns 404 if the workflow is not found or data has expired.
+
+**Auth:** Not required
+
+---
+
+## getStatus
+
+Get the current status of a workflow (e.g., running, completed, failed).
+
+```typescript
+const result = await lt.exports.getStatus({ workflowId: 'wf_abc123' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `workflowId` | `string` | Yes | The workflow's unique identifier |
+
+**Returns:** `LTApiResult<WorkflowStatus>` -- returns 404 if the workflow is not found or data has expired.
+
+**Auth:** Not required
+
+---
+
+## getState
+
+Get the current state data of a workflow.
+
+```typescript
+const result = await lt.exports.getState({ workflowId: 'wf_abc123' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `workflowId` | `string` | Yes | The workflow's unique identifier |
+
+**Returns:** `LTApiResult<WorkflowState>` -- returns 404 if the workflow is not found or data has expired.
+
+**Auth:** Not required