diff --git a/clients/event-catalog-client/package.json b/clients/event-catalog-client/package.json index 5f6325db..a0fe33e6 100644 --- a/clients/event-catalog-client/package.json +++ b/clients/event-catalog-client/package.json @@ -1,6 +1,6 @@ { "name": "@epilot/event-catalog-client", - "version": "0.6.2", + "version": "0.6.3", "description": "Client for epilot Event Catalog API", "main": "dist/index.js", "types": "dist/index.d.ts", diff --git a/clients/event-catalog-client/src/openapi.d.ts b/clients/event-catalog-client/src/openapi.d.ts index fbe55f1f..4535df89 100644 --- a/clients/event-catalog-client/src/openapi.d.ts +++ b/clients/event-catalog-client/src/openapi.d.ts @@ -205,6 +205,10 @@ declare namespace Components { * */ _ack_id?: string; + /** + * Inline downgrade chain stamped by Event Catalog at publish time, ordered newest-to-oldest. Present ONLY on multi-version events. Internal versioning transport: consumers (e.g. svc-webhooks) walk the payload back to a pinned version using these JSONata steps, then strip the field before delivery -- end customers never receive it. + */ + _downgrades?: /* One step of an event's inline `_downgrades` chain. Maps the current-version payload to the previous version via a JSONata expression. Stamped by Event Catalog at publish time; executed by consumers during walk-back, never by EC itself. */ InlineDowngradeStep[]; } /** * A file attachment associated with an event @@ -397,6 +401,41 @@ declare namespace Components { * true */ automation_trigger?: boolean; + /** + * Org-defined success criteria for this event: the entity attributes that an + * organization considers must be captured for an event change request to be + * treated as complete (e.g. for telephony / self-service flows). + * + * Advisory metadata — event-catalog does NOT require an org to define any and + * does NOT enforce them when an event is triggered or published. The org may + * define none (empty array or omitted). When provided, each entry is validated + * for well-formedness on write (see SuccessCriterion). + * + * example: + * [ + * { + * "entity_schema": "contract", + * "attribute": "installment_amount" + * }, + * { + * "entity_schema": "billing_account", + * "attribute": "due_date" + * } + * ] + */ + success_criteria?: /** + * A single org-defined success criterion: an entity attribute that must be captured + * for this event's change request to be considered complete. + * + * Identity is the entity schema plus the attribute name — mirroring the + * EntityOperationTrigger `schema`/`attribute` vocabulary. On write (PATCH), both + * `attribute` and `entity_schema` are required and `entity_schema` must match the + * `schema` of a node in the event's `entity_graph` (else the request is rejected) — + * this prevents unsatisfiable criteria. The criteria themselves are advisory and are + * never enforced when an event is triggered or published. + * + */ + SuccessCriterion[]; } /** * Base properties shared between EventConfig and UpdateEventPayload @@ -547,6 +586,41 @@ declare namespace Components { * true */ automation_trigger?: boolean; + /** + * Org-defined success criteria for this event: the entity attributes that an + * organization considers must be captured for an event change request to be + * treated as complete (e.g. for telephony / self-service flows). + * + * Advisory metadata — event-catalog does NOT require an org to define any and + * does NOT enforce them when an event is triggered or published. The org may + * define none (empty array or omitted). When provided, each entry is validated + * for well-formedness on write (see SuccessCriterion). + * + * example: + * [ + * { + * "entity_schema": "contract", + * "attribute": "installment_amount" + * }, + * { + * "entity_schema": "billing_account", + * "attribute": "due_date" + * } + * ] + */ + success_criteria?: /** + * A single org-defined success criterion: an entity attribute that must be captured + * for this event's change request to be considered complete. + * + * Identity is the entity schema plus the attribute name — mirroring the + * EntityOperationTrigger `schema`/`attribute` vocabulary. On write (PATCH), both + * `attribute` and `entity_schema` are required and `entity_schema` must match the + * `schema` of a node in the event's `entity_graph` (else the request is rejected) — + * this prevents unsatisfiable criteria. The criteria themselves are advisory and are + * never enforced when an event is triggered or published. + * + */ + SuccessCriterion[]; } /** * JSON Schema declaring the event payload structure @@ -890,6 +964,19 @@ declare namespace Components { */ fields?: string[]; } + /** + * One step of an event's inline `_downgrades` chain. Maps the current-version payload to the previous version via a JSONata expression. Stamped by Event Catalog at publish time; executed by consumers during walk-back, never by EC itself. + */ + export interface InlineDowngradeStep { + /** + * Version label this step downgrades to (the previous version). + */ + to: string; + /** + * JSONata expression mapping the current-shape payload to the previous-shape payload. + */ + jsonata: string; + } /** * A primitive JSON Schema field definition */ @@ -1054,6 +1141,32 @@ declare namespace Components { */ FieldsParam; } + /** + * A single org-defined success criterion: an entity attribute that must be captured + * for this event's change request to be considered complete. + * + * Identity is the entity schema plus the attribute name — mirroring the + * EntityOperationTrigger `schema`/`attribute` vocabulary. On write (PATCH), both + * `attribute` and `entity_schema` are required and `entity_schema` must match the + * `schema` of a node in the event's `entity_graph` (else the request is rejected) — + * this prevents unsatisfiable criteria. The criteria themselves are advisory and are + * never enforced when an event is triggered or published. + * + */ + export interface SuccessCriterion { + /** + * Entity schema slug the attribute belongs to (matches a node schema in the event's entity_graph). + * example: + * contract + */ + entity_schema: string; + /** + * Attribute name on the entity schema. + * example: + * installment_amount + */ + attribute: string; + } /** * Payload for explicitly triggering an event via API */ @@ -1125,7 +1238,7 @@ declare namespace Components { /** * Payload for updating an event configuration. * Accepts the same fields as EventConfig (all optional for PATCH). - * Currently `enabled` and `auto_trigger` fields are processed. + * Currently `enabled`, `auto_trigger` and `success_criteria` fields are processed. * */ export interface UpdateEventPayload { @@ -1274,6 +1387,41 @@ declare namespace Components { * true */ automation_trigger?: boolean; + /** + * Org-defined success criteria for this event: the entity attributes that an + * organization considers must be captured for an event change request to be + * treated as complete (e.g. for telephony / self-service flows). + * + * Advisory metadata — event-catalog does NOT require an org to define any and + * does NOT enforce them when an event is triggered or published. The org may + * define none (empty array or omitted). When provided, each entry is validated + * for well-formedness on write (see SuccessCriterion). + * + * example: + * [ + * { + * "entity_schema": "contract", + * "attribute": "installment_amount" + * }, + * { + * "entity_schema": "billing_account", + * "attribute": "due_date" + * } + * ] + */ + success_criteria?: /** + * A single org-defined success criterion: an entity attribute that must be captured + * for this event's change request to be considered complete. + * + * Identity is the entity schema plus the attribute name — mirroring the + * EntityOperationTrigger `schema`/`attribute` vocabulary. On write (PATCH), both + * `attribute` and `entity_schema` are required and `entity_schema` must match the + * `schema` of a node in the event's `entity_graph` (else the request is rejected) — + * this prevents unsatisfiable criteria. The criteria themselves are advisory and are + * never enforced when an event is triggered or published. + * + */ + SuccessCriterion[]; } /** * One entry of an event's version timeline. @@ -1577,7 +1725,7 @@ declare namespace Paths { export type RequestBody = /** * Payload for updating an event configuration. * Accepts the same fields as EventConfig (all optional for PATCH). - * Currently `enabled` and `auto_trigger` fields are processed. + * Currently `enabled`, `auto_trigger` and `success_criteria` fields are processed. * */ Components.Schemas.UpdateEventPayload; @@ -2010,10 +2158,12 @@ export type FieldsParam = Components.Schemas.FieldsParam; export type GraphDefinition = Components.Schemas.GraphDefinition; export type GraphEdge = Components.Schemas.GraphEdge; export type GraphNode = Components.Schemas.GraphNode; +export type InlineDowngradeStep = Components.Schemas.InlineDowngradeStep; export type PrimitiveField = Components.Schemas.PrimitiveField; export type SchemaField = Components.Schemas.SchemaField; export type SearchOptions = Components.Schemas.SearchOptions; export type SearchOptionsV2 = Components.Schemas.SearchOptionsV2; +export type SuccessCriterion = Components.Schemas.SuccessCriterion; export type TriggerEventPayload = Components.Schemas.TriggerEventPayload; export type TriggerEventResponse = Components.Schemas.TriggerEventResponse; export type UpdateEventPayload = Components.Schemas.UpdateEventPayload; diff --git a/clients/event-catalog-client/src/openapi.json b/clients/event-catalog-client/src/openapi.json index 7f05180f..b466fc37 100644 --- a/clients/event-catalog-client/src/openapi.json +++ b/clients/event-catalog-client/src/openapi.json @@ -593,6 +593,23 @@ "description": "Whether this event can be explicitly triggered by automations.\nWhen true, the event will appear in the automation builder as a\n\"Trigger Event\" action option.\nDefaults to false if not specified.\n", "default": false, "example": true + }, + "success_criteria": { + "type": "array", + "description": "Org-defined success criteria for this event: the entity attributes that an\norganization considers must be captured for an event change request to be\ntreated as complete (e.g. for telephony / self-service flows).\n\nAdvisory metadata — event-catalog does NOT require an org to define any and\ndoes NOT enforce them when an event is triggered or published. The org may\ndefine none (empty array or omitted). When provided, each entry is validated\nfor well-formedness on write (see SuccessCriterion).\n", + "items": { + "$ref": "#/components/schemas/SuccessCriterion" + }, + "example": [ + { + "entity_schema": "contract", + "attribute": "installment_amount" + }, + { + "entity_schema": "billing_account", + "attribute": "due_date" + } + ] } } }, @@ -613,7 +630,7 @@ ] }, "UpdateEventPayload": { - "description": "Payload for updating an event configuration.\nAccepts the same fields as EventConfig (all optional for PATCH).\nCurrently `enabled` and `auto_trigger` fields are processed.\n", + "description": "Payload for updating an event configuration.\nAccepts the same fields as EventConfig (all optional for PATCH).\nCurrently `enabled`, `auto_trigger` and `success_criteria` fields are processed.\n", "allOf": [ { "$ref": "#/components/schemas/EventConfigBase" @@ -696,6 +713,26 @@ } ] }, + "SuccessCriterion": { + "type": "object", + "description": "A single org-defined success criterion: an entity attribute that must be captured\nfor this event's change request to be considered complete.\n\nIdentity is the entity schema plus the attribute name — mirroring the\nEntityOperationTrigger `schema`/`attribute` vocabulary. On write (PATCH), both\n`attribute` and `entity_schema` are required and `entity_schema` must match the\n`schema` of a node in the event's `entity_graph` (else the request is rejected) —\nthis prevents unsatisfiable criteria. The criteria themselves are advisory and are\nnever enforced when an event is triggered or published.\n", + "properties": { + "entity_schema": { + "type": "string", + "description": "Entity schema slug the attribute belongs to (matches a node schema in the event's entity_graph).", + "example": "contract" + }, + "attribute": { + "type": "string", + "description": "Attribute name on the entity schema.", + "example": "installment_amount" + } + }, + "required": [ + "entity_schema", + "attribute" + ] + }, "CommonEventMetadata": { "type": "object", "description": "Common metadata fields present in all event payloads", @@ -878,6 +915,24 @@ ] } }, + "InlineDowngradeStep": { + "type": "object", + "description": "One step of an event's inline `_downgrades` chain. Maps the current-version payload to the previous version via a JSONata expression. Stamped by Event Catalog at publish time; executed by consumers during walk-back, never by EC itself.", + "properties": { + "to": { + "type": "string", + "description": "Version label this step downgrades to (the previous version)." + }, + "jsonata": { + "type": "string", + "description": "JSONata expression mapping the current-shape payload to the previous-shape payload." + } + }, + "required": [ + "to", + "jsonata" + ] + }, "Event": { "type": "object", "description": "An event instance in the event history", @@ -920,6 +975,13 @@ "_ack_id": { "type": "string", "description": "Unique acknowledgment tracking ID for the event.\nUsed to track event delivery and processing status.\n" + }, + "_downgrades": { + "type": "array", + "description": "Inline downgrade chain stamped by Event Catalog at publish time, ordered newest-to-oldest. Present ONLY on multi-version events. Internal versioning transport: consumers (e.g. svc-webhooks) walk the payload back to a pinned version using these JSONata steps, then strip the field before delivery -- end customers never receive it.", + "items": { + "$ref": "#/components/schemas/InlineDowngradeStep" + } } }, "required": [