Skip to content

EC success criteria #411

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
FlaviusMD merged 1 commit into from
Jul 4, 2026
Merged

EC success criteria #411

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion clients/event-catalog-client/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
154 changes: 152 additions & 2 deletions clients/event-catalog-client/src/openapi.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
*/
Expand Down Expand Up @@ -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
*/
Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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;
Expand Down
64 changes: 63 additions & 1 deletion clients/event-catalog-client/src/openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
]
}
}
},
Expand All @@ -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"
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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": [
Expand Down
Loading