@epilot/sdk 2.19.0 → 2.19.2

package/docs/targeting.md

@@ -44,7 +44,9 @@ const { data } = await targetingClient.changeCampaignStatus(...)
 - [`updateRecipient`](#updaterecipient)
 - [`updateRecipientPortalStatus`](#updaterecipientportalstatus)
 - [`updateRecipientEntityUiStatus`](#updaterecipiententityuistatus)
+- [`restoreRecipientEntityUiStatus`](#restorerecipiententityuistatus)
 - [`getRecipients`](#getrecipients)
+- [`getEmailStats`](#getemailstats)
 
 **Schemas**
 - [`BaseError`](#baseerror)
@@ -67,13 +69,15 @@ const { data } = await targetingClient.changeCampaignStatus(...)
 - [`MatchCampaignParams`](#matchcampaignparams)
 - [`NextBestAction`](#nextbestaction)
 - [`DiscoverCampaignsParams`](#discovercampaignsparams)
+- [`DiscoverResult`](#discoverresult)
 - [`MatchTargetParams`](#matchtargetparams)
 - [`GetTargetQueriesParams`](#gettargetqueriesparams)
 - [`TargetQueryResult`](#targetqueryresult)
 - [`AutomationStatus`](#automationstatus)
 - [`PortalStatus`](#portalstatus)
 - [`EntityUiStatus`](#entityuistatus)
-- [`Resolution`](#resolution)
+- [`EmailStatus`](#emailstatus)
+- [`EmailBounceType`](#emailbouncetype)
 - [`Recipient`](#recipient)
 - [`BaseRecipientPayload`](#baserecipientpayload)
 - [`AutomationRecipientPayload`](#automationrecipientpayload)
@@ -90,7 +94,7 @@ const { data } = await targetingClient.changeCampaignStatus(...)
 
 ### `changeCampaignStatus`
 
-Change the status of a campaign
+Change the status of a campaign to a desired status.
 
 `POST /v1/campaign/{campaign_id}/status`
 
@@ -180,7 +184,7 @@ const { data } = await client.getCampaignJobStatus({
 
 ### `getCampaignPortals`
 
-Get portals usage info for a campaign
+Get the list of portals and its widgets where the campaign is used.
 
 `GET /v1/campaign/{campaign_id}/portals`
 
@@ -220,7 +224,7 @@ const { data } = await client.getCampaignPortals({
 
 ### `retriggerCampaignAutomations`
 
-Retrigger automations for campaign recipients
+Retrigger automation executions for specific campaign recipients that have failed.
 
 `POST /v1/campaign/{campaign_id}/automations:retrigger`
 
@@ -258,7 +262,8 @@ const { data } = await client.retriggerCampaignAutomations(
 
 ### `setupCampaign`
 
-Set up a campaign with related entities and configurations
+Creates a `campaign` entity together with its related entities and configurations in a single call.
+Used by the campaign wizard UI, but not restricted to it.
 
 `POST /v1/campaign:setup`
 
@@ -325,7 +330,7 @@ const { data } = await client.setupCampaign(
 
 ### `matchCampaigns`
 
-Match campaigns
+Match campaigns based on target entities.
 
 `POST /v1/campaign:match`
 
@@ -398,7 +403,7 @@ const { data } = await client.matchCampaigns(
 
 ### `discoverCampaigns`
 
-Discover Entity-UI Next Best Actions for an entity
+Given an entity, returns the Next Best Actions it should see on the Entity-UI channel.
 
 `POST /v1/campaign:discover`
 
@@ -434,7 +439,6 @@ const { data } = await client.discoverCampaigns(
         "cta": {
           "type": "journey",
           "target": "string",
-          "label": "string",
           "context_params": [
             {
               "key": "string",
@@ -443,7 +447,36 @@ const { data } = await client.discoverCampaigns(
           ]
         }
       },
-      "status": "seen"
+      "status": "seen",
+      "status_updated_at": "1970-01-01T00:00:00.000Z"
+    }
+  ],
+  "dismissed": [
+    {
+      "campaign_id": "b8c01433-5556-4e2b-aad4-6f5348d1df84",
+      "nba": {
+        "category": "string",
+        "icon": {
+          "name": "string",
+          "color": "string"
+        },
+        "title": "string",
+        "body": "string",
+        "priority": "medium",
+        "is_dismissable": true,
+        "cta": {
+          "type": "journey",
+          "target": "string",
+          "context_params": [
+            {
+              "key": "string",
+              "value": "string"
+            }
+          ]
+        }
+      },
+      "status": "seen",
+      "status_updated_at": "1970-01-01T00:00:00.000Z"
     }
   ]
 }
@@ -455,7 +488,7 @@ const { data } = await client.discoverCampaigns(
 
 ### `matchTargets`
 
-Match targets
+Find targets from the provided list that include the provide entities.
 
 `POST /v1/target:match`
 
@@ -517,7 +550,8 @@ const { data } = await client.matchTargets(
 
 ### `getTargetQueries`
 
-Get target queries
+Transform target filters into Lucene queries for the provided target IDs.
+Returns the transformed query string for each target along with any errors encountered.
 
 `POST /v1/target/queries`
 
@@ -551,7 +585,7 @@ const { data } = await client.getTargetQueries(
 
 ### `createRecipient`
 
-Create a recipient associated with a campaign
+Creates a new recipient associated with a campaign.
 
 `POST /v1/campaign/{campaign_id}/recipient`
 
@@ -584,7 +618,15 @@ const { data } = await client.createRecipient(
   "portal_state": {},
   "entity_ui_status": "seen",
   "entity_ui_status_updated_at": "1970-01-01T00:00:00.000Z",
-  "resolution": "accepted",
+  "entity_ui_status_before_dismiss": "seen",
+  "message_entity_id": "string",
+  "email_status": "sent",
+  "email_status_updated_at": "1970-01-01T00:00:00.000Z",
+  "email_bounce_type": "permanent",
+  "email_bounce_subtype": "string",
+  "email_complaint_type": "string",
+  "email_bounce_reason": "string",
+  "email_send_error": {},
   "updated_at": "1970-01-01T00:00:00.000Z"
 }
 ```
@@ -595,7 +637,7 @@ const { data } = await client.createRecipient(
 
 ### `updateRecipient`
 
-Update a recipient
+Updates a recipient's attributes.
 
 `PATCH /v1/campaign/{campaign_id}/recipient/{recipient_id}`
 
@@ -629,7 +671,15 @@ const { data } = await client.updateRecipient(
   "portal_state": {},
   "entity_ui_status": "seen",
   "entity_ui_status_updated_at": "1970-01-01T00:00:00.000Z",
-  "resolution": "accepted",
+  "entity_ui_status_before_dismiss": "seen",
+  "message_entity_id": "string",
+  "email_status": "sent",
+  "email_status_updated_at": "1970-01-01T00:00:00.000Z",
+  "email_bounce_type": "permanent",
+  "email_bounce_subtype": "string",
+  "email_complaint_type": "string",
+  "email_bounce_reason": "string",
+  "email_send_error": {},
   "updated_at": "1970-01-01T00:00:00.000Z"
 }
 ```
@@ -640,7 +690,8 @@ const { data } = await client.updateRecipient(
 
 ### `updateRecipientPortalStatus`
 
-Update portal status for a campaign recipient
+Updates the portal status for a specific campaign recipient.
+The portal_status_updated_at timestamp is automatically set when the status changes.
 
 `PATCH /v1/campaign/{campaign_id}/recipient/{recipient_id}/portal:status`
 
@@ -671,7 +722,15 @@ const { data } = await client.updateRecipientPortalStatus(
   "portal_state": {},
   "entity_ui_status": "seen",
   "entity_ui_status_updated_at": "1970-01-01T00:00:00.000Z",
-  "resolution": "accepted",
+  "entity_ui_status_before_dismiss": "seen",
+  "message_entity_id": "string",
+  "email_status": "sent",
+  "email_status_updated_at": "1970-01-01T00:00:00.000Z",
+  "email_bounce_type": "permanent",
+  "email_bounce_subtype": "string",
+  "email_complaint_type": "string",
+  "email_bounce_reason": "string",
+  "email_send_error": {},
   "updated_at": "1970-01-01T00:00:00.000Z"
 }
 ```
@@ -682,7 +741,7 @@ const { data } = await client.updateRecipientPortalStatus(
 
 ### `updateRecipientEntityUiStatus`
 
-Update Entity-UI (Next Best Action) status for a campaign recipient
+Records a Next Best Action interaction for a recipient on the Entity-UI channel.
 
 `PATCH /v1/campaign/{campaign_id}/recipient/{recipient_id}/entity_ui:status`
 
@@ -714,7 +773,60 @@ const { data } = await client.updateRecipientEntityUiStatus(
   "portal_state": {},
   "entity_ui_status": "seen",
   "entity_ui_status_updated_at": "1970-01-01T00:00:00.000Z",
-  "resolution": "accepted",
+  "entity_ui_status_before_dismiss": "seen",
+  "message_entity_id": "string",
+  "email_status": "sent",
+  "email_status_updated_at": "1970-01-01T00:00:00.000Z",
+  "email_bounce_type": "permanent",
+  "email_bounce_subtype": "string",
+  "email_complaint_type": "string",
+  "email_bounce_reason": "string",
+  "email_send_error": {},
+  "updated_at": "1970-01-01T00:00:00.000Z"
+}
+```
+
+</details>
+
+---
+
+### `restoreRecipientEntityUiStatus`
+
+Undo a dismissal on the Entity-UI (Next Best Action) channel
+
+`POST /v1/campaign/{campaign_id}/recipient/{recipient_id}/entity_ui:restore`
+
+```ts
+const { data } = await client.restoreRecipientEntityUiStatus({
+  campaign_id: 'example',
+  recipient_id: 'example',
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "entity_id": "b8c01433-5556-4e2b-aad4-6f5348d1df84",
+  "entity_schema": "string",
+  "title": "string",
+  "automation_status": "pending",
+  "automation_execution_id": "string",
+  "portal_status": "sent",
+  "portal_status_updated_at": "1970-01-01T00:00:00.000Z",
+  "portal_state": {},
+  "entity_ui_status": "seen",
+  "entity_ui_status_updated_at": "1970-01-01T00:00:00.000Z",
+  "entity_ui_status_before_dismiss": "seen",
+  "message_entity_id": "string",
+  "email_status": "sent",
+  "email_status_updated_at": "1970-01-01T00:00:00.000Z",
+  "email_bounce_type": "permanent",
+  "email_bounce_subtype": "string",
+  "email_complaint_type": "string",
+  "email_bounce_reason": "string",
+  "email_send_error": {},
   "updated_at": "1970-01-01T00:00:00.000Z"
 }
 ```
@@ -725,7 +837,7 @@ const { data } = await client.updateRecipientEntityUiStatus(
 
 ### `getRecipients`
 
-Get campaign recipients
+Get a paginated list of recipients for a campaign.
 
 `GET /v1/campaign/{campaign_id}/recipients`
 
@@ -737,6 +849,7 @@ const { data } = await client.getRecipients({
   q: 'example',
   automation_status: ['...'],
   portal_status: 'example',
+  email_status: 'example',
 })
 ```
 
@@ -757,7 +870,15 @@ const { data } = await client.getRecipients({
       "portal_state": {},
       "entity_ui_status": "seen",
       "entity_ui_status_updated_at": "1970-01-01T00:00:00.000Z",
-      "resolution": "accepted",
+      "entity_ui_status_before_dismiss": "seen",
+      "message_entity_id": "string",
+      "email_status": "sent",
+      "email_status_updated_at": "1970-01-01T00:00:00.000Z",
+      "email_bounce_type": "permanent",
+      "email_bounce_subtype": "string",
+      "email_complaint_type": "string",
+      "email_bounce_reason": "string",
+      "email_send_error": {},
       "updated_at": "1970-01-01T00:00:00.000Z"
     }
   ],
@@ -770,6 +891,40 @@ const { data } = await client.getRecipients({
 
 ---
 
+### `getEmailStats`
+
+Aggregate email delivery counts for a campaign, for the KPI summary on the campaign UI.
+Counts cover the email (automation) channel only; `total_emailed` is the number of
+recipients with a recorded em
+
+`GET /v1/campaign/{campaign_id}/email-stats`
+
+```ts
+const { data } = await client.getEmailStats({
+  campaign_id: 'example',
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "total_emailed": 0,
+  "sent": 0,
+  "delivered": 0,
+  "bounced": 0,
+  "bounced_hard": 0,
+  "bounced_soft": 0,
+  "complained": 0,
+  "failed": 0
+}
+```
+
+</details>
+
+---
+
 ## Schemas
 
 ### `BaseError`
@@ -801,7 +956,7 @@ Describes the structure of a client error response, which can be one of several
 type ClientError = {
   message: string
 } | {
-  code: "CAMPAIGN_NOT_FOUND" | "CAMPAIGN_HAS_NO_TARGET" | "CAMPAIGN_HAS_NO_DELIVERY_METHOD" | "CAMPAIGN_HAS_JOB_IN_PROGRESS" | "CAMPAIGN_HAS_UNEXPECTED_STATUS" | "JOB_TOKEN_MISSING" | "TARGET_WITHOUT_FILTERS"
+  code: "CAMPAIGN_NOT_FOUND" | "CAMPAIGN_HAS_NO_TARGET" | "CAMPAIGN_HAS_NO_DELIVERY_METHOD" | "INVALID_NEXT_BEST_ACTION" | "CAMPAIGN_HAS_JOB_IN_PROGRESS" | "CAMPAIGN_HAS_UNEXPECTED_STATUS" | "JOB_TOKEN_MISSING" | "TARGET_WITHOUT_FILTERS"
 } | {
   error: string
   status: number
@@ -1021,9 +1176,8 @@ type NextBestAction = {
   priority?: "low" | "medium" | "high"
   is_dismissable?: boolean
   cta: {
-    type: "journey" | "workflow" | "url"
+    type: "journey" | "workflow" | "flow"
     target: string
-    label?: string
     context_params?: Array<{
       key: { ... }
       value: { ... }
@@ -1041,6 +1195,34 @@ type DiscoverCampaignsParams = {
 }
 ```
 
+### `DiscoverResult`
+
+One discovered Next Best Action, plus this entity's interaction state for it.
+
+```ts
+type DiscoverResult = {
+  campaign_id: string // uuid
+  nba: {
+    category?: string
+    icon?: {
+      name: { ... }
+      color?: { ... }
+    }
+    title: string
+    body?: string
+    priority?: "low" | "medium" | "high"
+    is_dismissable?: boolean
+    cta: {
+      type: { ... }
+      target: { ... }
+      context_params?: { ... }
+    }
+  }
+  status?: "seen" | "dismissed" | "clicked"
+  status_updated_at?: string // date-time
+}
+```
+
 ### `MatchTargetParams`
 
 ```ts
@@ -1094,15 +1276,23 @@ action is first rendered to an agent.
 type EntityUiStatus = "seen" | "dismissed" | "clicked"
 ```
 
-### `Resolution`
+### `EmailStatus`
+
+Delivery status of the email a campaign's automation sends to a recipient. Set to `sent`
+once the automation hands the email off, then updated asynchronously as SES notifications
+arrive (`bounced` / `complained`; an SES Reject maps to `bounced`). `failed` is a send-time
+failure (the automation execu
+
+```ts
+type EmailStatus = "sent" | "delivered" | "bounced" | "complained" | "failed"
+```
+
+### `EmailBounceType`
 
-Cross-channel resolution of a campaign for a recipient. Unlike the per-channel `*_status`
-fields (where `dismissed` is channel-local), a resolution suppresses the campaign on EVERY
-channel — the 360 Entity-UI card and the portal teaser alike. Server-managed and read-only:
-never sent by a client. Abs
+SES bounce classification: `permanent` (hard) or `transient` (soft).
 
 ```ts
-type Resolution = "accepted"
+type EmailBounceType = "permanent" | "transient"
 ```
 
 ### `Recipient`
@@ -1119,7 +1309,15 @@ type Recipient = {
   portal_state?: Record<string, unknown>
   entity_ui_status?: "seen" | "dismissed" | "clicked"
   entity_ui_status_updated_at?: string // date-time
-  resolution?: "accepted"
+  entity_ui_status_before_dismiss?: "seen" | "dismissed" | "clicked"
+  message_entity_id?: string
+  email_status?: "sent" | "delivered" | "bounced" | "complained" | "failed"
+  email_status_updated_at?: string // date-time
+  email_bounce_type?: "permanent" | "transient"
+  email_bounce_subtype?: string
+  email_complaint_type?: string
+  email_bounce_reason?: string
+  email_send_error?: Record<string, unknown>
   updated_at?: string // date-time
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epilot/sdk",
-  "version": "2.19.0",
+  "version": "2.19.2",
   "description": "JavaScript/TypeScript SDK for epilot APIs",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -322,16 +322,6 @@
     },
     "./workflow-definition/openapi.json": "./definitions/workflow-definition.json"
   },
-  "scripts": {
-    "generate": "tsx ../../scripts/generate-sdk-v2.ts && pnpm lint:fix",
-    "build": "tsup",
-    "build:watch": "tsup --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "lint": "biome check src",
-    "lint:fix": "biome check src --fix",
-    "prepublishOnly": "npm run build"
-  },
   "keywords": [
     "epilot",
     "sdk",
@@ -525,5 +515,14 @@
         "./dist/apis/workflow-definition.d.ts"
       ]
     }
+  },
+  "scripts": {
+    "generate": "tsx ../../scripts/generate-sdk-v2.ts && pnpm lint:fix",
+    "build": "tsup",
+    "build:watch": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome check src",
+    "lint:fix": "biome check src --fix"
   }
-}
+}