@epilot/sdk 2.18.21 → 2.18.23

package/docs/ai-agents.md

@@ -73,6 +73,8 @@ const { data } = await aiAgentsClient.createAgent(...)
 - [`PendingAction`](#pendingaction)
 - [`ExecutionError`](#executionerror)
 - [`ExecutionMetrics`](#executionmetrics)
+- [`AgentExecutionEventStatus`](#agentexecutioneventstatus)
+- [`AgentExecutionEvent`](#agentexecutionevent)
 - [`ToolPreview`](#toolpreview)
 - [`PreviewActionType`](#previewactiontype)
 - [`PreviewEntity`](#previewentity)
@@ -105,7 +107,7 @@ const { data } = await aiAgentsClient.createAgent(...)
 
 ### `createAgent`
 
-Create Agent definition
+Creates a new custom agent. System skills cannot be created via this endpoint.
 
 `POST /v1/agents`
 
@@ -215,7 +217,8 @@ const { data } = await client.createAgent(
 
 ### `listAgents`
 
-List all agent configurations
+Lists agents from both system skills and custom agents.
+Use query parameters to filter by source, availability, or entity schema.
 
 `GET /v1/agents`
 
@@ -292,7 +295,9 @@ const { data } = await client.listAgents({
 
 ### `getAgentById`
 
-Get the agent configuration by ID
+Retrieves an agent by ID. Supports both:
+- System skill IDs (prefixed): "skill:email-categorizer"
+- Custom agent IDs (UUID): "0336a235-9417-4dd8-894c-fe81285bba75"
 
 `GET /v1/agents/{agent_id}`
 
@@ -362,7 +367,7 @@ const { data } = await client.getAgentById({
 
 ### `updateAgentById`
 
-Update the agent configuration by ID
+Updates a custom agent. System skills cannot be updated via this endpoint.
 
 `PUT /v1/agents/{agent_id}`
 
@@ -474,7 +479,7 @@ const { data } = await client.updateAgentById(
 
 ### `deleteAgentById`
 
-Delete the agent configuration by ID
+Deletes a custom agent. System skills cannot be deleted via this endpoint.
 
 `DELETE /v1/agents/{agent_id}`
 
@@ -488,7 +493,10 @@ const { data } = await client.deleteAgentById({
 
 ### `executeAgent`
 
-Execute an agent
+Executes an agent (system skill or custom agent).
+Supports both:
+- System skill IDs (prefixed): "skill:email-categorizer"
+- Custom agent IDs (UUID): "0336a235-9417-4dd8-894c-fe81285bba75"
 
 `POST /v1/agents/{agent_id}/execute`
 
@@ -624,7 +632,9 @@ const { data } = await client.executeAgent(
 
 ### `executeAgentStream`
 
-Execute an agent with streaming response
+Executes an agent with real-time streaming of tokens and tool events.
+Returns Server-Sent Events (SSE) stream with token-by-token output,
+tool call progress, and completion status.
 
 `POST /v1/agents/{agent_id}/execute/stream`
 
@@ -1007,7 +1017,7 @@ const { data } = await client.cancelExecution({
 
 ### `getExecutionTrace`
 
-Get execution trace/iterations
+Returns the step-by-step reasoning and tool calls for ReAct mode executions. Returns empty iterations array for direct mode executions.
 
 `GET /v1/executions/{execution_id}/trace`
 
@@ -1113,7 +1123,7 @@ const { data } = await client.putExecutionFeedback(
 
 ### `approveExecution`
 
-Approve pending action
+Approves a pending tool action when execution is in waiting_approval status
 
 `POST /v1/executions/{execution_id}/approve`
 
@@ -1125,8 +1135,7 @@ const { data } = await client.approveExecution(
   {
     reason: 'string',
     approved_action_ids: ['string'],
-    rejected_action_ids: ['string'],
-    share_scope: 'primary_only'
+    rejected_action_ids: ['string']
   },
 )
 ```
@@ -1234,7 +1243,7 @@ const { data } = await client.approveExecution(
 
 ### `rejectExecution`
 
-Reject pending action
+Rejects a pending tool action when execution is in waiting_approval status
 
 `POST /v1/executions/{execution_id}/reject`
 
@@ -1352,7 +1361,7 @@ const { data } = await client.rejectExecution(
 
 ### `streamExecution`
 
-Reconnect to execution stream
+Reconnects to an execution's event stream after approval. Replays missed events from event log and continues streaming if execution is still running.
 
 `GET /v1/executions/{execution_id}/stream`
 
@@ -1367,7 +1376,7 @@ const { data } = await client.streamExecution({
 
 ### `chat`
 
-Streaming chat with AI agent
+Initiates a streaming chat session with an AI agent. Supports server-side conversation memory via conversationId or client-provided history via clientHistory.
 
 `POST /v1/chat`
 
@@ -1409,7 +1418,7 @@ const { data } = await client.chat(
 
 ### `listConversations`
 
-List conversations
+Lists conversations for the authenticated user, sorted by most recent.
 
 `GET /v1/conversations`
 
@@ -1453,7 +1462,7 @@ const { data } = await client.listConversations({
 
 ### `getConversation`
 
-Get conversation with messages
+Retrieves a conversation and its message history.
 
 `GET /v1/conversations/{conversation_id}`
 
@@ -1517,7 +1526,7 @@ const { data } = await client.getConversation({
 
 ### `deleteConversation`
 
-Delete conversation
+Deletes a conversation and all its messages.
 
 `DELETE /v1/conversations/{conversation_id}`
 
@@ -1531,7 +1540,7 @@ const { data } = await client.deleteConversation({
 
 ### `submitConversationFeedback`
 
-Submit feedback for an assistant turn
+Records a thumbs up/down (with optional comment) for the assistant turn identified by its Langfuse trace id. The rating is persisted on the message and mirrored to Langfuse as a trace score.
 
 `POST /v1/conversations/{conversation_id}/feedback`
 
@@ -1827,7 +1836,6 @@ type ApproveExecutionRequest = {
   reason?: string
   approved_action_ids?: string[]
   rejected_action_ids?: string[]
-  share_scope?: "primary_only" | "primary_and_relations"
 }
 ```
 
@@ -2072,6 +2080,55 @@ type ExecutionMetrics = {
 }
 ```
 
+### `AgentExecutionEventStatus`
+
+Lifecycle status carried on an agent execution event.
+
+Deliberately narrower than `ExecutionStatus`, which is the stored status of
+the execution row: `pending` and `running` both surface as `started`, and
+`cancelled` surfaces as `failed`. Consumers must not assume the two
+vocabularies are interchang
+
+```ts
+type AgentExecutionEventStatus = "started" | "completed" | "failed" | "approval_required"
+```
+
+### `AgentExecutionEvent`
+
+Detail payload of the `agent-execution-status-update` event, published on
+the AI Agents event bus with source `ai-agents`.
+
+`execution_context` and `input` are present on every status, so a consumer
+can tell whether an execution is theirs, and what it belonged to, from the
+terminal event alone — wit
+
+```ts
+type AgentExecutionEvent = {
+  executionId: string
+  agentId: string
+  orgId: string
+  userId?: string
+  execution_status: "started" | "completed" | "failed" | "approval_required"
+  execution_context?: "flows" | "copilot" | "api"
+  input?: Record<string, unknown>
+  output?: Record<string, unknown>
+  error?: {
+    message?: string
+    code?: string
+    stack?: string
+  }
+  duration?: number
+  iterations?: number
+  iteration?: number
+  message?: string
+  toolCalls?: Array<{
+    name?: string
+    args?: Record<string, unknown>
+  }>
+  timestamp?: string // date-time
+}
+```
+
 ### `ToolPreview`
 
 Structured preview data for approval UI. Provides a generic format that any tool can populate.

package/docs/customer-portal.md

@@ -131,6 +131,7 @@ const { data } = await customerPortalClient.upsertPortal(...)
 - [`createCustomEntityActivity`](#createcustomentityactivity)
 - [`saveEntityFile`](#saveentityfile)
 - [`deleteEntityFile`](#deleteentityfile)
+- [`getFilePreview`](#getfilepreview)
 - [`trackFileDownloaded`](#trackfiledownloaded)
 - [`getBillingEvents`](#getbillingevents)
 - [`triggerEntityAccessEvent`](#triggerentityaccessevent)
@@ -141,6 +142,7 @@ const { data } = await customerPortalClient.upsertPortal(...)
 - [`updateWorkflowStepAsDone`](#updateworkflowstepasdone)
 - [`getEntityWorkflows`](#getentityworkflows)
 - [`getEntityPortalWorkflows`](#getentityportalworkflows)
+- [`getEntityPortalWorkflowsBatch`](#getentityportalworkflowsbatch)
 - [`uploadMeterReadingPhoto`](#uploadmeterreadingphoto)
 - [`createMeterReading`](#createmeterreading)
 - [`getAllowedMeterReadingRange`](#getallowedmeterreadingrange)
@@ -245,6 +247,7 @@ const { data } = await customerPortalClient.upsertPortal(...)
 - [`EntityEditRule`](#entityeditrule)
 - [`ActivityItem`](#activityitem)
 - [`FileItem`](#fileitem)
+- [`FilePreviewResult`](#filepreviewresult)
 - [`EntityFileCount`](#entityfilecount)
 - [`AdminUser`](#adminuser)
 - [`Grant`](#grant)
@@ -256,6 +259,7 @@ const { data } = await customerPortalClient.upsertPortal(...)
 - [`WorkflowStep`](#workflowstep)
 - [`PortalWorkflow`](#portalworkflow)
 - [`PortalWorkflowTask`](#portalworkflowtask)
+- [`EntityPortalWorkflows`](#entityportalworkflows)
 - [`PortalTaskConfig`](#portaltaskconfig)
 - [`BaseBillingEvent`](#basebillingevent)
 - [`InstallmentEvent`](#installmentevent)
@@ -2056,7 +2060,7 @@ const { data } = await client.getPublicPortalExtensionDetailsV3({
 
 ### `getConsumption`
 
-Get Consumption
+Get energy consumption data between a given time period.
 
 `GET /v2/portal/consumption`
 
@@ -2095,7 +2099,7 @@ const { data } = await client.getConsumption({
 
 ### `prepareVisualizationExport`
 
-Prepare Visualization Export
+Asks an installed App to prepare a downloadable export of a visualization (consumption chart, dynamic tariff chart, etc.). The export is produced by the third-party App via a configured portal extensi
 
 `POST /v2/portal/visualization:export`
 
@@ -2136,7 +2140,7 @@ const { data } = await client.prepareVisualizationExport(
 
 ### `getVisualizationMetadata`
 
-Get Visualization Metadata
+Returns runtime metadata describing how a visualization (consumption / price / cost chart) should be rendered for a given portal context (meter, contract, etc). Resolves the extension's `visualization
 
 `GET /v2/portal/visualization/metadata`
 
@@ -2178,7 +2182,7 @@ const { data } = await client.getVisualizationMetadata({
 
 ### `getCosts`
 
-Get Costs
+Get energy cost data between a given time period.
 
 `GET /v2/portal/costs`
 
@@ -2219,7 +2223,7 @@ const { data } = await client.getCosts({
 
 ### `getPrices`
 
-Get Prices
+Get energy prices data between a given time period.
 
 `GET /v2/portal/prices`
 
@@ -5767,6 +5771,33 @@ const { data } = await client.getRegistrationIdentifiers()
 
 ---
 
+### `getFilePreview`
+
+resolves an in-portal preview for a file. Returns a Content-Disposition: inline URL for directly-previewable files (PDF, common image formats), or a document-api PDF conversion result for the Office f
+
+`GET /v2/portal/user/file/{id}/preview`
+
+```ts
+const { data } = await client.getFilePreview({
+  id: '123e4567-e89b-12d3-a456-426614174000',
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "kind": "pdf",
+  "url": "https://example.com/path",
+  "download_url": "https://example.com/path"
+}
+```
+
+</details>
+
+---
+
 ### `trackFileDownloaded`
 
 Track that user has downloaded a file
@@ -6386,7 +6417,7 @@ const { data } = await client.updateWorkflowStepAsDone({
 
 ### `getEntityWorkflows`
 
-Get workflows for an entity
+Get all workflows associated with an entity (requires access to the entity)
 
 `GET /v2/portal/entity/{slug}/{id}/workflows`
 
@@ -6448,7 +6479,8 @@ const { data } = await client.getEntityWorkflows({
 
 ### `getEntityPortalWorkflows`
 
-Get linearized workflows for an entity
+Get all portal-relevant workflows associated with an entity (requires access to the entity),
+linearized by the Workflows API into a flat, ordered list of portal-visible tasks.
 
 `GET /v2/portal/entity/{slug}/{id}/workflows/linearized`
 
@@ -6535,9 +6567,112 @@ const { data } = await client.getEntityPortalWorkflows({
 
 ---
 
+### `getEntityPortalWorkflowsBatch`
+
+Batch variant of `getEntityPortalWorkflows`: returns portal-relevant workflows for
+up to 50 entities — schemas may differ — in a single call, each already linearized
+by the Workflows API into a flat, 
+
+`POST /v2/portal/entities/workflows/linearized/batch`
+
+```ts
+const { data } = await client.getEntityPortalWorkflowsBatch(
+  null,
+  {
+    entities: [
+      {
+        id: 'string',
+        slug: 'order'
+      }
+    ]
+  },
+)
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "results": [
+    {
+      "entity_id": "string",
+      "portal_workflows": [
+        {
+          "id": "string",
+          "definition_id": "string",
+          "name": "string",
+          "status": "STARTED",
+          "version": 2,
+          "created_at": "string",
+          "updated_at": "string",
+          "completed_at": "string",
+          "due_date": "string",
+          "assigned_to": ["string"],
+          "contexts": [
+            {
+              "entity_id": "string",
+              "entity_schema": "string",
+              "is_primary": true
+            }
+          ],
+          "is_path_complete": true,
+          "tasks": [
+            {
+              "id": "string",
+              "name": "string",
+              "order": 0,
+              "status": "COMPLETED",
+              "is_active": true,
+              "ecp": {
+                "enabled": true,
+                "label": "string",
+                "description": "string",
+                "journey": {
+                  "id": "string",
+                  "journeyId": "string",
+                  "name": "string",
+                  "complete_task_automatically": true
+                }
+              },
+              "installer": {
+                "enabled": true,
+                "label": "string",
+                "description": "string",
+                "journey": {
+                  "id": "string",
+                  "journeyId": "string",
+                  "name": "string",
+                  "complete_task_automatically": true
+                }
+              },
+              "journey": {
+                "id": "string",
+                "journeyId": "string",
+                "name": "string",
+                "complete_task_automatically": true
+              },
+              "assigned_to": ["string"],
+              "phase_id": "string",
+              "phase_name": "string",
+              "completed_at": "string",
+              "updated_at": "string"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+</details>
+
+---
+
 ### `uploadMeterReadingPhoto`
 
-Upload Meter Reading Photo
+Uploads a Meter Reading photo and - if enabled - gives back data extracted from the photo.
 
 `POST /v2/portal/metering/reading/photo`
 
@@ -6578,7 +6713,7 @@ const { data } = await client.uploadMeterReadingPhoto(
 
 ### `createMeterReading`
 
-Create Meter Reading
+Inserts a new meter reading.
 
 `POST /v2/portal/metering/reading`
 
@@ -6638,6 +6773,10 @@ const { data } = await client.createMeterReading(
 
 ### `getAllowedMeterReadingRange`
 
+Get allowed reading range for all counters of a meter from the configured
+third-party plausibility check hook using 'range' mode. This endpoint requires
+a plausibility check hook to be configured for 
+
 `GET /v2/portal/metering/reading/allowed-range/{meter_id}`
 
 ```ts
@@ -6670,7 +6809,8 @@ const { data } = await client.getAllowedMeterReadingRange({
 
 ### `getMeterReadings`
 
-Get meter readings with optional template resolution
+Fetches meter readings for a counter and optionally resolves Handlebars
+template strings against each reading object using @epilot/variables.
 
 `POST /v2/portal/metering/readings`
 
@@ -7694,7 +7834,7 @@ const { data } = await client.getUserEntryPoint({
 
 ### `updateCampaignPortalBlockStatus`
 
-Update Campaign Portal Block Status
+Updates the status of a campaign portal block for multiple recipients.
 
 `PUT /v2/portal/campaign/{campaign_id}/entity:status`
 
@@ -9422,7 +9562,7 @@ const { data } = await client.swapPortalConfig(
   {
     source_portal_id: '453ad7bf-86d5-46c8-8252-bcc868df5e3c',
     target_portal_id: '453ad7bf-86d5-46c8-8252-bcc868df5e3c',
-    items_to_swap: ['all']
+    items_to_swap: ['email_templates']
   },
 )
 ```
@@ -10338,6 +10478,7 @@ type ContextEntities = Array<{
 ```ts
 type ErrorResp = {
   message?: string
+  reason?: string
 }
 ```
 
@@ -11923,6 +12064,16 @@ type FileItem = {
 }
 ```
 
+### `FilePreviewResult`
+
+```ts
+type FilePreviewResult = {
+  kind: "pdf" | "image" | "unsupported"
+  url?: string // uri
+  download_url?: string // uri
+}
+```
+
 ### `EntityFileCount`
 
 ```ts
@@ -12138,6 +12289,49 @@ type PortalWorkflowTask = {
 }
 ```
 
+### `EntityPortalWorkflows`
+
+Linearized portal workflows of a single entity
+
+```ts
+type EntityPortalWorkflows = {
+  entity_id: string
+  portal_workflows: Array<{
+    id: string
+    definition_id?: string
+    name: string
+    status: "STARTED" | "DONE" | "CLOSED"
+    version: 2 | 3
+    created_at?: string
+    updated_at?: string
+    completed_at?: string
+    due_date?: string
+    assigned_to?: string[]
+    contexts?: Array<{
+      entity_id?: { ... }
+      entity_schema?: { ... }
+      is_primary?: { ... }
+    }>
+    is_path_complete: boolean
+    tasks: Array<{
+      id: { ... }
+      name: { ... }
+      order: { ... }
+      status: { ... }
+      is_active: { ... }
+      ecp?: { ... }
+      installer?: { ... }
+      journey?: { ... }
+      assigned_to?: { ... }
+      phase_id?: { ... }
+      phase_name?: { ... }
+      completed_at?: { ... }
+      updated_at?: { ... }
+    }>
+  }>
+}
+```
+
 ### `PortalTaskConfig`
 
 Portal-specific (ECP / installer) display config of a workflow task
@@ -14174,8 +14368,10 @@ type JuiceSettings = {
 
 ### `SwappableConfig`
 
+Optional configuration item that a portal swap can additionally include. The swap always transfers the pages and the functional experience config that keep the portal working. These items are opt-in on top of that and are OFF by default. Domain and access/security settings (domain, cognito_details, 
+
 ```ts
-type SwappableConfig = "all" | "domain" | "users" | "email_templates"
+type SwappableConfig = "email_templates"
 ```
 
 ### `PortalUserRegistrationStatus`