npm - @voltro/plugin-webhooks - Versions diffs - 0.24.0 → 0.26.0 - Mend

@voltro/plugin-webhooks 0.24.0 → 0.26.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/CHANGELOG.md +670 -0
package/dist/errors.d.ts +1 -1
package/dist/index.d.ts +196 -9
package/dist/index.js +368 -249
package/dist/mixin.d.ts +48 -0
package/dist/mixin.js +1 -0
package/dist/providers/index.js +1 -1
package/dist/{signing-BOUxHdAo.js → signing-DUG4JWwk.js} +29 -32
package/package.json +7 -7

package/dist/errors.d.ts CHANGED Viewed

@@ -18,7 +18,7 @@ declare const WebhookDeliveryNotFound_base: Schema.TaggedErrorClass<WebhookDeliv
 /**
  * Thrown by `WebhooksService.emit` when the payload does not decode
  * against the outgoing event's declared `payload` schema (from its
- * `defineOutgoingEvent` descriptor). The emit is rejected BEFORE any
+ * declared event's `webhook:` block). The emit is rejected BEFORE any
  * delivery row is written or workflow triggered — a schema-violating
  * payload never reaches a subscriber.
  */

package/dist/index.d.ts CHANGED Viewed

@@ -4,6 +4,8 @@ import { ColumnDefinition } from '@voltro/database';
 import { Context } from 'effect';
 import { DataStore } from '@voltro/database';
 import { Effect } from 'effect';
+import { EventDescriptor } from '@voltro/protocol';
+import { EventWebhookSpec } from '@voltro/protocol';
 import { FieldDefinitions } from '@voltro/database';
 import { Schema } from 'effect';
 import { Table } from '@voltro/database';
@@ -23,6 +25,24 @@ import { WorkflowInstance } from '@effect/workflow/WorkflowEngine';
  */
 export declare const acquireRateSlots: (store: DataStore, scopes: ReadonlyArray<RateScope>, now: number, windowMs?: number) => Promise<RateAcquireResult>;
+/**
+ * Project a declared event onto the outgoing-event descriptor this plugin
+ * already understands.
+ *
+ * A projection rather than a second registry: every downstream consumer —
+ * the delivery workflow, the JSON-Schema export, the dashboard's event list —
+ * keeps reading ONE shape. Adding a parallel path for declared events would
+ * mean each of them handles two, which is how the two drift.
+ *
+ * The event's `name` becomes the webhook `id`, so a subscriber that registered
+ * for `orders.paid` keeps working across the migration and the dashboard shows
+ * one event rather than two spellings of it.
+ */
+export declare const asOutgoingEvent: <Name extends string, Key, Payload>(descriptor: EventDescriptor<Name, never, never> & {
+    readonly payload: unknown;
+    readonly webhook?: EventWebhookSpec | undefined;
+}) => OutgoingEventDescriptor<Payload> | undefined;
 /** What `recordDeliveryOutcome` did — surfaced so the workflow can log
  *  the auto-disable transition. */
 export declare interface AutoDisableOutcome {
@@ -82,6 +102,22 @@ export declare interface CustomSignatureScheme {
     readonly verify: (rawBody: Uint8Array, secret: string, signatureHeader: string) => boolean;
 }
+/** The structural slice of a `defineEvent` descriptor this plugin needs.
+ *  Structural rather than an import so the plugin does not depend on a specific
+ *  protocol version's class identity. */
+export declare interface DeclaredEventLike {
+    readonly kind: 'event';
+    readonly name: string;
+    readonly payload: unknown;
+    readonly webhook?: {
+        readonly description?: string;
+        readonly version?: number;
+        readonly rateLimit?: {
+            readonly perMinute: number;
+        };
+    } | undefined;
+}
 /** Default URL path for an incoming webhook when the descriptor
  *  doesn't override. Stage 4's discovery walker uses this to
  *  register routes. */
@@ -97,8 +133,6 @@ export declare const defaultRetryPolicy: () => RetryPolicy;
 export declare const defineIncomingWebhook: <Body>(spec: Omit<IncomingWebhookDescriptor<Body>, "_tag">) => IncomingWebhookDescriptor<Body>;
-export declare const defineOutgoingEvent: <Payload>(spec: Omit<OutgoingEventDescriptor<Payload>, "_tag">) => OutgoingEventDescriptor<Payload>;
 export declare const defineWebhookProvider: (spec: Omit<WebhookProviderDescriptor, "_tag">) => WebhookProviderDescriptor;
 /**
@@ -125,7 +159,8 @@ export declare const deliverWebhookWorkflow: Workflow.Workflow<"voltro.deliverWe
 }>, typeof Schema.Never>;
 declare interface DeliverWorkflowOptions {
-    /** Discovered `defineOutgoingEvent` descriptors — the workflow reads
+    /** Discovered outgoing events (declared events with a `webhook:` block,
+     *  projected by `asOutgoingEvent`) — the workflow reads
      *  the emitted event's `globalRateLimit` from here. Absent events
      *  simply have no global limit. */
     readonly events?: ReadonlyArray<OutgoingEventDescriptor<unknown>>;
@@ -134,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}`;
@@ -176,6 +234,11 @@ export declare const getIdempotencyCache: () => IdempotencyCache;
 /** GitHub-style: `X-Hub-Signature-256: sha256=hex` (no timestamp). */
 export declare const githubSignature: () => HmacSignatureScheme;
+/** Does this declared event opt into outbound HTTP delivery? */
+export declare const hasWebhookAudience: (descriptor: {
+    readonly webhook?: EventWebhookSpec | undefined;
+}) => boolean;
 export declare type HmacAlgorithm = 'hmacSha256' | 'hmacSha1';
 export declare interface HmacSignatureScheme {
@@ -478,7 +541,7 @@ export declare const releaseRateSlot: (store: DataStore, key: string, bucket: nu
  *  Default resolution is three-tiered: the subscriber's explicit
  *  value wins, then the event descriptor's per-event defaults
  *  (`defaultSigning` / `defaultRetry` / `version` from
- *  `defineOutgoingEvent`), then the package-global defaults. */
+ *  the declared event's `webhook:` block), then the package-global defaults. */
 export declare const resolveSubscribe: (input: SubscribeInput, event?: OutgoingEventDescriptor<unknown>) => {
     readonly id: string;
     readonly event: string;
@@ -487,6 +550,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;
@@ -569,6 +633,15 @@ 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>>;
+    /**
+     * 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';
@@ -592,10 +665,25 @@ 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";
 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;
@@ -781,6 +869,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. */
@@ -868,7 +980,7 @@ export declare type WebhookId = string;
 /**
  * Thrown by `WebhooksService.emit` when the payload does not decode
  * against the outgoing event's declared `payload` schema (from its
- * `defineOutgoingEvent` descriptor). The emit is rejected BEFORE any
+ * declared event's `webhook:` block). The emit is rejected BEFORE any
  * delivery row is written or workflow triggered — a schema-violating
  * payload never reaches a subscriber.
  */
@@ -940,7 +1052,7 @@ export declare class WebhooksService extends WebhooksService_base {
 declare const WebhooksService_base: Context.TagClass<WebhooksService, "@voltro/webhooks/WebhooksService", WebhooksServiceShape>;
 export declare interface WebhooksServiceOptions {
-    /** Discovered `defineOutgoingEvent` descriptors. When present,
+    /** Discovered outgoing events (projected from declared events). When present,
      *  `subscribe` resolves the event's `defaultSigning` /
      *  `defaultRetry` / `version` before the package-global defaults,
      *  and `emit` decodes the payload against the event's schema. */
@@ -950,13 +1062,13 @@ export declare interface WebhooksServiceOptions {
 export declare interface WebhooksServiceShape {
     readonly subscribe: (input: SubscribeInput) => Promise<SubscribeResult>;
     /** Emit an event to every subscribed target. Accepts the event id
-     *  OR the `defineOutgoingEvent` descriptor itself — passing the
+     *  OR the declared event itself — passing the
      *  descriptor types `payload` against its schema at the call site.
      *  Either way, when the descriptor is known (directly or via the
      *  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>, payload: P) => Promise<EmitResult>;
+    readonly emit: <P>(event: string | OutgoingEventDescriptor<P> | DeclaredEventLike, payload: P) => 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. */
@@ -964,7 +1076,12 @@ 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
@@ -994,6 +1111,52 @@ 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: (targetId: string, 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;
+        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>;
 }
 /**
@@ -1042,6 +1205,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. */