@hotmeshio/long-tail 0.1.3 → 0.1.5

package/docs/api/tasks.md

@@ -0,0 +1,167 @@
+# Tasks API
+
+Tasks represent workflow executions tracked by the LT interceptor. A task record is created when a workflow starts and updated when it completes. All endpoints require authentication.
+
+## List tasks
+
+```
+GET /api/tasks
+```
+
+**Query parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `status` | `string` | Filter by status: `pending` or `completed` |
+| `workflow_type` | `string` | Filter by workflow type (e.g., `reviewContent`) |
+| `workflow_id` | `string` | Filter by HotMesh workflow ID |
+| `lt_type` | `string` | Filter by interceptor classification |
+| `limit` | `integer` | Max results (default: 50) |
+| `offset` | `integer` | Pagination offset (default: 0) |
+
+**Example request:**
+
+```
+GET /api/tasks?status=completed&workflow_type=reviewContent&limit=10
+```
+
+**Response 200:**
+
+```json
+{
+  "tasks": [
+    {
+      "id": "d4e5f6a7-...",
+      "workflow_id": "review-orch-post-456-a1b2c3d4",
+      "workflow_type": "reviewContent",
+      "lt_type": "workflow",
+      "task_queue": "long-tail",
+      "modality": "default",
+      "status": "completed",
+      "priority": 2,
+      "signal_id": "sig-abc123",
+      "parent_workflow_id": "review-orch-post-456-a1b2c3d4",
+      "origin_id": "review-orch-post-456-a1b2c3d4",
+      "parent_id": null,
+      "started_at": "2025-01-15T10:00:00.000Z",
+      "completed_at": "2025-01-15T10:00:05.230Z",
+      "envelope": "{\"data\":{\"contentId\":\"post-456\",\"content\":\"...\"},\"metadata\":{}}",
+      "metadata": null,
+      "error": null,
+      "milestones": [
+        { "name": "ai_review", "value": "approved" }
+      ],
+      "data": "{\"approved\":true,\"analysis\":{\"confidence\":0.92}}",
+      "created_at": "2025-01-15T10:00:00.000Z",
+      "updated_at": "2025-01-15T10:00:05.230Z"
+    }
+  ],
+  "total": 1
+}
+```
+
+## Get task details
+
+```
+GET /api/tasks/:id
+```
+
+**Path parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| `id` | Task UUID |
+
+**Response 200:** A single task object (same shape as the array element above).
+
+**Response 404:**
+
+```json
+{ "error": "Task not found" }
+```
+
+## Get process stats
+
+```
+GET /api/tasks/processes/stats
+```
+
+Aggregated process statistics with optional time period.
+
+**Query parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `period` | `string` | Time period filter (e.g., `24h`, `7d`) |
+
+**Response 200:** Aggregated statistics object.
+
+## List processes
+
+```
+GET /api/tasks/processes
+```
+
+List distinct `origin_id` values with summary stats. Each origin ID represents a process (a top-level orchestration and all its child workflows).
+
+**Query parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `workflow_type` | `string` | Filter by workflow type |
+| `status` | `string` | Filter by status |
+| `search` | `string` | Search filter |
+| `limit` | `integer` | Max results (default: 50) |
+| `offset` | `integer` | Pagination offset (default: 0) |
+
+**Response 200:** Process list with summary stats.
+
+## Get process details
+
+```
+GET /api/tasks/processes/:originId
+```
+
+Returns all tasks and escalations for a process (identified by `origin_id`).
+
+**Path parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| `originId` | Origin ID (correlation ID shared by sibling workflows) |
+
+**Response 200:**
+
+```json
+{
+  "origin_id": "review-orch-post-456-a1b2c3d4",
+  "tasks": [],
+  "escalations": []
+}
+```
+
+## Task fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `UUID` | Primary key |
+| `workflow_id` | `string` | HotMesh workflow ID |
+| `workflow_type` | `string` | Registered workflow name |
+| `lt_type` | `string` | Interceptor classification |
+| `task_queue` | `string` | Task queue the workflow ran on |
+| `modality` | `string` | Modality from workflow config |
+| `status` | `string` | `pending` or `completed` |
+| `priority` | `integer` | Numeric priority (lower = higher) |
+| `signal_id` | `string` | HotMesh signal ID for resume/replay |
+| `parent_workflow_id` | `string` | Orchestrator workflow ID |
+| `origin_id` | `string` | Correlation ID shared by sibling workflows |
+| `parent_id` | `string` | Direct parent workflow ID |
+| `started_at` | `ISO 8601` | When the workflow began |
+| `completed_at` | `ISO 8601` | When it finished (null while pending) |
+| `envelope` | `string` | JSON-serialized input envelope |
+| `metadata` | `object` | Arbitrary metadata |
+| `error` | `string` | Error message on failure |
+| `milestones` | `array` | Milestone objects emitted during execution |
+| `data` | `string` | JSON-serialized workflow return data |
+
+See [Data Model](../data.md) for the full SQL schema.

package/docs/api/users.md

@@ -0,0 +1,180 @@
+# Users API
+
+Users represent the humans who claim and resolve escalations. Each user has a unique `external_id` that maps to your application's identity system. All endpoints require authentication. Mutating endpoints (create, update, delete, role management) require admin access (`admin` or `superadmin` role).
+
+For service identities (CI bots, schedulers, automated agents), use the [Service Accounts API](service-accounts.md) instead. Service accounts share the same RBAC system but authenticate with API keys rather than passwords or OAuth.
+
+## List users
+
+```
+GET /api/users
+```
+
+**Query parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `role` | `string` | Filter by role name (e.g., `reviewer`) |
+| `roleType` | `string` | Filter by role type: `superadmin`, `admin`, or `member` |
+| `status` | `string` | Filter by status: `active`, `inactive`, or `suspended` |
+| `limit` | `integer` | Max results (default: 50) |
+| `offset` | `integer` | Pagination offset (default: 0) |
+
+**Example request:**
+
+```
+GET /api/users?role=reviewer&status=active&limit=10
+```
+
+**Response 200:**
+
+```json
+{
+  "users": [
+    {
+      "id": "b2c3d4e5-...",
+      "external_id": "jane",
+      "email": "jane@acme.com",
+      "display_name": "Jane Chen",
+      "status": "active",
+      "metadata": null,
+      "created_at": "2025-01-10T08:00:00.000Z",
+      "updated_at": "2025-01-10T08:00:00.000Z",
+      "roles": [
+        { "user_id": "b2c3d4e5-...", "role": "reviewer", "type": "member", "created_at": "2025-01-10T08:00:00.000Z" },
+        { "user_id": "b2c3d4e5-...", "role": "senior-reviewer", "type": "admin", "created_at": "2025-01-10T08:00:00.000Z" }
+      ]
+    }
+  ],
+  "total": 1
+}
+```
+
+## Get user details
+
+```
+GET /api/users/:id
+```
+
+**Path parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| `id` | User UUID |
+
+**Response 200:** A single user object with roles array.
+
+**Response 404:**
+
+```json
+{ "error": "User not found" }
+```
+
+## Create user
+
+```
+POST /api/users
+```
+
+**Request body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `external_id` | `string` | yes | Your application's identifier for this user |
+| `email` | `string` | no | Email address |
+| `display_name` | `string` | no | Display name |
+| `roles` | `array` | no | Initial role assignments (see below) |
+| `metadata` | `object` | no | Arbitrary metadata |
+
+Each element in `roles`:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `role` | `string` | yes | Role name |
+| `type` | `string` | yes | `superadmin`, `admin`, or `member` |
+
+**Example request:**
+
+```json
+{
+  "external_id": "jane",
+  "email": "jane@acme.com",
+  "display_name": "Jane Chen",
+  "roles": [
+    { "role": "reviewer", "type": "member" },
+    { "role": "senior-reviewer", "type": "admin" }
+  ]
+}
+```
+
+**Response 201:** The created user object with roles array.
+
+**Response 400:**
+
+```json
+{ "error": "external_id is required" }
+```
+
+```json
+{ "error": "Each role must have a role name and type (superadmin, admin, member)" }
+```
+
+**Response 409:**
+
+```json
+{ "error": "User with this external_id already exists" }
+```
+
+## Update user
+
+```
+PUT /api/users/:id
+```
+
+Partial update — only the fields you include are changed.
+
+**Request body:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `email` | `string` | New email address |
+| `display_name` | `string` | New display name |
+| `status` | `string` | `active`, `inactive`, or `suspended` |
+| `metadata` | `object` | Replacement metadata |
+
+**Example request:**
+
+```json
+{
+  "status": "suspended",
+  "metadata": { "suspension_reason": "pending investigation" }
+}
+```
+
+**Response 200:** The updated user object.
+
+**Response 404:**
+
+```json
+{ "error": "User not found" }
+```
+
+## Delete user
+
+```
+DELETE /api/users/:id
+```
+
+Deletes the user and all associated role assignments (cascade).
+
+**Response 200:**
+
+```json
+{ "deleted": true }
+```
+
+**Response 404:**
+
+```json
+{ "error": "User not found" }
+```