@trigger.dev/sdk 4.7.4 → 4.8.0-webhooks.20261015065339

package/dist/commonjs/v3/webhookWaiters.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookWaiterPromise = void 0;
+exports.createWebhookWaiter = createWebhookWaiter;
+exports.waitForWebhookWaiter = waitForWebhookWaiter;
+exports.cancelWebhookWaiter = cancelWebhookWaiter;
+const api_1 = require("@opentelemetry/api");
+const v3_1 = require("@trigger.dev/core/v3");
+const ioSerialization_1 = require("@trigger.dev/core/v3/utils/ioSerialization");
+const tracer_js_1 = require("./tracer.js");
+/**
+ * Register a waiter on an endpoint: the next matching delivery that arrives after this call resumes
+ * whoever waits on it. Create it before doing whatever makes the provider send the webhook, and match
+ * on values you control (like your own order id in the event's metadata). Works inside a run and from
+ * your backend.
+ *
+ * @example
+ * ```ts
+ * const waiter = await webhooks.waiter.create(payments, {
+ *   match: { "event.data.object.metadata.orderId": order.id, "event.type": "payment_intent.succeeded" },
+ *   timeout: "1h",
+ * });
+ * await stripe.paymentIntents.create({ amount: 4200, currency: "usd", metadata: { orderId: order.id } });
+ * const { event } = await webhooks.waiter.wait(waiter).unwrap();
+ * ```
+ */
+async function createWebhookWaiter(endpoint, options = {}, requestOptions) {
+    const apiClient = v3_1.apiClientManager.clientOrThrow();
+    const idempotencyKey = (await (0, v3_1.makeIdempotencyKey)(options.idempotencyKey)) ?? globalThis.crypto.randomUUID();
+    const timeout = options.timeout instanceof Date ? options.timeout.toISOString() : options.timeout;
+    try {
+        const result = await apiClient.createWebhookWaiter(endpoint.id, {
+            ...(options.match ? { match: options.match } : {}),
+            ...(options.filter ? { filter: options.filter } : {}),
+            ...(timeout ? { timeout } : {}),
+            ...(options.tags ? { tags: options.tags } : {}),
+            idempotencyKey,
+            ...(options.idempotencyKeyTTL ? { idempotencyKeyTTL: options.idempotencyKeyTTL } : {}),
+        }, (0, v3_1.mergeRequestOptions)({
+            tracer: tracer_js_1.tracer,
+            name: "webhooks.waiter.create()",
+            icon: "wait",
+            attributes: {
+                endpoint: endpoint.id,
+                ...(options.match ? { match: Object.keys(options.match).join(", ") } : {}),
+            },
+            onResponseBody: (body, span) => span.setAttribute("id", body.id),
+        }, requestOptions));
+        return result;
+    }
+    catch (error) {
+        throw toWebhookWaiterError(error);
+    }
+}
+function toWebhookWaiterError(error) {
+    if (!(error instanceof v3_1.ApiError))
+        return error;
+    const body = error.body;
+    const message = typeof body?.error === "string" ? body.error : error.message;
+    switch (error.code) {
+        case "webhook_waiter_limit":
+            return new v3_1.WebhookWaiterLimitError(body?.reason ?? "endpoint_limit", message);
+        case "webhook_endpoint_not_found":
+            return new v3_1.WebhookEndpointNotFoundError(message);
+        case "webhook_filter_invalid":
+            return new v3_1.WebhookFilterError(message);
+        default:
+            return error;
+    }
+}
+/** A waiter's result. `.unwrap()` returns the output or throws its typed error. */
+class WebhookWaiterPromise extends Promise {
+    unwrap() {
+        return this.then((result) => {
+            if (result.ok)
+                return result.output;
+            throw result.error;
+        });
+    }
+}
+exports.WebhookWaiterPromise = WebhookWaiterPromise;
+function waiterIdOf(waiter) {
+    return typeof waiter === "string" ? waiter : waiter.id;
+}
+/**
+ * Suspend the current run until the waiter matches a delivery, times out or is cancelled. Only inside
+ * `task.run()`. The result's error is a `WaitpointTimeoutError` or a `WebhookWaiterCancelledError`.
+ */
+function waitForWebhookWaiter(waiter) {
+    return new WebhookWaiterPromise(async (resolve, reject) => {
+        try {
+            const ctx = v3_1.taskContext.ctx;
+            if (!ctx) {
+                throw new Error("webhooks.waiter.wait can only be used from inside a task.run()");
+            }
+            const apiClient = v3_1.apiClientManager.clientOrThrow();
+            const waiterId = waiterIdOf(waiter);
+            const result = await tracer_js_1.tracer.startActiveSpan("webhooks.waiter.wait()", async (span) => {
+                const response = await apiClient.waitForWaitpointToken({
+                    runFriendlyId: ctx.run.id,
+                    waitpointFriendlyId: waiterId,
+                });
+                if (!response.success) {
+                    throw new Error(`Failed to wait for webhook waiter ${waiterId}`);
+                }
+                const completion = await v3_1.runtime.waitUntil(waiterId);
+                const data = completion.output
+                    ? await (0, ioSerialization_1.conditionallyImportAndParsePacket)({ data: completion.output, dataType: completion.outputType ?? "application/json" }, apiClient)
+                    : undefined;
+                if (completion.ok) {
+                    return { ok: true, output: data };
+                }
+                const failure = data;
+                const error = failure?.name === "WebhookWaiterCancelledError"
+                    ? new v3_1.WebhookWaiterCancelledError(failure.message)
+                    : new v3_1.WaitpointTimeoutError(failure?.message ?? "The webhook waiter timed out");
+                span.recordException(error);
+                span.setStatus({ code: api_1.SpanStatusCode.ERROR });
+                return { ok: false, error };
+            }, {
+                attributes: {
+                    [v3_1.SemanticInternalAttributes.STYLE_ICON]: "wait",
+                    [v3_1.SemanticInternalAttributes.ENTITY_TYPE]: "waitpoint",
+                    [v3_1.SemanticInternalAttributes.ENTITY_ID]: waiterId,
+                    id: waiterId,
+                    ...(0, v3_1.accessoryAttributes)({
+                        items: [{ text: waiterId, variant: "normal" }],
+                        style: "codepath",
+                    }),
+                },
+            });
+            resolve(result);
+        }
+        catch (error) {
+            reject(error);
+        }
+    });
+}
+/**
+ * Cancel a waiter: frees its slot and fails its wait with `WebhookWaiterCancelledError`. If a delivery
+ * already claimed it, this is too late and the waiting run resumes with that delivery.
+ */
+async function cancelWebhookWaiter(waiter, requestOptions) {
+    const apiClient = v3_1.apiClientManager.clientOrThrow();
+    const waiterId = waiterIdOf(waiter);
+    const result = await apiClient.cancelWebhookWaiter(waiterId, (0, v3_1.mergeRequestOptions)({
+        tracer: tracer_js_1.tracer,
+        name: "webhooks.waiter.cancel()",
+        icon: "wait",
+        attributes: { id: waiterId },
+    }, requestOptions));
+    return result.cancelled
+        ? { cancelled: true }
+        : { cancelled: false, reason: "too_late", deliveryId: result.deliveryId ?? "" };
+}
+//# sourceMappingURL=webhookWaiters.js.map

package/dist/commonjs/v3/webhookWaiters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhookWaiters.js","sourceRoot":"","sources":["../../../src/v3/webhookWaiters.ts"],"names":[],"mappings":"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"}

package/dist/commonjs/v3/webhooks.d.ts

@@ -1,4 +1,8 @@
 import { Webhook } from "@trigger.dev/core/v3";
+import type { WebhookSource, InferWebhookEvent, AnyWebhookSource, ValidateWebhookFilter, NarrowWebhookEvent, ChatEvent, ValidatedWebhookKey, WebhookResponseConfig, WebhookUrlSecretConfig, WebhookVerifierConfig, StripeWebhookEvent, GitHubWebhookEvent, TaskRunContext, AnyWebhookEndpoint, InferWebhookEndpointEvent, WebhookEndpoint, WebhookEndpointContext } from "@trigger.dev/core/v3";
+import { cancelWebhookWaiter, createWebhookWaiter, waitForWebhookWaiter } from "./webhookWaiters.js";
+import { type Task } from "./shared.js";
+import { type WebhookProviderId } from "@trigger.dev/core/webhooks";
 /**
  * The type of error thrown when a webhook fails to parse or verify
  */
@@ -14,6 +18,153 @@ type ConstructEventOptions = {
     /** Signature header as string, Buffer, or string array */
     header: string | Buffer | Array<string>;
 };
+/**
+ * The verifier configs a hosted endpoint can enforce. A `url-secret` placed in the path is excluded:
+ * the hosted ingress URL is fixed per endpoint, so there is no path segment for the caller to choose,
+ * and the server refuses such a declaration at deploy time. Use `placement: "query"` instead.
+ */
+export type HostedWebhookVerifierConfig = Exclude<WebhookVerifierConfig, WebhookUrlSecretConfig> | (Omit<WebhookUrlSecretConfig, "placement"> & {
+    placement: "query";
+});
+export declare const webhookSources: {
+    readonly custom: <T = unknown>(config: HostedWebhookVerifierConfig, options?: {
+        /** Instructions for an AI agent registering an endpoint on this source with the provider. */
+        setupPrompt?: string;
+        /**
+         * How the endpoint answers the provider. `{ acceptedBody: "empty" }` acknowledges with an empty
+         * 200, for providers that show the response to a user (Slack slash commands).
+         */
+        response?: WebhookResponseConfig;
+    }) => WebhookSource<T>;
+    readonly stripe: <TEvent = StripeWebhookEvent>(opts?: {
+        toleranceSeconds?: number;
+    }) => WebhookSource<TEvent>;
+    readonly github: <TEvent = GitHubWebhookEvent>() => WebhookSource<TEvent>;
+    readonly svix: <T = unknown>() => WebhookSource<T>;
+    readonly standardWebhooks: <T = unknown>() => WebhookSource<T>;
+    readonly square: <T = unknown>() => WebhookSource<T>;
+    /**
+     * Discord: asymmetric Ed25519 over `{timestamp}{body}`. The "secret" stored on the endpoint is the
+     * application PUBLIC KEY (hex by default); there is no shared secret. Discord's response contract
+     * is declared as data on the artifact: the `{ type: 0 }` PING sent when the URL is saved is answered
+     * with a bodiless 204 and never recorded, accepted events are acknowledged with 204, and a bad
+     * signature gets 401.
+     */
+    readonly discord: <T = unknown>(opts?: {
+        publicKeyEncoding?: "raw-hex" | "pem";
+    }) => WebhookSource<T>;
+    /**
+     * Per-provider producers over shared presets. Each is a thin wrapper: same verifier config as the
+     * preset it references, differing only in `provider` (routing + picker identity) and who provisions
+     * the secret. Pass the provider's own published type for full typing, e.g. clerk<WebhookEvent>().
+     */
+    readonly clerk: <T = unknown>() => WebhookSource<T>;
+    readonly resend: <T = unknown>() => WebhookSource<T>;
+    readonly openai: <T = unknown>() => WebhookSource<T>;
+    readonly replicate: <T = unknown>() => WebhookSource<T>;
+    readonly recallai: <T = unknown>() => WebhookSource<T>;
+    readonly brex: <T = unknown>() => WebhookSource<T>;
+    readonly composio: <T = unknown>() => WebhookSource<T>;
+    readonly gitlab: <T = unknown>() => WebhookSource<T>;
+    /**
+     * WhatsApp Cloud API (Meta): `X-Hub-Signature-256` HMAC over the raw body, keyed by the App Secret,
+     * which Meta issues and you paste in as the endpoint's signing secret (it cannot be generated here).
+     * Meta verifies the callback URL with a GET carrying `hub.mode`, `hub.verify_token` and
+     * `hub.challenge`; the endpoint answers it when the token equals the verify token generated in
+     * the endpoint's Connect panel, which you paste into Meta's Verify Token field.
+     */
+    readonly whatsapp: <T = unknown>() => WebhookSource<T>;
+};
+type CamelCase<S extends string> = S extends `${infer Head}-${infer Tail}` ? `${Head}${Capitalize<CamelCase<Tail>>}` : S;
+/**
+ * Per-provider producers generated from the core config table (kind "config"). Each carries the
+ * provider's own HMAC verifier config and stays in lockstep with the round-trip-tested configs.
+ * The method is the provider id in camel case (`cal-com` is `webhooks.calCom()`); the emitted
+ * `provider` keeps the id itself.
+ */
+export type ProviderProducers = {
+    [K in Exclude<WebhookProviderId, "zoom"> as CamelCase<K>]: <TEvent = unknown>() => WebhookSource<TEvent>;
+};
+export declare const providerProducers: Omit<ProviderProducers, "slack">;
+export type WebhookEndpointOptions<TIdentifier extends string, TSource extends AnyWebhookSource> = {
+    /** The endpoint id. Subscribers reference the endpoint, and it names the endpoint's URL. */
+    id: TIdentifier;
+    /** The provider source: how deliveries are verified and who issues the signing secret. */
+    source: TSource;
+    description?: string;
+    /** Arbitrary metadata, passed to every subscriber and waiter as `endpoint.metadata`. */
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Declare a webhook endpoint: one URL you register with the provider. Subscribe to it with
+ * `webhook({ endpoint })`, `chat.event({ endpoint })` or a channel connector, and wait on it with
+ * `webhooks.waiter.create(endpoint, ...)`. An endpoint with no subscribers still gets a URL.
+ */
+export declare function defineWebhookEndpoint<TIdentifier extends string, TSource extends AnyWebhookSource>(options: WebhookEndpointOptions<TIdentifier, TSource>): WebhookEndpoint<InferWebhookEvent<TSource>> & {
+    id: TIdentifier;
+};
+export type WebhookOnEventParams<TEvent> = {
+    /** The verified event body, typed by the endpoint's source. */
+    event: TEvent;
+    /** The inbound request headers (case-insensitive, Web `Headers`). e.g. headers.get("x-github-event"). */
+    headers: Headers;
+    /** The endpoint the delivery arrived on. Unset when the task is triggered by hand without one. */
+    endpoint?: WebhookEndpointContext;
+    ctx: TaskRunContext;
+};
+export type WebhookOptions<TIdentifier extends string, TEndpoint extends AnyWebhookEndpoint, TEvent = InferWebhookEndpointEvent<TEndpoint>> = {
+    id: TIdentifier;
+    /** The endpoint this task subscribes to. */
+    endpoint: TEndpoint;
+    /**
+     * Optional server-side filter (a type-safe string DSL checked against the event shape). A delivery
+     * this subscriber's filter rejects is still recorded, and other subscribers on the endpoint still
+     * get it. e.g. `"event.action == 'created' && event.repository.private == false"`.
+     */
+    filter?: string;
+    /** Gets the event narrowed by the filter's `event.<field> == '<value>'` clauses. */
+    onEvent: (params: WebhookOnEventParams<TEvent>) => Promise<void> | void;
+};
+/**
+ * What a webhook task runs on: the verified event, the delivery headers and the endpoint. The hosted
+ * ingress sends it for every delivery; triggering the handle by hand (`myWebhook.trigger({ event })`,
+ * a replay, a test) sends the same shape, so `onEvent` sees the event either way.
+ */
+export type WebhookTaskPayload<TEvent> = {
+    event: TEvent;
+    headers?: Record<string, string>;
+    endpoint?: WebhookEndpointContext;
+};
+export type WebhookHandle<TIdentifier extends string, TEvent> = Task<TIdentifier, WebhookTaskPayload<TEvent>, void>;
+export declare function webhook<TIdentifier extends string, TEndpoint extends AnyWebhookEndpoint, const TFilter extends string = string>(options: WebhookOptions<TIdentifier, TEndpoint, NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>> & {
+    filter?: ValidateWebhookFilter<InferWebhookEndpointEvent<TEndpoint>, TFilter>;
+}): WebhookHandle<TIdentifier, NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>>;
+export declare function chatEvent<TEndpoint extends AnyWebhookEndpoint, const TId extends string = string, const TKey extends string = string, const TType extends string = TId, const TFilter extends string = string>(options: {
+    id: TId;
+    /** The endpoint this event subscribes to. */
+    endpoint: TEndpoint;
+    /**
+     * The session each delivery goes to, as a template: `{event.x}` reads the event, `{header.x}` a
+     * header and `{webhook.x}` the endpoint, and `{a || b}` falls back to `b` when `a` is empty. e.g.
+     * `"{webhook.externalRef}:{event.data.object.customer}"`.
+     */
+    key: ValidatedWebhookKey<NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>, TKey>;
+    /** The `action.type` the handler reads. Optional; defaults to `id`. */
+    type?: TType;
+    /**
+     * Optional server-side filter (same type-safe DSL as `webhook()`); a non-match is recorded FILTERED
+     * and not routed. Narrows the action's `event` like `webhook()`'s `onEvent`.
+     */
+    filter?: ValidateWebhookFilter<InferWebhookEndpointEvent<TEndpoint>, TFilter>;
+}): ChatEvent<TType, NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>>;
+export type { ChatEvent, AnyChatEvent, ChatEventAction, ChatEventActions, WebhookKeyMeta, } from "@trigger.dev/core/v3";
+/**
+ * Compiles a key template to its stored form. Each placeholder names its namespace the way a filter
+ * path does: `{event.x}` reads the event body (stored as `{body.x}`), `{header.x}` a header and
+ * `{webhook.x}` the endpoint. A placeholder without one of those namespaces throws.
+ */
+export declare function normalizeKeyString(key: string): string;
+export type { CreateWebhookEndpointParams } from "@trigger.dev/core/v3";
 /**
  * Interface describing the webhook utilities
  */
@@ -39,9 +190,34 @@ interface Webhooks {
     constructEvent(request: ConstructEventOptions | Request, secret: string): Promise<Webhook>;
     /** Header name used for webhook signatures */
     SIGNATURE_HEADER_NAME: string;
+    custom: typeof webhookSources.custom;
+    stripe: typeof webhookSources.stripe;
+    github: typeof webhookSources.github;
+    svix: typeof webhookSources.svix;
+    standardWebhooks: typeof webhookSources.standardWebhooks;
+    square: typeof webhookSources.square;
+    discord: typeof webhookSources.discord;
+    clerk: typeof webhookSources.clerk;
+    resend: typeof webhookSources.resend;
+    openai: typeof webhookSources.openai;
+    replicate: typeof webhookSources.replicate;
+    recallai: typeof webhookSources.recallai;
+    brex: typeof webhookSources.brex;
+    composio: typeof webhookSources.composio;
+    gitlab: typeof webhookSources.gitlab;
+    whatsapp: typeof webhookSources.whatsapp;
+    /** Declare the URLs providers deliver to. */
+    endpoint: {
+        define: typeof defineWebhookEndpoint;
+    };
+    /** Suspend a run until a matching webhook arrives. */
+    waiter: {
+        create: typeof createWebhookWaiter;
+        wait: typeof waitForWebhookWaiter;
+        cancel: typeof cancelWebhookWaiter;
+    };
 }
 /**
  * Webhook utilities for handling incoming webhook requests
  */
-export declare const webhooks: Webhooks;
-export {};
+export declare const webhooks: Webhooks & Omit<ProviderProducers, "slack">;