npm - @voltro/plugin-webhooks - Versions diffs - 0.29.0 → 0.30.1 - Mend

@voltro/plugin-webhooks 0.29.0 → 0.30.1

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/dist/index.d.ts CHANGED Viewed

@@ -7,11 +7,13 @@ import { Effect } from 'effect';
 import { EventDescriptor } from '@voltro/protocol';
 import { EventWebhookSpec } from '@voltro/protocol';
 import { FieldDefinitions } from '@voltro/database';
+import { OutboxHandlerDefinition } from '@voltro/runtime';
 import { Schema } from 'effect';
 import { Table } from '@voltro/database';
 import { Workflow } from '@effect/workflow';
 import { WorkflowEngine } from '@effect/workflow/WorkflowEngine';
 import { WorkflowInstance } from '@effect/workflow/WorkflowEngine';
+import { WorkflowRunHandle } from '@voltro/protocol';
 /**
  * Acquire one slot in EVERY scope for the window containing `now`
@@ -63,14 +65,6 @@ export declare const buildDeliverWebhookExecute: (ctx: AppContext, options?: Del
     attempts: number;
 }, never, WorkflowEngine | WorkflowInstance>;
-/**
- * Build a `WebhooksServiceShape` that uses the in-process store
- * directly + an injected `trigger` for delivery. The `trigger` is
- * the seam where the framework wires the actual @effect/workflow
- * runner (stage 4). For tests and the very first dev-mode loop we
- * accept a simple async function that resolves when the workflow
- * has been kicked off (NOT when it completes).
- */
 export declare const buildWebhooksService: (ctx: AppContext, trigger: (input: {
     readonly deliveryId: string;
     readonly targetId: string;
@@ -131,6 +125,13 @@ export declare const defaultOutgoingSignature: () => HmacSignatureScheme;
  *  640s. Total ~17 minutes before giving up. */
 export declare const defaultRetryPolicy: () => RetryPolicy;
+/** The row payload. Deliberately flat and JSON-only — see the header. */
+export declare interface DeferredEmitPayload {
+    readonly event: string;
+    readonly payload: unknown;
+    readonly tenantId: string | null;
+}
 export declare const defineIncomingWebhook: <Body>(spec: Omit<IncomingWebhookDescriptor<Body>, "_tag">) => IncomingWebhookDescriptor<Body>;
 export declare const defineWebhookProvider: (spec: Omit<WebhookProviderDescriptor, "_tag">) => WebhookProviderDescriptor;
@@ -219,6 +220,30 @@ export declare type DurationLiteral = `${number}${'ms' | 's' | 'm' | 'h' | 'd'}`
 export declare interface EmitOptions {
     /** Only deliver to targets of this tenant. Absent ⇒ every target. */
     readonly tenantId?: string | null;
+    /**
+     * Dispatch NOW instead of after the enclosing transaction commits.
+     *
+     * Inside a mutation, `emit` defaults to a transactional enqueue: the intent
+     * commits with your rows or rolls back with them, and the POST goes out
+     * afterwards. That is the right default and it is not the right answer
+     * everywhere — a diagnostic ping, or an emit whose receiver the caller is
+     * about to poll, wants the request on the wire immediately.
+     *
+     * It does NOT make the emit safe. A rollback after an immediate emit still
+     * tells a subscriber about a change that did not happen. The point of the flag
+     * is that the trade is written at the call site: the old behaviour was
+     * un-transactional by accident, and nothing said so.
+     *
+     * Outside a mutation this is a no-op — there is no transaction to skip.
+     *
+     * **Read by `ctx.webhooks`, not by this service.** The deferral lives in the
+     * request-scoped proxy (`cli/src/requestWebhooks.ts`), because only the
+     * request knows whether there is a transaction; the boot-level service is
+     * always immediate by construction. The option is declared here because this
+     * is the type a caller sees — but calling the boot service directly with it
+     * changes nothing, and that is the truthful behaviour rather than a gap.
+     */
+    readonly immediate?: boolean;
 }
 export declare interface EmitResult {
@@ -410,12 +435,7 @@ export declare interface IncomingWebhookDescriptor<Body> {
 }
 export 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;
@@ -442,6 +462,33 @@ export declare interface IncomingWorkflowFacade {
  *  must default-export one of these. */
 export declare const isWebhookDescriptor: (value: unknown) => value is WebhookDescriptor;
+/**
+ * Build the handler that performs a deferred emit after commit.
+ *
+ * `emitter` is the BOOT-level service — the same object `ctx.webhooks` proxies.
+ * By the time this runs the transaction is gone, so the tenant cannot be read
+ * from a request subject and travels in the row instead.
+ *
+ * `maxAttempts` is 1 on purpose and it is not a shortcut. The work here is
+ * "resolve targets and start a delivery workflow"; the DELIVERY itself already
+ * has its own retry policy per target, with backoff, a delivery-history table
+ * and a dashboard replay button. Retrying the fan-out on top would multiply the
+ * two schedules together and produce duplicate delivery rows for one emit —
+ * retrying a retry is how a webhook storm starts. What the outbox adds here is
+ * the guarantee that the fan-out HAPPENS at all, which is precisely the crash
+ * window the after-commit callback left open.
+ */
+export declare const makeDeferredEmitHandler: (
+/**
+ * Resolved LAZILY, and it has to be. `voltro dev` starts the outbox runner
+ * before it builds the webhooks service (the service needs a trigger context
+ * that needs the workflow engine), while `voltro serve` builds them the other
+ * way round. A thunk is the one shape both orders can register, so the two
+ * boot paths cannot disagree about whether this handler exists — which is the
+ * drift class this repo keeps re-learning.
+ */
+emitter: () => Pick<WebhooksServiceShape, "emit"> | undefined) => OutboxHandlerDefinition;
 /** Evaluate a target's filter against a payload. Returns `true`
  *  when the target should receive this delivery. Supports the
  *  simple key-path form `'payload.field': value` for v1; future
@@ -592,6 +639,7 @@ forEvent?: string, sharedSecret?: string) => {
     readonly autoDisableReason: string | null;
     readonly payloadVersion: number;
     readonly description: string | null;
+    readonly tenantId: string | null;
 };
 export declare interface RetryDecision {
@@ -654,6 +702,30 @@ export declare const stripeSignature: (header?: string) => HmacSignatureScheme;
 export declare interface SubscribeInput {
     /** A single event. Use `events` for a multi-event subscription. */
     readonly event?: string;
+    /**
+     * The tenant this subscription belongs to.
+     *
+     * **You should not normally pass this.** `ctx.webhooks.subscribe(...)` binds it
+     * from the acting subject, exactly as `emit` binds `EmitOptions.tenantId` — it
+     * is here for the same reason the read side has it, and for the admin tooling
+     * the error message names.
+     *
+     * It exists because the write path had NO binding at all and no way to supply
+     * one. `_voltro_webhook_targets` carries `.with(tenant())`, the mixin scopes by
+     * the REQUEST subject, and this service is built once at boot with the app-level
+     * store and no subject. So `subscribe` from an authenticated executor died with
+     * `TenantScopeViolation: cannot insert into tenant-scoped table without an
+     * authenticated tenant` — and both escapes that message offered were
+     * unreachable: you cannot "authenticate first" (the service is subject-less by
+     * construction) and you could not "pass tenantId explicitly" (this field did not
+     * exist).
+     *
+     * A consumer hit it on every subscribe for the life of the feature. The
+     * consequence worth recording: their `count(*) FROM _voltro_webhook_targets = 0`
+     * did not mean "unused", it meant "never worked" — and both sides read that zero
+     * as reassurance.
+     */
+    readonly tenantId?: string | null;
     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
@@ -857,7 +929,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. */
@@ -892,6 +964,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
@@ -1029,6 +1155,11 @@ export declare const _voltroWebhookTargetsTable: Table<"_voltro_webhook_targets"
     readonly updatedBy: ColumnDefinition<string | null, "reference", boolean>;
 }, true, never>;
+/** The effect name. Namespaced under `voltro.` because it is framework-owned:
+ *  an app's own `*.outbox.ts` may not claim it, and the loader's
+ *  duplicate-effect check is what enforces that. */
+export declare const WEBHOOK_EMIT_EFFECT = "voltro.webhook.emit";
 /**
  * Thrown by `WebhooksService.replay` when no delivery row exists for the
  * given `deliveryId` — the row can't be re-triggered because the
@@ -1409,7 +1540,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. */
@@ -1455,6 +1586,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 declare type WireFormat = 'json' | 'form' | 'xml';