@voltro/plugin-webhooks 0.22.1 → 0.24.0

package/dist/index.d.ts

@@ -666,6 +666,183 @@ export declare const verifySignature: (scheme: SignatureScheme, rawBody: Uint8Ar
  */
 export declare type VersionState = 'current' | 'behind' | 'ahead';
 
+/**
+ * One row per delivery attempt — NOT per emit. An emit fans out to
+ * N targets; each target then runs ≤ `maxAttempts` deliveries. The
+ * primary key is `(deliveryId, attempt)`; `deliveryId` is shared
+ * across retries of the SAME (event, payload, target) tuple so the
+ * dashboard groups them.
+ *
+ * Status lifecycle: `pending` (queued — the target was paused at emit
+ * time, or the attempt is rate-deferred to the next window) →
+ * `inFlight` → `succeeded` | `failed` | `retryScheduled`. On retry the
+ * workflow creates a new `(deliveryId, attempt+1)` row; on
+ * resume/deferral the SAME attempt-1 row transitions out of `pending`.
+ */
+export declare const _voltroWebhookDeliveriesTable: Table<"_voltro_webhook_deliveries", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    /** Grouping key for retries of the same delivery. See above. */
+    readonly deliveryId: ColumnBuilder<string, "text", boolean>;
+    /** FK to `_voltro_webhook_targets.id`. */
+    readonly targetId: ColumnBuilder<string, "text", boolean>;
+    /** Event id at emit time — denormalised so dashboard listings
+     *  don't need to JOIN through `_voltro_webhook_targets` (which
+     *  may have been deleted by the time someone audits this row). */
+    readonly event: ColumnBuilder<string, "text", boolean>;
+    /** The emit's `eventId` (shared by every target fan-out of one
+     *  emit) — lets `resumeTarget`'s flush re-trigger a queued delivery
+     *  with its ORIGINAL event id, and correlates rows across targets. */
+    readonly eventId: ColumnBuilder<string | null, "text", boolean>;
+    /** Attempt counter (1-indexed). */
+    readonly attempt: ColumnBuilder<number, "integer", boolean>;
+    readonly status: ColumnBuilder<"failed" | "succeeded" | "pending" | "inFlight" | "retryScheduled", "text", boolean>;
+    /** Payload as sent over the wire. Stored verbatim — re-rendering
+     *  from a referenced event row would lose the snapshot if the
+     *  source event was deleted. */
+    readonly payload: ColumnBuilder<unknown, "json", boolean>;
+    /** HTTP status code returned. `null` for transport errors (DNS,
+     *  TLS, timeout) — `errorMessage` carries the detail. */
+    readonly responseStatus: ColumnBuilder<number | null, "integer", boolean>;
+    /** Response body sample (clipped to 8 KB). Lets the dashboard
+     *  show the recipient's error reply inline. */
+    readonly responseBody: ColumnBuilder<string | null, "text", boolean>;
+    /** Transport-layer error message ("ENOTFOUND", "ETIMEDOUT", TLS
+     *  handshake failure). Null on HTTP-layer errors (those carry
+     *  `responseStatus`). */
+    readonly errorMessage: ColumnBuilder<string | null, "text", boolean>;
+    /** End-to-end attempt latency in ms — includes DNS, TLS, request,
+     *  response read. Useful for the dashboard's "slowest endpoint"
+     *  ranking. */
+    readonly latencyMs: ColumnBuilder<number | null, "integer", boolean>;
+    /** When this attempt was scheduled (NOT when it was sent — sent
+     *  time is approximately `scheduledAt + queueDelay`). */
+    readonly scheduledAt: ColumnBuilder<Date, "timestamp", boolean>;
+    /** When the next retry is due (set ONLY when `status =
+     *  retryScheduled`). Lets the workflow's sleep block read its
+     *  wake time from the persisted row across restarts. */
+    readonly nextAttemptAt: ColumnBuilder<Date | null, "timestamp", boolean>;
+}> & {
+    tenantId: ColumnDefinition<string>;
+} & {
+    readonly createdAt: ColumnDefinition<Date, "timestamp", true>;
+    readonly updatedAt: ColumnDefinition<Date, "timestamp", true>;
+    readonly createdBy: ColumnDefinition<string | null, "reference", boolean>;
+    readonly updatedBy: ColumnDefinition<string | null, "reference", boolean>;
+}, true, never>;
+
+/**
+ * Fixed-window rate-limit counters — one row per (scope, minute
+ * bucket), where scope is `target:<targetId>` (per-target
+ * `rateLimitPerMinute`) or `event:<eventId>` (an outgoing event's
+ * `globalRateLimit`). The delivery workflow claims a slot via a CAS
+ * loop over `count` (see `rateLimit.ts`) BEFORE every wire POST, so
+ * the cap holds across replicas — the counter lives here, never in
+ * process memory.
+ *
+ * Deliberately NOT tenant-scoped: rows carry only a scope key + an
+ * integer count (no payload, no secret, no tenant data), and the
+ * background delivery workflow that writes them has no request
+ * subject. The deterministic PK `<scope>@<bucket>` is the
+ * `insertIgnore` conflict target for the first-in-window create race.
+ */
+export declare const _voltroWebhookRateWindowsTable: Table<"_voltro_webhook_rate_windows", FieldDefinitions<{
+    /** Deterministic `<scope>@<bucket>` — always supplied explicitly by
+     *  the CAS writer (the prefix scheme only fires for omitted ids,
+     *  which never happens here). */
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    /** `target:<targetId>` | `event:<eventId>`. */
+    readonly scope: ColumnBuilder<string, "text", boolean>;
+    /** Epoch-minute bucket (`floor(now / windowMs)`). */
+    readonly bucket: ColumnBuilder<number, "integer", boolean>;
+    /** Slots consumed in this window. */
+    readonly count: ColumnBuilder<number, "integer", true>;
+    readonly createdAt: ColumnBuilder<Date, "timestamp", boolean>;
+    readonly updatedAt: ColumnBuilder<Date, "timestamp", boolean>;
+}>, true, never>;
+
+/**
+ * One row per subscribed delivery target. Created via
+ * `webhooks.subscribe(...)`. Read-only from app code; mutate via
+ * the `webhooks` service so the framework can run validation +
+ * generate secrets + invalidate caches.
+ */
+export declare const _voltroWebhookTargetsTable: Table<"_voltro_webhook_targets", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    /** Event id from the outgoing-event descriptor (e.g. `'order.completed'`). */
+    readonly event: ColumnBuilder<string, "text", boolean>;
+    /** Active subscription URL the delivery posts to. */
+    readonly url: ColumnBuilder<string, "text", boolean>;
+    /** Per-target signing secret. Generated at subscribe time when not
+     *  supplied. Stored as-is — encryption is a deployment concern
+     *  (Postgres-at-rest, KMS-wrapped column, vault sidecar). */
+    readonly secret: ColumnBuilder<string, "text", boolean>;
+    /** Serialised `SignatureScheme` discriminated union — see `signing.ts`.
+     *  Stored as JSON so future schemes don't require a schema migration. */
+    readonly signing: ColumnBuilder<unknown, "json", boolean>;
+    /** Serialised `RetryPolicy` — see `retry.ts`. */
+    readonly retry: ColumnBuilder<unknown, "json", boolean>;
+    /** Optional predicate filter (subset of `Predicate`) — the engine
+     *  evaluates this against each emit's payload to decide whether
+     *  this target receives the delivery. */
+    readonly filter: ColumnBuilder<unknown, "json", boolean>;
+    /** Optional custom headers merged with the framework's
+     *  Content-Type + signature header. Values larger than 2 KB are
+     *  rejected at subscribe time. */
+    readonly headers: ColumnBuilder<unknown, "json", boolean>;
+    /** Per-target rate limit — at most N wire POSTs per minute to this
+     *  target, enforced by the delivery workflow via a shared-store
+     *  fixed-window counter (`_voltro_webhook_rate_windows`, so the cap
+     *  holds across replicas). Excess deliveries are DEFERRED: parked as
+     *  `status='pending'` rows and durable-slept until the next window
+     *  opens — they're never dropped silently. */
+    readonly rateLimitPerMinute: ColumnBuilder<number | null, "integer", boolean>;
+    /** Soft-disable without deleting the row — the dashboard's
+     *  "Pause" affordance flips this. While paused, emits against this
+     *  target accumulate as `_voltro_webhook_deliveries` rows with
+     *  status `'pending'` (no POST happens); `resumeTarget` flushes
+     *  them through the delivery workflow in emit order. */
+    readonly active: ColumnBuilder<boolean, "boolean", true>;
+    /** Format the payload is delivered as. `json` is the default and
+     *  what every modern integration expects. `form`
+     *  (`application/x-www-form-urlencoded`, bracketed-key flattening)
+     *  and `xml` (`application/xml`, `<webhook>`-rooted) exist for
+     *  SOAP-era partners; the delivery workflow re-encodes the payload
+     *  into this format and signs the re-encoded bytes. */
+    readonly format: ColumnBuilder<"json" | "form" | "xml", "text", true>;
+    /** Auto-disable threshold — after this many CONSECUTIVE terminal
+     *  delivery failures the target is auto-paused (dead-letter guard).
+     *  `null` (the default) disables the feature. When it trips, the
+     *  target flips to `active=false` and subsequent emits QUEUE as
+     *  `status='pending'` rows (same as a manual pause — nothing is
+     *  dropped); a manual `resumeTarget` re-activates, flushes the queue,
+     *  and clears the streak. */
+    readonly autoDisableAfter: ColumnBuilder<number | null, "integer", boolean>;
+    /** Consecutive terminal-failure streak. Incremented on each terminal
+     *  `failed` delivery, reset to 0 on any `succeeded`. Drives
+     *  `autoDisableAfter`. Multi-replica-correct via a CAS loop
+     *  (`autoDisable.ts`). */
+    readonly consecutiveFailures: ColumnBuilder<number, "integer", true>;
+    /** When the auto-disable last fired (`null` = never / cleared by a
+     *  manual resume). Surfaced on the inspect panel. */
+    readonly autoDisabledAt: ColumnBuilder<Date | null, "timestamp", boolean>;
+    /** The terminal failure reason that tripped the auto-disable
+     *  (`null` = not auto-disabled). Surfaced on the inspect panel. */
+    readonly autoDisableReason: ColumnBuilder<string | null, "text", boolean>;
+    /** Schema version bound at subscribe time. Lets the dashboard
+     *  show which targets are still pinned to an older event version
+     *  after the producer bumps it. */
+    readonly payloadVersion: ColumnBuilder<number, "integer", true>;
+    /** Human-readable label surfaced in the dashboard listing. */
+    readonly description: ColumnBuilder<string | null, "text", boolean>;
+}> & {
+    tenantId: ColumnDefinition<string>;
+} & {
+    readonly createdAt: ColumnDefinition<Date, "timestamp", true>;
+    readonly updatedAt: ColumnDefinition<Date, "timestamp", true>;
+    readonly createdBy: ColumnDefinition<string | null, "reference", boolean>;
+    readonly updatedBy: ColumnDefinition<string | null, "reference", boolean>;
+}, true, never>;
+
 /**
  * Thrown by `WebhooksService.replay` when no delivery row exists for the
  * given `deliveryId` — the row can't be re-triggered because the