@hotmeshio/long-tail 0.1.6 → 0.1.8

package/docs/api/sdk/settings.md

@@ -0,0 +1,24 @@
+# lt.settings
+
+Platform settings for the current deployment.
+
+## get
+
+Return platform settings including telemetry configuration, escalation claim duration options, and event transport details.
+
+```typescript
+const result = await lt.settings.get();
+```
+
+**Parameters:** None
+
+**Returns:** `LTApiResult<{ telemetry, escalation, events }>`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `telemetry.traceUrl` | `string \| null` | Trace URL for the telemetry provider |
+| `escalation.claimDurations` | `number[]` | Available claim duration options (minutes) |
+| `events.transport` | `'socketio' \| 'nats' \| 'none'` | Active event transport |
+| `events.natsWsUrl` | `string \| null` | NATS WebSocket URL (only when transport is `nats`) |
+
+**Auth:** Not required

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