@voltro/plugin-webhooks 0.28.0 → 0.30.0

package/THIRD-PARTY-NOTICES.md

@@ -5,7 +5,7 @@ property of its respective copyright holders and is used under the terms of
 its license. This file is provided for attribution; it grants no rights in
 @voltro/plugin-webhooks itself, which is proprietary (see LICENSE).
 
-Generated from the resolved runtime dependency closure (49 packages).
+Generated from the resolved runtime dependency closure (52 packages).
 
 ---
 
@@ -3956,6 +3956,34 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 ```
 
+## isomorphic.js@0.2.5
+
+License: MIT
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2020 Kevin Jahns <kevin.jahns@protonmail.com>.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
 ## jose@6.2.4
 
 License: MIT
@@ -4018,6 +4046,34 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
+## lib0@0.2.117
+
+License: MIT
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2019 Kevin Jahns <kevin.jahns@protonmail.com>.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
 ## mime@3.0.0
 
 License: MIT
@@ -4566,3 +4622,33 @@ IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 ```
 
+## yjs@13.6.31
+
+License: MIT
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2023
+  - Kevin Jahns <kevin.jahns@protonmail.com>.
+  - Chair of Computer Science 5 (Databases & Information Systems), RWTH Aachen University, Germany
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+

package/dist/index.d.ts

@@ -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';