@epilot/sdk 2.14.0 → 2.14.1

package/dist/{targeting.d-Bq3onSes.d.ts → targeting.d-DaK3kwZg.d.ts}

@@ -65,6 +65,38 @@ declare namespace Components {
          *
          */
         Schemas.ClientError;
+        export interface DiscoverCampaignsResponse {
+            /**
+             * Number of matching NBAs.
+             */
+            hits: number;
+            /**
+             * Matching NBAs, sorted by priority (desc); one entry per campaign.
+             */
+            results: {
+                campaign_id: /**
+                 * example:
+                 * b8c01433-5556-4e2b-aad4-6f5348d1df84
+                 */
+                Schemas.BaseUUID /* uuid */;
+                nba: /**
+                 * A Next Best Action configured on a campaign's Entity-UI channel.
+                 * This is the canonical NBA contract shared by discovery (this API), authoring, and rendering.
+                 * NBA content is single-language in v1; text fields may contain `{{placeholders}}` resolved at render time.
+                 *
+                 */
+                Schemas.NextBestAction;
+                /**
+                 * The recipient's current Entity-UI status for this campaign, present only
+                 * when a recipient record already exists (i.e. the entity has previously seen
+                 * or clicked this NBA). Absent when the entity has not yet interacted with it.
+                 * Dismissed NBAs are filtered out server-side, so this is only ever `seen` or
+                 * `clicked`. Lets the client skip a redundant `seen` call for NBAs already seen.
+                 *
+                 */
+                status?: "seen" | "dismissed" | "clicked";
+            }[];
+        }
         export interface GetTargetQueriesResponse {
             /**
              * List of target query results.
@@ -339,6 +371,24 @@ declare namespace Components {
                 [name: string]: any;
             };
         };
+        export interface DiscoverCampaignsParams {
+            entity_id: /**
+             * example:
+             * b8c01433-5556-4e2b-aad4-6f5348d1df84
+             */
+            BaseUUID /* uuid */;
+            /**
+             * The schema slug of the entity (e.g. "contact" or "account").
+             */
+            entity_schema: string;
+        }
+        /**
+         * Lifecycle status of a Next Best Action on the Entity-UI channel. Unlike the portal
+         * channel there is no `sent` state: an NBA recipient is born at `seen`, the moment the
+         * action is first rendered to an agent.
+         *
+         */
+        export type EntityUiStatus = "seen" | "dismissed" | "clicked";
         export interface ExecutionSummaryItem {
             execution_id?: string;
             execution_status?: string;
@@ -1415,6 +1465,71 @@ declare namespace Components {
                 BaseUUID /* uuid */?
             ];
         }
+        /**
+         * A Next Best Action configured on a campaign's Entity-UI channel.
+         * This is the canonical NBA contract shared by discovery (this API), authoring, and rendering.
+         * NBA content is single-language in v1; text fields may contain `{{placeholders}}` resolved at render time.
+         *
+         */
+        export interface NextBestAction {
+            /**
+             * Light category label shown above the title. Free-form text.
+             */
+            category?: string;
+            /**
+             * Curated icon for the NBA.
+             */
+            icon?: {
+                /**
+                 * Icon name from "@epilot360/icons".
+                 */
+                name: string;
+                /**
+                 * Optional icon color.
+                 */
+                color?: string;
+            };
+            /**
+             * Bold action title. Required. Supports `{{placeholders}}`.
+             */
+            title: string;
+            /**
+             * Optional description. Supports `{{placeholders}}` (incl. relative dates).
+             */
+            body?: string;
+            /**
+             * Display priority. NBAs are shown highest-priority first.
+             */
+            priority?: "low" | "medium" | "high";
+            /**
+             * Whether the agent can dismiss the NBA.
+             */
+            is_dismissable?: boolean;
+            /**
+             * The NBA's single call-to-action.
+             */
+            cta: {
+                type: "journey" | "workflow" | "url";
+                /**
+                 * Journey id, workflow definition id, or URL, depending on `type`.
+                 */
+                target: string;
+                /**
+                 * Optional CTA button label.
+                 */
+                label?: string;
+                /**
+                 * Journey context parameters (journey CTA only). Maps the journey's declared
+                 * context parameters so the journey knows which entity it is about. Discovery
+                 * returns them verbatim; they are passed to the journey when it launches.
+                 *
+                 */
+                context_params?: {
+                    key: string;
+                    value: string;
+                }[];
+            };
+        }
         export interface PortalRecipientPayload {
             portal_status: PortalStatus;
             portal_state?: {
@@ -1437,8 +1552,32 @@ declare namespace Components {
             portal_state?: {
                 [name: string]: any;
             };
+            entity_ui_status?: /**
+             * Lifecycle status of a Next Best Action on the Entity-UI channel. Unlike the portal
+             * channel there is no `sent` state: an NBA recipient is born at `seen`, the moment the
+             * action is first rendered to an agent.
+             *
+             */
+            EntityUiStatus;
+            entity_ui_status_updated_at?: string; // date-time
+            resolution?: /**
+             * 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. Absence means unresolved.
+             *
+             */
+            Resolution;
             updated_at?: string; // date-time
         }
+        /**
+         * 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. Absence means unresolved.
+         *
+         */
+        export type Resolution = "accepted";
         export interface RetriggerAutomationsRequest {
             /**
              * List of recipient IDs to retrigger automations for
@@ -1669,6 +1808,21 @@ declare namespace Components {
              */
             error?: string;
         }
+        export interface UpdateEntityUiStatusRequest {
+            status: /**
+             * Lifecycle status of a Next Best Action on the Entity-UI channel. Unlike the portal
+             * channel there is no `sent` state: an NBA recipient is born at `seen`, the moment the
+             * action is first rendered to an agent.
+             *
+             */
+            EntityUiStatus;
+            /**
+             * Schema slug of the recipient entity (e.g. "contact"). Required when recording the
+             * first `seen`, which lazily creates the recipient record; ignored on later transitions.
+             *
+             */
+            entity_schema?: string;
+        }
         export interface UpdatePortalStatusRequest {
             status: PortalStatus;
         }
@@ -1718,6 +1872,14 @@ declare namespace Paths {
             export type $500 = Components.Responses.ServerErrorResponse;
         }
     }
+    namespace DiscoverCampaigns {
+        export type RequestBody = Components.Schemas.DiscoverCampaignsParams;
+        namespace Responses {
+            export type $200 = Components.Responses.DiscoverCampaignsResponse;
+            export type $400 = Components.Responses.ClientErrorResponse;
+            export type $500 = Components.Responses.ServerErrorResponse;
+        }
+    }
     namespace GetCampaignJobStatus {
         namespace Parameters {
             export type CampaignId = /**
@@ -1861,6 +2023,32 @@ declare namespace Paths {
             export type $500 = Components.Responses.ServerErrorResponse;
         }
     }
+    namespace UpdateRecipientEntityUiStatus {
+        namespace Parameters {
+            export type CampaignId = /**
+             * example:
+             * b8c01433-5556-4e2b-aad4-6f5348d1df84
+             */
+            Components.Schemas.BaseUUID /* uuid */;
+            export type RecipientId = /**
+             * example:
+             * b8c01433-5556-4e2b-aad4-6f5348d1df84
+             */
+            Components.Schemas.BaseUUID /* uuid */;
+        }
+        export interface PathParameters {
+            campaign_id: Parameters.CampaignId;
+            recipient_id: Parameters.RecipientId;
+        }
+        export type RequestBody = Components.Schemas.UpdateEntityUiStatusRequest;
+        namespace Responses {
+            export type $200 = Components.Responses.RecipientResponse;
+            export type $400 = Components.Responses.ClientErrorResponse;
+            export type $404 = Components.Responses.ClientErrorResponse;
+            export type $409 = Components.Responses.ClientErrorResponse;
+            export type $500 = Components.Responses.ServerErrorResponse;
+        }
+    }
     namespace UpdateRecipientPortalStatus {
         namespace Parameters {
             export type CampaignId = /**
@@ -1969,6 +2157,24 @@ interface OperationMethods {
     data?: Paths.MatchCampaigns.RequestBody,
     config?: AxiosRequestConfig  
   ): OperationResponse<Paths.MatchCampaigns.Responses.$200>
+  /**
+   * 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.
+   * 
+   * Enumerates the organization's **active** campaigns that carry a valid Entity-UI Next Best
+   * Action, live-matches each against the entity using the existing match engine, and returns
+   * the matching NBAs priority-sorted (one per campaign).
+   * 
+   * This is a pure read: it writes nothing. An entity that matches no campaigns returns an
+   * empty list, not an error.
+   * 
+   */
+  'discoverCampaigns'(
+    parameters?: Parameters<UnknownParamsObject> | null,
+    data?: Paths.DiscoverCampaigns.RequestBody,
+    config?: AxiosRequestConfig  
+  ): OperationResponse<Paths.DiscoverCampaigns.Responses.$200>
   /**
    * matchTargets - Match targets
    * 
@@ -2029,6 +2235,32 @@ interface OperationMethods {
     data?: Paths.UpdateRecipientPortalStatus.RequestBody,
     config?: AxiosRequestConfig  
   ): OperationResponse<Paths.UpdateRecipientPortalStatus.Responses.$200>
+  /**
+   * 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.
+   * 
+   * Unlike the portal channel, an NBA recipient is created lazily: the first `seen` creates
+   * the recipient record (and requires `entity_schema`). `seen` is idempotent — re-viewing an
+   * NBA that is already seen/clicked/dismissed is a no-op success and never regresses the status.
+   * 
+   * Status transition rules:
+   * - `seen`: lazily creates the recipient; a no-op success if a status already exists
+   * - From `seen`: can change to `clicked` or `dismissed`
+   * - From `clicked`: can change to `dismissed`
+   * - From `dismissed`: cannot be changed (final state)
+   * 
+   * `dismissed` and `clicked` require an existing recipient (404 otherwise, since an NBA is
+   * born at `seen`) and reject invalid transitions (409).
+   * 
+   * The entity_ui_status_updated_at timestamp is automatically set when the status changes.
+   * 
+   */
+  'updateRecipientEntityUiStatus'(
+    parameters?: Parameters<Paths.UpdateRecipientEntityUiStatus.PathParameters> | null,
+    data?: Paths.UpdateRecipientEntityUiStatus.RequestBody,
+    config?: AxiosRequestConfig  
+  ): OperationResponse<Paths.UpdateRecipientEntityUiStatus.Responses.$200>
   /**
    * getRecipients - Get campaign recipients
    * 
@@ -2132,6 +2364,26 @@ interface PathsDictionary {
       config?: AxiosRequestConfig  
     ): OperationResponse<Paths.MatchCampaigns.Responses.$200>
   }
+  ['/v1/campaign:discover']: {
+    /**
+     * 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.
+     * 
+     * Enumerates the organization's **active** campaigns that carry a valid Entity-UI Next Best
+     * Action, live-matches each against the entity using the existing match engine, and returns
+     * the matching NBAs priority-sorted (one per campaign).
+     * 
+     * This is a pure read: it writes nothing. An entity that matches no campaigns returns an
+     * empty list, not an error.
+     * 
+     */
+    'post'(
+      parameters?: Parameters<UnknownParamsObject> | null,
+      data?: Paths.DiscoverCampaigns.RequestBody,
+      config?: AxiosRequestConfig  
+    ): OperationResponse<Paths.DiscoverCampaigns.Responses.$200>
+  }
   ['/v1/target:match']: {
     /**
      * matchTargets - Match targets
@@ -2202,6 +2454,34 @@ interface PathsDictionary {
       config?: AxiosRequestConfig  
     ): OperationResponse<Paths.UpdateRecipientPortalStatus.Responses.$200>
   }
+  ['/v1/campaign/{campaign_id}/recipient/{recipient_id}/entity_ui:status']: {
+    /**
+     * 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.
+     * 
+     * Unlike the portal channel, an NBA recipient is created lazily: the first `seen` creates
+     * the recipient record (and requires `entity_schema`). `seen` is idempotent — re-viewing an
+     * NBA that is already seen/clicked/dismissed is a no-op success and never regresses the status.
+     * 
+     * Status transition rules:
+     * - `seen`: lazily creates the recipient; a no-op success if a status already exists
+     * - From `seen`: can change to `clicked` or `dismissed`
+     * - From `clicked`: can change to `dismissed`
+     * - From `dismissed`: cannot be changed (final state)
+     * 
+     * `dismissed` and `clicked` require an existing recipient (404 otherwise, since an NBA is
+     * born at `seen`) and reject invalid transitions (409).
+     * 
+     * The entity_ui_status_updated_at timestamp is automatically set when the status changes.
+     * 
+     */
+    'patch'(
+      parameters?: Parameters<Paths.UpdateRecipientEntityUiStatus.PathParameters> | null,
+      data?: Paths.UpdateRecipientEntityUiStatus.RequestBody,
+      config?: AxiosRequestConfig  
+    ): OperationResponse<Paths.UpdateRecipientEntityUiStatus.Responses.$200>
+  }
   ['/v1/campaign/{campaign_id}/recipients']: {
     /**
      * getRecipients - Get campaign recipients
@@ -2236,14 +2516,18 @@ type Campaign = Components.Schemas.Campaign;
 type CampaignStatus = Components.Schemas.CampaignStatus;
 type ClientError = Components.Schemas.ClientError;
 type CreateRecipientPayload = Components.Schemas.CreateRecipientPayload;
+type DiscoverCampaignsParams = Components.Schemas.DiscoverCampaignsParams;
+type EntityUiStatus = Components.Schemas.EntityUiStatus;
 type ExecutionSummaryItem = Components.Schemas.ExecutionSummaryItem;
 type GetTargetQueriesParams = Components.Schemas.GetTargetQueriesParams;
 type JobStatus = Components.Schemas.JobStatus;
 type MatchCampaignParams = Components.Schemas.MatchCampaignParams;
 type MatchTargetParams = Components.Schemas.MatchTargetParams;
+type NextBestAction = Components.Schemas.NextBestAction;
 type PortalRecipientPayload = Components.Schemas.PortalRecipientPayload;
 type PortalStatus = Components.Schemas.PortalStatus;
 type Recipient = Components.Schemas.Recipient;
+type Resolution = Components.Schemas.Resolution;
 type RetriggerAutomationsRequest = Components.Schemas.RetriggerAutomationsRequest;
 type RetriggerAutomationsResult = Components.Schemas.RetriggerAutomationsResult;
 type ServerError = Components.Schemas.ServerError;
@@ -2252,7 +2536,8 @@ type SetupTariffChangeCampaignRequest = Components.Schemas.SetupTariffChangeCamp
 type SetupTariffChangeCampaignResponse = Components.Schemas.SetupTariffChangeCampaignResponse;
 type Target = Components.Schemas.Target;
 type TargetQueryResult = Components.Schemas.TargetQueryResult;
+type UpdateEntityUiStatusRequest = Components.Schemas.UpdateEntityUiStatusRequest;
 type UpdatePortalStatusRequest = Components.Schemas.UpdatePortalStatusRequest;
 type UpdateRecipientPayload = Components.Schemas.UpdateRecipientPayload;
 
-export { type AutomationRecipientPayload as A, type BaseEntityAcl as B, type Client as C, type UpdateRecipientPayload as D, type ExecutionSummaryItem as E, type GetTargetQueriesParams as G, type JobStatus as J, type MatchCampaignParams as M, type OperationMethods as O, Paths as P, type Recipient as R, type ServerError as S, type Target as T, type UpdatePortalStatusRequest as U, Components as a, type PathsDictionary as b, type AutomationStatus as c, type BaseEntityOwner as d, type BaseError as e, type BaseNanoID as f, type BaseRecipientPayload as g, type BaseRelation as h, type BaseSystemFields as i, type BaseSystemFieldsRequired as j, type BaseSystemId as k, type BaseTags as l, type BaseUUID as m, type Campaign as n, type CampaignStatus as o, type ClientError as p, type CreateRecipientPayload as q, type MatchTargetParams as r, type PortalRecipientPayload as s, type PortalStatus as t, type RetriggerAutomationsRequest as u, type RetriggerAutomationsResult as v, type SetupCampaignRequest as w, type SetupTariffChangeCampaignRequest as x, type SetupTariffChangeCampaignResponse as y, type TargetQueryResult as z };
+export { type AutomationRecipientPayload as A, type BaseEntityAcl as B, type Client as C, type DiscoverCampaignsParams as D, type EntityUiStatus as E, type SetupTariffChangeCampaignResponse as F, type GetTargetQueriesParams as G, type TargetQueryResult as H, type UpdatePortalStatusRequest as I, type JobStatus as J, type UpdateRecipientPayload as K, type MatchCampaignParams as M, type NextBestAction as N, type OperationMethods as O, Paths as P, type Recipient as R, type ServerError as S, type Target as T, type UpdateEntityUiStatusRequest as U, Components as a, type PathsDictionary as b, type AutomationStatus as c, type BaseEntityOwner as d, type BaseError as e, type BaseNanoID as f, type BaseRecipientPayload as g, type BaseRelation as h, type BaseSystemFields as i, type BaseSystemFieldsRequired as j, type BaseSystemId as k, type BaseTags as l, type BaseUUID as m, type Campaign as n, type CampaignStatus as o, type ClientError as p, type CreateRecipientPayload as q, type ExecutionSummaryItem as r, type MatchTargetParams as s, type PortalRecipientPayload as t, type PortalStatus as u, type Resolution as v, type RetriggerAutomationsRequest as w, type RetriggerAutomationsResult as x, type SetupCampaignRequest as y, type SetupTariffChangeCampaignRequest as z };

package/docs/targeting.md

@@ -30,6 +30,7 @@ const { data } = await targetingClient.changeCampaignStatus(...)
 - [`getCampaignPortals`](#getcampaignportals)
 - [`setupCampaign`](#setupcampaign)
 - [`matchCampaigns`](#matchcampaigns)
+- [`discoverCampaigns`](#discovercampaigns)
 
 **Campaign Delivery**
 - [`retriggerCampaignAutomations`](#retriggercampaignautomations)
@@ -42,6 +43,7 @@ const { data } = await targetingClient.changeCampaignStatus(...)
 - [`createRecipient`](#createrecipient)
 - [`updateRecipient`](#updaterecipient)
 - [`updateRecipientPortalStatus`](#updaterecipientportalstatus)
+- [`updateRecipientEntityUiStatus`](#updaterecipiententityuistatus)
 - [`getRecipients`](#getrecipients)
 
 **Schemas**
@@ -63,11 +65,15 @@ const { data } = await targetingClient.changeCampaignStatus(...)
 - [`Campaign`](#campaign)
 - [`Target`](#target)
 - [`MatchCampaignParams`](#matchcampaignparams)
+- [`NextBestAction`](#nextbestaction)
+- [`DiscoverCampaignsParams`](#discovercampaignsparams)
 - [`MatchTargetParams`](#matchtargetparams)
 - [`GetTargetQueriesParams`](#gettargetqueriesparams)
 - [`TargetQueryResult`](#targetqueryresult)
 - [`AutomationStatus`](#automationstatus)
 - [`PortalStatus`](#portalstatus)
+- [`EntityUiStatus`](#entityuistatus)
+- [`Resolution`](#resolution)
 - [`Recipient`](#recipient)
 - [`BaseRecipientPayload`](#baserecipientpayload)
 - [`AutomationRecipientPayload`](#automationrecipientpayload)
@@ -77,6 +83,7 @@ const { data } = await targetingClient.changeCampaignStatus(...)
 - [`RetriggerAutomationsRequest`](#retriggerautomationsrequest)
 - [`RetriggerAutomationsResult`](#retriggerautomationsresult)
 - [`UpdatePortalStatusRequest`](#updateportalstatusrequest)
+- [`UpdateEntityUiStatusRequest`](#updateentityuistatusrequest)
 - [`SetupCampaignRequest`](#setupcampaignrequest)
 - [`SetupTariffChangeCampaignRequest`](#setuptariffchangecampaignrequest)
 - [`SetupTariffChangeCampaignResponse`](#setuptariffchangecampaignresponse)
@@ -389,6 +396,63 @@ const { data } = await client.matchCampaigns(
 
 ---
 
+### `discoverCampaigns`
+
+Discover Entity-UI Next Best Actions for an entity
+
+`POST /v1/campaign:discover`
+
+```ts
+const { data } = await client.discoverCampaigns(
+  null,
+  {
+    entity_id: 'b8c01433-5556-4e2b-aad4-6f5348d1df84',
+    entity_schema: 'string'
+  },
+)
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "hits": 0,
+  "results": [
+    {
+      "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",
+          "label": "string",
+          "context_params": [
+            {
+              "key": "string",
+              "value": "string"
+            }
+          ]
+        }
+      },
+      "status": "seen"
+    }
+  ]
+}
+```
+
+</details>
+
+---
+
 ### `matchTargets`
 
 Match targets
@@ -518,6 +582,9 @@ const { data } = await client.createRecipient(
   "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",
+  "resolution": "accepted",
   "updated_at": "1970-01-01T00:00:00.000Z"
 }
 ```
@@ -560,6 +627,9 @@ const { data } = await client.updateRecipient(
   "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",
+  "resolution": "accepted",
   "updated_at": "1970-01-01T00:00:00.000Z"
 }
 ```
@@ -599,6 +669,52 @@ const { data } = await client.updateRecipientPortalStatus(
   "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",
+  "resolution": "accepted",
+  "updated_at": "1970-01-01T00:00:00.000Z"
+}
+```
+
+</details>
+
+---
+
+### `updateRecipientEntityUiStatus`
+
+Update Entity-UI (Next Best Action) status for a campaign recipient
+
+`PATCH /v1/campaign/{campaign_id}/recipient/{recipient_id}/entity_ui:status`
+
+```ts
+const { data } = await client.updateRecipientEntityUiStatus(
+  {
+    campaign_id: 'example',
+    recipient_id: 'example',
+  },
+  {
+    status: 'seen',
+    entity_schema: 'string'
+  },
+)
+```
+
+<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",
+  "resolution": "accepted",
   "updated_at": "1970-01-01T00:00:00.000Z"
 }
 ```
@@ -639,6 +755,9 @@ const { data } = await client.getRecipients({
       "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",
+      "resolution": "accepted",
       "updated_at": "1970-01-01T00:00:00.000Z"
     }
   ],
@@ -883,6 +1002,45 @@ type MatchCampaignParams = {
 }
 ```
 
+### `NextBestAction`
+
+A Next Best Action configured on a campaign's Entity-UI channel.
+This is the canonical NBA contract shared by discovery (this API), authoring, and rendering.
+NBA content is single-language in v1; text fields may contain `{{placeholders}}` resolved at render time.
+
+
+```ts
+type NextBestAction = {
+  category?: string
+  icon?: {
+    name: string
+    color?: string
+  }
+  title: string
+  body?: string
+  priority?: "low" | "medium" | "high"
+  is_dismissable?: boolean
+  cta: {
+    type: "journey" | "workflow" | "url"
+    target: string
+    label?: string
+    context_params?: Array<{
+      key: { ... }
+      value: { ... }
+    }>
+  }
+}
+```
+
+### `DiscoverCampaignsParams`
+
+```ts
+type DiscoverCampaignsParams = {
+  entity_id: string // uuid
+  entity_schema: string
+}
+```
+
 ### `MatchTargetParams`
 
 ```ts
@@ -925,6 +1083,28 @@ type AutomationStatus = "pending" | "in_progress" | "success" | "failed" | "canc
 type PortalStatus = "sent" | "seen" | "dismissed" | "clicked"
 ```
 
+### `EntityUiStatus`
+
+Lifecycle status of a Next Best Action on the Entity-UI channel. Unlike the portal
+channel there is no `sent` state: an NBA recipient is born at `seen`, the moment the
+action is first rendered to an agent.
+
+
+```ts
+type EntityUiStatus = "seen" | "dismissed" | "clicked"
+```
+
+### `Resolution`
+
+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
+
+```ts
+type Resolution = "accepted"
+```
+
 ### `Recipient`
 
 ```ts
@@ -937,6 +1117,9 @@ type Recipient = {
   portal_status?: "sent" | "seen" | "dismissed" | "clicked"
   portal_status_updated_at?: string // date-time
   portal_state?: Record<string, unknown>
+  entity_ui_status?: "seen" | "dismissed" | "clicked"
+  entity_ui_status_updated_at?: string // date-time
+  resolution?: "accepted"
   updated_at?: string // date-time
 }
 ```
@@ -1029,6 +1212,15 @@ type UpdatePortalStatusRequest = {
 }
 ```
 
+### `UpdateEntityUiStatusRequest`
+
+```ts
+type UpdateEntityUiStatusRequest = {
+  status: "seen" | "dismissed" | "clicked"
+  entity_schema?: string
+}
+```
+
 ### `SetupCampaignRequest`
 
 Discriminated by `type`. Each campaign variant has its own request shape;