@voltro/plugin-webhooks 0.29.0 → 0.30.1

package/dist/mixin.d.ts

@@ -32,7 +32,7 @@ export declare const _voltroWebhookDeliveriesTable: Table<"_voltro_webhook_deliv
     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>;
+    readonly status: ColumnBuilder<"failed" | "succeeded" | "inFlight" | "pending" | "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. */
@@ -67,6 +67,60 @@ export declare const _voltroWebhookDeliveriesTable: Table<"_voltro_webhook_deliv
     readonly updatedBy: ColumnDefinition<string | null, "reference", boolean>;
 }, true, never>;
 
+/**
+ * ONE row per declared event, stamped every time `emit` runs.
+ *
+ * **Why this is not derivable from `_voltro_webhook_deliveries`, which is the
+ * whole reason the table exists.** A delivery row is written when an emit MATCHES
+ * a target. So "no delivery rows" conflates three different facts:
+ *
+ *   1. no `emit(...)` call site exists, or none ever ran   ← the defect
+ *   2. it ran, but nobody was subscribed yet
+ *   3. it ran, but every target's `filter` excluded the payload, or every
+ *      target was paused
+ *
+ * Only (1) is a bug, and it is the one a consumer spent a week finding by hand:
+ * seven of eleven advertised events had no emit call site anywhere. Reading (2)
+ * or (3) as (1) turns a working integration into a false alarm; reading (1) as
+ * (2) hides it. Delivery history also ages out — `_voltro_webhook_deliveries`
+ * carries a 90-day retention — so an event emitted correctly and quietly can
+ * decay into looking dead.
+ *
+ * This row is written REGARDLESS of whether any target matched, which is
+ * precisely the axis history cannot see. The dashboard shows both, labelled,
+ * and their disagreement is itself the useful signal: emitted but never
+ * delivered means every target is paused, filtered out, or failing.
+ *
+ * Deliberately NOT tenant-scoped. The question is "does this event have a live
+ * call site in this deployment", which is a property of the CODE, not of a
+ * tenant's data — and scoping it per tenant would make an event look dead for
+ * every tenant that has not happened to trigger it yet.
+ */
+export declare const _voltroWebhookEventStatsTable: Table<"_voltro_webhook_event_stats", FieldDefinitions<{
+    /**
+     * A GENERATED id. The event name is the natural key and it is deliberately
+     * NOT reused here.
+     *
+     * An `id()` column is `VARCHAR(64)` on MySQL/MariaDB (`applier.ts`), while an
+     * event name is allowed 191. Using the name as the id would make a namespaced
+     * event longer than 64 characters fail its insert — and because the stats
+     * write is best-effort and swallows every error, it would fail SILENTLY and
+     * the dashboard would report "never emitted" for a live event. That is
+     * precisely the false positive this table exists to remove, reintroduced by
+     * its own primary key, on exactly the dialect that reported the original
+     * defect.
+     */
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    /** The natural key. Unique, so a concurrent double-insert loses rather than
+     *  duplicating the row. */
+    readonly event: ColumnBuilder<string, "text", boolean>;
+    /** Total emits seen, including those that matched no target. */
+    readonly emitCount: ColumnBuilder<number, "integer", true>;
+    readonly lastEmitAt: ColumnBuilder<Date, "timestamp", boolean>;
+    readonly createdAt: ColumnBuilder<Date, "timestamp", boolean>;
+    readonly updatedAt: ColumnBuilder<Date, "timestamp", boolean>;
+}>, true, never>;
+
 /**
  * Fixed-window rate-limit counters — one row per (scope, minute
  * bucket), where scope is `target:<targetId>` (per-target
@@ -330,7 +384,7 @@ export declare const webhookTables: () => readonly [ Table<"_voltro_webhook_targ
     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>;
+    readonly status: ColumnBuilder<"failed" | "succeeded" | "inFlight" | "pending" | "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. */
@@ -376,6 +430,29 @@ export declare const webhookTables: () => readonly [ Table<"_voltro_webhook_targ
     readonly count: ColumnBuilder<number, "integer", true>;
     readonly createdAt: ColumnBuilder<Date, "timestamp", boolean>;
     readonly updatedAt: ColumnBuilder<Date, "timestamp", boolean>;
+}>, true, never>, Table<"_voltro_webhook_event_stats", FieldDefinitions<{
+    /**
+     * A GENERATED id. The event name is the natural key and it is deliberately
+     * NOT reused here.
+     *
+     * An `id()` column is `VARCHAR(64)` on MySQL/MariaDB (`applier.ts`), while an
+     * event name is allowed 191. Using the name as the id would make a namespaced
+     * event longer than 64 characters fail its insert — and because the stats
+     * write is best-effort and swallows every error, it would fail SILENTLY and
+     * the dashboard would report "never emitted" for a live event. That is
+     * precisely the false positive this table exists to remove, reintroduced by
+     * its own primary key, on exactly the dialect that reported the original
+     * defect.
+     */
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    /** The natural key. Unique, so a concurrent double-insert loses rather than
+     *  duplicating the row. */
+    readonly event: ColumnBuilder<string, "text", boolean>;
+    /** Total emits seen, including those that matched no target. */
+    readonly emitCount: ColumnBuilder<number, "integer", true>;
+    readonly lastEmitAt: ColumnBuilder<Date, "timestamp", boolean>;
+    readonly createdAt: ColumnBuilder<Date, "timestamp", boolean>;
+    readonly updatedAt: ColumnBuilder<Date, "timestamp", boolean>;
 }>, true, never>];
 
 export { }

package/dist/mixin.js

@@ -52,7 +52,14 @@ var u = o("_voltro_webhook_targets", {
 	count: n().default(0),
 	createdAt: c(),
 	updatedAt: c()
-}), p = () => (i({
+}), p = o("_voltro_webhook_event_stats", {
+	id: t({ prefix: "whstat" }),
+	event: s().maxLength(191).unique(),
+	emitCount: n().default(0),
+	lastEmitAt: c(),
+	createdAt: c(),
+	updatedAt: c()
+}), m = () => (i({
 	table: "_voltro_webhook_deliveries",
 	timeColumn: "createdAt",
 	ttlMs: a(process.env.VOLTRO_WEBHOOK_DELIVERIES_TTL_HOURS, 2160)
@@ -63,7 +70,8 @@ var u = o("_voltro_webhook_targets", {
 }), [
 	u,
 	d,
-	f
+	f,
+	p
 ]);
 //#endregion
-export { d as _voltroWebhookDeliveriesTable, f as _voltroWebhookRateWindowsTable, u as _voltroWebhookTargetsTable, p as webhookTables };
+export { d as _voltroWebhookDeliveriesTable, p as _voltroWebhookEventStatsTable, f as _voltroWebhookRateWindowsTable, u as _voltroWebhookTargetsTable, m as webhookTables };

package/dist/providers/index.d.ts

@@ -1,4 +1,5 @@
 import { Schema } from 'effect';
+import { WorkflowRunHandle } from '@voltro/protocol';
 
 declare interface CustomSignatureScheme {
     readonly _tag: 'custom';
@@ -106,12 +107,7 @@ declare interface IncomingWebhookDescriptor<Body> {
 }
 
 declare interface IncomingWorkflowFacade {
-    start<Payload = unknown>(workflowName: string, payload: Payload): Promise<{
-        readonly id: string;
-        readonly workflowName: string;
-        readonly executionId: string;
-        readonly status: 'running';
-    }>;
+    start<Payload = unknown>(workflowName: string, payload: Payload): Promise<WorkflowRunHandle>;
     signal(target: {
         readonly id?: string;
         readonly executionId?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-webhooks",
-  "version": "0.29.0",
+  "version": "0.30.1",
   "description": "Webhooks plugin — first-class outgoing (multi-target, durable-workflow delivery, HMAC signing, retry policies, rate limits) + incoming (signature verification, idempotency, provider templates for Stripe / GitHub / Slack / generic).",
   "keywords": [
     "voltro",
@@ -48,12 +48,12 @@
   },
   "dependencies": {
     "@effect/workflow": "^0.19.0",
-    "@voltro/database": "0.29.0",
-    "@voltro/integration-http": "0.29.0",
-    "@voltro/logger": "0.29.0",
-    "@voltro/plugin-multitenancy": "0.29.0",
-    "@voltro/protocol": "0.29.0",
-    "@voltro/runtime": "0.29.0"
+    "@voltro/database": "0.30.1",
+    "@voltro/integration-http": "0.30.1",
+    "@voltro/logger": "0.30.1",
+    "@voltro/plugin-multitenancy": "0.30.1",
+    "@voltro/protocol": "0.30.1",
+    "@voltro/runtime": "0.30.1"
   },
   "peerDependencies": {
     "effect": "^3.22.0"