@voltro/plugin-webhooks 0.25.0 → 0.27.0

package/dist/index.d.ts

@@ -169,6 +169,29 @@ declare interface DeliverWorkflowOptions {
     readonly rateWindowMs?: number;
 }
 
+/** `getDelivery` adds the two heavy columns `listDeliveries` omits. */
+export declare interface DeliveryDetail extends DeliverySummary {
+    readonly payload: unknown;
+    readonly responseBody: string | null;
+}
+
+/** One delivery ATTEMPT, as the management UI reads it. */
+export declare interface DeliverySummary {
+    readonly id: string;
+    readonly deliveryId: string;
+    readonly targetId: string;
+    readonly event: string;
+    readonly eventId: string | null;
+    readonly attempt: number;
+    readonly status: 'pending' | 'inFlight' | 'succeeded' | 'failed' | 'retryScheduled';
+    readonly responseStatus: number | null;
+    readonly errorMessage: string | null;
+    readonly latencyMs: number | null;
+    readonly scheduledAt: string | null;
+    readonly nextAttemptAt: string | null;
+    readonly createdAt: string | null;
+}
+
 /** Compact duration literal — parsed without a deps-pulling library.
  *  Covers ms / s / m / h / d. Default seconds (no suffix). */
 export declare type DurationLiteral = `${number}${'ms' | 's' | 'm' | 'h' | 'd'}` | `${number}`;
@@ -200,6 +223,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;
@@ -519,7 +545,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;
@@ -527,6 +556,7 @@ export declare const resolveSubscribe: (input: SubscribeInput, event?: OutgoingE
     readonly signing: SignatureScheme;
     readonly retry: RetryPolicy;
     readonly filter: Readonly<Record<string, unknown>> | null;
+    readonly scope: Readonly<Record<string, unknown>> | null;
     readonly headers: Readonly<Record<string, string>> | null;
     readonly rateLimitPerMinute: number | null;
     readonly active: boolean;
@@ -597,7 +627,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
@@ -609,6 +640,34 @@ export declare interface SubscribeInput {
      *  this predicate fan-out to this target. The shape mirrors the
      *  schema-builder's `Predicate` from `@voltro/database`. */
     readonly filter?: Readonly<Record<string, unknown>>;
+    /**
+     * 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.
+     *
+     * `.with(tenant())` is one level too coarse for real deployments: endpoints
+     * are commonly scoped to a team, a project or a workspace, and a tenant has
+     * many of those. Pass whatever identifies yours; `listTargets({ scope })`
+     * filters on equality against it. The framework never interprets it.
+     */
+    readonly scope?: Readonly<Record<string, unknown>>;
     readonly headers?: Readonly<Record<string, string>>;
     readonly rateLimitPerMinute?: number;
     readonly format?: 'json' | 'form' | 'xml';
@@ -621,6 +680,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;
@@ -632,10 +697,42 @@ export declare interface SubscribeResult {
     readonly retry: RetryPolicy;
 }
 
+/** The patchable subset of a target. Absent keys are left alone. */
+export declare interface TargetPatch {
+    readonly url?: string;
+    readonly description?: string | null;
+    readonly filter?: Readonly<Record<string, unknown>> | null;
+    readonly scope?: Readonly<Record<string, unknown>> | null;
+    readonly headers?: Readonly<Record<string, string>> | null;
+    readonly rateLimitPerMinute?: number | null;
+    readonly autoDisableAfter?: number | null;
+    readonly format?: 'json' | 'form' | 'xml';
+}
+
 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.
+     *  `null` when the app stored none. */
+    readonly scope: Readonly<Record<string, unknown>> | null;
     readonly event: string;
     readonly url: string;
     readonly active: boolean;
@@ -675,8 +772,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 = {
@@ -821,6 +916,30 @@ export declare const _voltroWebhookTargetsTable: Table<"_voltro_webhook_targets"
     readonly signing: ColumnBuilder<unknown, "json", boolean>;
     /** Serialised `RetryPolicy` — see `retry.ts`. */
     readonly retry: ColumnBuilder<unknown, "json", boolean>;
+    /**
+     * The APP's own scoping dimension. Opaque to the framework.
+     *
+     * Stored and returned verbatim, never interpreted — the framework does not
+     * know what a team, a project or a workspace is, and does not need to. Reads
+     * filter on equality against the json you wrote:
+     *
+     *   subscribe({ event, url, scope: { teamId: 'q970…' } })
+     *   listTargets({ scope: { teamId } })
+     *
+     * It exists because `.with(tenant())` is one level too coarse for real
+     * deployments. A consumer's endpoints are scoped to a TEAM and a tenant has
+     * many teams; every read filters by it and every write guards on it, so
+     * without this column the plugin cannot hold their rows at all and they keep
+     * a parallel table.
+     *
+     * The precedent is `_voltro_presence.meta`, and it is worth stating because
+     * it decided a migration: that column is json the framework stores and never
+     * interprets, and it is the ONLY reason the same consumer's presence
+     * migration was lossless — their three denormalised columns went straight in.
+     * The general form: a plugin that stores rows in an app's database on the
+     * app's behalf needs one place for the app's own dimension.
+     */
+    readonly scope: 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. */
@@ -1004,29 +1123,43 @@ export declare interface WebhooksServiceShape {
     /** List currently-subscribed targets for an event, or all when
      *  `event` is omitted. The dashboard's "Targets" page consumes
      *  this. */
-    readonly listTargets: (event?: string) => Promise<ReadonlyArray<TargetSummary>>;
+    readonly listTargets: (event?: string, 
+    /** Filter to targets whose opaque `scope` equals this, key for key. The
+     *  match is exact on the keys you pass — a target with extra keys still
+     *  matches, so `{ teamId }` finds targets scoped to that team regardless of
+     *  what else the app stored beside it. */
+    scope?: Readonly<Record<string, unknown>>) => Promise<ReadonlyArray<TargetSummary>>;
     /** Soft-disable a target without deleting the row. While paused,
      *  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
@@ -1034,6 +1167,55 @@ export declare interface WebhooksServiceShape {
      *  the consumer has updated their handler to accept the new
      *  payload shape. */
     readonly updateTargetPayloadVersion: (targetId: string, version: number) => Promise<void>;
+    /**
+     * Edit a target in place.
+     *
+     * Without it, changing a URL, description, filter, headers or rate limit
+     * means delete + re-subscribe — which ROTATES the secret (every receiver has
+     * to be reconfigured) and ORPHANS the delivery history (the rows point at a
+     * target id that no longer exists). Neither is what "I fixed a typo in the
+     * URL" should cost.
+     *
+     * `event` and `secret` are deliberately not patchable: changing the event
+     * makes it a different subscription, and the secret has `rotateSecret`, which
+     * returns the new value once.
+     */
+    readonly updateTarget: (target: TargetSelector, patch: TargetPatch) => Promise<void>;
+    /**
+     * Send one delivery to ONE target, bypassing fan-out and the filter.
+     *
+     * `emit` fans out to every matching target, so there is no way to answer "is
+     * THIS endpoint reachable" — the first button in every webhook UI. The
+     * delivery is real: it is signed, recorded in the delivery log and retried
+     * like any other, so what it proves is what production will do.
+     */
+    readonly testTarget: (targetId: string, payload?: unknown) => Promise<{
+        readonly deliveryId: string;
+    }>;
+    /**
+     * Read the delivery log.
+     *
+     * There was no service method for it, so the only way to build a management
+     * view was to query `_voltro_webhook_deliveries` directly — and a consumer
+     * declined, correctly: the 0.24.0 `agent_messages` rename taught them what
+     * app code coupled to a framework table name costs. That one was survivable
+     * because it was a rename; a column change would not be.
+     *
+     * The two heavy columns (`payload`, `responseBody`) are omitted here and
+     * available from `getDelivery`, so a list view does not pull response bodies
+     * for 200 rows.
+     */
+    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;
+    }) => Promise<ReadonlyArray<DeliverySummary>>;
+    /** One delivery attempt including its payload and response body. */
+    readonly getDelivery: (id: string) => Promise<DeliveryDetail | null>;
 }
 
 /**
@@ -1082,6 +1264,30 @@ export declare const webhookTables: () => readonly [ Table<"_voltro_webhook_targ
     readonly signing: ColumnBuilder<unknown, "json", boolean>;
     /** Serialised `RetryPolicy` — see `retry.ts`. */
     readonly retry: ColumnBuilder<unknown, "json", boolean>;
+    /**
+     * The APP's own scoping dimension. Opaque to the framework.
+     *
+     * Stored and returned verbatim, never interpreted — the framework does not
+     * know what a team, a project or a workspace is, and does not need to. Reads
+     * filter on equality against the json you wrote:
+     *
+     *   subscribe({ event, url, scope: { teamId: 'q970…' } })
+     *   listTargets({ scope: { teamId } })
+     *
+     * It exists because `.with(tenant())` is one level too coarse for real
+     * deployments. A consumer's endpoints are scoped to a TEAM and a tenant has
+     * many teams; every read filters by it and every write guards on it, so
+     * without this column the plugin cannot hold their rows at all and they keep
+     * a parallel table.
+     *
+     * The precedent is `_voltro_presence.meta`, and it is worth stating because
+     * it decided a migration: that column is json the framework stores and never
+     * interprets, and it is the ONLY reason the same consumer's presence
+     * migration was lossless — their three denormalised columns went straight in.
+     * The general form: a plugin that stores rows in an app's database on the
+     * app's behalf needs one place for the app's own dimension.
+     */
+    readonly scope: 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. */