@hotmeshio/long-tail 0.1.4 → 0.1.6

package/docs/api/roles.md

@@ -0,0 +1,390 @@
+# Roles API
+
+Roles connect workflows to people. When a workflow escalates, the escalation targets a role. Users assigned that role see the escalation in their queue. Roles are implicit — they exist the moment you reference them. There is no separate "create role" step.
+
+Role management endpoints are nested under `/api/users/:id/roles`. All endpoints require authentication.
+
+## Role Types
+
+Every role assignment has a `type` that controls management permissions. All three types can claim and resolve escalations for their role.
+
+| Type | Permissions |
+|------|-------------|
+| `member` | Claim and resolve escalations for this role |
+| `admin` | Everything a member can do, plus manage users within this role |
+| `superadmin` | Full access — manage all roles, all users, system configuration |
+
+A user can hold multiple roles with different types. For example, a user might be a `member` of `reviewer` and an `admin` of `senior-reviewer`.
+
+## List roles for a user
+
+```
+GET /api/users/:id/roles
+```
+
+**Path parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| `id` | User UUID |
+
+**Response 200:**
+
+```json
+{
+  "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"
+    }
+  ]
+}
+```
+
+## Add role to user
+
+```
+POST /api/users/:id/roles
+```
+
+**Path parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| `id` | User UUID |
+
+**Request body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `role` | `string` | yes | Role name (e.g., `reviewer`) |
+| `type` | `string` | yes | `superadmin`, `admin`, or `member` |
+
+**Example request:**
+
+```json
+{ "role": "reviewer", "type": "member" }
+```
+
+**Response 201:**
+
+```json
+{
+  "user_id": "b2c3d4e5-...",
+  "role": "reviewer",
+  "type": "member",
+  "created_at": "2025-01-15T12:00:00.000Z"
+}
+```
+
+**Response 400:**
+
+```json
+{ "error": "role and type are required" }
+```
+
+```json
+{ "error": "type must be superadmin, admin, or member" }
+```
+
+A user can hold each role at most once. The primary key is `(user_id, role)`. Adding a role that already exists will return an error.
+
+## Remove role from user
+
+```
+DELETE /api/users/:id/roles/:role
+```
+
+**Path parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| `id` | User UUID |
+| `role` | Role name to remove |
+
+**Response 200:**
+
+```json
+{ "removed": true }
+```
+
+**Response 404:**
+
+```json
+{ "error": "Role not found" }
+```
+
+---
+
+## Role Management
+
+These endpoints manage roles as standalone entities and are nested under `/api/roles`. All endpoints require authentication.
+
+### List all roles
+
+```
+GET /api/roles
+```
+
+Returns all distinct role names known to the system.
+
+**Response 200:**
+
+```json
+{
+  "roles": ["reviewer", "senior-reviewer", "admin"]
+}
+```
+
+### List roles with details
+
+```
+GET /api/roles/details
+```
+
+Returns all roles with usage counts.
+
+**Response 200:**
+
+```json
+{
+  "roles": [
+    { "role": "reviewer", "user_count": 5 },
+    { "role": "senior-reviewer", "user_count": 2 }
+  ]
+}
+```
+
+### Create a role
+
+```
+POST /api/roles
+```
+
+Create a standalone role. Requires admin.
+
+**Request body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `role` | `string` | yes | Role name (lowercase letters, numbers, hyphens, underscores; must start with a letter) |
+
+**Example request:**
+
+```json
+{ "role": "senior-reviewer" }
+```
+
+**Response 201:**
+
+```json
+{ "role": "senior-reviewer" }
+```
+
+**Response 400:**
+
+```json
+{ "error": "role is required" }
+```
+
+```json
+{ "error": "Role must start with a letter and contain only lowercase letters, numbers, hyphens, and underscores" }
+```
+
+### Delete a role
+
+```
+DELETE /api/roles/:role
+```
+
+Delete a role if it has no references. Requires admin.
+
+**Path parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| `role` | Role name to delete |
+
+**Response 200:**
+
+```json
+{ "deleted": true }
+```
+
+**Response 409:**
+
+```json
+{ "error": "Cannot delete role" }
+```
+
+---
+
+## Escalation Chains
+
+Escalation chains define which roles can escalate to which other roles. Managed under `/api/roles/escalation-chains`.
+
+### List all escalation chains
+
+```
+GET /api/roles/escalation-chains
+```
+
+Returns all escalation chain pairs.
+
+**Response 200:**
+
+```json
+{
+  "chains": [
+    { "source_role": "reviewer", "target_role": "senior-reviewer" }
+  ]
+}
+```
+
+### Add an escalation chain
+
+```
+POST /api/roles/escalation-chains
+```
+
+Add a single escalation chain entry. Requires admin.
+
+**Request body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `source_role` | `string` | yes | Role that can escalate |
+| `target_role` | `string` | yes | Role to escalate to |
+
+**Example request:**
+
+```json
+{ "source_role": "reviewer", "target_role": "senior-reviewer" }
+```
+
+**Response 201:**
+
+```json
+{ "source_role": "reviewer", "target_role": "senior-reviewer" }
+```
+
+**Response 400:**
+
+```json
+{ "error": "source_role and target_role are required" }
+```
+
+### Remove an escalation chain
+
+```
+DELETE /api/roles/escalation-chains
+```
+
+Remove a single escalation chain entry. Requires admin.
+
+**Request body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `source_role` | `string` | yes | Source role |
+| `target_role` | `string` | yes | Target role |
+
+**Response 200:**
+
+```json
+{ "removed": true }
+```
+
+**Response 404:**
+
+```json
+{ "error": "Chain entry not found" }
+```
+
+### Get escalation targets for a role
+
+```
+GET /api/roles/:role/escalation-targets
+```
+
+Returns the allowed escalation targets for a specific role.
+
+**Path parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| `role` | Role name |
+
+**Response 200:**
+
+```json
+{
+  "targets": ["senior-reviewer", "manager"]
+}
+```
+
+### Replace escalation targets for a role
+
+```
+PUT /api/roles/:role/escalation-targets
+```
+
+Replace all escalation targets for a role. Requires admin.
+
+**Path parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| `role` | Role name |
+
+**Request body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `targets` | `string[]` | yes | New list of target roles |
+
+**Example request:**
+
+```json
+{ "targets": ["senior-reviewer", "manager"] }
+```
+
+**Response 200:**
+
+```json
+{ "role": "reviewer", "targets": ["senior-reviewer", "manager"] }
+```
+
+**Response 400:**
+
+```json
+{ "error": "targets must be an array of strings" }
+```
+
+---
+
+## Roles in Workflow Configuration
+
+Roles also appear in workflow configuration. When you register a workflow, `default_role` sets the escalation target and `roles` lists every role allowed to claim escalations:
+
+```
+PUT /api/workflows/reviewContent/config
+
+{
+  "is_lt": true,
+  "default_role": "reviewer",
+  "roles": ["reviewer", "senior-reviewer"]
+}
+```
+
+When `reviewContent` escalates, the escalation targets `reviewer` by default. Users with either `reviewer` or `senior-reviewer` can claim it.
+
+See [Workflows API](workflows.md) for full configuration details.

package/docs/api/service-accounts.md

@@ -0,0 +1,188 @@
+# Service Accounts API
+
+Service accounts are named identities that authenticate with API keys instead of passwords. They share the same role-based access control as human users. All endpoints require admin access.
+
+## List service accounts
+
+```
+GET /api/bot-accounts
+```
+
+**Query parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `limit` | `integer` | Max results (default: 50) |
+| `offset` | `integer` | Pagination offset (default: 0) |
+
+**Response 200:**
+
+```json
+{
+  "bots": [
+    {
+      "id": "a1b2c3d4-...",
+      "external_id": "ci-bot",
+      "display_name": "CI Bot",
+      "account_type": "bot",
+      "description": "Runs scheduled workflows",
+      "status": "active",
+      "roles": [
+        { "role": "scheduler", "type": "member", "created_at": "2025-03-01T00:00:00.000Z" }
+      ],
+      "created_at": "2025-03-01T00:00:00.000Z",
+      "updated_at": "2025-03-01T00:00:00.000Z"
+    }
+  ],
+  "total": 1
+}
+```
+
+## Get service account details
+
+```
+GET /api/bot-accounts/:id
+```
+
+**Response 200:** A single service account object.
+
+**Response 404:**
+
+```json
+{ "error": "Bot not found" }
+```
+
+## Create service account
+
+```
+POST /api/bot-accounts
+```
+
+**Request body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | `string` | yes | Unique identifier (used as `external_id`) |
+| `display_name` | `string` | no | Human-readable name |
+| `description` | `string` | no | Purpose of this service account |
+| `roles` | `array` | no | Initial role assignments: `[{ role, type }]` |
+
+**Response 201:** The created service account object.
+
+**Response 409:**
+
+```json
+{ "error": "Bot with this name already exists" }
+```
+
+## Update service account
+
+```
+PUT /api/bot-accounts/:id
+```
+
+**Request body:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `display_name` | `string` | New display name |
+| `description` | `string` | New description |
+| `status` | `string` | `active`, `inactive`, or `suspended` |
+
+**Response 200:** The updated service account object.
+
+## Delete service account
+
+```
+DELETE /api/bot-accounts/:id
+```
+
+Deletes the service account and all its API keys (cascade).
+
+**Response 200:**
+
+```json
+{ "deleted": true }
+```
+
+## Service account roles
+
+Roles work identically to user roles.
+
+```
+GET    /api/bot-accounts/:id/roles
+POST   /api/bot-accounts/:id/roles       { "role": "scheduler", "type": "member" }
+DELETE /api/bot-accounts/:id/roles/:role
+```
+
+## API keys
+
+### Generate key
+
+```
+POST /api/bot-accounts/:id/api-keys
+```
+
+**Request body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | `string` | yes | Key name (unique per service account) |
+| `scopes` | `string[]` | no | Allowed scopes (default: `[]`) |
+| `expires_at` | `string` | no | ISO 8601 expiry date |
+
+**Response 201:**
+
+```json
+{
+  "id": "key-uuid",
+  "rawKey": "lt_bot_a1b2c3d4e5f6..."
+}
+```
+
+The `rawKey` is shown **once**. It cannot be retrieved again.
+
+### List keys
+
+```
+GET /api/bot-accounts/:id/api-keys
+```
+
+Returns key metadata without secret values.
+
+```json
+{
+  "keys": [
+    {
+      "id": "key-uuid",
+      "name": "production",
+      "scopes": ["mcp:tool:call"],
+      "last_used_at": "2025-03-15T12:00:00.000Z",
+      "created_at": "2025-03-01T00:00:00.000Z"
+    }
+  ]
+}
+```
+
+### Revoke key
+
+```
+DELETE /api/bot-accounts/:id/api-keys/:keyId
+```
+
+**Response 200:**
+
+```json
+{ "revoked": true }
+```
+
+## Using a service account API key
+
+Include the raw key as a Bearer token in any API request:
+
+```bash
+curl -H "Authorization: Bearer lt_bot_a1b2c3d4e5f6..." \
+  http://localhost:3000/api/tasks
+```
+
+The service account authenticates through the same middleware as human users. RBAC checks use the account's assigned roles.

package/docs/api/settings.md

@@ -0,0 +1,33 @@
+# Settings API
+
+Returns frontend-relevant configuration. No secrets are exposed. This endpoint does not require authentication — it is public so the login page can read configuration before the user has a token.
+
+## Get settings
+
+```
+GET /api/settings
+```
+
+**Response 200:**
+
+```json
+{
+  "telemetry": {
+    "traceUrl": "https://ui.honeycomb.io/pubsubdb/environments/test/datasets/long-tail/trace?trace_id={traceId}"
+  },
+  "escalation": {
+    "claimDurations": [15, 30, 60, 120, 480]
+  },
+  "events": {
+    "transport": "nats",
+    "natsWsUrl": "ws://localhost:8222"
+  }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `telemetry.traceUrl` | `string \| null` | Template string where `{traceId}` is replaced with the actual trace ID to build a link to the trace viewer. Returns `null` if no trace URL is configured. |
+| `escalation.claimDurations` | `number[]` | Available claim duration options in minutes. Used by the frontend to populate duration selectors. Configurable via the `LT_CLAIM_DURATION_OPTIONS` environment variable (JSON array). |
+| `events.transport` | `string \| null` | Event transport type (e.g., `"nats"`). `null` if no event transport is configured. |
+| `events.natsWsUrl` | `string \| null` | NATS WebSocket URL for real-time event subscriptions. Only present when NATS is the configured transport. |