@xtandard/webhooks 0.1.0

package/dist/schema-mo__wv4P.d.cts

@@ -0,0 +1,233 @@
+//#region src/schema.d.ts
+/**
+ * Core type definitions for `@xtandard/webhooks`.
+ *
+ * This module is **types only** — no runtime code beyond tiny guards and the
+ * schema-version constant, no dependencies. It is safe to import from the
+ * publish hot path and the receiver. Runtime validation (which pulls in
+ * `valibot`) lives in {@link ./validation}.
+ *
+ * @module
+ */
+/** JSON-serializable value, used for payloads, metadata, and event-type schemas. */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+/**
+ * A duration for configuration options: either milliseconds as a number, or a
+ * human-friendly string such as `"5s"`, `"30m"`, `"2h"`, `"5d"`. Parsed by
+ * {@link ./duration.durationToMs}.
+ */
+type WebhookDuration = number | `${number}${"ms" | "s" | "m" | "h" | "d"}`;
+/** Identity captured on audit records and passed by callers of audited mutations. */
+interface Actor {
+  id: string;
+  email?: string;
+  name?: string;
+}
+/** Current schema version for stored records. */
+declare const SCHEMA_VERSION: 1;
+/**
+ * An application is the unit of tenancy — typically one of *your* customers.
+ * Endpoints, messages, and deliveries are all scoped to an application, and a
+ * portal token grants access to exactly one application.
+ */
+interface Application {
+  /** Unique key. Allowed characters: `a-z A-Z 0-9 . _ -`. */
+  key: string;
+  /** Optional human-friendly name shown in the UI. */
+  name?: string;
+  /** Arbitrary host-defined metadata. */
+  metadata?: JsonValue;
+  /** ISO-8601 creation timestamp, server-stamped. */
+  createdAt?: string;
+  /** ISO-8601 last-update timestamp, server-stamped. */
+  updatedAt?: string;
+}
+/**
+ * A named kind of event in the **global** catalog (shared by all applications),
+ * e.g. `"invoice.paid"`. Endpoints subscribe to event types by name.
+ */
+interface EventType {
+  /** Unique dot-delimited name, e.g. `"invoice.paid"`. Allowed: `a-z A-Z 0-9 . _ -`. */
+  name: string;
+  /** Optional description shown in the UI and the public catalog. */
+  description?: string;
+  /** Optional UI grouping label (e.g. `"Billing"`). Purely presentational. */
+  groupName?: string;
+  /**
+   * Optional JSON Schema describing the payload. Documentation by default;
+   * enforced only when the core is configured with a `payloadValidator`.
+   */
+  schema?: JsonValue;
+  /** Deprecated event types are flagged in the UI but still deliverable. */
+  deprecated?: boolean;
+  /** ISO-8601 creation timestamp, server-stamped. */
+  createdAt?: string;
+  /** ISO-8601 last-update timestamp, server-stamped. */
+  updatedAt?: string;
+}
+/**
+ * A signing secret attached to an endpoint. Secrets are `whsec_` + base64 per
+ * the Standard Webhooks spec. Rotation keeps the previous secret verifiable
+ * until `expiresAt` (the grace window); expired secrets are pruned lazily.
+ */
+interface EndpointSecret {
+  /** `"whsec_"` + base64-encoded random key material. */
+  secret: string;
+  /** ISO-8601 creation timestamp. */
+  createdAt: string;
+  /** Set when superseded by rotation; the secret stops signing after this instant. */
+  expiresAt?: string;
+}
+/** Why an endpoint is disabled: by an operator, or by the auto-disable policy. */
+type EndpointDisabledReason = "manual" | "auto";
+/**
+ * A customer-registered URL that receives deliveries for one application.
+ */
+interface Endpoint {
+  /** `"ep_"` + 22-char base62, server-generated. */
+  id: string;
+  /** Destination URL. `https` is enforced by default (`allowInsecureUrls` for dev). */
+  url: string;
+  /** Optional description shown in the UI. */
+  description?: string;
+  /**
+   * Event type names this endpoint subscribes to. Empty or absent = receives
+   * **all** event types.
+   */
+  eventTypes?: string[];
+  /** Disabled endpoints receive no deliveries (pending ones are held, not failed). */
+  disabled?: boolean;
+  /** Who/what disabled it — an operator (`"manual"`) or the failure policy (`"auto"`). */
+  disabledReason?: EndpointDisabledReason;
+  /** Static extra headers merged into every delivery request. */
+  headers?: Record<string, string>;
+  /** Signing secrets. `[0]` is current; extras are still-verifiable rotation grace. */
+  secrets: EndpointSecret[];
+  /** Arbitrary host-defined metadata. */
+  metadata?: JsonValue;
+  /** ISO-8601 creation timestamp, server-stamped. */
+  createdAt?: string;
+  /** ISO-8601 last-update timestamp, server-stamped. */
+  updatedAt?: string;
+  /**
+   * Start of the current unbroken failure streak (any successful delivery
+   * clears it). Drives the auto-disable policy.
+   */
+  firstFailingAt?: string | null;
+}
+/**
+ * A published event for one application. The message is the receiver-facing
+ * unit: its id is the `webhook-id` header (stable across retries — receivers
+ * dedupe on it), and its payload is the `data` of the wire envelope.
+ */
+interface Message {
+  /** `"msg_"` + 22-char base62, server-generated. Sent as `webhook-id`. */
+  id: string;
+  /** Event type name (usually from the global catalog). */
+  eventType: string;
+  /** The `data` of the wire envelope. */
+  payload: JsonValue;
+  /** ISO-8601 event-occurred time (defaults to publish time). Sent in the envelope. */
+  timestamp: string;
+  /** Optional caller-supplied dedupe key; same key within retention returns the same message. */
+  idempotencyKey?: string;
+  /**
+   * The wire envelope serialized **once at publish time** so the signed bytes
+   * are identical across every retry of every delivery.
+   */
+  envelope: string;
+  /** ISO-8601 creation timestamp, server-stamped. */
+  createdAt: string;
+}
+/**
+ * Delivery lifecycle. `"failed"` means the retry schedule is exhausted — the
+ * dead-letter state. A manual retry moves a failed delivery back to `"pending"`.
+ */
+type DeliveryStatus = "pending" | "delivering" | "succeeded" | "failed";
+/** Guard: has this delivery reached a terminal state? */
+declare function isTerminalDeliveryStatus(status: DeliveryStatus): boolean;
+/**
+ * One message × one endpoint. Created at publish time (fan-out) and driven to
+ * a terminal state by the dispatcher.
+ */
+interface Delivery {
+  /** `"dlv_"` + 22-char base62, server-generated. */
+  id: string;
+  /** The application this delivery belongs to (deliveries cross the dispatcher denormalized). */
+  applicationKey: string;
+  messageId: string;
+  endpointId: string;
+  status: DeliveryStatus;
+  /** Number of attempts made so far. */
+  attemptCount: number;
+  /** When the next attempt is due. `null` once terminal. */
+  nextAttemptAt?: string | null;
+  /** Dispatcher claim expiry; an expired lease makes the delivery reclaimable. */
+  leaseUntil?: string | null;
+  /**
+   * How the *next* attempt should be recorded: set to `"manual"` by
+   * retry/recover so the resulting attempt is attributed correctly, then
+   * cleared. Absent = `"schedule"`.
+   */
+  pendingTrigger?: AttemptTrigger;
+  /** ISO-8601 creation timestamp. */
+  createdAt: string;
+  /** ISO-8601 last-transition timestamp. */
+  updatedAt: string;
+}
+/** What initiated a delivery attempt. */
+type AttemptTrigger = "schedule" | "manual" | "test";
+/** The recorded outcome of a single HTTP delivery attempt. */
+interface DeliveryAttempt {
+  /** `"atp_"` + 22-char base62, server-generated. */
+  id: string;
+  deliveryId: string;
+  /** 1-based attempt ordinal within the delivery. */
+  attemptNumber: number;
+  /** ISO-8601 timestamp of the attempt. */
+  at: string;
+  /** Wall-clock duration of the HTTP round trip. */
+  durationMs: number;
+  /** True when the receiver answered 2xx. */
+  ok: boolean;
+  /** HTTP status code; absent on network error or timeout. */
+  httpStatus?: number;
+  /** Truncated error message on network error/timeout. */
+  error?: string;
+  /** Truncated response body (default cap 4096 chars). */
+  responseBody?: string;
+  /** What initiated this attempt. */
+  trigger: AttemptTrigger;
+}
+/** Actions recorded in the control-plane audit log. */
+type AuditAction = "application.create" | "application.update" | "application.delete" | "event-type.create" | "event-type.update" | "event-type.delete" | "endpoint.create" | "endpoint.update" | "endpoint.delete" | "endpoint.rotate-secret" | "endpoint.disable" | "endpoint.enable" | "delivery.retry" | "endpoint.recover";
+/**
+ * A single control-plane audit record. Publishes are deliberately *not*
+ * audited — they are data-plane traffic, and the message log is their record.
+ */
+interface AuditEntry {
+  action: AuditAction;
+  /** ISO-8601 timestamp. */
+  at: string;
+  by?: Actor | null;
+  /** The application the action was scoped to (absent for global event types). */
+  applicationKey?: string;
+  /** Endpoint id / event type name / delivery id the action targeted. */
+  subjectId?: string;
+  message?: string;
+}
+/**
+ * The wire envelope receivers get — the Standard Webhooks recommended shape.
+ * `type` is the event type name, `timestamp` the event-occurred time, and
+ * `data` the published payload.
+ */
+interface WebhookEnvelope {
+  type: string;
+  timestamp: string;
+  data: JsonValue;
+}
+//#endregion
+export { WebhookEnvelope as _, AuditEntry as a, DeliveryStatus as c, EndpointSecret as d, EventType as f, WebhookDuration as g, SCHEMA_VERSION as h, AuditAction as i, Endpoint as l, Message as m, Application as n, Delivery as o, JsonValue as p, AttemptTrigger as r, DeliveryAttempt as s, Actor as t, EndpointDisabledReason as u, isTerminalDeliveryStatus as v };
+//# sourceMappingURL=schema-mo__wv4P.d.cts.map

package/dist/schema-mo__wv4P.d.mts

@@ -0,0 +1,233 @@
+//#region src/schema.d.ts
+/**
+ * Core type definitions for `@xtandard/webhooks`.
+ *
+ * This module is **types only** — no runtime code beyond tiny guards and the
+ * schema-version constant, no dependencies. It is safe to import from the
+ * publish hot path and the receiver. Runtime validation (which pulls in
+ * `valibot`) lives in {@link ./validation}.
+ *
+ * @module
+ */
+/** JSON-serializable value, used for payloads, metadata, and event-type schemas. */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+/**
+ * A duration for configuration options: either milliseconds as a number, or a
+ * human-friendly string such as `"5s"`, `"30m"`, `"2h"`, `"5d"`. Parsed by
+ * {@link ./duration.durationToMs}.
+ */
+type WebhookDuration = number | `${number}${"ms" | "s" | "m" | "h" | "d"}`;
+/** Identity captured on audit records and passed by callers of audited mutations. */
+interface Actor {
+  id: string;
+  email?: string;
+  name?: string;
+}
+/** Current schema version for stored records. */
+declare const SCHEMA_VERSION: 1;
+/**
+ * An application is the unit of tenancy — typically one of *your* customers.
+ * Endpoints, messages, and deliveries are all scoped to an application, and a
+ * portal token grants access to exactly one application.
+ */
+interface Application {
+  /** Unique key. Allowed characters: `a-z A-Z 0-9 . _ -`. */
+  key: string;
+  /** Optional human-friendly name shown in the UI. */
+  name?: string;
+  /** Arbitrary host-defined metadata. */
+  metadata?: JsonValue;
+  /** ISO-8601 creation timestamp, server-stamped. */
+  createdAt?: string;
+  /** ISO-8601 last-update timestamp, server-stamped. */
+  updatedAt?: string;
+}
+/**
+ * A named kind of event in the **global** catalog (shared by all applications),
+ * e.g. `"invoice.paid"`. Endpoints subscribe to event types by name.
+ */
+interface EventType {
+  /** Unique dot-delimited name, e.g. `"invoice.paid"`. Allowed: `a-z A-Z 0-9 . _ -`. */
+  name: string;
+  /** Optional description shown in the UI and the public catalog. */
+  description?: string;
+  /** Optional UI grouping label (e.g. `"Billing"`). Purely presentational. */
+  groupName?: string;
+  /**
+   * Optional JSON Schema describing the payload. Documentation by default;
+   * enforced only when the core is configured with a `payloadValidator`.
+   */
+  schema?: JsonValue;
+  /** Deprecated event types are flagged in the UI but still deliverable. */
+  deprecated?: boolean;
+  /** ISO-8601 creation timestamp, server-stamped. */
+  createdAt?: string;
+  /** ISO-8601 last-update timestamp, server-stamped. */
+  updatedAt?: string;
+}
+/**
+ * A signing secret attached to an endpoint. Secrets are `whsec_` + base64 per
+ * the Standard Webhooks spec. Rotation keeps the previous secret verifiable
+ * until `expiresAt` (the grace window); expired secrets are pruned lazily.
+ */
+interface EndpointSecret {
+  /** `"whsec_"` + base64-encoded random key material. */
+  secret: string;
+  /** ISO-8601 creation timestamp. */
+  createdAt: string;
+  /** Set when superseded by rotation; the secret stops signing after this instant. */
+  expiresAt?: string;
+}
+/** Why an endpoint is disabled: by an operator, or by the auto-disable policy. */
+type EndpointDisabledReason = "manual" | "auto";
+/**
+ * A customer-registered URL that receives deliveries for one application.
+ */
+interface Endpoint {
+  /** `"ep_"` + 22-char base62, server-generated. */
+  id: string;
+  /** Destination URL. `https` is enforced by default (`allowInsecureUrls` for dev). */
+  url: string;
+  /** Optional description shown in the UI. */
+  description?: string;
+  /**
+   * Event type names this endpoint subscribes to. Empty or absent = receives
+   * **all** event types.
+   */
+  eventTypes?: string[];
+  /** Disabled endpoints receive no deliveries (pending ones are held, not failed). */
+  disabled?: boolean;
+  /** Who/what disabled it — an operator (`"manual"`) or the failure policy (`"auto"`). */
+  disabledReason?: EndpointDisabledReason;
+  /** Static extra headers merged into every delivery request. */
+  headers?: Record<string, string>;
+  /** Signing secrets. `[0]` is current; extras are still-verifiable rotation grace. */
+  secrets: EndpointSecret[];
+  /** Arbitrary host-defined metadata. */
+  metadata?: JsonValue;
+  /** ISO-8601 creation timestamp, server-stamped. */
+  createdAt?: string;
+  /** ISO-8601 last-update timestamp, server-stamped. */
+  updatedAt?: string;
+  /**
+   * Start of the current unbroken failure streak (any successful delivery
+   * clears it). Drives the auto-disable policy.
+   */
+  firstFailingAt?: string | null;
+}
+/**
+ * A published event for one application. The message is the receiver-facing
+ * unit: its id is the `webhook-id` header (stable across retries — receivers
+ * dedupe on it), and its payload is the `data` of the wire envelope.
+ */
+interface Message {
+  /** `"msg_"` + 22-char base62, server-generated. Sent as `webhook-id`. */
+  id: string;
+  /** Event type name (usually from the global catalog). */
+  eventType: string;
+  /** The `data` of the wire envelope. */
+  payload: JsonValue;
+  /** ISO-8601 event-occurred time (defaults to publish time). Sent in the envelope. */
+  timestamp: string;
+  /** Optional caller-supplied dedupe key; same key within retention returns the same message. */
+  idempotencyKey?: string;
+  /**
+   * The wire envelope serialized **once at publish time** so the signed bytes
+   * are identical across every retry of every delivery.
+   */
+  envelope: string;
+  /** ISO-8601 creation timestamp, server-stamped. */
+  createdAt: string;
+}
+/**
+ * Delivery lifecycle. `"failed"` means the retry schedule is exhausted — the
+ * dead-letter state. A manual retry moves a failed delivery back to `"pending"`.
+ */
+type DeliveryStatus = "pending" | "delivering" | "succeeded" | "failed";
+/** Guard: has this delivery reached a terminal state? */
+declare function isTerminalDeliveryStatus(status: DeliveryStatus): boolean;
+/**
+ * One message × one endpoint. Created at publish time (fan-out) and driven to
+ * a terminal state by the dispatcher.
+ */
+interface Delivery {
+  /** `"dlv_"` + 22-char base62, server-generated. */
+  id: string;
+  /** The application this delivery belongs to (deliveries cross the dispatcher denormalized). */
+  applicationKey: string;
+  messageId: string;
+  endpointId: string;
+  status: DeliveryStatus;
+  /** Number of attempts made so far. */
+  attemptCount: number;
+  /** When the next attempt is due. `null` once terminal. */
+  nextAttemptAt?: string | null;
+  /** Dispatcher claim expiry; an expired lease makes the delivery reclaimable. */
+  leaseUntil?: string | null;
+  /**
+   * How the *next* attempt should be recorded: set to `"manual"` by
+   * retry/recover so the resulting attempt is attributed correctly, then
+   * cleared. Absent = `"schedule"`.
+   */
+  pendingTrigger?: AttemptTrigger;
+  /** ISO-8601 creation timestamp. */
+  createdAt: string;
+  /** ISO-8601 last-transition timestamp. */
+  updatedAt: string;
+}
+/** What initiated a delivery attempt. */
+type AttemptTrigger = "schedule" | "manual" | "test";
+/** The recorded outcome of a single HTTP delivery attempt. */
+interface DeliveryAttempt {
+  /** `"atp_"` + 22-char base62, server-generated. */
+  id: string;
+  deliveryId: string;
+  /** 1-based attempt ordinal within the delivery. */
+  attemptNumber: number;
+  /** ISO-8601 timestamp of the attempt. */
+  at: string;
+  /** Wall-clock duration of the HTTP round trip. */
+  durationMs: number;
+  /** True when the receiver answered 2xx. */
+  ok: boolean;
+  /** HTTP status code; absent on network error or timeout. */
+  httpStatus?: number;
+  /** Truncated error message on network error/timeout. */
+  error?: string;
+  /** Truncated response body (default cap 4096 chars). */
+  responseBody?: string;
+  /** What initiated this attempt. */
+  trigger: AttemptTrigger;
+}
+/** Actions recorded in the control-plane audit log. */
+type AuditAction = "application.create" | "application.update" | "application.delete" | "event-type.create" | "event-type.update" | "event-type.delete" | "endpoint.create" | "endpoint.update" | "endpoint.delete" | "endpoint.rotate-secret" | "endpoint.disable" | "endpoint.enable" | "delivery.retry" | "endpoint.recover";
+/**
+ * A single control-plane audit record. Publishes are deliberately *not*
+ * audited — they are data-plane traffic, and the message log is their record.
+ */
+interface AuditEntry {
+  action: AuditAction;
+  /** ISO-8601 timestamp. */
+  at: string;
+  by?: Actor | null;
+  /** The application the action was scoped to (absent for global event types). */
+  applicationKey?: string;
+  /** Endpoint id / event type name / delivery id the action targeted. */
+  subjectId?: string;
+  message?: string;
+}
+/**
+ * The wire envelope receivers get — the Standard Webhooks recommended shape.
+ * `type` is the event type name, `timestamp` the event-occurred time, and
+ * `data` the published payload.
+ */
+interface WebhookEnvelope {
+  type: string;
+  timestamp: string;
+  data: JsonValue;
+}
+//#endregion
+export { WebhookEnvelope as _, AuditEntry as a, DeliveryStatus as c, EndpointSecret as d, EventType as f, WebhookDuration as g, SCHEMA_VERSION as h, AuditAction as i, Endpoint as l, Message as m, Application as n, Delivery as o, JsonValue as p, AttemptTrigger as r, DeliveryAttempt as s, Actor as t, EndpointDisabledReason as u, isTerminalDeliveryStatus as v };
+//# sourceMappingURL=schema-mo__wv4P.d.mts.map

package/dist/schema.cjs

@@ -0,0 +1,13 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/schema.ts
+/** Current schema version for stored records. */
+const SCHEMA_VERSION = 1;
+/** Guard: has this delivery reached a terminal state? */
+function isTerminalDeliveryStatus(status) {
+	return status === "succeeded" || status === "failed";
+}
+//#endregion
+exports.SCHEMA_VERSION = SCHEMA_VERSION;
+exports.isTerminalDeliveryStatus = isTerminalDeliveryStatus;
+
+//# sourceMappingURL=schema.cjs.map

package/dist/schema.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.cjs","names":[],"sources":["../src/schema.ts"],"sourcesContent":["/**\n * Core type definitions for `@xtandard/webhooks`.\n *\n * This module is **types only** — no runtime code beyond tiny guards and the\n * schema-version constant, no dependencies. It is safe to import from the\n * publish hot path and the receiver. Runtime validation (which pulls in\n * `valibot`) lives in {@link ./validation}.\n *\n * @module\n */\n\n/** JSON-serializable value, used for payloads, metadata, and event-type schemas. */\nexport type JsonValue =\n  | string\n  | number\n  | boolean\n  | null\n  | JsonValue[]\n  | { [key: string]: JsonValue };\n\n/**\n * A duration for configuration options: either milliseconds as a number, or a\n * human-friendly string such as `\"5s\"`, `\"30m\"`, `\"2h\"`, `\"5d\"`. Parsed by\n * {@link ./duration.durationToMs}.\n */\nexport type WebhookDuration = number | `${number}${\"ms\" | \"s\" | \"m\" | \"h\" | \"d\"}`;\n\n/** Identity captured on audit records and passed by callers of audited mutations. */\nexport interface Actor {\n  id: string;\n  email?: string;\n  name?: string;\n}\n\n/** Current schema version for stored records. */\nexport const SCHEMA_VERSION = 1 as const;\n\n/**\n * An application is the unit of tenancy — typically one of *your* customers.\n * Endpoints, messages, and deliveries are all scoped to an application, and a\n * portal token grants access to exactly one application.\n */\nexport interface Application {\n  /** Unique key. Allowed characters: `a-z A-Z 0-9 . _ -`. */\n  key: string;\n  /** Optional human-friendly name shown in the UI. */\n  name?: string;\n  /** Arbitrary host-defined metadata. */\n  metadata?: JsonValue;\n  /** ISO-8601 creation timestamp, server-stamped. */\n  createdAt?: string;\n  /** ISO-8601 last-update timestamp, server-stamped. */\n  updatedAt?: string;\n}\n\n/**\n * A named kind of event in the **global** catalog (shared by all applications),\n * e.g. `\"invoice.paid\"`. Endpoints subscribe to event types by name.\n */\nexport interface EventType {\n  /** Unique dot-delimited name, e.g. `\"invoice.paid\"`. Allowed: `a-z A-Z 0-9 . _ -`. */\n  name: string;\n  /** Optional description shown in the UI and the public catalog. */\n  description?: string;\n  /** Optional UI grouping label (e.g. `\"Billing\"`). Purely presentational. */\n  groupName?: string;\n  /**\n   * Optional JSON Schema describing the payload. Documentation by default;\n   * enforced only when the core is configured with a `payloadValidator`.\n   */\n  schema?: JsonValue;\n  /** Deprecated event types are flagged in the UI but still deliverable. */\n  deprecated?: boolean;\n  /** ISO-8601 creation timestamp, server-stamped. */\n  createdAt?: string;\n  /** ISO-8601 last-update timestamp, server-stamped. */\n  updatedAt?: string;\n}\n\n/**\n * A signing secret attached to an endpoint. Secrets are `whsec_` + base64 per\n * the Standard Webhooks spec. Rotation keeps the previous secret verifiable\n * until `expiresAt` (the grace window); expired secrets are pruned lazily.\n */\nexport interface EndpointSecret {\n  /** `\"whsec_\"` + base64-encoded random key material. */\n  secret: string;\n  /** ISO-8601 creation timestamp. */\n  createdAt: string;\n  /** Set when superseded by rotation; the secret stops signing after this instant. */\n  expiresAt?: string;\n}\n\n/** Why an endpoint is disabled: by an operator, or by the auto-disable policy. */\nexport type EndpointDisabledReason = \"manual\" | \"auto\";\n\n/**\n * A customer-registered URL that receives deliveries for one application.\n */\nexport interface Endpoint {\n  /** `\"ep_\"` + 22-char base62, server-generated. */\n  id: string;\n  /** Destination URL. `https` is enforced by default (`allowInsecureUrls` for dev). */\n  url: string;\n  /** Optional description shown in the UI. */\n  description?: string;\n  /**\n   * Event type names this endpoint subscribes to. Empty or absent = receives\n   * **all** event types.\n   */\n  eventTypes?: string[];\n  /** Disabled endpoints receive no deliveries (pending ones are held, not failed). */\n  disabled?: boolean;\n  /** Who/what disabled it — an operator (`\"manual\"`) or the failure policy (`\"auto\"`). */\n  disabledReason?: EndpointDisabledReason;\n  /** Static extra headers merged into every delivery request. */\n  headers?: Record<string, string>;\n  /** Signing secrets. `[0]` is current; extras are still-verifiable rotation grace. */\n  secrets: EndpointSecret[];\n  /** Arbitrary host-defined metadata. */\n  metadata?: JsonValue;\n  /** ISO-8601 creation timestamp, server-stamped. */\n  createdAt?: string;\n  /** ISO-8601 last-update timestamp, server-stamped. */\n  updatedAt?: string;\n  /**\n   * Start of the current unbroken failure streak (any successful delivery\n   * clears it). Drives the auto-disable policy.\n   */\n  firstFailingAt?: string | null;\n}\n\n/**\n * A published event for one application. The message is the receiver-facing\n * unit: its id is the `webhook-id` header (stable across retries — receivers\n * dedupe on it), and its payload is the `data` of the wire envelope.\n */\nexport interface Message {\n  /** `\"msg_\"` + 22-char base62, server-generated. Sent as `webhook-id`. */\n  id: string;\n  /** Event type name (usually from the global catalog). */\n  eventType: string;\n  /** The `data` of the wire envelope. */\n  payload: JsonValue;\n  /** ISO-8601 event-occurred time (defaults to publish time). Sent in the envelope. */\n  timestamp: string;\n  /** Optional caller-supplied dedupe key; same key within retention returns the same message. */\n  idempotencyKey?: string;\n  /**\n   * The wire envelope serialized **once at publish time** so the signed bytes\n   * are identical across every retry of every delivery.\n   */\n  envelope: string;\n  /** ISO-8601 creation timestamp, server-stamped. */\n  createdAt: string;\n}\n\n/**\n * Delivery lifecycle. `\"failed\"` means the retry schedule is exhausted — the\n * dead-letter state. A manual retry moves a failed delivery back to `\"pending\"`.\n */\nexport type DeliveryStatus = \"pending\" | \"delivering\" | \"succeeded\" | \"failed\";\n\n/** Guard: has this delivery reached a terminal state? */\nexport function isTerminalDeliveryStatus(status: DeliveryStatus): boolean {\n  return status === \"succeeded\" || status === \"failed\";\n}\n\n/**\n * One message × one endpoint. Created at publish time (fan-out) and driven to\n * a terminal state by the dispatcher.\n */\nexport interface Delivery {\n  /** `\"dlv_\"` + 22-char base62, server-generated. */\n  id: string;\n  /** The application this delivery belongs to (deliveries cross the dispatcher denormalized). */\n  applicationKey: string;\n  messageId: string;\n  endpointId: string;\n  status: DeliveryStatus;\n  /** Number of attempts made so far. */\n  attemptCount: number;\n  /** When the next attempt is due. `null` once terminal. */\n  nextAttemptAt?: string | null;\n  /** Dispatcher claim expiry; an expired lease makes the delivery reclaimable. */\n  leaseUntil?: string | null;\n  /**\n   * How the *next* attempt should be recorded: set to `\"manual\"` by\n   * retry/recover so the resulting attempt is attributed correctly, then\n   * cleared. Absent = `\"schedule\"`.\n   */\n  pendingTrigger?: AttemptTrigger;\n  /** ISO-8601 creation timestamp. */\n  createdAt: string;\n  /** ISO-8601 last-transition timestamp. */\n  updatedAt: string;\n}\n\n/** What initiated a delivery attempt. */\nexport type AttemptTrigger = \"schedule\" | \"manual\" | \"test\";\n\n/** The recorded outcome of a single HTTP delivery attempt. */\nexport interface DeliveryAttempt {\n  /** `\"atp_\"` + 22-char base62, server-generated. */\n  id: string;\n  deliveryId: string;\n  /** 1-based attempt ordinal within the delivery. */\n  attemptNumber: number;\n  /** ISO-8601 timestamp of the attempt. */\n  at: string;\n  /** Wall-clock duration of the HTTP round trip. */\n  durationMs: number;\n  /** True when the receiver answered 2xx. */\n  ok: boolean;\n  /** HTTP status code; absent on network error or timeout. */\n  httpStatus?: number;\n  /** Truncated error message on network error/timeout. */\n  error?: string;\n  /** Truncated response body (default cap 4096 chars). */\n  responseBody?: string;\n  /** What initiated this attempt. */\n  trigger: AttemptTrigger;\n}\n\n/** Actions recorded in the control-plane audit log. */\nexport type AuditAction =\n  | \"application.create\"\n  | \"application.update\"\n  | \"application.delete\"\n  | \"event-type.create\"\n  | \"event-type.update\"\n  | \"event-type.delete\"\n  | \"endpoint.create\"\n  | \"endpoint.update\"\n  | \"endpoint.delete\"\n  | \"endpoint.rotate-secret\"\n  | \"endpoint.disable\"\n  | \"endpoint.enable\"\n  | \"delivery.retry\"\n  | \"endpoint.recover\";\n\n/**\n * A single control-plane audit record. Publishes are deliberately *not*\n * audited — they are data-plane traffic, and the message log is their record.\n */\nexport interface AuditEntry {\n  action: AuditAction;\n  /** ISO-8601 timestamp. */\n  at: string;\n  by?: Actor | null;\n  /** The application the action was scoped to (absent for global event types). */\n  applicationKey?: string;\n  /** Endpoint id / event type name / delivery id the action targeted. */\n  subjectId?: string;\n  message?: string;\n}\n\n/**\n * The wire envelope receivers get — the Standard Webhooks recommended shape.\n * `type` is the event type name, `timestamp` the event-occurred time, and\n * `data` the published payload.\n */\nexport interface WebhookEnvelope {\n  type: string;\n  timestamp: string;\n  data: JsonValue;\n}\n"],"mappings":";;;AAmCA,MAAa,iBAAiB;;AAiI9B,SAAgB,yBAAyB,QAAiC;CACxE,OAAO,WAAW,eAAe,WAAW;AAC9C"}

package/dist/schema.d.cts

@@ -0,0 +1,2 @@
+import { _ as WebhookEnvelope, a as AuditEntry, c as DeliveryStatus, d as EndpointSecret, f as EventType, g as WebhookDuration, h as SCHEMA_VERSION, i as AuditAction, l as Endpoint, m as Message, n as Application, o as Delivery, p as JsonValue, r as AttemptTrigger, s as DeliveryAttempt, t as Actor, u as EndpointDisabledReason, v as isTerminalDeliveryStatus } from "./schema-mo__wv4P.cjs";
+export { Actor, Application, AttemptTrigger, AuditAction, AuditEntry, Delivery, DeliveryAttempt, DeliveryStatus, Endpoint, EndpointDisabledReason, EndpointSecret, EventType, JsonValue, Message, SCHEMA_VERSION, WebhookDuration, WebhookEnvelope, isTerminalDeliveryStatus };

package/dist/schema.d.mts

@@ -0,0 +1,2 @@
+import { _ as WebhookEnvelope, a as AuditEntry, c as DeliveryStatus, d as EndpointSecret, f as EventType, g as WebhookDuration, h as SCHEMA_VERSION, i as AuditAction, l as Endpoint, m as Message, n as Application, o as Delivery, p as JsonValue, r as AttemptTrigger, s as DeliveryAttempt, t as Actor, u as EndpointDisabledReason, v as isTerminalDeliveryStatus } from "./schema-mo__wv4P.mjs";
+export { Actor, Application, AttemptTrigger, AuditAction, AuditEntry, Delivery, DeliveryAttempt, DeliveryStatus, Endpoint, EndpointDisabledReason, EndpointSecret, EventType, JsonValue, Message, SCHEMA_VERSION, WebhookDuration, WebhookEnvelope, isTerminalDeliveryStatus };

package/dist/schema.mjs

@@ -0,0 +1,11 @@
+//#region src/schema.ts
+/** Current schema version for stored records. */
+const SCHEMA_VERSION = 1;
+/** Guard: has this delivery reached a terminal state? */
+function isTerminalDeliveryStatus(status) {
+	return status === "succeeded" || status === "failed";
+}
+//#endregion
+export { SCHEMA_VERSION, isTerminalDeliveryStatus };
+
+//# sourceMappingURL=schema.mjs.map

package/dist/schema.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.mjs","names":[],"sources":["../src/schema.ts"],"sourcesContent":["/**\n * Core type definitions for `@xtandard/webhooks`.\n *\n * This module is **types only** — no runtime code beyond tiny guards and the\n * schema-version constant, no dependencies. It is safe to import from the\n * publish hot path and the receiver. Runtime validation (which pulls in\n * `valibot`) lives in {@link ./validation}.\n *\n * @module\n */\n\n/** JSON-serializable value, used for payloads, metadata, and event-type schemas. */\nexport type JsonValue =\n  | string\n  | number\n  | boolean\n  | null\n  | JsonValue[]\n  | { [key: string]: JsonValue };\n\n/**\n * A duration for configuration options: either milliseconds as a number, or a\n * human-friendly string such as `\"5s\"`, `\"30m\"`, `\"2h\"`, `\"5d\"`. Parsed by\n * {@link ./duration.durationToMs}.\n */\nexport type WebhookDuration = number | `${number}${\"ms\" | \"s\" | \"m\" | \"h\" | \"d\"}`;\n\n/** Identity captured on audit records and passed by callers of audited mutations. */\nexport interface Actor {\n  id: string;\n  email?: string;\n  name?: string;\n}\n\n/** Current schema version for stored records. */\nexport const SCHEMA_VERSION = 1 as const;\n\n/**\n * An application is the unit of tenancy — typically one of *your* customers.\n * Endpoints, messages, and deliveries are all scoped to an application, and a\n * portal token grants access to exactly one application.\n */\nexport interface Application {\n  /** Unique key. Allowed characters: `a-z A-Z 0-9 . _ -`. */\n  key: string;\n  /** Optional human-friendly name shown in the UI. */\n  name?: string;\n  /** Arbitrary host-defined metadata. */\n  metadata?: JsonValue;\n  /** ISO-8601 creation timestamp, server-stamped. */\n  createdAt?: string;\n  /** ISO-8601 last-update timestamp, server-stamped. */\n  updatedAt?: string;\n}\n\n/**\n * A named kind of event in the **global** catalog (shared by all applications),\n * e.g. `\"invoice.paid\"`. Endpoints subscribe to event types by name.\n */\nexport interface EventType {\n  /** Unique dot-delimited name, e.g. `\"invoice.paid\"`. Allowed: `a-z A-Z 0-9 . _ -`. */\n  name: string;\n  /** Optional description shown in the UI and the public catalog. */\n  description?: string;\n  /** Optional UI grouping label (e.g. `\"Billing\"`). Purely presentational. */\n  groupName?: string;\n  /**\n   * Optional JSON Schema describing the payload. Documentation by default;\n   * enforced only when the core is configured with a `payloadValidator`.\n   */\n  schema?: JsonValue;\n  /** Deprecated event types are flagged in the UI but still deliverable. */\n  deprecated?: boolean;\n  /** ISO-8601 creation timestamp, server-stamped. */\n  createdAt?: string;\n  /** ISO-8601 last-update timestamp, server-stamped. */\n  updatedAt?: string;\n}\n\n/**\n * A signing secret attached to an endpoint. Secrets are `whsec_` + base64 per\n * the Standard Webhooks spec. Rotation keeps the previous secret verifiable\n * until `expiresAt` (the grace window); expired secrets are pruned lazily.\n */\nexport interface EndpointSecret {\n  /** `\"whsec_\"` + base64-encoded random key material. */\n  secret: string;\n  /** ISO-8601 creation timestamp. */\n  createdAt: string;\n  /** Set when superseded by rotation; the secret stops signing after this instant. */\n  expiresAt?: string;\n}\n\n/** Why an endpoint is disabled: by an operator, or by the auto-disable policy. */\nexport type EndpointDisabledReason = \"manual\" | \"auto\";\n\n/**\n * A customer-registered URL that receives deliveries for one application.\n */\nexport interface Endpoint {\n  /** `\"ep_\"` + 22-char base62, server-generated. */\n  id: string;\n  /** Destination URL. `https` is enforced by default (`allowInsecureUrls` for dev). */\n  url: string;\n  /** Optional description shown in the UI. */\n  description?: string;\n  /**\n   * Event type names this endpoint subscribes to. Empty or absent = receives\n   * **all** event types.\n   */\n  eventTypes?: string[];\n  /** Disabled endpoints receive no deliveries (pending ones are held, not failed). */\n  disabled?: boolean;\n  /** Who/what disabled it — an operator (`\"manual\"`) or the failure policy (`\"auto\"`). */\n  disabledReason?: EndpointDisabledReason;\n  /** Static extra headers merged into every delivery request. */\n  headers?: Record<string, string>;\n  /** Signing secrets. `[0]` is current; extras are still-verifiable rotation grace. */\n  secrets: EndpointSecret[];\n  /** Arbitrary host-defined metadata. */\n  metadata?: JsonValue;\n  /** ISO-8601 creation timestamp, server-stamped. */\n  createdAt?: string;\n  /** ISO-8601 last-update timestamp, server-stamped. */\n  updatedAt?: string;\n  /**\n   * Start of the current unbroken failure streak (any successful delivery\n   * clears it). Drives the auto-disable policy.\n   */\n  firstFailingAt?: string | null;\n}\n\n/**\n * A published event for one application. The message is the receiver-facing\n * unit: its id is the `webhook-id` header (stable across retries — receivers\n * dedupe on it), and its payload is the `data` of the wire envelope.\n */\nexport interface Message {\n  /** `\"msg_\"` + 22-char base62, server-generated. Sent as `webhook-id`. */\n  id: string;\n  /** Event type name (usually from the global catalog). */\n  eventType: string;\n  /** The `data` of the wire envelope. */\n  payload: JsonValue;\n  /** ISO-8601 event-occurred time (defaults to publish time). Sent in the envelope. */\n  timestamp: string;\n  /** Optional caller-supplied dedupe key; same key within retention returns the same message. */\n  idempotencyKey?: string;\n  /**\n   * The wire envelope serialized **once at publish time** so the signed bytes\n   * are identical across every retry of every delivery.\n   */\n  envelope: string;\n  /** ISO-8601 creation timestamp, server-stamped. */\n  createdAt: string;\n}\n\n/**\n * Delivery lifecycle. `\"failed\"` means the retry schedule is exhausted — the\n * dead-letter state. A manual retry moves a failed delivery back to `\"pending\"`.\n */\nexport type DeliveryStatus = \"pending\" | \"delivering\" | \"succeeded\" | \"failed\";\n\n/** Guard: has this delivery reached a terminal state? */\nexport function isTerminalDeliveryStatus(status: DeliveryStatus): boolean {\n  return status === \"succeeded\" || status === \"failed\";\n}\n\n/**\n * One message × one endpoint. Created at publish time (fan-out) and driven to\n * a terminal state by the dispatcher.\n */\nexport interface Delivery {\n  /** `\"dlv_\"` + 22-char base62, server-generated. */\n  id: string;\n  /** The application this delivery belongs to (deliveries cross the dispatcher denormalized). */\n  applicationKey: string;\n  messageId: string;\n  endpointId: string;\n  status: DeliveryStatus;\n  /** Number of attempts made so far. */\n  attemptCount: number;\n  /** When the next attempt is due. `null` once terminal. */\n  nextAttemptAt?: string | null;\n  /** Dispatcher claim expiry; an expired lease makes the delivery reclaimable. */\n  leaseUntil?: string | null;\n  /**\n   * How the *next* attempt should be recorded: set to `\"manual\"` by\n   * retry/recover so the resulting attempt is attributed correctly, then\n   * cleared. Absent = `\"schedule\"`.\n   */\n  pendingTrigger?: AttemptTrigger;\n  /** ISO-8601 creation timestamp. */\n  createdAt: string;\n  /** ISO-8601 last-transition timestamp. */\n  updatedAt: string;\n}\n\n/** What initiated a delivery attempt. */\nexport type AttemptTrigger = \"schedule\" | \"manual\" | \"test\";\n\n/** The recorded outcome of a single HTTP delivery attempt. */\nexport interface DeliveryAttempt {\n  /** `\"atp_\"` + 22-char base62, server-generated. */\n  id: string;\n  deliveryId: string;\n  /** 1-based attempt ordinal within the delivery. */\n  attemptNumber: number;\n  /** ISO-8601 timestamp of the attempt. */\n  at: string;\n  /** Wall-clock duration of the HTTP round trip. */\n  durationMs: number;\n  /** True when the receiver answered 2xx. */\n  ok: boolean;\n  /** HTTP status code; absent on network error or timeout. */\n  httpStatus?: number;\n  /** Truncated error message on network error/timeout. */\n  error?: string;\n  /** Truncated response body (default cap 4096 chars). */\n  responseBody?: string;\n  /** What initiated this attempt. */\n  trigger: AttemptTrigger;\n}\n\n/** Actions recorded in the control-plane audit log. */\nexport type AuditAction =\n  | \"application.create\"\n  | \"application.update\"\n  | \"application.delete\"\n  | \"event-type.create\"\n  | \"event-type.update\"\n  | \"event-type.delete\"\n  | \"endpoint.create\"\n  | \"endpoint.update\"\n  | \"endpoint.delete\"\n  | \"endpoint.rotate-secret\"\n  | \"endpoint.disable\"\n  | \"endpoint.enable\"\n  | \"delivery.retry\"\n  | \"endpoint.recover\";\n\n/**\n * A single control-plane audit record. Publishes are deliberately *not*\n * audited — they are data-plane traffic, and the message log is their record.\n */\nexport interface AuditEntry {\n  action: AuditAction;\n  /** ISO-8601 timestamp. */\n  at: string;\n  by?: Actor | null;\n  /** The application the action was scoped to (absent for global event types). */\n  applicationKey?: string;\n  /** Endpoint id / event type name / delivery id the action targeted. */\n  subjectId?: string;\n  message?: string;\n}\n\n/**\n * The wire envelope receivers get — the Standard Webhooks recommended shape.\n * `type` is the event type name, `timestamp` the event-occurred time, and\n * `data` the published payload.\n */\nexport interface WebhookEnvelope {\n  type: string;\n  timestamp: string;\n  data: JsonValue;\n}\n"],"mappings":";;AAmCA,MAAa,iBAAiB;;AAiI9B,SAAgB,yBAAyB,QAAiC;CACxE,OAAO,WAAW,eAAe,WAAW;AAC9C"}