@epilot/cli 0.1.130 → 0.1.132

package/README.md

@@ -29,7 +29,7 @@ npm install -g @epilot/cli
 
 <!-- usage-help -->
 ```
-epilot v0.1.130 — CLI for epilot APIs
+epilot v0.1.132 — CLI for epilot APIs
 
 USAGE
   epilot <api> <operationId> [params...] [flags]

package/definitions/app.json

@@ -1438,6 +1438,70 @@
         }
       }
     },
+    "/v1/app/{appId}/options/resolve": {
+      "post": {
+        "summary": "resolveOptions",
+        "description": "Resolve the effective app-level options of an installation, including decrypted sensitive values (secrets). This endpoint accepts epilot internal-auth tokens exclusively (internal service calls, e.g. automation-workers or the customer portal API) — no user token, API key, or app token can call it, regardless of roles. Every call is audit-logged with the caller identity.",
+        "operationId": "resolveOptions",
+        "tags": [
+          "App Installation"
+        ],
+        "parameters": [
+          {
+            "name": "appId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "keys": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Narrow the response to these option keys"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Effective options with resolved values",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "options": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/Options"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Caller is not authenticated with an internal-auth token"
+          },
+          "404": {
+            "description": "App installation not found"
+          }
+        }
+      }
+    },
     "/v1/app-events": {
       "post": {
         "summary": "ingestEvent",
@@ -1831,6 +1895,13 @@
                     "$ref": "#/components/schemas/FunctionDefinition"
                   },
                   "description": "Replaces the full set of server-side functions for this version"
+                },
+                "options": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/Options"
+                  },
+                  "description": "Replaces the full set of app-level option declarations for this version.\nOption keys must be unique app-wide; `secret`-touching options are always\nsensitive and must not declare `sensitive: false`.\n"
                 }
               }
             }
@@ -1984,6 +2055,25 @@
               "object"
             ],
             "description": "The type of this option. `object` declares a structured value whose fields are listed\nunder `fields`. Combine with `repeatable: true` to express a list of these objects.\n"
+          },
+          "sensitive": {
+            "type": "boolean",
+            "description": "Write-only, server-side only value — like a sensitive environment variable\n(app-level options only). Sensitive values are never serialized in any response;\nthey are resolvable only via server-side channels (API proxy injection, function\n`secrets` allowlist, the internal options/resolve endpoint). Non-sensitive values\nare readable wherever the app runs, including the end-customer browser (journey and\nportal runtime). Forced to true for `secret`-touching options. Default: false.\n"
+          },
+          "configured": {
+            "type": "boolean",
+            "readOnly": true,
+            "description": "Serialized instead of `value` for sensitive options (secrets): true when a\nvalue is stored.\n"
+          },
+          "lifted": {
+            "type": "boolean",
+            "readOnly": true,
+            "description": "Compatibility marker: this option is declared at app level and folded back\ninto the component's options so existing consumers (journey runtime, portal\nblocks, older services) keep working unchanged. New consumers should read\napp-level options from the installation's `options` array instead.\n"
+          },
+          "value_updated_at": {
+            "type": "string",
+            "readOnly": true,
+            "description": "Timestamp of the last value change. Only returned for sensitive options\n(alongside `configured`) so installers can see when a secret was last rotated.\n"
           }
         }
       },
@@ -2048,7 +2138,7 @@
         "properties": {
           "component_id": {
             "type": "string",
-            "description": "ID of the component these values are for"
+            "description": "ID of the component these values are for. Use the sentinel `$app` for\napp-level option values (options declared at the manifest top level).\n"
           },
           "options": {
             "type": "array",
@@ -2118,7 +2208,7 @@
           "label": {
             "allOf": [
               {
-                "description": null
+                "description": "Human-readable display name of the function, shown to installing organizations (e.g. in the scheduled-functions summary)\n"
               },
               {
                 "$ref": "#/components/schemas/TranslatedString"
@@ -2164,7 +2254,8 @@
             "items": {
               "type": "string"
             },
-            "description": "Keys of installation options of type secret made available to the function via input.app_options\n"
+            "deprecated": true,
+            "description": "DEPRECATED and ignored — functions receive the app's full effective option keyspace (sensitive values included) via input.app_options. Kept for manifest compatibility.\n"
           }
         }
       },
@@ -2254,6 +2345,13 @@
             },
             "description": "List of options for the app component"
           },
+          "uses_options": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Keys of app-level options this component uses. Narrows which options are\nfolded back into `options` for legacy consumers (e.g. which values a journey\nblock receives in its public args) — a scoping hint, never a security\nboundary. Stamped automatically by the component-options migration; may also\nbe declared by the app developer.\n"
+          },
           "surfaces": {
             "type": "object"
           }
@@ -4840,6 +4938,14 @@
             "minItems": 0,
             "description": "Server-side functions of the app, including scheduled functions"
           },
+          "options": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Options"
+            },
+            "minItems": 0,
+            "description": "App-level option declarations (with sensitivity) of this version"
+          },
           "visibility": {
             "type": "string",
             "enum": [
@@ -5077,6 +5183,14 @@
             },
             "readOnly": true
           },
+          "options": {
+            "description": "Effective app-level options of the installation: declared top-level options plus\ncomponent-level options lifted to the app keyspace, each with its configured\n`value`. Values of sensitive options (secrets) are never included — they carry\n`configured` and `value_updated_at` instead.\n",
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Options"
+            },
+            "readOnly": true
+          },
           "installed_version": {
             "type": "string",
             "description": "Version of the app that is installed",
@@ -5192,6 +5306,14 @@
             "minItems": 0,
             "description": "Server-side functions of the app, including scheduled functions"
           },
+          "options": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Options"
+            },
+            "minItems": 0,
+            "description": "App-level option declarations (with sensitivity) of this version"
+          },
           "is_beta": {
             "type": "boolean",
             "description": "Flag to indicate if the app is in beta.",
@@ -5442,6 +5564,11 @@
               "correlation_id": {
                 "type": "string",
                 "description": "Filter by correlation ID for tracing"
+              },
+              "search": {
+                "type": "string",
+                "maxLength": 200,
+                "description": "Case-insensitive substring match over event details and component id"
               }
             }
           },
@@ -5492,6 +5619,11 @@
                 "minimum": 1,
                 "maximum": 1000,
                 "default": 100
+              },
+              "before": {
+                "type": "string",
+                "format": "date-time",
+                "description": "Cursor: only return events strictly older than this timestamp. Use the timestamp of the last received event to fetch the next page; more efficient than increasing page/page_size.\n"
               }
             }
           },

package/definitions/entity.json

@@ -2,7 +2,7 @@
   "openapi": "3.0.2",
   "info": {
     "title": "Entity API",
-    "version": "2.9.0",
+    "version": "2.10.0",
     "description": "Flexible data layer for epilot Entities.\n\nUse this API configure and access your business objects like Contacts, Opportunities and Products.\n\n[Feature Documentation](https://docs.epilot.io/docs/entities/flexible-entities)\n"
   },
   "tags": [
@@ -5072,7 +5072,8 @@
               },
               "grid_layout": {
                 "type": "object",
-                "description": "Widget-grid layout for the entity-details page (builder-authored); columns/cells drive the grid geometry.",
+                "deprecated": true,
+                "description": "Superseded by `widget_widths`. A whole-grid layout preset that assigned each widget a width by its POSITION, so a widget that rendered nothing shifted every width after it. Neither the entity app nor the entity builder reads it any more; values stored before it was replaced are left in place rather than migrated.",
                 "properties": {
                   "id": {
                     "type": "string",
@@ -5108,6 +5109,23 @@
                   "next_best_action": true,
                   "address_map": false
                 }
+              },
+              "widget_widths": {
+                "type": "object",
+                "description": "Per-widget width in the entity-details widget grid, keyed by widget id (a capability widget's `component`, or `summary` for the synthesized summary card). Spans a 12-column grid: `one_third_width` = 4, `half_width` = 6, `two_third_width` = 8, `full_width` = 12. Holds only the admin's deviations from each widget's declared default: a widget absent from this map falls back to its ui_hook `default_width`, and then to `full_width`. Do not seed this map from migrations — doing so would freeze today's defaults into the schema. Replaces the positional `grid_layout` preset.",
+                "additionalProperties": {
+                  "type": "string",
+                  "enum": [
+                    "one_third_width",
+                    "half_width",
+                    "two_third_width",
+                    "full_width"
+                  ]
+                },
+                "example": {
+                  "address_map": "full_width",
+                  "recent_communications": "one_third_width"
+                }
               }
             }
           },
@@ -7577,6 +7595,17 @@
                   "description": "Whether this widget is switched on by default for entity types that have the capability. Only meaningful on the `EntityDetailsV2:Widget` hook. Defaults to true when omitted. An admin's explicit choice in the entity builder is stored in the schema's `ui_config.widget_visibility` and wins over this.",
                   "example": false
                 },
+                "default_width": {
+                  "type": "string",
+                  "enum": [
+                    "one_third_width",
+                    "half_width",
+                    "two_third_width",
+                    "full_width"
+                  ],
+                  "description": "How wide this widget is by default in the entity-details widget grid. Only meaningful on the `EntityDetailsV2:Widget` and `EntityDetailsV2:Header` hooks. Defaults to `full_width` when omitted — deliberately unlike the attribute layout default of `half_width`, because a full-width widget can never leave a hole in a row. An admin's explicit choice in the entity builder is stored in the schema's `ui_config.widget_widths` and wins over this.",
+                  "example": "half_width"
+                },
                 "pricing_tier_setting": {
                   "type": "string",
                   "description": "The pricing-tier settings key an organisation must have enabled to use this widget. Omit for widgets available to everyone. Resolved against `GET /v2/pricing-tiers/me` as `override_settings[key].enabled ?? settings[key].enabled`. Note this is commercial packaging enforced in the UI, not a security control — the key must also be added to the pricing tier settings list in epilot-admin-portal, or it can never be switched on for a tier.",
@@ -8964,6 +8993,39 @@
                 "description": "Optional array of field names to include in the hydrated entity response for this node.\nWhen specified, only the requested fields plus required internal fields (_id, _schema, _org) will be returned.\nOnly applies when hydrate=true.\n"
               }
             ]
+          },
+          "filter": {
+            "type": "array",
+            "description": "Narrows this node's traversal results to entities matching every filter (AND semantics). Useful for\ndisambiguating among multiple entities reachable via the same graph edge.\n",
+            "items": {
+              "$ref": "#/components/schemas/GraphNodeFilter"
+            }
+          }
+        }
+      },
+      "GraphNodeFilter": {
+        "type": "object",
+        "description": "Entities are included in this node's result only if `attribute` exactly equals the literal `value`.",
+        "required": [
+          "attribute",
+          "value"
+        ],
+        "properties": {
+          "attribute": {
+            "type": "string",
+            "description": "Entity attribute name to match against. Must be a plain attribute name, not an Elasticsearch field path.",
+            "example": "order_number"
+          },
+          "value": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/SearchFilterValue"
+              },
+              {
+                "description": "Literal value the attribute must exactly equal for the entity to be included in this node's result."
+              }
+            ],
+            "example": "OR-113"
           }
         }
       },

package/definitions/pricing.json

@@ -4773,6 +4773,9 @@
           "conditions",
           "valid_from",
           "values",
+          "_created_at",
+          "_updated_at",
+          "_revision",
           "warnings"
         ],
         "properties": {
@@ -4805,14 +4808,19 @@
             "$ref": "#/components/schemas/VariantValues"
           },
           "_created_at": {
-            "type": "string"
+            "type": "string",
+            "description": "When the first version was created.",
+            "readOnly": true
           },
           "_updated_at": {
-            "type": "string"
+            "type": "string",
+            "description": "When the first version was last written.",
+            "readOnly": true
           },
           "_revision": {
             "type": "number",
-            "description": "The revision a later write to this version must carry to be accepted. Genuinely current,\nunlike one read back later from an eventually-consistent read.\n"
+            "description": "The revision a later write to this version must carry to be accepted. Genuinely current,\nunlike one read back later from an eventually-consistent read.\n",
+            "readOnly": true
           },
           "warnings": {
             "type": "array",
@@ -4827,7 +4835,9 @@
         "type": "object",
         "required": [
           "code",
-          "message"
+          "message",
+          "variant_count",
+          "cap"
         ],
         "properties": {
           "code": {
@@ -4890,7 +4900,10 @@
           "schema",
           "conditions",
           "valid_from",
-          "values"
+          "values",
+          "_created_at",
+          "_updated_at",
+          "_revision"
         ],
         "properties": {
           "variant_id": {
@@ -4921,14 +4934,19 @@
             "$ref": "#/components/schemas/VariantValues"
           },
           "_created_at": {
-            "type": "string"
+            "type": "string",
+            "description": "When this version was created.",
+            "readOnly": true
           },
           "_updated_at": {
-            "type": "string"
+            "type": "string",
+            "description": "When this version was last written.",
+            "readOnly": true
           },
           "_revision": {
             "type": "integer",
             "description": "The revision a write to this version must carry to be accepted. Always current: every read\nthat returns one is strongly consistent, so it is never a marker a write would be refused\nfor having read too early.\n",
+            "readOnly": true,
             "example": 3
           }
         }

package/definitions/targeting.json

@@ -37,7 +37,7 @@
     "/v1/campaign/{campaign_id}/status": {
       "post": {
         "operationId": "changeCampaignStatus",
-        "summary": "Change the status of a campaign",
+        "summary": "changeCampaignStatus",
         "description": "Change the status of a campaign to a desired status.\n\nThe status can be one of the following: active, inactive.\n\nStatus transition is accompanied by side effects, e.g., automation execution.\n",
         "tags": [
           "Campaign"
@@ -69,7 +69,7 @@
       "get": {
         "operationId": "getCampaignJobStatus",
         "description": "Get the status of a campaign's automation job",
-        "summary": "Get the status of a campaign's automation job",
+        "summary": "getCampaignJobStatus",
         "tags": [
           "Campaign"
         ],
@@ -99,7 +99,7 @@
     "/v1/campaign/{campaign_id}/portals": {
       "get": {
         "operationId": "getCampaignPortals",
-        "summary": "Get portals usage info for a campaign",
+        "summary": "getCampaignPortals",
         "description": "Get the list of portals and its widgets where the campaign is used.\n",
         "tags": [
           "Campaign"
@@ -130,7 +130,7 @@
     "/v1/campaign/{campaign_id}/automations:retrigger": {
       "post": {
         "operationId": "retriggerCampaignAutomations",
-        "summary": "Retrigger automations for campaign recipients",
+        "summary": "retriggerCampaignAutomations",
         "description": "Retrigger automation executions for specific campaign recipients that have failed.\n\nThis endpoint starts new automation executions for the specified recipients\nusing the campaign's associated automation flow. Only recipients with\nautomation_status 'failed' will be processed. Recipients with other statuses\n(success, pending, in_progress, cancelled) will be skipped to prevent\naccidentally retriggering successful or ongoing automations.\n",
         "tags": [
           "Campaign Delivery"
@@ -174,7 +174,7 @@
     "/v1/campaign:setup": {
       "post": {
         "operationId": "setupCampaign",
-        "summary": "Set up a campaign with related entities and configurations",
+        "summary": "setupCampaign",
         "description": "Creates a `campaign` entity together with its related entities and configurations in a single call.\nUsed by the campaign wizard UI, but not restricted to it.\n",
         "tags": [
           "Campaign"
@@ -210,7 +210,7 @@
     "/v1/campaign:match": {
       "post": {
         "operationId": "matchCampaigns",
-        "summary": "Match campaigns",
+        "summary": "matchCampaigns",
         "description": "Match campaigns based on target entities.\n\nThis endpoint returns the list of campaigns where the provided entities are part of the target.\n",
         "tags": [
           "Campaign"
@@ -246,7 +246,7 @@
     "/v1/campaign:discover": {
       "post": {
         "operationId": "discoverCampaigns",
-        "summary": "Discover Entity-UI Next Best Actions for an entity",
+        "summary": "discoverCampaigns",
         "description": "Given an entity, returns the Next Best Actions it should see on the Entity-UI channel.\n\nEnumerates the organization's **active** campaigns that carry a valid Entity-UI Next Best\nAction, live-matches each against the entity using the existing match engine, and returns\nthe matching NBAs priority-sorted (one per campaign).\n\nThis is a pure read: it writes nothing. An entity that matches no campaigns returns an\nempty list, not an error.\n",
         "tags": [
           "Campaign"
@@ -282,7 +282,7 @@
     "/v1/target:match": {
       "post": {
         "operationId": "matchTargets",
-        "summary": "Match targets",
+        "summary": "matchTargets",
         "description": "Find targets from the provided list that include the provide entities.\n",
         "tags": [
           "Target"
@@ -318,7 +318,7 @@
     "/v1/target/queries": {
       "post": {
         "operationId": "getTargetQueries",
-        "summary": "Get target queries",
+        "summary": "getTargetQueries",
         "description": "Transform target filters into Lucene queries for the provided target IDs.\nReturns the transformed query string for each target along with any errors encountered.\n",
         "tags": [
           "Target"
@@ -354,7 +354,7 @@
     "/v1/campaign/{campaign_id}/recipient": {
       "post": {
         "operationId": "createRecipient",
-        "summary": "Create a recipient associated with a campaign",
+        "summary": "createRecipient",
         "description": "Creates a new recipient associated with a campaign.",
         "tags": [
           "Campaign Recipient"
@@ -395,7 +395,7 @@
     "/v1/campaign/{campaign_id}/recipient/{recipient_id}": {
       "patch": {
         "operationId": "updateRecipient",
-        "summary": "Update a recipient",
+        "summary": "updateRecipient",
         "description": "Updates a recipient's attributes.",
         "tags": [
           "Campaign Recipient"
@@ -439,7 +439,7 @@
     "/v1/campaign/{campaign_id}/recipient/{recipient_id}/portal:status": {
       "patch": {
         "operationId": "updateRecipientPortalStatus",
-        "summary": "Update portal status for a campaign recipient",
+        "summary": "updateRecipientPortalStatus",
         "description": "Updates the portal status for a specific campaign recipient.\nThe portal_status_updated_at timestamp is automatically set when the status changes.\n\nStatus transition rules:\n- From 'sent': can change to 'seen', 'dismissed', or 'clicked'\n- From 'seen': can change to 'dismissed' or 'clicked'\n- From 'dismissed' or 'clicked': cannot be changed (final states)\n",
         "tags": [
           "Campaign Recipient"
@@ -489,8 +489,8 @@
     "/v1/campaign/{campaign_id}/recipient/{recipient_id}/entity_ui:status": {
       "patch": {
         "operationId": "updateRecipientEntityUiStatus",
-        "summary": "Update Entity-UI (Next Best Action) status for a campaign recipient",
-        "description": "Records a Next Best Action interaction for a recipient on the Entity-UI channel.\n\nUnlike the portal channel, an NBA recipient is created lazily: the first `seen` creates\nthe recipient record (and requires `entity_schema`). `seen` is idempotent — re-viewing an\nNBA that is already seen/clicked/dismissed is a no-op success and never regresses the status.\n\nStatus transition rules:\n- `seen`: lazily creates the recipient; a no-op success if a status already exists\n- From `seen`: can change to `clicked` or `dismissed`\n- From `clicked`: can change to `dismissed`\n- From `dismissed`: cannot be changed (final state)\n\n`dismissed` and `clicked` require an existing recipient (404 otherwise, since an NBA is\nborn at `seen`) and reject invalid transitions (409).\n\nThe entity_ui_status_updated_at timestamp is automatically set when the status changes.\n",
+        "summary": "updateRecipientEntityUiStatus",
+        "description": "Records a Next Best Action interaction for a recipient on the Entity-UI channel.\n\nUnlike the portal channel, an NBA recipient is created lazily: the first `seen` creates\nthe recipient record (and requires `entity_schema`). `seen` is idempotent — re-viewing an\nNBA that is already seen/clicked/dismissed is a no-op success and never regresses the status.\n\nStatus transition rules:\n- `seen`: lazily creates the recipient; a no-op success if a status already exists\n- From `seen`: can change to `clicked` or `dismissed`\n- From `clicked`: can change to `dismissed`\n- From `dismissed`: cannot be changed via this operation — use `entity_ui:restore`\n\n`dismissed` and `clicked` require an existing recipient (404 otherwise, since an NBA is\nborn at `seen`) and reject invalid transitions (409).\n\nThe entity_ui_status_updated_at timestamp is automatically set when the status changes.\n",
         "tags": [
           "Campaign Recipient"
         ],
@@ -536,10 +536,47 @@
         }
       }
     },
+    "/v1/campaign/{campaign_id}/recipient/{recipient_id}/entity_ui:restore": {
+      "post": {
+        "operationId": "restoreRecipientEntityUiStatus",
+        "summary": "Undo a dismissal on the Entity-UI (Next Best Action) channel",
+        "description": "Reverses a dismissal so the Next Best Action becomes visible to the entity again. This is\nthe only way out of `dismissed` — `entity_ui:status` cannot leave that state.\n\nThe recipient's status is restored to whatever it was immediately before the dismissal\n(recorded in `entity_ui_status_before_dismiss`), so a `clicked` NBA that was dismissed\nreturns to `clicked` and does not lose its recorded click. Falls back to `seen` when no\nprevious status was recorded.\n\nScoped to the Entity-UI channel only: the recipient's portal and automation state is never\ntouched. Takes no request body — the recipient's current state fully determines the result.\n\nReturns 404 when the recipient has no Entity-UI status at all, and 409 when it has one but\nis not currently `dismissed` (there is nothing to undo).\n",
+        "tags": [
+          "Campaign Recipient"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/CampaignIdPathParam"
+          },
+          {
+            "$ref": "#/components/parameters/RecipientIdPathParam"
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/RecipientResponse"
+          },
+          "404": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "409": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerErrorResponse"
+          }
+        }
+      }
+    },
     "/v1/campaign/{campaign_id}/recipients": {
       "get": {
         "operationId": "getRecipients",
-        "summary": "Get campaign recipients",
+        "summary": "getRecipients",
         "description": "Get a paginated list of recipients for a campaign.",
         "tags": [
           "Campaign Recipient"
@@ -598,6 +635,14 @@
             "schema": {
               "$ref": "#/components/schemas/PortalStatus"
             }
+          },
+          {
+            "name": "email_status",
+            "in": "query",
+            "description": "Filter by email delivery status (e.g. bounced, delivered). The response total reflects the count for the filtered status.",
+            "schema": {
+              "$ref": "#/components/schemas/EmailStatus"
+            }
           }
         ],
         "responses": {
@@ -612,6 +657,37 @@
           }
         }
       }
+    },
+    "/v1/campaign/{campaign_id}/email-stats": {
+      "get": {
+        "operationId": "getEmailStats",
+        "summary": "getEmailStats",
+        "description": "Aggregate email delivery counts for a campaign, for the KPI summary on the campaign UI.\nCounts cover the email (automation) channel only; `total_emailed` is the number of\nrecipients with a recorded email status. `delivered` is derivable as\n`total_emailed - bounced - complained - failed`.\n",
+        "tags": [
+          "Campaign Recipient"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/CampaignIdPathParam"
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/EmailStatsResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerErrorResponse"
+          }
+        }
+      }
     }
   },
   "components": {
@@ -666,6 +742,7 @@
                   "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",
@@ -1010,6 +1087,7 @@
         "properties": {
           "category": {
             "type": "string",
+            "maxLength": 30,
             "description": "Light category label shown above the title. Free-form text."
           },
           "icon": {
@@ -1031,10 +1109,12 @@
           },
           "title": {
             "type": "string",
+            "maxLength": 60,
             "description": "Bold action title. Required. Supports `{{placeholders}}`."
           },
           "body": {
             "type": "string",
+            "maxLength": 140,
             "description": "Optional description. Supports `{{placeholders}}` (incl. relative dates)."
           },
           "priority": {
@@ -1061,16 +1141,12 @@
                 "enum": [
                   "journey",
                   "workflow",
-                  "url"
+                  "flow"
                 ]
               },
               "target": {
                 "type": "string",
-                "description": "Journey id, workflow definition id, or URL, depending on `type`."
-              },
-              "label": {
-                "type": "string",
-                "description": "Optional CTA button label."
+                "description": "Journey id, workflow definition id, or flow template id, depending on `type`."
               },
               "context_params": {
                 "type": "array",
@@ -1120,6 +1196,35 @@
         ],
         "additionalProperties": false
       },
+      "DiscoverResult": {
+        "type": "object",
+        "description": "One discovered Next Best Action, plus this entity's interaction state for it.",
+        "properties": {
+          "campaign_id": {
+            "$ref": "#/components/schemas/BaseUUID"
+          },
+          "nba": {
+            "$ref": "#/components/schemas/NextBestAction"
+          },
+          "status": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/EntityUiStatus"
+              }
+            ],
+            "description": "The recipient's current Entity-UI status for this campaign, present only when a\nrecipient record already exists (i.e. the entity has previously seen, clicked or\ndismissed this NBA). Absent when the entity has not yet interacted with it.\n\nIn `results` this is only ever `seen` or `clicked`; in `dismissed` it is always\n`dismissed`. Lets the client skip a redundant `seen` call for NBAs already seen.\n"
+          },
+          "status_updated_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When `status` was last written. Present whenever `status` is. Lets the client show how\nlong ago an NBA was dismissed.\n"
+          }
+        },
+        "required": [
+          "campaign_id",
+          "nba"
+        ]
+      },
       "MatchTargetParams": {
         "type": "object",
         "properties": {
@@ -1233,11 +1338,23 @@
           "clicked"
         ]
       },
-      "Resolution": {
+      "EmailStatus": {
         "type": "string",
-        "description": "Cross-channel resolution of a campaign for a recipient. Unlike the per-channel `*_status`\nfields (where `dismissed` is channel-local), a resolution suppresses the campaign on EVERY\nchannel — the 360 Entity-UI card and the portal teaser alike. Server-managed and read-only:\nnever sent by a client. Absence means unresolved.\n",
+        "description": "Delivery status of the email a campaign's automation sends to a recipient. Set to `sent`\nonce the automation hands the email off, then updated asynchronously as SES notifications\narrive (`bounced` / `complained`; an SES Reject maps to `bounced`). `failed` is a send-time\nfailure (the automation execution could not send at all), distinct from an asynchronous\nbounce. `delivered` is reserved for when Delivery events are published.\n",
         "enum": [
-          "accepted"
+          "sent",
+          "delivered",
+          "bounced",
+          "complained",
+          "failed"
+        ]
+      },
+      "EmailBounceType": {
+        "type": "string",
+        "description": "SES bounce classification: `permanent` (hard) or `transient` (soft).",
+        "enum": [
+          "permanent",
+          "transient"
         ]
       },
       "Recipient": {
@@ -1276,8 +1393,44 @@
             "type": "string",
             "format": "date-time"
           },
-          "resolution": {
-            "$ref": "#/components/schemas/Resolution"
+          "entity_ui_status_before_dismiss": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/EntityUiStatus"
+              }
+            ],
+            "description": "The Entity-UI status the recipient held immediately before it was dismissed, so\n`entity_ui:restore` can put it back without losing a recorded click.\n\nServer-managed — never send this from a client; it is ignored on write. Meaningful\n**only while** `entity_ui_status` is `dismissed`: a restore intentionally leaves the\nvalue behind rather than clearing it, so a stale value after a restore is expected and\nmust not be read.\n"
+          },
+          "message_entity_id": {
+            "type": "string",
+            "description": "The message entity id of the email sent to this recipient by the campaign's automation\n(not the SES/provider message id), used to correlate SES delivery notifications back to\nthe recipient. Server-managed.\n"
+          },
+          "email_status": {
+            "$ref": "#/components/schemas/EmailStatus"
+          },
+          "email_status_updated_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "email_bounce_type": {
+            "$ref": "#/components/schemas/EmailBounceType"
+          },
+          "email_bounce_subtype": {
+            "type": "string",
+            "description": "SES bounce sub-type (e.g. `General`, `NoEmail`, `MailboxFull`)."
+          },
+          "email_complaint_type": {
+            "type": "string",
+            "description": "SES complaint feedback type (e.g. `abuse`, `fraud`), set for complaints."
+          },
+          "email_bounce_reason": {
+            "type": "string",
+            "description": "Human-readable failure reason — the SES bounce `diagnosticCode`, the complaint\nfeedback type, or a send-time error message.\n"
+          },
+          "email_send_error": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "The raw SES notification (or send error) kept verbatim for a detail view."
           },
           "updated_at": {
             "type": "string",
@@ -1774,6 +1927,56 @@
           }
         }
       },
+      "EmailStatsResponse": {
+        "description": "Aggregate email delivery counts for a campaign.",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "required": [
+                "total_emailed",
+                "sent",
+                "delivered",
+                "bounced",
+                "bounced_hard",
+                "bounced_soft",
+                "complained",
+                "failed"
+              ],
+              "properties": {
+                "total_emailed": {
+                  "type": "integer",
+                  "description": "Recipients with a recorded email status (the KPI denominator)."
+                },
+                "sent": {
+                  "type": "integer"
+                },
+                "delivered": {
+                  "type": "integer",
+                  "description": "Currently always 0 (Delivery events are not published yet)."
+                },
+                "bounced": {
+                  "type": "integer"
+                },
+                "bounced_hard": {
+                  "type": "integer",
+                  "description": "Bounces classified permanent (bounced_hard + bounced_soft = bounced)."
+                },
+                "bounced_soft": {
+                  "type": "integer",
+                  "description": "Bounces classified transient."
+                },
+                "complained": {
+                  "type": "integer"
+                },
+                "failed": {
+                  "type": "integer"
+                }
+              }
+            }
+          }
+        }
+      },
       "MatchCampaignsResponse": {
         "description": "List of campaigns where the target entities match the given entities.",
         "content": {
@@ -1814,39 +2017,27 @@
               "properties": {
                 "hits": {
                   "type": "number",
-                  "description": "Number of matching NBAs."
+                  "description": "Number of matching NBAs. Counts `results` only — dismissed ones are excluded."
                 },
                 "results": {
                   "type": "array",
                   "description": "Matching NBAs, sorted by priority (desc); one entry per campaign.",
                   "items": {
-                    "type": "object",
-                    "properties": {
-                      "campaign_id": {
-                        "$ref": "#/components/schemas/BaseUUID"
-                      },
-                      "nba": {
-                        "$ref": "#/components/schemas/NextBestAction"
-                      },
-                      "status": {
-                        "allOf": [
-                          {
-                            "$ref": "#/components/schemas/EntityUiStatus"
-                          }
-                        ],
-                        "description": "The recipient's current Entity-UI status for this campaign, present only\nwhen a recipient record already exists (i.e. the entity has previously seen\nor clicked this NBA). Absent when the entity has not yet interacted with it.\nDismissed NBAs are filtered out server-side, so this is only ever `seen` or\n`clicked`. Lets the client skip a redundant `seen` call for NBAs already seen.\n"
-                      }
-                    },
-                    "required": [
-                      "campaign_id",
-                      "nba"
-                    ]
+                    "$ref": "#/components/schemas/DiscoverResult"
+                  }
+                },
+                "dismissed": {
+                  "type": "array",
+                  "description": "NBAs this entity has dismissed that would otherwise be in `results` — same shape,\nalso priority-sorted. Returned so the client can show the agent what it hid and\noffer to restore it, without a second round-trip.\n\nOnly currently-relevant dismissals appear: each one is matched against its\ncampaign's target exactly like a visible NBA, so a dismissal is dropped once the\ncampaign ends or the entity stops matching. Capped, so this is not a complete\ndismissal history.\n",
+                  "items": {
+                    "$ref": "#/components/schemas/DiscoverResult"
                   }
                 }
               },
               "required": [
                 "hits",
-                "results"
+                "results",
+                "dismissed"
               ]
             }
           }

package/dist/bin/epilot.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   API_LIST
-} from "../chunk-4J5ZADZC.js";
+} from "../chunk-4A3TISYH.js";
 
 // bin/epilot.ts
 import { runMain } from "citty";
@@ -11,7 +11,7 @@ import { defineCommand } from "citty";
 var main = defineCommand({
   meta: {
     name: "epilot",
-    version: "0.1.130",
+    version: "0.1.132",
     description: "CLI for epilot APIs"
   },
   args: {
@@ -30,8 +30,8 @@ var main = defineCommand({
     auth: () => import("../auth-WMXFMPWE.js").then((m) => m.default),
     profile: () => import("../profile-OZJL5ZPT.js").then((m) => m.default),
     config: () => import("../config-DGZIMLZK.js").then((m) => m.default),
-    completion: () => import("../completion-GFINH6YJ.js").then((m) => m.default),
-    upgrade: () => import("../upgrade-QPOYGFSB.js").then((m) => m.default),
+    completion: () => import("../completion-MSAMXF3P.js").then((m) => m.default),
+    upgrade: () => import("../upgrade-I3HYEYCU.js").then((m) => m.default),
     "access-token": () => import("../access-token-WWE6BDJH.js").then((m) => m.default),
     address: () => import("../address-EH3C4CVB.js").then((m) => m.default),
     "address-suggestions": () => import("../address-suggestions-RRSLOBFW.js").then((m) => m.default),
@@ -134,13 +134,13 @@ process.stderr.on("error", (err) => {
   if (err.code === "EPIPE") process.exit(0);
   throw err;
 });
-var VERSION = true ? "0.1.130" : (await null).default.version;
+var VERSION = true ? "0.1.132" : (await null).default.version;
 var reorderedArgv = hoistFlagsAfterSubcommand(process.argv.slice(2));
 process.argv = [process.argv[0], process.argv[1], ...reorderedArgv];
 var args = process.argv.slice(2);
 var completionsIdx = args.indexOf("--_completions");
 if (completionsIdx >= 0) {
-  const { handleCompletions } = await import("../completion-GFINH6YJ.js");
+  const { handleCompletions } = await import("../completion-MSAMXF3P.js");
   handleCompletions(args[completionsIdx + 1], args[completionsIdx + 2]);
   process.exit(0);
 }

package/dist/{chunk-4J5ZADZC.js → chunk-4A3TISYH.js}

@@ -71,7 +71,7 @@ var API_LIST = [
     kebabName: "app",
     title: "App API",
     serverUrl: "https://app.sls.epilot.io",
-    operationCount: 35,
+    operationCount: 36,
     operationIds: [
       "getPublicFacingComponent",
       "listConfigurations",
@@ -102,6 +102,7 @@ var API_LIST = [
       "patchInstallation",
       "uninstall",
       "promoteVersion",
+      "resolveOptions",
       "ingestEvent",
       "publicProxyGet",
       "publicProxyPost",
@@ -1370,7 +1371,7 @@ var API_LIST = [
     kebabName: "targeting",
     title: "Targeting API",
     serverUrl: "https://targeting.sls.epilot.io",
-    operationCount: 14,
+    operationCount: 16,
     operationIds: [
       "changeCampaignStatus",
       "getCampaignJobStatus",
@@ -1385,7 +1386,9 @@ var API_LIST = [
       "updateRecipient",
       "updateRecipientPortalStatus",
       "updateRecipientEntityUiStatus",
-      "getRecipients"
+      "restoreRecipientEntityUiStatus",
+      "getRecipients",
+      "getEmailStats"
     ]
   },
   {

package/dist/{completion-GFINH6YJ.js → completion-MSAMXF3P.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   API_LIST
-} from "./chunk-4J5ZADZC.js";
+} from "./chunk-4A3TISYH.js";
 import {
   DIM,
   GREEN,

package/dist/{upgrade-QPOYGFSB.js → upgrade-I3HYEYCU.js}

@@ -72,7 +72,7 @@ ${GREEN}${BOLD}Upgraded to @epilot/cli@${latest}${RESET}
   }
 });
 var getCurrentVersion = () => {
-  if (true) return "0.1.130";
+  if (true) return "0.1.132";
   try {
     const output = execSync("npm ls -g @epilot/cli --depth=0 --json 2>/dev/null", {
       encoding: "utf-8",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epilot/cli",
-  "version": "0.1.130",
+  "version": "0.1.132",
   "description": "CLI for epilot APIs",
   "type": "module",
   "bin": {