@minded-ai/mindedjs 3.1.31 → 3.1.32

package/docs/api/analytics.md

@@ -0,0 +1,132 @@
+# Analytics API
+
+Query agent analytics events for dashboards, BI tools, and audits.
+
+**Required scope**: `analytics`
+
+## Endpoints
+
+| Method | Endpoint        | Description                      |
+| ------ | --------------- | -------------------------------- |
+| GET    | `/agents/list`  | List agents in your organization |
+| POST   | `/events/agent` | Query agent analytics events     |
+
+---
+
+## List Agents
+
+```http
+GET /agents/list
+```
+
+Returns all agents belonging to your organization.
+
+### Response
+
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "agentId": "agent-uuid-1",
+      "displayName": "My Support Agent",
+      "createdAt": "2025-10-01T10:30:00.000Z"
+    }
+  ],
+  "count": 1
+}
+```
+
+### Response Fields
+
+| Field               | Type   | Description                      |
+| ------------------- | ------ | -------------------------------- |
+| `data[].agentId`    | string | Unique agent identifier          |
+| `data[].displayName`| string | Human-readable agent name        |
+| `data[].createdAt`  | string | ISO 8601 creation timestamp      |
+| `count`             | number | Total number of agents returned  |
+
+---
+
+## Query Agent Events
+
+```http
+POST /events/agent
+```
+
+Query analytics events for a specific agent.
+
+### Request Body
+
+| Field                 | Type   | Required | Description                                                   |
+| --------------------- | ------ | -------- | ------------------------------------------------------------- |
+| `agentId`             | string | Yes      | Agent UUID (must belong to your organization)                 |
+| `filters.environment` | string | No       | `development`, `staging`, or `production`. Default: `production` |
+| `filters.sessionId`   | string | No       | Filter by specific session UUID                               |
+| `filters.eventName`   | string | No       | Filter by event type                                          |
+| `filters.startDate`   | string | No       | Start date (ISO 8601)                                         |
+| `filters.endDate`     | string | No       | End date (ISO 8601)                                           |
+| `limit`               | number | No       | Records per page (1–1000). Default: 100                       |
+| `offset`              | number | No       | Records to skip. Default: 0                                   |
+
+### Request Example
+
+```json
+{
+  "agentId": "your-agent-id",
+  "filters": {
+    "environment": "production",
+    "startDate": "2025-10-01T00:00:00Z",
+    "endDate": "2025-10-31T23:59:59Z"
+  },
+  "limit": 100,
+  "offset": 0
+}
+```
+
+### Response
+
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": 1,
+      "agentId": "your-agent-id",
+      "sessionId": "session-uuid",
+      "environment": "production",
+      "eventName": "invocation_start",
+      "payload": { ... },
+      "created_at": "2025-10-14T08:37:44.000Z"
+    }
+  ],
+  "count": 1,
+  "limit": 100,
+  "offset": 0
+}
+```
+
+### Response Fields
+
+| Field              | Type   | Description                               |
+| ------------------ | ------ | ----------------------------------------- |
+| `data[].id`        | number | Event record ID                           |
+| `data[].agentId`   | string | Agent UUID                                |
+| `data[].sessionId` | string | Session UUID                              |
+| `data[].environment` | string | Environment where event occurred        |
+| `data[].eventName` | string | Event type                                |
+| `data[].payload`   | object | Event-specific data                       |
+| `data[].created_at`| string | ISO 8601 timestamp when event was recorded|
+| `count`            | number | Number of events in current page          |
+| `limit`            | number | Page size used                            |
+| `offset`           | number | Offset used                               |
+
+## Event Types
+
+The SDK automatically tracks built-in events. You can also emit custom events.
+
+**Built-in events**: `invocation_start`, `invocation_error`, `node_execution`, and more.
+
+**Custom events**: Use `trackAnalyticsEvent()` from your agent code.
+
+See [SDK Events - ANALYTICS_EVENT](../sdk/events.md#analytics_event) for details.

package/docs/api/knowledge.md

@@ -0,0 +1,460 @@
+# Knowledge API
+
+Manage documents within knowledge bases programmatically. Upload, update, retrieve metadata, and delete documents.
+
+**Required scope**: `knowledge-management`
+
+> **Prerequisite**: Knowledge bases are created in the platform dashboard. See [Knowledge Bases](../platform/knowledge-bases.md). This API manages documents within existing knowledge bases.
+
+## Document Upload Flow
+
+Uploading a document requires three steps:
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│  1. Request     │     │  2. Upload      │     │  3. Complete    │     │  4. Poll        │
+│  Upload Link    │────▶│  File to S3     │────▶│  Upload         │────▶│  Status         │
+└─────────────────┘     └─────────────────┘     └─────────────────┘     └─────────────────┘
+        │                       │                       │                       │
+        ▼                       ▼                       ▼                       ▼
+   POST /upload-link      PUT to uploadUrl      POST /upload-complete    GET /documents
+   Returns: uploadUrl,    Include headers       Returns: status          Check status
+   uploadId, s3Key        from response         "pending"                until "ready"
+```
+
+1. **Request upload link** — Call `/knowledge/documents/upload-link` to get a pre-signed S3 URL
+2. **Upload file** — PUT the file bytes to the returned `uploadUrl` with `requiredHeaders`
+3. **Complete upload** — Call `/knowledge/documents/upload-complete` with the `uploadId`
+4. **Poll status** — Query `/knowledge/documents` until `status` becomes `ready` or `failed`
+
+## Document Status Values
+
+| Status      | Description                                                    |
+| ----------- | -------------------------------------------------------------- |
+| `pending`   | Document uploaded, processing not yet started                  |
+| `processing`| Document is being processed (text extraction, chunking, embedding) |
+| `ready`     | Document processed successfully and available for retrieval    |
+| `failed`    | Processing failed; check error details                         |
+
+## Document Identifiers
+
+Documents can be referenced using two identifiers:
+
+| Identifier         | Description                                                                                     |
+| ------------------ | ----------------------------------------------------------------------------------------------- |
+| `s3Key`            | System-generated path in format `agents/<agentId>/<env>/<kbId>/<filename>`. Returned by upload endpoints. |
+| `customDocumentId` | Optional user-defined identifier. Use this to map documents to your external system IDs (e.g., CRM record ID, ticket ID). When provided during upload, you can use it instead of `s3Key` for update and delete operations. |
+
+## Custom Metadata
+
+The `metadata` field accepts arbitrary key-value pairs that you define. This is your custom metadata for filtering and organizing documents—not a predefined schema.
+
+```json
+{
+  "metadata": {
+    "category": "policy",
+    "locale": "en-US",
+    "version": "2.1",
+    "department": "support"
+  }
+}
+```
+
+Use metadata to filter documents during retrieval (see [Knowledge Base RAG API](../sdk/knowledge-base-rag.md)).
+
+---
+
+## Endpoints
+
+| Method | Endpoint                              | Description                        |
+| ------ | ------------------------------------- | ---------------------------------- |
+| POST   | `/knowledge/documents/upload-link`    | Get pre-signed URL for new document|
+| POST   | `/knowledge/documents/upload-complete`| Finalize new document upload       |
+| POST   | `/knowledge/documents/update/upload-link` | Get pre-signed URL to update document |
+| POST   | `/knowledge/documents/update/upload-complete` | Finalize document update   |
+| PATCH  | `/knowledge/documents/metadata`       | Update document metadata only      |
+| GET    | `/knowledge/documents`                | Get document metadata              |
+| DELETE | `/knowledge/documents`                | Delete a document                  |
+
+---
+
+## Create Upload Link
+
+```http
+POST /knowledge/documents/upload-link
+```
+
+Generate a pre-signed URL to upload a new document.
+
+### Request Body
+
+| Field              | Type   | Required | Description                                                     |
+| ------------------ | ------ | -------- | --------------------------------------------------------------- |
+| `agentId`          | string | Yes      | Agent UUID                                                      |
+| `environment`      | string | Yes      | `development`, `staging`, or `production`                       |
+| `knowledgeBaseId`  | string | Yes      | Knowledge base UUID                                             |
+| `fileName`         | string | Yes      | File name with extension (e.g., `policy.pdf`). If `.zip`, triggers batch import. |
+| `name`             | string | No       | Display name for the document                                   |
+| `metadata`         | object | No       | Custom key-value pairs for filtering                            |
+| `customDocumentId` | string | No       | Your external identifier for this document                      |
+
+### Request Example
+
+```json
+{
+  "agentId": "your-agent-id",
+  "environment": "production",
+  "knowledgeBaseId": "kb-abc123",
+  "fileName": "refund-policy.pdf",
+  "name": "Refund Policy",
+  "metadata": {
+    "category": "policy",
+    "locale": "en"
+  },
+  "customDocumentId": "DOC-12345"
+}
+```
+
+### Response
+
+```json
+{
+  "uploadId": "upload-uuid",
+  "uploadUrl": "https://s3.amazonaws.com/...",
+  "expiresIn": 3600,
+  "s3Key": "agents/agent-id/production/kb-abc123/refund-policy.pdf",
+  "documentId": "document-uuid",
+  "requiredHeaders": {
+    "Content-Type": "application/pdf"
+  }
+}
+```
+
+### Response Fields
+
+| Field             | Type   | Description                                              |
+| ----------------- | ------ | -------------------------------------------------------- |
+| `uploadId`        | string | Unique identifier for this upload session                |
+| `uploadUrl`       | string | Pre-signed S3 URL for file upload (expires per `expiresIn`) |
+| `expiresIn`       | number | Seconds until `uploadUrl` expires                        |
+| `s3Key`           | string | Document path in storage; use for subsequent operations  |
+| `documentId`      | string | System-generated document UUID                           |
+| `requiredHeaders` | object | Headers to include when uploading to `uploadUrl`         |
+
+### Uploading the File
+
+After receiving the response, upload your file:
+
+```bash
+curl -X PUT "<uploadUrl>" \
+  -H "Content-Type: application/pdf" \
+  --data-binary @refund-policy.pdf
+```
+
+---
+
+## Complete Upload
+
+```http
+POST /knowledge/documents/upload-complete
+```
+
+Finalize the upload and trigger document processing.
+
+### Request Body
+
+| Field      | Type   | Required | Description           |
+| ---------- | ------ | -------- | --------------------- |
+| `uploadId` | string | Yes      | The `uploadId` from upload-link response |
+
+### Request Example
+
+```json
+{
+  "uploadId": "upload-uuid"
+}
+```
+
+### Response (Document)
+
+```json
+{
+  "type": "document",
+  "s3Key": "agents/agent-id/production/kb-abc123/refund-policy.pdf",
+  "documentId": "document-uuid",
+  "name": "Refund Policy",
+  "createdAt": "2026-01-15T12:00:00.000Z",
+  "updatedAt": "2026-01-15T12:00:00.000Z",
+  "status": "pending"
+}
+```
+
+### Response (ZIP Import)
+
+When `fileName` ends with `.zip`, the response indicates a batch import job:
+
+```json
+{
+  "type": "zip_import",
+  "zipJobId": "job-uuid",
+  "status": "Pending",
+  "s3Key": "agents/agent-id/production/kb-abc123/archive.zip"
+}
+```
+
+### Response Fields
+
+| Field        | Type   | Description                                           |
+| ------------ | ------ | ----------------------------------------------------- |
+| `type`       | string | `document` for single files, `zip_import` for archives|
+| `s3Key`      | string | Document path in storage                              |
+| `documentId` | string | Document UUID (for `document` type)                   |
+| `zipJobId`   | string | Import job UUID (for `zip_import` type)               |
+| `name`       | string | Document display name                                 |
+| `status`     | string | Processing status (see [Status Values](#document-status-values)) |
+| `createdAt`  | string | ISO 8601 creation timestamp                           |
+| `updatedAt`  | string | ISO 8601 last update timestamp                        |
+
+---
+
+## Create Update Upload Link
+
+```http
+POST /knowledge/documents/update/upload-link
+```
+
+Generate a pre-signed URL to replace an existing document's content.
+
+### Request Body
+
+| Field              | Type   | Required | Description                                                     |
+| ------------------ | ------ | -------- | --------------------------------------------------------------- |
+| `agentId`          | string | Yes      | Agent UUID                                                      |
+| `environment`      | string | Yes      | `development`, `staging`, or `production`                       |
+| `knowledgeBaseId`  | string | Yes      | Knowledge base UUID                                             |
+| `s3Key`            | string | *        | Document path to update. Required if `customDocumentId` not provided. |
+| `customDocumentId` | string | *        | Your external document ID. Required if `s3Key` not provided.    |
+| `fileName`         | string | Yes      | New file name                                                   |
+| `metadata`         | object | No       | Updated custom metadata (replaces existing)                     |
+
+> **Note**: Provide either `s3Key` or `customDocumentId`, not both.
+
+### Request Example
+
+```json
+{
+  "agentId": "your-agent-id",
+  "environment": "production",
+  "knowledgeBaseId": "kb-abc123",
+  "customDocumentId": "DOC-12345",
+  "fileName": "refund-policy-v2.pdf",
+  "metadata": {
+    "category": "policy",
+    "locale": "en",
+    "version": "2.0"
+  }
+}
+```
+
+### Response
+
+```json
+{
+  "uploadId": "upload-uuid",
+  "uploadUrl": "https://s3.amazonaws.com/...",
+  "expiresIn": 3600,
+  "s3Key": "agents/agent-id/production/kb-abc123/refund-policy-v2.pdf",
+  "requiredHeaders": {
+    "Content-Type": "application/pdf"
+  }
+}
+```
+
+---
+
+## Complete Update Upload
+
+```http
+POST /knowledge/documents/update/upload-complete
+```
+
+Finalize document update and trigger reprocessing.
+
+### Request Body
+
+| Field      | Type   | Required | Description           |
+| ---------- | ------ | -------- | --------------------- |
+| `uploadId` | string | Yes      | The `uploadId` from update/upload-link response |
+
+### Request Example
+
+```json
+{
+  "uploadId": "upload-uuid"
+}
+```
+
+### Response
+
+```json
+{
+  "s3Key": "agents/agent-id/production/kb-abc123/refund-policy-v2.pdf",
+  "documentId": "document-uuid",
+  "name": "Refund Policy",
+  "updatedAt": "2026-01-16T12:00:00.000Z",
+  "status": "pending"
+}
+```
+
+---
+
+## Update Metadata
+
+```http
+PATCH /knowledge/documents/metadata
+```
+
+Update document display name and/or metadata without re-uploading the file.
+
+### Request Body
+
+| Field              | Type   | Required | Description                                                     |
+| ------------------ | ------ | -------- | --------------------------------------------------------------- |
+| `agentId`          | string | Yes      | Agent UUID                                                      |
+| `environment`      | string | Yes      | `development`, `staging`, or `production`                       |
+| `knowledgeBaseId`  | string | Yes      | Knowledge base UUID                                             |
+| `s3Key`            | string | *        | Document path. Required if `customDocumentId` not provided.     |
+| `customDocumentId` | string | *        | Your external document ID. Required if `s3Key` not provided.    |
+| `name`             | string | No       | New display name                                                |
+| `metadata`         | object | No       | New custom metadata (replaces existing)                         |
+
+### Request Example
+
+```json
+{
+  "agentId": "your-agent-id",
+  "environment": "production",
+  "knowledgeBaseId": "kb-abc123",
+  "s3Key": "agents/agent-id/production/kb-abc123/refund-policy.pdf",
+  "name": "Refund Policy (Updated)",
+  "metadata": {
+    "category": "policy",
+    "locale": "en",
+    "reviewed": "true"
+  }
+}
+```
+
+### Response
+
+```json
+{
+  "s3Key": "agents/agent-id/production/kb-abc123/refund-policy.pdf",
+  "documentId": "document-uuid",
+  "name": "Refund Policy (Updated)",
+  "metadata": {
+    "category": "policy",
+    "locale": "en",
+    "reviewed": "true"
+  },
+  "updatedAt": "2026-01-16T14:00:00.000Z"
+}
+```
+
+---
+
+## Get Document
+
+```http
+GET /knowledge/documents
+```
+
+Retrieve metadata for a specific document.
+
+### Query Parameters
+
+| Parameter          | Type   | Required | Description                                                     |
+| ------------------ | ------ | -------- | --------------------------------------------------------------- |
+| `agentId`          | string | Yes      | Agent UUID                                                      |
+| `environment`      | string | Yes      | `development`, `staging`, or `production`                       |
+| `knowledgeBaseId`  | string | Yes      | Knowledge base UUID                                             |
+| `s3Key`            | string | *        | Document path. Required if `customDocumentId` not provided.     |
+| `customDocumentId` | string | *        | Your external document ID. Required if `s3Key` not provided.    |
+
+### Request Example
+
+```
+GET /knowledge/documents?agentId=your-agent-id&environment=production&knowledgeBaseId=kb-abc123&s3Key=agents/agent-id/production/kb-abc123/refund-policy.pdf
+```
+
+### Response
+
+```json
+{
+  "s3Key": "agents/agent-id/production/kb-abc123/refund-policy.pdf",
+  "documentId": "document-uuid",
+  "customDocumentId": "DOC-12345",
+  "name": "Refund Policy",
+  "status": "ready",
+  "metadata": {
+    "category": "policy",
+    "locale": "en"
+  },
+  "createdAt": "2026-01-15T12:00:00.000Z",
+  "updatedAt": "2026-01-16T14:00:00.000Z"
+}
+```
+
+### Response Fields
+
+| Field              | Type   | Description                                              |
+| ------------------ | ------ | -------------------------------------------------------- |
+| `s3Key`            | string | Document path in storage                                 |
+| `documentId`       | string | System-generated document UUID                           |
+| `customDocumentId` | string | Your external document ID (if provided during upload)    |
+| `name`             | string | Document display name                                    |
+| `status`           | string | Processing status (see [Status Values](#document-status-values)) |
+| `metadata`         | object | Custom key-value pairs                                   |
+| `createdAt`        | string | ISO 8601 creation timestamp                              |
+| `updatedAt`        | string | ISO 8601 last update timestamp                           |
+
+---
+
+## Delete Document
+
+```http
+DELETE /knowledge/documents
+```
+
+Remove a document from the knowledge base.
+
+### Request Body
+
+| Field              | Type   | Required | Description                                                     |
+| ------------------ | ------ | -------- | --------------------------------------------------------------- |
+| `agentId`          | string | Yes      | Agent UUID                                                      |
+| `environment`      | string | Yes      | `development`, `staging`, or `production`                       |
+| `knowledgeBaseId`  | string | Yes      | Knowledge base UUID                                             |
+| `s3Key`            | string | *        | Document path. Required if `customDocumentId` not provided.     |
+| `customDocumentId` | string | *        | Your external document ID. Required if `s3Key` not provided.    |
+
+### Request Example
+
+```json
+{
+  "agentId": "your-agent-id",
+  "environment": "production",
+  "knowledgeBaseId": "kb-abc123",
+  "customDocumentId": "DOC-12345"
+}
+```
+
+### Response
+
+```json
+{
+  "success": true,
+  "s3Key": "agents/agent-id/production/kb-abc123/refund-policy.pdf",
+  "documentId": "document-uuid"
+}
+```

package/docs/api/overview.md

@@ -0,0 +1,78 @@
+# REST API Overview
+
+The Minded REST API provides programmatic access to analytics events and knowledge base document management.
+
+## Base URL
+
+```
+https://api.minded.com/api/v1
+```
+
+## Authentication
+
+All API requests require an **organization API token** passed via the `Authorization` header:
+
+```http
+Authorization: Bearer md_yourTokenHere
+```
+
+### Token Characteristics
+
+- **Scoped**: Permissions are granted per token
+- **Org-bound**: Requests are authorized for the organization tied to the token
+- **One-time visible**: The plaintext token is shown only when created and cannot be recovered
+
+### Managing Tokens
+
+In the Minded dashboard, navigate to **Organization Settings → API Tokens** to create, view, or revoke tokens.
+
+### Token Scopes
+
+| Scope                  | Grants Access To           |
+| ---------------------- | -------------------------- |
+| `analytics`            | [Analytics API](analytics.md) |
+| `knowledge-management` | [Knowledge API](knowledge.md) |
+
+## Rate Limiting
+
+Rate limits vary by deployment (default: ~10 requests/minute). Response headers indicate current limits:
+
+| Header                  | Description                    |
+| ----------------------- | ------------------------------ |
+| `RateLimit-Limit`       | Maximum requests allowed       |
+| `RateLimit-Remaining`   | Requests remaining in window   |
+| `RateLimit-Reset`       | Seconds until limit resets     |
+
+## Response Format
+
+All responses are JSON. Successful responses typically include:
+
+```json
+{
+  "success": true,
+  "data": { ... }
+}
+```
+
+## Error Codes
+
+| Code | Description                                                  |
+| ---- | ------------------------------------------------------------ |
+| 400  | Bad request — missing required fields or invalid parameters  |
+| 401  | Unauthorized — invalid or missing token                      |
+| 403  | Forbidden — token missing required scope                     |
+| 404  | Not found — resource does not exist or does not belong to your organization |
+| 429  | Too many requests — rate limit exceeded                      |
+| 500  | Internal server error                                        |
+
+Error responses include details:
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Missing required field: agentId"
+  }
+}
+```