@epilot/cli 0.1.68 → 0.1.70

package/definitions/targeting.json

@@ -243,6 +243,42 @@
         }
       }
     },
+    "/v1/campaign:discover": {
+      "post": {
+        "operationId": "discoverCampaigns",
+        "summary": "Discover Entity-UI Next Best Actions for an entity",
+        "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"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DiscoverCampaignsParams"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/DiscoverCampaignsResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerErrorResponse"
+          }
+        }
+      }
+    },
     "/v1/target:match": {
       "post": {
         "operationId": "matchTargets",
@@ -450,6 +486,56 @@
         }
       }
     },
+    "/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",
+        "tags": [
+          "Campaign Recipient"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/CampaignIdPathParam"
+          },
+          {
+            "$ref": "#/components/parameters/RecipientIdPathParam"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateEntityUiStatusRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/RecipientResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "404": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "409": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerErrorResponse"
+          }
+        }
+      }
+    },
     "/v1/campaign/{campaign_id}/recipients": {
       "get": {
         "operationId": "getRecipients",
@@ -918,6 +1004,122 @@
         ],
         "additionalProperties": false
       },
+      "NextBestAction": {
+        "type": "object",
+        "description": "A Next Best Action configured on a campaign's Entity-UI channel.\nThis is the canonical NBA contract shared by discovery (this API), authoring, and rendering.\nNBA content is single-language in v1; text fields may contain `{{placeholders}}` resolved at render time.\n",
+        "properties": {
+          "category": {
+            "type": "string",
+            "description": "Light category label shown above the title. Free-form text."
+          },
+          "icon": {
+            "type": "object",
+            "description": "Curated icon for the NBA.",
+            "properties": {
+              "name": {
+                "type": "string",
+                "description": "Icon name from \"@epilot360/icons\"."
+              },
+              "color": {
+                "type": "string",
+                "description": "Optional icon color."
+              }
+            },
+            "required": [
+              "name"
+            ]
+          },
+          "title": {
+            "type": "string",
+            "description": "Bold action title. Required. Supports `{{placeholders}}`."
+          },
+          "body": {
+            "type": "string",
+            "description": "Optional description. Supports `{{placeholders}}` (incl. relative dates)."
+          },
+          "priority": {
+            "type": "string",
+            "enum": [
+              "low",
+              "medium",
+              "high"
+            ],
+            "default": "medium",
+            "description": "Display priority. NBAs are shown highest-priority first."
+          },
+          "is_dismissable": {
+            "type": "boolean",
+            "default": true,
+            "description": "Whether the agent can dismiss the NBA."
+          },
+          "cta": {
+            "type": "object",
+            "description": "The NBA's single call-to-action.",
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "journey",
+                  "workflow",
+                  "url"
+                ]
+              },
+              "target": {
+                "type": "string",
+                "description": "Journey id, workflow definition id, or URL, depending on `type`."
+              },
+              "label": {
+                "type": "string",
+                "description": "Optional CTA button label."
+              },
+              "context_params": {
+                "type": "array",
+                "description": "Journey context parameters (journey CTA only). Maps the journey's declared\ncontext parameters so the journey knows which entity it is about. Discovery\nreturns them verbatim; they are passed to the journey when it launches.\n",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "key": {
+                      "type": "string"
+                    },
+                    "value": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "key",
+                    "value"
+                  ]
+                }
+              }
+            },
+            "required": [
+              "type",
+              "target"
+            ]
+          }
+        },
+        "required": [
+          "title",
+          "cta"
+        ]
+      },
+      "DiscoverCampaignsParams": {
+        "type": "object",
+        "properties": {
+          "entity_id": {
+            "$ref": "#/components/schemas/BaseUUID"
+          },
+          "entity_schema": {
+            "type": "string",
+            "description": "The schema slug of the entity (e.g. \"contact\" or \"account\")."
+          }
+        },
+        "required": [
+          "entity_id",
+          "entity_schema"
+        ],
+        "additionalProperties": false
+      },
       "MatchTargetParams": {
         "type": "object",
         "properties": {
@@ -1022,6 +1224,22 @@
           "clicked"
         ]
       },
+      "EntityUiStatus": {
+        "type": "string",
+        "description": "Lifecycle status of a Next Best Action on the Entity-UI channel. Unlike the portal\nchannel there is no `sent` state: an NBA recipient is born at `seen`, the moment the\naction is first rendered to an agent.\n",
+        "enum": [
+          "seen",
+          "dismissed",
+          "clicked"
+        ]
+      },
+      "Resolution": {
+        "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",
+        "enum": [
+          "accepted"
+        ]
+      },
       "Recipient": {
         "type": "object",
         "properties": {
@@ -1051,6 +1269,16 @@
             "type": "object",
             "additionalProperties": true
           },
+          "entity_ui_status": {
+            "$ref": "#/components/schemas/EntityUiStatus"
+          },
+          "entity_ui_status_updated_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "resolution": {
+            "$ref": "#/components/schemas/Resolution"
+          },
           "updated_at": {
             "type": "string",
             "format": "date-time"
@@ -1216,6 +1444,22 @@
           "status"
         ]
       },
+      "UpdateEntityUiStatusRequest": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "$ref": "#/components/schemas/EntityUiStatus"
+          },
+          "entity_schema": {
+            "type": "string",
+            "description": "Schema slug of the recipient entity (e.g. \"contact\"). Required when recording the\nfirst `seen`, which lazily creates the recipient record; ignored on later transitions.\n"
+          }
+        },
+        "required": [
+          "status"
+        ],
+        "additionalProperties": false
+      },
       "SetupCampaignRequest": {
         "description": "Discriminated by `type`. Each campaign variant has its own request shape;\nnew variants are added by introducing a new schema and extending the `oneOf` list.\n",
         "oneOf": [
@@ -1561,6 +1805,53 @@
           }
         }
       },
+      "DiscoverCampaignsResponse": {
+        "description": "The Next Best Actions the entity should see on the Entity-UI channel, priority-sorted.",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "hits": {
+                  "type": "number",
+                  "description": "Number of matching NBAs."
+                },
+                "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"
+                    ]
+                  }
+                }
+              },
+              "required": [
+                "hits",
+                "results"
+              ]
+            }
+          }
+        }
+      },
       "MatchTargetsResponse": {
         "description": "List of targets where the given entities are found.",
         "content": {

package/definitions/user.json

@@ -1046,6 +1046,117 @@
         }
       }
     },
+    "/v2/users/public/resetPassword": {
+      "post": {
+        "operationId": "resetPassword",
+        "summary": "resetPassword",
+        "description": "Set a new password using a reset token from the password reset email.\nThe token is single-use and time-limited.\n",
+        "security": [],
+        "x-rate-limit": {
+          "limit": 10
+        },
+        "tags": [
+          "User V2"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "email",
+                  "token",
+                  "password"
+                ],
+                "properties": {
+                  "email": {
+                    "type": "string",
+                    "description": "Email address of the account",
+                    "example": "test@example.com"
+                  },
+                  "token": {
+                    "type": "string",
+                    "description": "Reset token from the password reset email"
+                  },
+                  "password": {
+                    "type": "string",
+                    "description": "The new password"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Password reset successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "success"
+                  ],
+                  "properties": {
+                    "success": {
+                      "type": "boolean",
+                      "example": true
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid or expired reset link, or password does not meet the requirements",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "error",
+                    "message"
+                  ],
+                  "properties": {
+                    "error": {
+                      "type": "string",
+                      "description": "Discriminator distinguishing token errors from policy errors",
+                      "enum": [
+                        "INVALID_RESET_LINK",
+                        "PASSWORD_POLICY"
+                      ]
+                    },
+                    "message": {
+                      "type": "string",
+                      "example": "Password does not meet the requirements"
+                    },
+                    "violations": {
+                      "type": "array",
+                      "description": "Itemized password-policy violation codes (only present when error is PASSWORD_POLICY)",
+                      "items": {
+                        "type": "string",
+                        "enum": [
+                          "too_short",
+                          "missing_lowercase",
+                          "missing_uppercase",
+                          "missing_number",
+                          "missing_symbol"
+                        ]
+                      },
+                      "example": [
+                        "too_short",
+                        "missing_uppercase"
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/v2/users/public/checkToken": {
       "get": {
         "operationId": "checkInviteToken",
@@ -1998,6 +2109,19 @@
             "format": "date-time",
             "readOnly": true
           },
+          "password_reset_token_hash": {
+            "description": "Internal: sha256 hash of the active password-reset token. Server-set, never returned in responses.",
+            "type": "string",
+            "nullable": true,
+            "readOnly": true
+          },
+          "password_reset_token_expires_at": {
+            "description": "Internal: expiry for the active password-reset token (ISO 8601). Server-set, never returned in responses.",
+            "type": "string",
+            "nullable": true,
+            "format": "date-time",
+            "readOnly": true
+          },
           "department": {
             "type": "string",
             "description": "User's department",
@@ -2130,6 +2254,17 @@
               "deleted_opportunity": true
             }
           },
+          "in_app_notification_setting": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Per-notification-type in-app delivery preferences (notification type key -> enabled). Written by the my-account notification settings UI and honored by svc-notification-api at delivery time. Absent or partial keys fall back to each notification type's configured default. Mirrors email_notification_setting for the in-app channel.",
+            "example": {
+              "integration_critical_error": true,
+              "integration_error_threshold": true,
+              "assigned_opportunity": true,
+              "assigned_task": true
+            }
+          },
           "properties": {
             "type": "array",
             "items": {
@@ -2149,6 +2284,17 @@
                 "value"
               ]
             }
+          },
+          "tags": {
+            "type": "array",
+            "description": "User tags/labels assigned for classification (e.g. label slugs)",
+            "nullable": true,
+            "items": {
+              "type": "string"
+            },
+            "example": [
+              "non-billable"
+            ]
           }
         }
       },

package/definitions/webhooks.json

@@ -1094,14 +1094,15 @@
       },
       "WebhookCondition": {
         "type": "object",
-        "description": "A condition that must be met for the webhook to fire.",
+        "description": "A condition that must be met for the webhook to fire. A condition is EITHER a classic field + operation comparison OR a single jsonata_expression evaluated against the event payload — the two forms are mutually exclusive.",
         "properties": {
           "field": {
             "type": "string",
-            "description": "Dot-notation path to the field in the event payload (e.g. \"entity.status\", \"entity.line_items\")"
+            "description": "Dot-notation path to the field in the event payload (e.g. \"entity.status\", \"entity.line_items\"). Supports array indices in either spelling, which resolve identically: \"meter_readings.1.file_id\" or \"meter_readings[1].file_id\"."
           },
           "operation": {
             "type": "string",
+            "description": "Comparison operator. The length_* operations compare the item count of the field value (an array yields its length, a missing or null field yields 0, and any single non-array value yields 1) against values[0], which must be a non-negative integer.",
             "enum": [
               "equals",
               "not_equals",
@@ -1116,7 +1117,13 @@
               "greater_than_or_equals",
               "less_than_or_equals",
               "is_empty",
-              "is_not_empty"
+              "is_not_empty",
+              "length_equals",
+              "length_not_equals",
+              "length_greater_than",
+              "length_less_than",
+              "length_greater_than_or_equals",
+              "length_less_than_or_equals"
             ]
           },
           "values": {
@@ -1147,12 +1154,13 @@
             "type": "boolean",
             "description": "When true, evaluates conditions per-item in repeatable array fields",
             "default": false
+          },
+          "jsonata_expression": {
+            "type": "string",
+            "maxLength": 15000,
+            "description": "JSONata expression evaluated against the event payload; the condition passes when the result is truthy per JSONata $boolean semantics. Mutually exclusive with field/operation."
           }
-        },
-        "required": [
-          "field",
-          "operation"
-        ]
+        }
       },
       "WebhookConditionGroup": {
         "type": "object",
@@ -1498,7 +1506,8 @@
         ],
         "properties": {
           "status_code": {
-            "type": "string"
+            "type": "string",
+            "description": "The HTTP status returned by the customer endpoint (or the upstream gateway). ABSENT for epilot-internal errors (code INTERNAL_ERROR / INTERNAL_RESPONSE_TOO_LARGE), which are not customer HTTP outcomes; PRESENT only for real HTTP/upstream results. When the response was delivered but too large to record, a recovered delivered status may still be present."
           },
           "message": {
             "type": "string"
@@ -1507,7 +1516,8 @@
             "type": "object"
           },
           "code": {
-            "type": "string"
+            "type": "string",
+            "description": "Machine-readable classification of the outcome. Known values: OAuthTokenExchangeError (OAuth token exchange / upstream gateway failure), DataLimitExceeded (legacy oversized-response marker), INTERNAL_RESPONSE_TOO_LARGE (request delivered but the response was too large for epilot to record), INTERNAL_ERROR (epilot-internal processing failure — not a customer HTTP outcome)."
           },
           "status": {
             "type": "string",
@@ -1678,7 +1688,8 @@
             "type": "object",
             "properties": {
               "status_code": {
-                "type": "integer"
+                "type": "integer",
+                "description": "The HTTP status returned by the customer endpoint (or the upstream gateway). ABSENT for epilot-internal errors (code INTERNAL_ERROR / INTERNAL_RESPONSE_TOO_LARGE), which are not customer HTTP outcomes; PRESENT only for real HTTP/upstream results. When the response was delivered but too large to record, a recovered delivered status may still be present."
               },
               "message": {
                 "type": "string"
@@ -1687,7 +1698,8 @@
                 "type": "object"
               },
               "code": {
-                "type": "string"
+                "type": "string",
+                "description": "Machine-readable classification of the outcome. Known values: OAuthTokenExchangeError (OAuth token exchange / upstream gateway failure), DataLimitExceeded (legacy oversized-response marker), INTERNAL_RESPONSE_TOO_LARGE (request delivered but the response was too large for epilot to record), INTERNAL_ERROR (epilot-internal processing failure — not a customer HTTP outcome)."
               }
             }
           },