@peable.to/contracts 0.4.0 → 1.1.0

package/dist/esm/resources/events/events.js

@@ -0,0 +1,353 @@
+import { z } from 'zod';
+import { listOf } from '../../common/envelopes.js';
+import { defineComponent, defineObject, resolveObject } from '../../common/objects.js';
+import { idParam, listQuery, queryBoolean, retrieveQuery } from '../../common/params.js';
+import { livemode, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { WEBHOOK_EVENT_OBJECTS, WEBHOOK_EVENT_TYPES, } from '../../vocabulary/events.js';
+/**
+ * Events (`evt_…`, ADR 0014 D4) — Stripe's event names (ADR 0019) with the
+ * resource nested under `data.object`. Stored once, in the transaction of the
+ * change it records, kept 30 days (`/v1/events`), and delivered HMAC-signed to
+ * every matching webhook endpoint: a delivery's body and `GET /v1/events/:id`
+ * are byte for byte the same object.
+ */
+/**
+ * The payload of `billing.observation.updated`: a wake-up, never paid or grant
+ * authority. Re-read the owner-bound resource it names.
+ */
+export const billingObservationSchema = defineObject('billing_observation', 'BillingObservation', z
+    .object({
+    object: z.literal('billing_observation'),
+    livemode: livemode.describe('The mode of the billing cohort observed (ADR 0017).'),
+    resource_kind: z.enum(['subscription', 'invoice']),
+    resource_id: z.string().describe('The provider subscription or invoice observed.'),
+    subscription_id: z
+        .string()
+        .optional()
+        .describe('Owner-scoped wake-up hint only; re-read the subscription before resolving a payer.'),
+    revision: z.number().int().describe('The observation revision; later revisions are newer.'),
+    observed_at: unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            object: 'billing_observation',
+            livemode: false,
+            resource_kind: 'subscription',
+            resource_id: 'sub_1Q2w3E4r5T6y7U8i',
+            subscription_id: 'sub_1Q2w3E4r5T6y7U8i',
+            revision: 3,
+            observed_at: 1793750400,
+        },
+    ],
+});
+/**
+ * What caused an event, when an API request did (Stripe's `event.request`).
+ * Both `null` for an event caused by something else — the chain watcher, the
+ * expiry sweeper, a provider's own notification.
+ */
+export const eventRequestSchema = defineComponent('EventRequest', z
+    .object({
+    id: z
+        .string()
+        .nullable()
+        .describe('The `Request-Id` of the request whose change produced the event.'),
+    idempotency_key: z
+        .string()
+        .nullable()
+        .describe('The `Idempotency-Key` that request carried, if any.'),
+})
+    .strict());
+const previousAttributes = z
+    .record(z.string(), z.unknown())
+    .optional()
+    .describe('The fields of `object` that this change moved, with their values BEFORE it. Absent when the event is not a change of an existing object.');
+/**
+ * The fields of the envelope that do not depend on its type, in the wire's
+ * order around `type` and `data` (`lib/serialize.ts` `toEventDTO`).
+ */
+const head = {
+    id: z.string().describe('`evt_…`.'),
+    object: z.literal('event'),
+};
+const tail = {
+    created: unixSeconds,
+    livemode: livemode.describe('The mode of the merchant it was sent to, and of the object it carries (ADR 0017).'),
+    api_version: z
+        .string()
+        .describe('The wire version the event was rendered with — the `Peable-Version` of the deployment that stored it. An event is a stored snapshot; it is not re-rendered when the wire moves on.'),
+    account: z
+        .string()
+        .optional()
+        .describe('The connected account (`ca_…`) this event is about (ADR 0012 D7). Present on every event for an on-behalf payment and on `connected_account.updated`; absent otherwise.'),
+};
+/** The envelope around `type` and `data.object`. */
+function envelope(type, object) {
+    return z
+        .object({
+        ...head,
+        type,
+        ...tail,
+        data: z.object({ object, previous_attributes: previousAttributes }).strict(),
+        request: eventRequestSchema,
+    })
+        .strict();
+}
+/** The schema of the object an event of `type` carries, once its module registered it. */
+const objectOf = (type) => z.lazy(() => resolveObject(WEBHOOK_EVENT_OBJECTS[type]));
+/** Every object type an event can carry, each once. */
+const EVENT_OBJECT_TYPES = [...new Set(Object.values(WEBHOOK_EVENT_OBJECTS))];
+/**
+ * An event of any type. `data.object` is the resource `type` names
+ * (`WEBHOOK_EVENT_OBJECTS`), checked against THAT object's schema — a
+ * `payment_intent.succeeded` carrying a Customer is refused even though a
+ * Customer is a valid event object.
+ */
+export const eventSchema = defineObject('event', 'Event', envelope(z.enum(WEBHOOK_EVENT_TYPES), z
+    .union(EVENT_OBJECT_TYPES.map((type) => z.lazy(() => resolveObject(type))))
+    .describe('The resource the event is about, as the API rendered it at the time.')).superRefine((event, ctx) => {
+    const expected = WEBHOOK_EVENT_OBJECTS[event.type];
+    const parsed = resolveObject(expected).safeParse(event.data.object);
+    if (parsed.success)
+        return;
+    for (const issue of parsed.error.issues) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['data', 'object', ...issue.path],
+            message: `a ${event.type} event carries a ${expected}: ${issue.message}`,
+        });
+    }
+}), {
+    examples: [
+        {
+            id: 'evt_0193b8f2c1a87d3e9f4b',
+            object: 'event',
+            type: 'webhook_endpoint.test',
+            created: 1793750400,
+            livemode: false,
+            api_version: '2026-11-03',
+            data: {
+                object: {
+                    id: 'we_0193b8f2c1a87d3e9f4c',
+                    object: 'webhook_endpoint',
+                    livemode: false,
+                    url: 'https://example.com/peable/webhooks',
+                    description: null,
+                    enabled_events: ['*'],
+                    status: 'enabled',
+                    disabled_reason: null,
+                    api_version: '2026-11-03',
+                    metadata: {},
+                    created: 1793750000,
+                    updated_at: 1793750000,
+                },
+            },
+            request: { id: 'req_0193b8f2c1a87d3e9f4d', idempotency_key: null },
+        },
+    ],
+});
+/**
+ * The envelope of one event type, `data.object` narrowed to its object: the
+ * request body of that type's webhook in the OpenAPI document.
+ */
+export function eventSchemaOf(type) {
+    return envelope(z.literal(type), objectOf(type));
+}
+/**
+ * `type=payment_intent.settled` (exact) or `type=payment_intent.*` (a dotted
+ * prefix). `*` alone is no filter. Lowercase dotted names only, so the value is
+ * never a LIKE pattern of the caller's choosing.
+ */
+const TYPE_FILTER_PATTERN = /^(\*|[a-z_]+(\.[a-z_]+)*(\.\*)?)$/;
+function toTypeFilter(value) {
+    if (value === '*')
+        return undefined;
+    if (value.endsWith('.*'))
+        return { kind: 'prefix', prefix: value.slice(0, -1) };
+    return { kind: 'exact', type: value };
+}
+const typeFilter = z
+    .string()
+    .max(100)
+    .regex(TYPE_FILTER_PATTERN, 'type is an event type, or a prefix ending in .* (payment_intent.*)')
+    .transform(toTypeFilter);
+/** The filters `GET /v1/events` adds to the list parameters. */
+export const listEventsFilters = {
+    type: typeFilter
+        .optional()
+        .describe('An exact event type, or a prefix ending in `.*` (`payment_intent.*`).'),
+    delivery_success: queryBoolean
+        .optional()
+        .describe('`true`: only events every delivery of which succeeded. `false`: only events with a delivery still pending or failed.'),
+    payment_intent: idParam
+        .optional()
+        .describe('`pi_…`: only the events about that payment — the timeline of one payment.'),
+};
+export const listEventsQuery = listQuery(listEventsFilters);
+export const retrieveEventQuery = retrieveQuery({});
+/**
+ * The stream's `types`: a comma-separated list of the same filters
+ * (`payment_intent.settled,connected_account.*`). Absent, or any `*`, is every
+ * event.
+ */
+export const streamEventsQuery = z
+    .object({
+    types: z
+        .string()
+        .max(2000)
+        .transform((value) => value.split(',').map((part) => part.trim()))
+        .pipe(z
+        .array(z
+        .string()
+        .max(100)
+        .regex(TYPE_FILTER_PATTERN, 'types is a comma-separated list of event types, or prefixes ending in .*')
+        .transform(toTypeFilter))
+        .min(1)
+        .max(32))
+        .optional()
+        .describe('Comma-separated event types or `prefix.*` patterns (`payment_intent.succeeded,charge.*`). Absent: every event.'),
+})
+    .strict();
+/** One line per event type: what happened when it is sent. Total, like the vocabulary. */
+export const WEBHOOK_EVENT_DESCRIPTIONS = {
+    'payment_intent.created': 'A PaymentIntent was created.',
+    'payment_intent.requires_action': 'A PaymentIntent needs the payer to act (pay, authenticate).',
+    'payment_intent.processing': 'A PaymentIntent is processing: a FairCoin payment was broadcast, or a card payment is pending.',
+    'payment_intent.amount_capturable_updated': 'A PaymentIntent was authorized and awaits capture (`capture_method: manual`).',
+    'payment_intent.succeeded': 'A PaymentIntent succeeded: the payment is final.',
+    'payment_intent.payment_failed': 'A payment attempt failed; a card PaymentIntent returns to `requires_payment_method`.',
+    'payment_intent.canceled': 'A PaymentIntent was canceled — by the merchant, by expiry, or underpaid.',
+    'charge.refunded': 'A Charge was refunded, partially or fully: `amount_refunded` moved.',
+    'charge.dispute.created': 'A cardholder disputed a charge. Evidence is due by its deadline.',
+    'charge.dispute.updated': 'A Dispute changed: evidence was staged or submitted.',
+    'charge.dispute.closed': 'A Dispute closed; `status` carries the outcome.',
+    'charge.dispute.funds_withdrawn': 'The network took the disputed amount from the balance.',
+    'charge.dispute.funds_reinstated': 'The network returned the disputed amount (the dispute was won, or withdrawn).',
+    'refund.created': 'A Refund was created.',
+    'refund.updated': 'A Refund changed state.',
+    'refund.failed': 'A Refund failed: the bank rejected it.',
+    'customer.created': 'A Customer was created.',
+    'customer.updated': 'A Customer was updated; `previous_attributes` names what moved.',
+    'customer.deleted': 'A Customer was deleted.',
+    'payment_method.attached': 'A PaymentMethod was attached to a Customer.',
+    'payment_method.detached': 'A PaymentMethod was detached from its Customer.',
+    'payment_method.updated': 'A PaymentMethod was updated.',
+    'setup_intent.created': 'A SetupIntent was created.',
+    'setup_intent.requires_action': 'A SetupIntent needs the customer to authenticate.',
+    'setup_intent.succeeded': 'A SetupIntent succeeded: its PaymentMethod is saved.',
+    'setup_intent.setup_failed': 'A SetupIntent attempt failed.',
+    'setup_intent.canceled': 'A SetupIntent was canceled.',
+    'billing.observation.updated': 'A recurring billing resource was observed to change. A wake-up only: re-read the resource.',
+    'connected_account.updated': "A seller's connected account changed — its readiness, in practice.",
+    'product.created': 'A Product was created.',
+    'product.updated': 'A Product was updated; `previous_attributes` names what moved.',
+    'product.deleted': 'A Product was deleted (it carries the product as it stood before).',
+    'price.created': 'A Price was created.',
+    'price.updated': 'A Price was updated (archiving one is `active: false`).',
+    'coupon.created': 'A Coupon was created.',
+    'coupon.updated': 'A Coupon was updated.',
+    'coupon.deleted': 'A Coupon was deleted.',
+    'promotion_code.created': 'A PromotionCode was created.',
+    'promotion_code.updated': 'A PromotionCode was updated (archiving one is `active: false`).',
+    'account.updated': "The merchant's own account changed: readiness, requirements or settings.",
+    'application_fee.created': "Orbit's fee was taken on a succeeded charge.",
+    'application_fee.refunded': 'Part or all of an application fee went back.',
+    'payout.created': 'A Payout was created.',
+    'payout.updated': 'A Payout changed.',
+    'payout.paid': 'A Payout arrived in the bank account.',
+    'payout.failed': 'A Payout failed.',
+    'payout.canceled': 'A Payout was canceled.',
+    'balance.available': 'Funds became available in the balance.',
+    'checkout.session.completed': 'The payer finished a Checkout Session (paid, authorized, or a FairCoin payment confirming).',
+    'checkout.session.expired': 'A Checkout Session expired, or the merchant expired it.',
+    'checkout.session.async_payment_succeeded': "A completed Checkout Session's FairCoin payment confirmed.",
+    'checkout.session.async_payment_failed': "A completed Checkout Session's FairCoin payment failed.",
+    'payment_link.created': 'A PaymentLink was created.',
+    'payment_link.updated': 'A PaymentLink was updated.',
+    'reporting.report_run.succeeded': 'A ReportRun finished: its CSV is `result`.',
+    'reporting.report_run.failed': 'A ReportRun could not be produced; `error` says why.',
+    'customer.subscription.created': 'A Subscription was created.',
+    'customer.subscription.updated': 'A Subscription changed; `previous_attributes` names what moved.',
+    'customer.subscription.deleted': 'A Subscription ended.',
+    'customer.subscription.trial_will_end': "A Subscription's trial ends in three days.",
+    'customer.subscription.paused': 'A Subscription was paused (a trial ended with no payment method).',
+    'customer.subscription.resumed': 'A paused Subscription resumed.',
+    'invoice.created': 'An Invoice was created.',
+    'invoice.updated': 'An Invoice changed.',
+    'invoice.deleted': 'A draft Invoice was deleted.',
+    'invoice.finalized': 'An Invoice was finalized.',
+    'invoice.paid': 'An Invoice was paid.',
+    'invoice.payment_failed': 'An attempt to pay an Invoice failed.',
+    'invoice.payment_action_required': 'Paying an Invoice needs the customer to act.',
+    'invoice.voided': 'An Invoice was voided.',
+    'invoice.marked_uncollectible': 'An Invoice was marked uncollectible.',
+    'invoice.upcoming': 'A renewal is days away; it carries a preview Invoice (`id` empty).',
+    'invoice.sent': 'An Invoice was emailed to the customer.',
+    'invoiceitem.created': 'An InvoiceItem was created.',
+    'invoiceitem.deleted': 'An InvoiceItem was deleted.',
+    'credit_note.created': 'A CreditNote was issued.',
+    'credit_note.updated': 'A CreditNote was updated.',
+    'credit_note.voided': 'A CreditNote was voided.',
+    'test_helpers.test_clock.created': 'A test clock was created.',
+    'test_helpers.test_clock.advancing': 'A test clock started advancing.',
+    'test_helpers.test_clock.ready': 'A test clock finished advancing.',
+    'test_helpers.test_clock.deleted': 'A test clock was deleted.',
+    'billing.meter.created': 'A billing Meter was created.',
+    'billing.meter.updated': 'A billing Meter was updated.',
+    'billing.meter.deactivated': 'A billing Meter was deactivated.',
+    'billing.meter.reactivated': 'A billing Meter was reactivated.',
+    'entitlements.active_entitlement_summary.updated': "A customer's active entitlements changed — re-read them, then grant or withdraw access.",
+    'billing_portal.configuration.created': 'A customer portal configuration was created.',
+    'billing_portal.configuration.updated': 'A customer portal configuration was updated.',
+    'billing_portal.session.created': 'A customer portal session was created.',
+    'tax.assessment.created': 'A tax compliance assessment was run. Nothing was registered, filed or collected.',
+    'tax.review_item.created': 'A tax assessment finding opened a review item.',
+    'tax.review_item.updated': 'A tax review item was decided, or found again.',
+    'webhook_endpoint.test': 'A test event, sent to ONE endpoint when its owner asks. It cannot be subscribed to.',
+};
+export const eventRoutes = [
+    defineRoute({
+        operationId: 'listEvents',
+        method: 'get',
+        path: '/v1/events',
+        tag: 'Events',
+        summary: 'List events',
+        description: 'Every event of the last 30 days, newest first, rendered exactly as its webhook deliveries carried it.',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listEventsQuery,
+        response: listOf(eventSchema),
+        sdk: 'events.list',
+        expandable: 'event',
+    }),
+    defineRoute({
+        operationId: 'streamEvents',
+        method: 'get',
+        path: '/v1/events/stream',
+        tag: 'Events',
+        summary: 'Stream events',
+        description: 'Server-Sent Events: every event of this merchant as it commits, rendered exactly as a webhook delivery carries it (`event: event`, `id:` the `evt_…`). Resumes after `Last-Event-ID`. Test mode only — what `peable listen` forwards to a local server.',
+        auth: 'service',
+        scope: 'payments:read',
+        testModeOnly: true,
+        query: streamEventsQuery,
+        response: { kind: 'stream', event: eventSchema },
+        sdk: 'events.stream',
+    }),
+    defineRoute({
+        operationId: 'retrieveEvent',
+        method: 'get',
+        path: '/v1/events/{id}',
+        tag: 'Events',
+        summary: 'Retrieve an event',
+        description: 'A `404` once the event is older than 30 days.',
+        auth: 'service',
+        scope: 'payments:read',
+        params: { id: 'The event (`evt_…`).' },
+        query: retrieveEventQuery,
+        response: eventSchema,
+        sdk: 'events.retrieve',
+        expandable: 'event',
+    }),
+];

package/dist/esm/resources/events/index.js

@@ -0,0 +1,12 @@
+import { eventRoutes } from './events.js';
+import { webhookDeliveryRoutes } from './webhookDeliveries.js';
+import { webhookEndpointRoutes } from './webhookEndpoints.js';
+export * from './events.js';
+export * from './webhookDeliveries.js';
+export * from './webhookEndpoints.js';
+/** Events, the webhook endpoints they are sent to, and the deliveries of them. */
+export const eventsRoutes = [
+    ...eventRoutes,
+    ...webhookEndpointRoutes,
+    ...webhookDeliveryRoutes,
+];

package/dist/esm/resources/events/webhookDeliveries.js

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+import { listOf } from '../../common/envelopes.js';
+import { defineObject } from '../../common/objects.js';
+import { idParam, listQuery } from '../../common/params.js';
+import { livemode, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { WEBHOOK_DELIVERY_STATUSES, WEBHOOK_EVENT_TYPES } from '../../vocabulary/events.js';
+/**
+ * Webhook deliveries (ADR 0014 D4) — one event sent to one webhook endpoint.
+ * An event that matches three endpoints is three deliveries, each with its own
+ * attempts, retried for about three days (ADR 0001 D7).
+ */
+export const webhookDeliverySchema = defineObject('webhook_delivery', 'WebhookDelivery', z
+    .object({
+    id: z.string(),
+    object: z.literal('webhook_delivery'),
+    livemode: livemode.describe('The mode of the merchant it was sent for (ADR 0017).'),
+    event_id: z.string().describe('The `evt_…` delivered — `GET /v1/events/:id` returns it.'),
+    event_type: z.enum(WEBHOOK_EVENT_TYPES),
+    webhook_endpoint_id: z.string().describe('The `we_…` it was sent to.'),
+    url: z.string().describe('The URL actually POSTed to, as of the latest attempt.'),
+    attempts: z.number().int().nonnegative(),
+    delivered: z.boolean(),
+    last_status: z
+        .enum(WEBHOOK_DELIVERY_STATUSES)
+        .describe('`pending`: will be attempted (`next_attempt_at`). `delivered`: terminal success. `failed`: the endpoint refused it (a 4xx, a blocked address) or was disabled first — never retried. `dead`: every attempt failed transiently for three days; it can be redelivered.'),
+    last_error: z
+        .string()
+        .optional()
+        .describe('Why the last attempt did not succeed — operator-facing, never a secret.'),
+    next_attempt_at: unixSeconds
+        .optional()
+        .describe('When the next attempt is due. Absent once the delivery is terminal.'),
+    created: unixSeconds,
+    updated_at: unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            id: '0193b8f2-c1a8-7d3e-9f4a-7d3e0193b8f2',
+            object: 'webhook_delivery',
+            livemode: false,
+            event_id: 'evt_0193b8f2c1a87d3e9f4b',
+            event_type: 'payment_intent.succeeded',
+            webhook_endpoint_id: 'we_0193b8f2c1a87d3e9f4c',
+            url: 'https://example.com/peable/webhooks',
+            attempts: 1,
+            delivered: true,
+            last_status: 'delivered',
+            created: 1793750400,
+            updated_at: 1793750401,
+        },
+    ],
+});
+/** The filters `GET /v1/webhook_deliveries` adds to the list parameters. */
+export const listWebhookDeliveriesFilters = {
+    event: idParam.optional().describe('Only the deliveries of this event (`evt_…`).'),
+    webhook_endpoint: idParam.optional().describe('Only the deliveries to this endpoint (`we_…`).'),
+};
+export const listWebhookDeliveriesQuery = listQuery(listWebhookDeliveriesFilters);
+export const webhookDeliveryRoutes = [
+    defineRoute({
+        operationId: 'listWebhookDeliveries',
+        method: 'get',
+        path: '/v1/webhook_deliveries',
+        tag: 'Webhook deliveries',
+        summary: 'List webhook deliveries',
+        description: "The delivery log, newest first: one event's deliveries, or one endpoint's. Both filters are public ids resolved inside your scope.",
+        auth: 'service',
+        scope: 'payments:read',
+        query: listWebhookDeliveriesQuery,
+        response: listOf(webhookDeliverySchema),
+        sdk: 'webhookDeliveries.list',
+        expandable: 'webhook_delivery',
+    }),
+    defineRoute({
+        operationId: 'redeliverWebhookDelivery',
+        method: 'post',
+        path: '/v1/webhook_deliveries/{id}/redeliver',
+        tag: 'Webhook deliveries',
+        summary: 'Redeliver a webhook delivery',
+        description: "Send the delivery's event to its endpoint again — the SAME stored event, as a NEW delivery, attempted at once; answers that new delivery. Refused while the endpoint is disabled (`webhook_endpoint_disabled`).",
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: { id: 'The webhook delivery.' },
+        response: webhookDeliverySchema,
+        sdk: 'webhookDeliveries.redeliver',
+    }),
+];

package/dist/esm/resources/events/webhookEndpoints.js

@@ -0,0 +1,212 @@
+import { z } from 'zod';
+import { deletedOf, listOf } from '../../common/envelopes.js';
+import { defineComponent, defineObject } from '../../common/objects.js';
+import { expandOnlyQuery, listQuery, metadataCreateParam, metadataUpdateParam, } from '../../common/params.js';
+import { livemode, metadata, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { WEBHOOK_ENABLED_EVENTS, WEBHOOK_ENDPOINT_DESCRIPTION_MAX, WEBHOOK_ENDPOINT_DISABLED_REASONS, WEBHOOK_ENDPOINT_STATUSES, WEBHOOK_SECRET_ROLL_MAX_EXPIRES_IN_SECONDS, } from '../../vocabulary/events.js';
+import { webhookDeliverySchema } from './webhookDeliveries.js';
+/**
+ * Webhook endpoints (`we_…`, ADR 0014 D4) — one URL a merchant receives events
+ * at, with the event types it wants and the secret deliveries to it are signed
+ * with. A merchant may hold several; every event fans out to each ENABLED
+ * endpoint whose `enabled_events` matches it, as one delivery per endpoint.
+ */
+const enabledEvent = z.enum(WEBHOOK_ENABLED_EVENTS);
+const endpointShape = {
+    id: z.string(),
+    object: z.literal('webhook_endpoint'),
+    livemode: livemode.describe('The mode of the merchant that owns it (ADR 0017).'),
+    url: z.string(),
+    description: z.string().nullable(),
+    enabled_events: z
+        .array(enabledEvent)
+        .describe('The event types sent to it; `*` is every type, including ones added later.'),
+    status: z.enum(WEBHOOK_ENDPOINT_STATUSES),
+    disabled_reason: z
+        .enum(WEBHOOK_ENDPOINT_DISABLED_REASONS)
+        .nullable()
+        .describe('`null` exactly when `status` is `enabled`. `delivery_failures`: every delivery failed for three days straight.'),
+    api_version: z.string().describe('The wire version events are rendered with for this endpoint.'),
+    metadata,
+    created: unixSeconds,
+    updated_at: unixSeconds,
+};
+const endpointExample = {
+    id: 'we_0193b8f2c1a87d3e9f4c',
+    object: 'webhook_endpoint',
+    livemode: false,
+    url: 'https://example.com/peable/webhooks',
+    description: 'Order fulfilment',
+    enabled_events: ['payment_intent.succeeded', 'charge.refunded'],
+    status: 'enabled',
+    disabled_reason: null,
+    api_version: '2026-11-03',
+    metadata: {},
+    created: 1793750000,
+    updated_at: 1793750000,
+};
+/** An endpoint as every answer but a create and a roll renders it: never the secret. */
+export const webhookEndpointSchema = defineObject('webhook_endpoint', 'WebhookEndpoint', z.object(endpointShape).strict(), { examples: [endpointExample] });
+/**
+ * The answer of a create and of a `roll_secret` — the ONLY two that show the
+ * signing secret. Peable never shows it again; a lost secret is rolled, not
+ * retrieved.
+ */
+export const webhookEndpointWithSecretSchema = defineComponent('WebhookEndpointWithSecret', z
+    .object({
+    ...endpointShape,
+    secret: z
+        .string()
+        .regex(/^whsec_/)
+        .describe('The signing secret (`whsec_…`), shown on this answer only.'),
+})
+    .strict(), { examples: [{ ...endpointExample, secret: 'whsec_9f4a7d3e0193b8f2c1a87d3e9f4a7d3e' }] });
+/** What `DELETE /v1/webhook_endpoints/:id` answers. */
+export const deletedWebhookEndpointSchema = defineComponent('DeletedWebhookEndpoint', deletedOf('webhook_endpoint'));
+const enabledEventsParam = z
+    .array(enabledEvent)
+    .min(1, 'enabled_events needs at least one event type, or "*"')
+    .max(WEBHOOK_ENABLED_EVENTS.length)
+    // A repeated type means nothing more than one; stored once.
+    .transform((list) => [...new Set(list)]);
+const descriptionParam = z.string().max(WEBHOOK_ENDPOINT_DESCRIPTION_MAX);
+const urlParam = z
+    .string()
+    .min(1)
+    .describe('An `https` URL (a test-mode endpoint may also use `http`), ports 80/443 only.');
+export const createWebhookEndpointParams = z
+    .object({
+    url: urlParam,
+    enabled_events: enabledEventsParam,
+    description: descriptionParam.min(1).optional(),
+    metadata: metadataCreateParam.optional(),
+})
+    .strict();
+export const updateWebhookEndpointParams = z
+    .object({
+    url: urlParam.optional(),
+    enabled_events: enabledEventsParam.optional(),
+    disabled: z
+        .boolean()
+        .optional()
+        .describe('`true` stops deliveries; `false` re-enables an endpoint, whatever disabled it.'),
+    description: descriptionParam.optional().describe('`""` clears it.'),
+    metadata: metadataUpdateParam.optional(),
+})
+    .strict();
+export const rollWebhookEndpointSecretParams = z
+    .object({
+    expires_in_seconds: z
+        .number()
+        .int()
+        .min(0)
+        .max(WEBHOOK_SECRET_ROLL_MAX_EXPIRES_IN_SECONDS)
+        .optional()
+        .describe('How long the PREVIOUS secret keeps signing beside the new one, in seconds (0–86400, default 0). While both are live every delivery carries two `v1=` signatures, so a receiver can switch secrets without a gap.'),
+})
+    .strict();
+export const listWebhookEndpointsQuery = listQuery({});
+const idDoc = { id: 'The webhook endpoint (`we_…`).' };
+export const webhookEndpointRoutes = [
+    defineRoute({
+        operationId: 'createWebhookEndpoint',
+        method: 'post',
+        path: '/v1/webhook_endpoints',
+        tag: 'Webhook endpoints',
+        summary: 'Create a webhook endpoint',
+        description: 'The answer is the ONLY one that shows `secret`. A retry with the same `Idempotency-Key` replays it, secret included, for 24 hours. At most 16 endpoints per merchant and mode.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: createWebhookEndpointParams,
+        response: webhookEndpointWithSecretSchema,
+        sdk: 'webhookEndpoints.create',
+    }),
+    defineRoute({
+        operationId: 'listWebhookEndpoints',
+        method: 'get',
+        path: '/v1/webhook_endpoints',
+        tag: 'Webhook endpoints',
+        summary: 'List webhook endpoints',
+        description: 'Newest first. Never the secret.',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listWebhookEndpointsQuery,
+        response: listOf(webhookEndpointSchema),
+        sdk: 'webhookEndpoints.list',
+        expandable: 'webhook_endpoint',
+    }),
+    defineRoute({
+        operationId: 'retrieveWebhookEndpoint',
+        method: 'get',
+        path: '/v1/webhook_endpoints/{id}',
+        tag: 'Webhook endpoints',
+        summary: 'Retrieve a webhook endpoint',
+        description: 'Never the secret: a lost secret is rolled, not retrieved.',
+        auth: 'service',
+        scope: 'payments:read',
+        params: idDoc,
+        query: expandOnlyQuery,
+        response: webhookEndpointSchema,
+        sdk: 'webhookEndpoints.retrieve',
+        expandable: 'webhook_endpoint',
+    }),
+    defineRoute({
+        operationId: 'updateWebhookEndpoint',
+        method: 'post',
+        path: '/v1/webhook_endpoints/{id}',
+        tag: 'Webhook endpoints',
+        summary: 'Update a webhook endpoint',
+        description: '`url`, `enabled_events`, `disabled`, `description` (`""` clears it) and `metadata` (a patch).',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: idDoc,
+        body: updateWebhookEndpointParams,
+        response: webhookEndpointSchema,
+        sdk: 'webhookEndpoints.update',
+    }),
+    defineRoute({
+        operationId: 'deleteWebhookEndpoint',
+        method: 'delete',
+        path: '/v1/webhook_endpoints/{id}',
+        tag: 'Webhook endpoints',
+        summary: 'Delete a webhook endpoint',
+        description: 'Its deliveries go with it, pending ones included.',
+        auth: 'service',
+        scope: 'payments:write',
+        params: idDoc,
+        response: deletedWebhookEndpointSchema,
+        sdk: 'webhookEndpoints.del',
+    }),
+    defineRoute({
+        operationId: 'rollWebhookEndpointSecret',
+        method: 'post',
+        path: '/v1/webhook_endpoints/{id}/roll_secret',
+        tag: 'Webhook endpoints',
+        summary: 'Roll the signing secret',
+        description: 'Mint a new secret and show it once. With `expires_in_seconds` (≤ 24h) the previous one keeps signing beside it until then; without, it stops now.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: idDoc,
+        body: rollWebhookEndpointSecretParams,
+        response: webhookEndpointWithSecretSchema,
+        sdk: 'webhookEndpoints.rollSecret',
+    }),
+    defineRoute({
+        operationId: 'sendWebhookEndpointTestEvent',
+        method: 'post',
+        path: '/v1/webhook_endpoints/{id}/test',
+        tag: 'Webhook endpoints',
+        summary: 'Send a test event',
+        description: 'Send this endpoint a `webhook_endpoint.test` event now and answer the delivery after its first attempt. A disabled endpoint is refused (`webhook_endpoint_disabled`).',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: idDoc,
+        response: webhookDeliverySchema,
+        sdk: 'webhookEndpoints.sendTestEvent',
+    }),
+];