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

@voltro/plugin-webhooks 0.24.0 → 0.25.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 (7) hide show

package/CHANGELOG.md +426 -0
package/dist/errors.d.ts +1 -1
package/dist/index.d.ts +48 -8
package/dist/index.js +183 -173
package/dist/providers/index.js +1 -1
package/dist/{signing-BOUxHdAo.js → signing-DUG4JWwk.js} +29 -32
package/package.json +7 -7

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>>;
@@ -176,6 +211,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 +518,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;
@@ -868,7 +908,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 +980,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 +990,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. */