@voltro/plugin-webhooks 0.26.0 → 0.28.0

package/dist/index.d.ts

@@ -196,6 +196,31 @@ export declare interface DeliverySummary {
  *  Covers ms / s / m / h / d. Default seconds (no suffix). */
 export declare type DurationLiteral = `${number}${'ms' | 's' | 'm' | 'h' | 'd'}` | `${number}`;
 
+/**
+ * Per-emit scoping.
+ *
+ * **The outgoing fan-out was NOT tenant-scoped, and this is what closes it.**
+ * The service is built once at boot with the app-level store, so the `tenant()`
+ * mixin on `_voltro_webhook_targets` had no request subject to scope by — the
+ * target lookup was `eq('event', name)` and nothing else. Confinement therefore
+ * rested entirely on each target's own `filter`, i.e. on the app remembering.
+ *
+ * A consumer found this by reading the CLI, and named exactly why it had looked
+ * safe: target filters usually predicate on a globally unique app id, so a
+ * cross-tenant match is impossible **by accident**. It stopped being accidental
+ * for them the moment they introduced a value deliberately equal across teams
+ * (a tenant-wide audience marker).
+ *
+ * `ctx.webhooks` binds this from the request subject, so an emit inside a
+ * handler is scoped without the handler saying anything. Absent — a background
+ * job, a schedule, a replay — keeps the unscoped behaviour, because there is no
+ * tenant to scope BY and refusing would break every system emit.
+ */
+export declare interface EmitOptions {
+    /** Only deliver to targets of this tenant. Absent ⇒ every target. */
+    readonly tenantId?: string | null;
+}
+
 export declare interface EmitResult {
     /** Stable id matching the row(s) the deliverWebhook workflow
      *  writes to `_voltro_webhook_deliveries`. Use as the foreign
@@ -223,6 +248,9 @@ export declare interface EncodedPayload {
  *  be honestly represented in the requested format. */
 export declare const encodePayload: (format: WireFormat, payloadJson: string) => EncodedPayload;
 
+/** The events a subscribe names, whichever spelling was used. */
+export declare const eventsOf: (input: SubscribeInput) => ReadonlyArray<string>;
+
 /** Aggressive policy — retry every 30s for an hour. Use for a
  *  downstream that's expected to come back quickly. */
 export declare const fastRetryPolicy: () => RetryPolicy;
@@ -418,7 +446,7 @@ export declare const isWebhookDescriptor: (value: unknown) => value is WebhookDe
  *  when the target should receive this delivery. Supports the
  *  simple key-path form `'payload.field': value` for v1; future
  *  versions can grow operators ({ gt, lt, in, … }). */
-export declare const matchesFilter: (filter: Readonly<Record<string, unknown>> | null, payload: unknown) => boolean;
+export declare const matchesFilter: (filter: WebhookFilter | Readonly<Record<string, unknown>> | null, payload: unknown) => boolean;
 
 /**
  * Build a request handler for a specific `IncomingWebhookDescriptor`.
@@ -542,7 +570,10 @@ export declare const releaseRateSlot: (store: DataStore, key: string, bucket: nu
  *  value wins, then the event descriptor's per-event defaults
  *  (`defaultSigning` / `defaultRetry` / `version` from
  *  the declared event's `webhook:` block), then the package-global defaults. */
-export declare const resolveSubscribe: (input: SubscribeInput, event?: OutgoingEventDescriptor<unknown>) => {
+export declare const resolveSubscribe: (input: SubscribeInput, event?: OutgoingEventDescriptor<unknown>, 
+/** The event this ROW is for, and the secret the group shares. Both default
+ *  to the single-event behaviour, so existing callers are unchanged. */
+forEvent?: string, sharedSecret?: string) => {
     readonly id: string;
     readonly event: string;
     readonly url: string;
@@ -621,7 +652,8 @@ export declare const slackSignature: () => CustomSignatureScheme;
 export declare const stripeSignature: (header?: string) => HmacSignatureScheme;
 
 export declare interface SubscribeInput {
-    readonly event: string;
+    /** A single event. Use `events` for a multi-event subscription. */
+    readonly event?: string;
     readonly url: string;
     /** Secret used to sign deliveries to this target. Auto-generated
      *  when omitted (32-byte hex). The caller receives it ONCE in the
@@ -629,10 +661,31 @@ export declare interface SubscribeInput {
     readonly secret?: string;
     readonly signing?: SignatureScheme;
     readonly retry?: RetryPolicy;
-    /** Optional predicate filter — only emits whose payload matches
-     *  this predicate fan-out to this target. The shape mirrors the
-     *  schema-builder's `Predicate` from `@voltro/database`. */
-    readonly filter?: Readonly<Record<string, unknown>>;
+    /**
+     * Optional routing filter — only emits whose payload matches fan out to this
+     * target. See {@link WebhookFilter}: dotted paths into `{ payload }`, a bare
+     * value for equality, or `{ eq | in | gt | gte | lt | lte }`.
+     */
+    readonly filter?: WebhookFilter;
+    /**
+     * Subscribe ONE url to SEVERAL events at once.
+     *
+     * A subscription, as every webhook UI models it, is one URL with a list of
+     * event checkboxes — ours, Stripe's, GitHub's. The row is one event, so five
+     * checkboxes are five rows, and the gap between the two is where an app ends
+     * up hand-rolling every operation a user thinks of as single.
+     *
+     * The rows created here share ONE secret and one `scope`, which is what makes
+     * the group addressable afterwards — and it is not a convenience: the receiver
+     * verifies one signature for one URL, so N rows for one endpoint MUST sign
+     * identically. Without this the only way to say so was to read the secret
+     * column back out of `_voltro_webhook_targets`, which is exactly the coupling
+     * `listDeliveries` was added to remove, re-entered through another door.
+     *
+     * Mutually exclusive with `event`. Pass whichever reads better; one event is
+     * still one row.
+     */
+    readonly events?: ReadonlyArray<string>;
     /**
      * The APP's own scoping dimension — opaque, stored and returned verbatim.
      *
@@ -654,6 +707,12 @@ export declare interface SubscribeInput {
 }
 
 export declare interface SubscribeResult {
+    /** Every row created, when `events` named more than one. Absent for a
+     *  single-event subscribe, where `id` and `event` already say it. */
+    readonly targets?: ReadonlyArray<{
+        readonly id: string;
+        readonly event: string;
+    }>;
     readonly id: string;
     readonly event: string;
     readonly url: string;
@@ -669,7 +728,7 @@ export declare interface SubscribeResult {
 export declare interface TargetPatch {
     readonly url?: string;
     readonly description?: string | null;
-    readonly filter?: Readonly<Record<string, unknown>> | null;
+    readonly filter?: WebhookFilter | null;
     readonly scope?: Readonly<Record<string, unknown>> | null;
     readonly headers?: Readonly<Record<string, string>> | null;
     readonly rateLimitPerMinute?: number | null;
@@ -679,6 +738,23 @@ export declare interface TargetPatch {
 
 export declare const TARGETS_TABLE = "_voltro_webhook_targets";
 
+/**
+ * WHICH target(s) an operation addresses.
+ *
+ * A string is one row. A `{ scope }` is the GROUP — every row whose opaque
+ * scope matches, which for a multi-event subscription is the whole endpoint.
+ *
+ * This exists because a subscription, as a user models it, is one URL with a
+ * list of event checkboxes, while a row is one event. Without a group selector
+ * every operation the user thinks of as single — pause the endpoint, fix its
+ * URL, rotate its secret, read its history — becomes a fan-out the app writes
+ * by hand, and `rotateSecret` in particular becomes delete + re-subscribe,
+ * which mints new ids and orphans the delivery history.
+ */
+export declare type TargetSelector = string | {
+    readonly scope: Readonly<Record<string, unknown>>;
+};
+
 export declare interface TargetSummary {
     readonly id: string;
     /** The app's own scoping dimension as written at subscribe time, verbatim.
@@ -723,8 +799,6 @@ export declare const useWebhooks: (ctx: {
 
 export declare const useWebhooksEffect: Effect.Effect<WebhooksServiceShape, never, WebhooksService>;
 
-/** Validate subscribe input. Throws on policy violations so the
- *  caller's catch block can surface a 422-style error. */
 export declare const validateSubscribe: (input: SubscribeInput) => void;
 
 export declare type VerifyResult = {
@@ -972,6 +1046,24 @@ declare const WebhookDeliveryNotFound_base: Schema.TaggedErrorClass<WebhookDeliv
 
 export declare type WebhookDescriptor = OutgoingEventDescriptor<unknown> | IncomingWebhookDescriptor<unknown> | WebhookProviderDescriptor;
 
+/**
+ * A target's routing filter: dotted paths INTO the emitted envelope.
+ *
+ * The root is `{ payload }`, so every path starts `payload.` — a path that does
+ * not resolve reads as `undefined` and the comparison fails, which is how a
+ * typo'd path silently routes nothing.
+ */
+export declare type WebhookFilter = Readonly<Record<string, WebhookFilterValue>>;
+
+export declare type WebhookFilterValue = string | number | boolean | null | {
+    readonly eq?: string | number | boolean | null;
+    readonly in?: ReadonlyArray<string | number | boolean | null>;
+    readonly gt?: number | string;
+    readonly gte?: number | string;
+    readonly lt?: number | string;
+    readonly lte?: number | string;
+};
+
 /** Stable identifier for an event or webhook. Drives the database
  *  primary key, the inspect endpoint URL, the dashboard listing. Use
  *  dotted-camelCase (`order.completed`, `user.signedUp`). */
@@ -1068,7 +1160,7 @@ export declare interface WebhooksServiceShape {
      *  discovered-events registry) the payload is DECODED against its
      *  schema and a mismatch throws `WebhookPayloadInvalid` before any
      *  delivery is created. */
-    readonly emit: <P>(event: string | OutgoingEventDescriptor<P> | DeclaredEventLike, payload: P) => Promise<EmitResult>;
+    readonly emit: <P>(event: string | OutgoingEventDescriptor<P> | DeclaredEventLike, payload: P, options?: EmitOptions) => Promise<EmitResult>;
     /** Manual re-trigger for the dashboard's "Replay" button on a
      *  failed delivery row. Re-runs the workflow at attempt 1 with
      *  the original payload. */
@@ -1086,24 +1178,33 @@ export declare interface WebhooksServiceShape {
      *  emits against this target queue under
      *  `_voltro_webhook_deliveries` with status='pending' (no POST
      *  happens); `resumeTarget` flushes them. */
-    readonly pauseTarget: (targetId: string) => Promise<void>;
+    /** Every row a selector addresses. Refuses a scope that matches nothing —
+     *  an operation that silently affects zero rows is worse than an error. */
+    readonly resolveTargets: (selector: TargetSelector) => Promise<ReadonlyArray<string>>;
+    readonly pauseTarget: (target: TargetSelector) => Promise<void>;
     /** Re-enable a paused target AND flush its queued
      *  `status='pending'` deliveries through the normal delivery
      *  workflow, in emit order (`createdAt` ascending — millisecond
      *  granularity) per target. */
-    readonly resumeTarget: (targetId: string) => Promise<void>;
+    readonly resumeTarget: (target: TargetSelector) => Promise<void>;
     /** Hard-delete a target. Its queued `status='pending'` rows are
      *  deleted with it (nothing left to flush); an in-flight workflow
      *  run's `fetch-target` activity sees a null row and exits
      *  cleanly. */
-    readonly deleteTarget: (targetId: string) => Promise<void>;
+    readonly deleteTarget: (target: TargetSelector) => Promise<void>;
     /** Rotate the per-target signing secret. Returns the new secret
      *  ONCE — store it client-side if you need to display it again.
      *  In-flight retries continue with the OLD secret since signing
      *  happens at attempt time using the row's then-current value
      *  (acceptable: providers retry within seconds, the rotation
      *  window is tight). */
-    readonly rotateSecret: (targetId: string) => Promise<{
+    /**
+     * Rotate the signing secret. Addressed by a SCOPE this rotates every row of
+     * the endpoint to the SAME new value — which is the point: N rows for one URL
+     * must sign identically, and the previous way to achieve it was delete +
+     * re-subscribe, minting new ids and orphaning the delivery history.
+     */
+    readonly rotateSecret: (target: TargetSelector) => Promise<{
         readonly secret: string;
     }>;
     /** Re-pin a target's `payloadVersion` to the event's current
@@ -1124,7 +1225,7 @@ export declare interface WebhooksServiceShape {
      * makes it a different subscription, and the secret has `rotateSecret`, which
      * returns the new value once.
      */
-    readonly updateTarget: (targetId: string, patch: TargetPatch) => Promise<void>;
+    readonly updateTarget: (target: TargetSelector, patch: TargetPatch) => Promise<void>;
     /**
      * Send one delivery to ONE target, bypassing fan-out and the filter.
      *
@@ -1151,6 +1252,9 @@ export declare interface WebhooksServiceShape {
      */
     readonly listDeliveries: (filter?: {
         readonly targetId?: string;
+        /** Every row of an endpoint's group, so a history view needs no N-way
+         *  merge-and-re-sort in the app. */
+        readonly scope?: Readonly<Record<string, unknown>>;
         readonly status?: DeliverySummary['status'];
         readonly since?: Date;
         readonly limit?: number;