@hotmeshio/long-tail 0.1.7 → 0.1.8

package/docs/api/sdk/tasks.md

@@ -0,0 +1,120 @@
+# lt.tasks
+
+Query workflow tasks and processes tracked by the Long Tail interceptor.
+
+## list
+
+List tasks with optional filters.
+
+```typescript
+const result = await lt.tasks.list({
+  status: 'pending',
+  workflow_type: 'reviewContent',
+  limit: 25,
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `status` | `string` | No | Filter by `pending` or `completed` |
+| `lt_type` | `string` | No | Filter by interceptor classification |
+| `workflow_type` | `string` | No | Filter by workflow function name |
+| `workflow_id` | `string` | No | Filter by HotMesh workflow ID |
+| `parent_workflow_id` | `string` | No | Filter by parent orchestrator ID |
+| `origin_id` | `string` | No | Filter by root process origin ID |
+| `limit` | `number` | No | Max results (default: 50) |
+| `offset` | `number` | No | Pagination offset (default: 0) |
+
+**Returns:** `LTApiResult<{ tasks, total }>`
+
+**Auth:** Not required
+
+---
+
+## get
+
+Get a single task by ID.
+
+```typescript
+const result = await lt.tasks.get({ id: 'task_abc123' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | Task UUID |
+
+**Returns:** `LTApiResult<Task>` -- returns status 404 if not found.
+
+**Auth:** Not required
+
+---
+
+## listProcesses
+
+List processes (grouped by origin_id) with optional filters.
+
+```typescript
+const result = await lt.tasks.listProcesses({
+  workflow_type: 'reviewContent',
+  status: 'pending',
+  limit: 20,
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `limit` | `number` | No | Max results (default: 50) |
+| `offset` | `number` | No | Pagination offset |
+| `workflow_type` | `string` | No | Filter by workflow type |
+| `status` | `string` | No | Filter by status |
+| `search` | `string` | No | Full-text search across process fields |
+
+**Returns:** `LTApiResult<{ processes, total }>`
+
+**Auth:** Not required
+
+---
+
+## getProcess
+
+Get a single process with all its tasks and escalations.
+
+```typescript
+const result = await lt.tasks.getProcess({ originId: 'origin_xyz' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `originId` | `string` | Yes | Root process origin ID |
+
+**Returns:** `LTApiResult<{ origin_id, tasks, escalations }>`
+
+**Auth:** Not required
+
+---
+
+## getProcessStats
+
+Return aggregate process statistics.
+
+```typescript
+const result = await lt.tasks.getProcessStats({ period: '24h' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `period` | `string` | No | Time window (`1h`, `24h`, `7d`, `30d`) |
+
+**Returns:** `LTApiResult<ProcessStats>`
+
+**Auth:** Not required

package/docs/api/sdk/users.md

@@ -0,0 +1,196 @@
+# lt.users
+
+Manage user accounts and their role assignments.
+
+## list
+
+List users with optional filters.
+
+```typescript
+const result = await lt.users.list({
+  role: 'reviewer',
+  roleType: 'admin',
+  limit: 50,
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `role` | `string` | No | Filter by role name |
+| `roleType` | `string` | No | Filter by role type (`superadmin`, `admin`, `member`) |
+| `status` | `string` | No | Filter by user status |
+| `limit` | `number` | No | Max results |
+| `offset` | `number` | No | Pagination offset |
+
+**Returns:** `LTApiResult<User[]>`
+
+**Auth:** Not required
+
+---
+
+## get
+
+Retrieve a single user by ID.
+
+```typescript
+const result = await lt.users.get({ id: 'user_123' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | User UUID |
+
+**Returns:** `LTApiResult<User>` -- returns 404 if not found.
+
+**Auth:** Not required
+
+---
+
+## create
+
+Create a new user.
+
+```typescript
+const result = await lt.users.create({
+  external_id: 'jane.doe',
+  email: 'jane@example.com',
+  display_name: 'Jane Doe',
+  roles: [{ role: 'reviewer', type: 'member' }],
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `external_id` | `string` | Yes | External system identifier |
+| `email` | `string` | No | Email address |
+| `display_name` | `string` | No | Display name |
+| `roles` | `{ role: string; type: string }[]` | No | Initial role assignments (type: `superadmin`, `admin`, or `member`) |
+| `metadata` | `Record<string, any>` | No | Arbitrary key-value metadata |
+
+**Returns:** `LTApiResult<User>` (status 201) -- returns 409 if `external_id` already exists.
+
+**Auth:** Not required
+
+---
+
+## update
+
+Update an existing user's profile fields. Only provided fields are changed.
+
+```typescript
+const result = await lt.users.update({
+  id: 'user_123',
+  display_name: 'Jane Smith',
+  metadata: { department: 'engineering' },
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | User UUID |
+| `email` | `string` | No | New email address |
+| `display_name` | `string` | No | New display name |
+| `status` | `string` | No | New user status |
+| `metadata` | `Record<string, any>` | No | Replacement metadata object |
+
+**Returns:** `LTApiResult<User>` -- returns 404 if not found.
+
+**Auth:** Not required
+
+---
+
+## delete
+
+Delete a user by ID.
+
+```typescript
+const result = await lt.users.delete({ id: 'user_123' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | User UUID |
+
+**Returns:** `LTApiResult<{ deleted: true }>` -- returns 404 if not found.
+
+**Auth:** Not required
+
+---
+
+## getRoles
+
+Retrieve all roles assigned to a user.
+
+```typescript
+const result = await lt.users.getRoles({ id: 'user_123' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | User UUID |
+
+**Returns:** `LTApiResult<{ roles: Role[] }>`
+
+**Auth:** Not required
+
+---
+
+## addRole
+
+Assign a role to a user.
+
+```typescript
+const result = await lt.users.addRole({
+  id: 'user_123',
+  role: 'reviewer',
+  type: 'member',
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | User UUID |
+| `role` | `string` | Yes | Role name to assign |
+| `type` | `string` | Yes | Role type (`superadmin`, `admin`, or `member`) |
+
+**Returns:** `LTApiResult<UserRole>` (status 201)
+
+**Auth:** Not required
+
+---
+
+## removeRole
+
+Remove a role from a user.
+
+```typescript
+const result = await lt.users.removeRole({
+  id: 'user_123',
+  role: 'reviewer',
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | User UUID |
+| `role` | `string` | Yes | Role name to remove |
+
+**Returns:** `LTApiResult<{ removed: true }>` -- returns 404 if role not found.
+
+**Auth:** Not required

package/docs/api/sdk/workflow-sets.md

@@ -0,0 +1,135 @@
+# lt.workflowSets
+
+Manage compositional workflow sets: plan, build, and deploy groups of related workflows.
+
+## create
+
+Create a new workflow set and kick off the LLM-powered planner.
+
+```typescript
+const result = await lt.workflowSets.create({
+  name: 'onboarding-pipeline',
+  specification: 'A multi-step onboarding pipeline that verifies email, provisions accounts, and sends a welcome message',
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | `string` | Yes | Unique name for the workflow set |
+| `description` | `string` | No | Description of the workflow set |
+| `specification` | `string` | Yes | Free-text specification the planner uses to generate workflows |
+
+**Returns:** `LTApiResult<{ ...WorkflowSet, source_workflow_id: string, planner_workflow_id: string }>`
+
+**Auth:** Optional (userId forwarded to the planner when provided)
+
+---
+
+## list
+
+List workflow sets with optional filtering and pagination.
+
+```typescript
+const result = await lt.workflowSets.list({ status: 'planned', limit: 10 });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `status` | `string` | No | Filter by workflow set status |
+| `search` | `string` | No | Free-text search across set names or descriptions |
+| `limit` | `number` | No | Maximum number of results to return |
+| `offset` | `number` | No | Pagination offset |
+
+**Returns:** `LTApiResult<WorkflowSet[]>`
+
+**Auth:** Not required
+
+---
+
+## get
+
+Retrieve a single workflow set by ID.
+
+```typescript
+const result = await lt.workflowSets.get({ id: 'set-id' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | Unique identifier of the workflow set |
+
+**Returns:** `LTApiResult<WorkflowSet>`
+
+**Auth:** Not required
+
+---
+
+## updatePlan
+
+Replace the plan and optional namespaces on a workflow set.
+
+```typescript
+const result = await lt.workflowSets.updatePlan({
+  id: 'set-id',
+  plan: [{ name: 'step1', description: 'Verify email' }],
+  namespaces: [{ name: 'onboarding', description: 'Onboarding namespace' }],
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | Unique identifier of the workflow set to update |
+| `plan` | `any[]` | Yes | Array of plan entries |
+| `namespaces` | `any[]` | No | Array of namespace definitions associated with the plan |
+
+**Returns:** `LTApiResult<WorkflowSet>`
+
+**Auth:** Not required
+
+---
+
+## build
+
+Transition a workflow set from "planned" to "building" status.
+
+```typescript
+const result = await lt.workflowSets.build({ id: 'set-id' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | Unique identifier of the workflow set to build |
+
+**Returns:** `LTApiResult<{ status: 'building', id: string }>`
+
+**Auth:** Not required
+
+---
+
+## deploy
+
+Transition a workflow set to "deploying" status.
+
+```typescript
+const result = await lt.workflowSets.deploy({ id: 'set-id' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | Unique identifier of the workflow set to deploy |
+
+**Returns:** `LTApiResult<{ status: 'deploying', id: string }>`
+
+**Auth:** Not required

package/docs/api/sdk/workflows.md

@@ -0,0 +1,271 @@
+# lt.workflows
+
+Invoke, inspect, and configure HotMesh Durable workflows.
+
+## invoke
+
+Start a workflow execution.
+
+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`.
+
+```typescript
+const result = await lt.workflows.invoke({
+  type: 'reviewContent',
+  data: { url: 'https://example.com/page' },
+  metadata: { source: 'dashboard' },
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | `string` | Yes | Workflow function name |
+| `data` | `Record<string, any>` | No | Envelope data payload |
+| `metadata` | `Record<string, any>` | No | Envelope metadata |
+| `execute_as` | `string` | No | Service account for proxy invocation |
+| `options` | `Record<string, any>` | No | Passthrough to Durable WorkflowOptions |
+
+**Returns:** `LTApiResult<{ workflowId, message }>`  (status 202)
+
+**Auth:** Required
+
+---
+
+## getStatus
+
+Get the execution status of a workflow.
+
+```typescript
+const result = await lt.workflows.getStatus({ workflowId: 'wf_abc' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `workflowId` | `string` | Yes | HotMesh workflow ID |
+
+**Returns:** `LTApiResult<{ workflowId, status }>` -- status 0 = completed, 1 = running. Returns 404 if not found.
+
+**Auth:** Not required
+
+---
+
+## getResult
+
+Get the result of a completed workflow.
+
+Returns 202 if the workflow is still running. Never blocks.
+
+```typescript
+const result = await lt.workflows.getResult({ workflowId: 'wf_abc' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `workflowId` | `string` | Yes | HotMesh workflow ID |
+
+**Returns:** `LTApiResult<{ workflowId, result }>` (status 200 when complete) or `LTApiResult<{ workflowId, status: 'running' }>` (status 202 when still running). Returns 404 if not found.
+
+**Auth:** Not required
+
+---
+
+## terminate
+
+Terminate a running workflow.
+
+```typescript
+const result = await lt.workflows.terminate({ workflowId: 'wf_abc' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `workflowId` | `string` | Yes | HotMesh workflow ID |
+
+**Returns:** `LTApiResult<{ terminated: true, workflowId }>` -- returns 404 if not found.
+
+**Auth:** Not required
+
+---
+
+## export
+
+Export the full state of a workflow.
+
+Returns the serialized workflow state including all activity results, signals, and metadata.
+
+```typescript
+const result = await lt.workflows.export({ workflowId: 'wf_abc' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `workflowId` | `string` | Yes | HotMesh workflow ID |
+
+**Returns:** `LTApiResult<ExportedState>` -- returns 404 if not found.
+
+**Auth:** Not required
+
+---
+
+## listWorkers
+
+List active workflow workers with their registration status.
+
+```typescript
+const result = await lt.workflows.listWorkers({ include_system: false });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `include_system` | `boolean` | No | Include system workflows (default: false) |
+
+**Returns:** `LTApiResult<{ workers: [{ name, task_queue, registered, system }] }>`
+
+**Auth:** Not required
+
+---
+
+## listDiscovered
+
+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.
+
+```typescript
+const result = await lt.workflows.listDiscovered({ include_system: false });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `include_system` | `boolean` | No | Include system workflows (default: false) |
+
+**Returns:** `LTApiResult<{ workflows: [{ workflow_type, task_queue, registered, active, invocable, system, description, roles, invocation_roles, execute_as }] }>`
+
+**Auth:** Not required
+
+---
+
+## getCronStatus
+
+List all cron-scheduled workflows and their active state.
+
+```typescript
+const result = await lt.workflows.getCronStatus();
+```
+
+**Parameters:** None (pass `{}` or `undefined`).
+
+**Returns:** `LTApiResult<{ schedules: [{ workflow_type, cron_schedule, description, task_queue, invocable, active, envelope_schema }] }>`
+
+**Auth:** Not required
+
+---
+
+## listConfigs
+
+List all registered workflow configurations.
+
+```typescript
+const result = await lt.workflows.listConfigs();
+```
+
+**Parameters:** None (pass `{}` or `undefined`).
+
+**Returns:** `LTApiResult<{ workflows: LTWorkflowConfig[] }>`
+
+**Auth:** Not required
+
+---
+
+## getConfig
+
+Get a single workflow configuration by type.
+
+```typescript
+const result = await lt.workflows.getConfig({ type: 'reviewContent' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | `string` | Yes | Workflow type name |
+
+**Returns:** `LTApiResult<LTWorkflowConfig>` -- returns 404 if not found.
+
+**Auth:** Not required
+
+---
+
+## upsertConfig
+
+Create or replace a workflow configuration.
+
+Invalidates the config cache and restarts the cron schedule if one is defined. Idempotent.
+
+```typescript
+const result = await lt.workflows.upsertConfig({
+  type: 'reviewContent',
+  invocable: true,
+  task_queue: 'content-review',
+  default_role: 'reviewer',
+  description: 'Review flagged content',
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | `string` | Yes | Workflow type name |
+| `invocable` | `boolean` | No | Whether the workflow can be started via the API |
+| `task_queue` | `string \| null` | No | HotMesh task queue |
+| `default_role` | `string` | No | Default escalation role |
+| `description` | `string \| null` | No | Human-readable description |
+| `execute_as` | `string \| null` | No | Service account for proxy invocation |
+| `roles` | `string[]` | No | Roles that can resolve escalations |
+| `invocation_roles` | `string[]` | No | Roles that can invoke this workflow |
+| `consumes` | `string[]` | No | Workflow types whose data this workflow consumes |
+| `tool_tags` | `string[]` | No | MCP tool tags for discovery |
+| `envelope_schema` | `any` | No | JSON Schema for envelope.data validation |
+| `resolver_schema` | `any` | No | JSON Schema for resolver payload validation |
+| `cron_schedule` | `string \| null` | No | Cron expression for scheduled execution |
+
+**Returns:** `LTApiResult<LTWorkflowConfig>`
+
+**Auth:** Not required
+
+---
+
+## deleteConfig
+
+Delete a workflow configuration.
+
+Removes the config record and invalidates the cache. Active workers continue running.
+
+```typescript
+const result = await lt.workflows.deleteConfig({ type: 'reviewContent' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | `string` | Yes | Workflow type name |
+
+**Returns:** `LTApiResult<{ deleted: true, workflow_type }>` -- returns 404 if not found.
+
+**Auth:** Not required