@zenglobal/api-client 5.0.15 → 5.0.16

package/dist/client/types.gen.d.ts

@@ -8364,6 +8364,174 @@ export type VoucherTypeResponse = {
         version: string;
     };
 };
+/**
+ * A webhook destination: one HTTPS endpoint, the events it receives, and how
+ * deliveries to it are authenticated and retried.
+ *
+ * Every property here is returned on read. `active`, `has_credentials`,
+ * `created_at` and `updated_at` are read-only — see
+ * `WebhookDestinationInput` for what you can send.
+ */
+export type WebhookDestination = {
+    /**
+     * Unique key within your company. 3-64 lowercase letters, digits or underscores. Cannot be changed after creation. `zen_` and `pc_` are reserved prefixes, and the exact name `validate` is reserved.
+     */
+    name: string;
+    /**
+     * Human-readable description
+     */
+    label: string;
+    /**
+     * Destination URL. Must be https://.
+     */
+    url: string;
+    /**
+     * An ADDITIONAL credential your endpoint requires, on top of the signature every delivery already carries. `none` is a complete choice, not an absent one: the HMAC signature authenticates the request by itself.
+     */
+    auth_scheme: 'none' | 'body_key' | 'bearer' | 'custom_header';
+    /**
+     * Scheme-specific settings: `header_name` for custom_header. Null for none, body_key and bearer, which take no additional keys. Never contains a secret.
+     */
+    auth_config?: {
+        [key: string]: unknown;
+    } | null;
+    /**
+     * The events this destination receives. Always non-empty.
+     */
+    event_types: Array<WebhookEventType>;
+    /**
+     * Site codes events are delivered for. Null means every site in your company; a list is an allowlist. Only permitted when EVERY subscribed event type carries a site dimension: item.soh, item.price, offer.redeem, transaction.complete. This is delivery efficiency, not an entitlement — a partner credential already reaches every site in the company.
+     */
+    site_filter?: Array<number> | null;
+    /**
+     * Whether deliveries must arrive in order. Ordered delivery means a failing event blocks those behind it, so enable it only if your endpoint genuinely requires sequence.
+     */
+    ordered: boolean;
+    /**
+     * Retry settings. Null uses the platform default.
+     */
+    retry_policy?: {
+        [key: string]: unknown;
+    } | null;
+    /**
+     * Optional response-body check that decides whether a 2xx really succeeded
+     */
+    response_check?: {
+        [key: string]: unknown;
+    } | null;
+    /**
+     * Whether a 4xx response from your endpoint counts as a permanent failure or a retryable one
+     */
+    treat_4xx_as: 'failed' | 'retry';
+    /**
+     * Read-only. Whether this destination is live. Creating sets it true and deleting sets it false; it cannot be driven from a request body.
+     */
+    active: boolean;
+    /**
+     * Read-only. Whether an authentication secret is stored. The secret itself is never returned by any operation.
+     */
+    has_credentials: boolean;
+    /**
+     * Read-only.
+     */
+    created_at: string;
+    /**
+     * Read-only.
+     */
+    updated_at: string;
+};
+export type WebhookDestinationHealthResponse = {
+    /**
+     * False when the delivery engine could not be reached. The destination itself is unaffected.
+     */
+    engine_available: boolean;
+    /**
+     * Recent delivery health, or null when the engine is unavailable
+     */
+    health?: {
+        [key: string]: unknown;
+    } | null;
+};
+/**
+ * The writable fields.
+ *
+ * `name` is required on create and cannot be changed afterwards. On update,
+ * every field is optional and an omitted one keeps its stored value — with two
+ * exceptions where an explicit `null` is meaningful and distinct from omission:
+ * sending `site_filter: null` clears an allowlist, and `retry_policy: null`
+ * returns the destination to the platform default.
+ *
+ * `active` is NOT writable and is ignored if sent: create always activates the
+ * destination, an update always preserves whatever is stored, and only DELETE
+ * retires one. A body-driven `active: false` would otherwise retire a
+ * destination through `write:webhooks` alone, which is the job of DELETE and is
+ * gated behind `delete:webhooks`.
+ *
+ * `chain_code` is likewise ignored rather than rejected — the company always
+ * comes from your credential — so a client may safely send back a destination
+ * it previously read.
+ */
+export type WebhookDestinationInput = {
+    /**
+     * Required on create, and must match the path on update. 3-64 lowercase letters, digits or underscores.
+     */
+    name?: string;
+    label?: string;
+    url?: string;
+    auth_scheme?: 'none' | 'body_key' | 'bearer' | 'custom_header';
+    /**
+     * Scheme-specific settings. `custom_header` requires `header_name`. Changing `auth_scheme` without supplying a new `auth_config` drops the old scheme's config rather than carrying it across.
+     */
+    auth_config?: {
+        [key: string]: unknown;
+    } | null;
+    /**
+     * The shared secret deliveries are signed with. Write-only, never returned. Omit it or send a blank string on update to keep the stored one.
+     */
+    auth_secret?: string;
+    event_types?: Array<WebhookEventType>;
+    site_filter?: Array<number> | null;
+    ordered?: boolean;
+    retry_policy?: {
+        [key: string]: unknown;
+    } | null;
+    response_check?: {
+        [key: string]: unknown;
+    } | null;
+    treat_4xx_as?: 'failed' | 'retry';
+};
+export type WebhookDestinationListResponse = {
+    destinations: Array<WebhookDestination>;
+};
+/**
+ * The error body every failure on these operations returns.
+ *
+ * NOTE: these operations use conventional HTTP status codes and this body
+ * shape. They do NOT use the `{result, errormessage}` envelope the rest of the
+ * Zen v1 API returns, frequently over HTTP 200. Error handling written against
+ * other Zen endpoints will misread these responses as successes with a missing
+ * `result` field.
+ */
+export type WebhookErrorBody = {
+    /**
+     * Human-readable summary. For a validation or conflict failure this is the first violation's message.
+     */
+    error: string;
+    /**
+     * Field-level failures, where the failure can be attributed to a field. Empty for 403 scope refusals on a path other than `event_types`, and for 404.
+     */
+    violations: Array<WebhookViolation>;
+};
+/**
+ * The events a webhook destination can subscribe to.
+ *
+ * These are LEAVES: one subscribable key per event shape, `resource.action`.
+ * The list is enumerate-only — `offer` is NOT shorthand for the four `offer.*`
+ * leaves and is rejected. A destination subscribed to a resource-level
+ * shorthand would silently start receiving a new event type the day one is
+ * added, which is exactly what this granularity prevents.
+ */
+export type WebhookEventType = 'loyalty.card' | 'loyalty.points' | 'customer.upsert' | 'offer.create' | 'offer.update' | 'offer.redeem' | 'offer.delete' | 'item.soh' | 'item.price' | 'transaction.complete';
 /**
  * Outbound Webhook Models
  *
@@ -8400,6 +8568,18 @@ export type WebhookPayload = {
      */
     viaBody: boolean;
 };
+/**
+ * 200 — a newly generated signing key.
+ *
+ * This is the ONLY response in the API that contains a signing key. Store it
+ * when you receive it: there is no operation that reads it back.
+ */
+export type WebhookSigningKeyResponse = {
+    /**
+     * The new signing key. Shown once, here, and never again.
+     */
+    signing_key: string;
+};
 /**
  * Transaction loyalty information
  */
@@ -8433,6 +8613,19 @@ export type WebhookTransactionLoyalty = {
      */
     CardType: string;
 };
+/**
+ * A field-level validation failure.
+ */
+export type WebhookViolation = {
+    /**
+     * The request field this failure belongs to, or an empty string when the failure cannot be attributed to one field
+     */
+    propertyPath: string;
+    /**
+     * Human-readable explanation
+     */
+    title: string;
+};
 /**
  * Not found error (404)
  */
@@ -11761,6 +11954,237 @@ export type VoucherSearchVouchersFlatResponses = {
     200: VoucherFlatSearchResponse;
 };
 export type VoucherSearchVouchersFlatResponse = VoucherSearchVouchersFlatResponses[keyof VoucherSearchVouchersFlatResponses];
+export type WebhookDestinationsListDestinationsData = {
+    body?: never;
+    path?: never;
+    query?: never;
+    url: '/v1/webhooks/destinations';
+};
+export type WebhookDestinationsListDestinationsResponses = {
+    /**
+     * The request has succeeded.
+     */
+    200: WebhookDestinationListResponse;
+};
+export type WebhookDestinationsListDestinationsResponse = WebhookDestinationsListDestinationsResponses[keyof WebhookDestinationsListDestinationsResponses];
+export type WebhookDestinationsCreateDestinationData = {
+    body: WebhookDestinationInput;
+    path?: never;
+    query?: never;
+    url: '/v1/webhooks/destinations';
+};
+export type WebhookDestinationsCreateDestinationErrors = {
+    /**
+     * 403 — your credential holds the endpoint scope but not the data scope one of
+     * the subscribed event types requires. The message names both the event type
+     * and the missing scope, and `propertyPath` is `eventTypes`. The subscription
+     * is never silently trimmed to the permitted subset.
+     */
+    403: WebhookErrorBody;
+    /**
+     * 409 — a destination with that name already exists in your company. Names
+     * stay reserved after a destination is deleted, because its delivery history
+     * is keyed on them.
+     */
+    409: WebhookErrorBody;
+    /**
+     * 422 — the request body was rejected. `violations[].propertyPath` names the
+     * offending field: one of `name`, `url`, `eventTypes`, `authScheme` or
+     * `siteFilter`.
+     */
+    422: WebhookErrorBody;
+};
+export type WebhookDestinationsCreateDestinationError = WebhookDestinationsCreateDestinationErrors[keyof WebhookDestinationsCreateDestinationErrors];
+export type WebhookDestinationsCreateDestinationResponses = {
+    /**
+     * The request has succeeded and a new resource has been created as a result.
+     */
+    201: WebhookDestination;
+};
+export type WebhookDestinationsCreateDestinationResponse = WebhookDestinationsCreateDestinationResponses[keyof WebhookDestinationsCreateDestinationResponses];
+export type WebhookDestinationsDeleteDestinationData = {
+    body?: never;
+    path: {
+        name: string;
+    };
+    query?: never;
+    url: '/v1/webhooks/destinations/{name}';
+};
+export type WebhookDestinationsDeleteDestinationErrors = {
+    /**
+     * 404 — no such destination. A destination belonging to another company, and a
+     * destination that has been deleted, are both reported as not found: a 403
+     * would confirm that the name exists.
+     */
+    404: WebhookErrorBody;
+};
+export type WebhookDestinationsDeleteDestinationError = WebhookDestinationsDeleteDestinationErrors[keyof WebhookDestinationsDeleteDestinationErrors];
+export type WebhookDestinationsDeleteDestinationResponses = {
+    /**
+     * There is no content to send for this request, but the headers may be useful.
+     */
+    204: void;
+};
+export type WebhookDestinationsDeleteDestinationResponse = WebhookDestinationsDeleteDestinationResponses[keyof WebhookDestinationsDeleteDestinationResponses];
+export type WebhookDestinationsGetDestinationData = {
+    body?: never;
+    path: {
+        name: string;
+    };
+    query?: never;
+    url: '/v1/webhooks/destinations/{name}';
+};
+export type WebhookDestinationsGetDestinationErrors = {
+    /**
+     * 404 — no such destination. A destination belonging to another company, and a
+     * destination that has been deleted, are both reported as not found: a 403
+     * would confirm that the name exists.
+     */
+    404: WebhookErrorBody;
+};
+export type WebhookDestinationsGetDestinationError = WebhookDestinationsGetDestinationErrors[keyof WebhookDestinationsGetDestinationErrors];
+export type WebhookDestinationsGetDestinationResponses = {
+    /**
+     * The request has succeeded.
+     */
+    200: WebhookDestination;
+};
+export type WebhookDestinationsGetDestinationResponse = WebhookDestinationsGetDestinationResponses[keyof WebhookDestinationsGetDestinationResponses];
+export type WebhookDestinationsUpdateDestinationData = {
+    body: WebhookDestinationInput;
+    path: {
+        name: string;
+    };
+    query?: never;
+    url: '/v1/webhooks/destinations/{name}';
+};
+export type WebhookDestinationsUpdateDestinationErrors = {
+    /**
+     * 403 — your credential holds the endpoint scope but not the data scope one of
+     * the subscribed event types requires. The message names both the event type
+     * and the missing scope, and `propertyPath` is `eventTypes`. The subscription
+     * is never silently trimmed to the permitted subset.
+     */
+    403: WebhookErrorBody;
+    /**
+     * 404 — no such destination. A destination belonging to another company, and a
+     * destination that has been deleted, are both reported as not found: a 403
+     * would confirm that the name exists.
+     */
+    404: WebhookErrorBody;
+    /**
+     * 409 — a destination with that name already exists in your company. Names
+     * stay reserved after a destination is deleted, because its delivery history
+     * is keyed on them.
+     */
+    409: WebhookErrorBody;
+    /**
+     * 422 — the request body was rejected. `violations[].propertyPath` names the
+     * offending field: one of `name`, `url`, `eventTypes`, `authScheme` or
+     * `siteFilter`.
+     */
+    422: WebhookErrorBody;
+};
+export type WebhookDestinationsUpdateDestinationError = WebhookDestinationsUpdateDestinationErrors[keyof WebhookDestinationsUpdateDestinationErrors];
+export type WebhookDestinationsUpdateDestinationResponses = {
+    /**
+     * The request has succeeded.
+     */
+    200: WebhookDestination;
+};
+export type WebhookDestinationsUpdateDestinationResponse = WebhookDestinationsUpdateDestinationResponses[keyof WebhookDestinationsUpdateDestinationResponses];
+export type WebhookDestinationsGetDestinationHealthData = {
+    body?: never;
+    path: {
+        name: string;
+    };
+    query?: never;
+    url: '/v1/webhooks/destinations/{name}/health';
+};
+export type WebhookDestinationsGetDestinationHealthErrors = {
+    /**
+     * 404 — no such destination. A destination belonging to another company, and a
+     * destination that has been deleted, are both reported as not found: a 403
+     * would confirm that the name exists.
+     */
+    404: WebhookErrorBody;
+};
+export type WebhookDestinationsGetDestinationHealthError = WebhookDestinationsGetDestinationHealthErrors[keyof WebhookDestinationsGetDestinationHealthErrors];
+export type WebhookDestinationsGetDestinationHealthResponses = {
+    /**
+     * The request has succeeded.
+     */
+    200: WebhookDestinationHealthResponse;
+};
+export type WebhookDestinationsGetDestinationHealthResponse = WebhookDestinationsGetDestinationHealthResponses[keyof WebhookDestinationsGetDestinationHealthResponses];
+export type WebhookDestinationsRotateSigningKeyData = {
+    body?: never;
+    path: {
+        name: string;
+    };
+    query?: never;
+    url: '/v1/webhooks/destinations/{name}/signing-key';
+};
+export type WebhookDestinationsRotateSigningKeyErrors = {
+    /**
+     * 404 — no such destination. A destination belonging to another company, and a
+     * destination that has been deleted, are both reported as not found: a 403
+     * would confirm that the name exists.
+     */
+    404: WebhookErrorBody;
+    /**
+     * 409 — a destination with that name already exists in your company. Names
+     * stay reserved after a destination is deleted, because its delivery history
+     * is keyed on them.
+     */
+    409: WebhookErrorBody;
+};
+export type WebhookDestinationsRotateSigningKeyError = WebhookDestinationsRotateSigningKeyErrors[keyof WebhookDestinationsRotateSigningKeyErrors];
+export type WebhookDestinationsRotateSigningKeyResponses = {
+    /**
+     * The request has succeeded.
+     */
+    200: WebhookSigningKeyResponse;
+};
+export type WebhookDestinationsRotateSigningKeyResponse = WebhookDestinationsRotateSigningKeyResponses[keyof WebhookDestinationsRotateSigningKeyResponses];
+export type WebhookDestinationsTestDestinationData = {
+    body?: never;
+    path: {
+        name: string;
+    };
+    query?: never;
+    url: '/v1/webhooks/destinations/{name}/test';
+};
+export type WebhookDestinationsTestDestinationErrors = {
+    /**
+     * 404 — no such destination. A destination belonging to another company, and a
+     * destination that has been deleted, are both reported as not found: a 403
+     * would confirm that the name exists.
+     */
+    404: WebhookErrorBody;
+    /**
+     * 409 — a destination with that name already exists in your company. Names
+     * stay reserved after a destination is deleted, because its delivery history
+     * is keyed on them.
+     */
+    409: WebhookErrorBody;
+    /**
+     * 429 — too many test dispatches for this destination. Retry after the number
+     * of seconds given in the `Retry-After` response header.
+     */
+    429: WebhookErrorBody;
+};
+export type WebhookDestinationsTestDestinationError = WebhookDestinationsTestDestinationErrors[keyof WebhookDestinationsTestDestinationErrors];
+export type WebhookDestinationsTestDestinationResponses = {
+    /**
+     * 202 — the test dispatch has been accepted for delivery. The body is the
+     * delivery engine's acknowledgement.
+     */
+    202: {
+        [key: string]: unknown;
+    };
+};
+export type WebhookDestinationsTestDestinationResponse = WebhookDestinationsTestDestinationResponses[keyof WebhookDestinationsTestDestinationResponses];
 export type CustomerDeleteData = {
     body?: never;
     path: {