@webhooks-cc/sdk 0.5.0 → 1.0.0

package/dist/index.d.ts

@@ -1,325 +1,5 @@
-/**
- * A webhook endpoint that captures incoming HTTP requests.
- * Create endpoints via the dashboard or SDK to receive webhooks.
- */
-interface Endpoint {
-    /** Unique identifier for this endpoint */
-    id: string;
-    /** URL-safe identifier used in webhook URLs (/w/{slug}) */
-    slug: string;
-    /** Display name for the endpoint */
-    name?: string;
-    /** Full URL where webhooks should be sent (undefined if server is misconfigured) */
-    url?: string;
-    /** Unix timestamp (ms) when the endpoint was created */
-    createdAt: number;
-}
-/**
- * A captured webhook request with full HTTP details.
- * Stored when a webhook arrives at an endpoint.
- */
-interface Request {
-    /** Unique identifier for this request */
-    id: string;
-    /** Endpoint that received this request */
-    endpointId: string;
-    /** HTTP method (GET, POST, PUT, etc.) */
-    method: string;
-    /** Request path after the endpoint slug */
-    path: string;
-    /** HTTP headers from the original request */
-    headers: Record<string, string>;
-    /** Request body, if present */
-    body?: string;
-    /** URL query parameters */
-    queryParams: Record<string, string>;
-    /** Content-Type header value, if present */
-    contentType?: string;
-    /** Client IP address */
-    ip: string;
-    /** Request body size in bytes */
-    size: number;
-    /** Unix timestamp (ms) when the request arrived */
-    receivedAt: number;
-}
-/**
- * Options for creating a new endpoint.
- */
-interface CreateEndpointOptions {
-    /** Display name for the endpoint */
-    name?: string;
-}
-/**
- * Options for updating an existing endpoint.
- */
-interface UpdateEndpointOptions {
-    /** New display name */
-    name?: string;
-    /** Mock response config, or null to clear */
-    mockResponse?: {
-        status: number;
-        body: string;
-        headers: Record<string, string>;
-    } | null;
-}
-/**
- * Options for sending a test webhook to an endpoint.
- */
-interface SendOptions {
-    /** HTTP method (default: "POST") */
-    method?: string;
-    /** HTTP headers to include */
-    headers?: Record<string, string>;
-    /** Request body (will be JSON-serialized if not a string) */
-    body?: unknown;
-}
-type TemplateProvider = "stripe" | "github" | "shopify" | "twilio" | "standard-webhooks";
-/**
- * Options for sending a provider template webhook with signed headers.
- */
-interface SendTemplateOptions {
-    /** Provider template to use */
-    provider: TemplateProvider;
-    /** Provider-specific template preset (uses provider default if omitted) */
-    template?: string;
-    /** Shared secret used for provider signature generation */
-    secret: string;
-    /** Provider event/topic name (provider default used if omitted) */
-    event?: string;
-    /** HTTP method override (default: "POST") */
-    method?: string;
-    /** Additional headers merged after template headers */
-    headers?: Record<string, string>;
-    /** Body override; if omitted a provider-specific template body is generated */
-    body?: unknown;
-    /** Unix timestamp (seconds) override for deterministic signatures in tests */
-    timestamp?: number;
-}
-/**
- * Options for listing captured requests.
- */
-interface ListRequestsOptions {
-    /** Maximum number of requests to return */
-    limit?: number;
-    /** Only return requests received after this timestamp (ms) */
-    since?: number;
-}
-/**
- * Options for waitFor() polling behavior.
- */
-interface WaitForOptions {
-    /** Maximum time to wait (ms or duration string like "30s", "5m") (default: 30000) */
-    timeout?: number | string;
-    /** Interval between polls (ms or duration string) (default: 500, min: 10, max: 60000) */
-    pollInterval?: number | string;
-    /** Filter function to match specific requests */
-    match?: (request: Request) => boolean;
-}
-/**
- * Options for subscribe() SSE streaming.
- */
-interface SubscribeOptions {
-    /** AbortSignal to cancel the subscription */
-    signal?: AbortSignal;
-    /** Maximum time to stream (ms or duration string like "30m") */
-    timeout?: number | string;
-}
-/** Info passed to the onRequest hook before a request is sent. */
-interface RequestHookInfo {
-    method: string;
-    url: string;
-}
-/** Info passed to the onResponse hook after a successful response. */
-interface ResponseHookInfo {
-    method: string;
-    url: string;
-    status: number;
-    durationMs: number;
-}
-/** Info passed to the onError hook when a request fails. */
-interface ErrorHookInfo {
-    method: string;
-    url: string;
-    error: Error;
-    durationMs: number;
-}
-/**
- * Lifecycle hooks for observability and telemetry integration.
- * All hooks are optional and are called synchronously (fire-and-forget).
- */
-interface ClientHooks {
-    onRequest?: (info: RequestHookInfo) => void;
-    onResponse?: (info: ResponseHookInfo) => void;
-    onError?: (info: ErrorHookInfo) => void;
-}
-/**
- * Configuration options for the WebhooksCC client.
- */
-interface ClientOptions {
-    /** API key for authentication (format: whcc_...) */
-    apiKey: string;
-    /** Base URL for the API (default: https://webhooks.cc) */
-    baseUrl?: string;
-    /** Base URL for sending webhooks (default: https://go.webhooks.cc) */
-    webhookUrl?: string;
-    /** Request timeout in milliseconds (default: 30000) */
-    timeout?: number;
-    /** Lifecycle hooks for observability */
-    hooks?: ClientHooks;
-}
-/** Description of a single SDK operation. */
-interface OperationDescription {
-    description: string;
-    params: Record<string, string>;
-}
-/**
- * Options for sending a webhook directly to an arbitrary URL.
- * Supports optional provider signing (Standard Webhooks, Stripe, etc.).
- */
-interface SendToOptions {
-    /** Provider template for signing (optional). When set, secret is required. */
-    provider?: TemplateProvider;
-    /** Provider-specific template preset (e.g. "checkout.session.completed" for Stripe) */
-    template?: string;
-    /** Secret for provider signature generation (required when provider is set) */
-    secret?: string;
-    /** Event name for provider headers */
-    event?: string;
-    /** HTTP method (default: "POST") */
-    method?: string;
-    /** HTTP headers to include */
-    headers?: Record<string, string>;
-    /** Request body (will be JSON-serialized if not a string) */
-    body?: unknown;
-    /** Unix timestamp (seconds) override for deterministic signatures in tests */
-    timestamp?: number;
-}
-/** Self-describing schema returned by client.describe(). */
-interface SDKDescription {
-    version: string;
-    endpoints: Record<string, OperationDescription>;
-    sendTo: OperationDescription;
-    requests: Record<string, OperationDescription>;
-}
-
-/**
- * Base error class for all webhooks.cc SDK errors.
- * Extends the standard Error with an HTTP status code.
- */
-declare class WebhooksCCError extends Error {
-    readonly statusCode: number;
-    constructor(statusCode: number, message: string);
-}
-/** Thrown when the API key is invalid or missing (401). */
-declare class UnauthorizedError extends WebhooksCCError {
-    constructor(message?: string);
-}
-/** Thrown when the requested resource does not exist (404). */
-declare class NotFoundError extends WebhooksCCError {
-    constructor(message?: string);
-}
-/** Thrown when the request times out. */
-declare class TimeoutError extends WebhooksCCError {
-    constructor(timeoutMs: number);
-}
-/** Thrown when the API returns 429 Too Many Requests. */
-declare class RateLimitError extends WebhooksCCError {
-    /** Seconds until the rate limit resets, if provided by the server. */
-    readonly retryAfter?: number;
-    constructor(retryAfter?: number);
-}
-
-/**
- * @fileoverview webhooks.cc SDK client for programmatic webhook management.
- *
- * @example
- * ```typescript
- * import { WebhooksCC, matchMethod } from '@webhooks-cc/sdk';
- *
- * const client = new WebhooksCC({ apiKey: 'whcc_...' });
- * const endpoint = await client.endpoints.create({ name: 'My Webhook' });
- * const request = await client.requests.waitFor(endpoint.slug, {
- *   timeout: '30s',
- *   match: matchMethod('POST'),
- * });
- * ```
- */
-
-/**
- * @deprecated Use {@link WebhooksCCError} instead. Kept for backward compatibility.
- */
-declare const ApiError: typeof WebhooksCCError;
-/**
- * Client for the webhooks.cc API.
- *
- * Provides methods to create endpoints, list captured requests, and wait
- * for incoming webhooks. Handles authentication, request signing, and
- * response validation.
- */
-declare class WebhooksCC {
-    private readonly apiKey;
-    private readonly baseUrl;
-    private readonly webhookUrl;
-    private readonly timeout;
-    private readonly hooks;
-    constructor(options: ClientOptions);
-    private request;
-    /** Returns a static description of all SDK operations (no API call). */
-    describe(): SDKDescription;
-    endpoints: {
-        create: (options?: CreateEndpointOptions) => Promise<Endpoint>;
-        list: () => Promise<Endpoint[]>;
-        get: (slug: string) => Promise<Endpoint>;
-        update: (slug: string, options: UpdateEndpointOptions) => Promise<Endpoint>;
-        delete: (slug: string) => Promise<void>;
-        send: (slug: string, options?: SendOptions) => Promise<Response>;
-        sendTemplate: (slug: string, options: SendTemplateOptions) => Promise<Response>;
-    };
-    /**
-     * Send a webhook directly to any URL with optional provider signing.
-     * Use this for local integration testing — send properly signed webhooks
-     * to localhost handlers without routing through webhooks.cc infrastructure.
-     *
-     * @param url - Target URL to send the webhook to (http or https)
-     * @param options - Method, headers, body, and optional provider signing
-     * @returns Raw fetch Response from the target
-     */
-    sendTo: (url: string, options?: SendToOptions) => Promise<Response>;
-    requests: {
-        list: (endpointSlug: string, options?: ListRequestsOptions) => Promise<Request[]>;
-        get: (requestId: string) => Promise<Request>;
-        /**
-         * Polls for incoming requests until one matches or timeout expires.
-         *
-         * Fetches requests that arrived since the last successful check. On API
-         * errors, continues polling without updating the timestamp to avoid
-         * missing requests during transient failures.
-         *
-         * @param endpointSlug - Endpoint to monitor
-         * @param options - Timeout, poll interval, and optional match filter
-         * @returns First matching request, or first request if no match filter
-         * @throws Error if timeout expires or max iterations (10000) reached
-         */
-        waitFor: (endpointSlug: string, options?: WaitForOptions) => Promise<Request>;
-        /**
-         * Replay a captured request to a target URL.
-         *
-         * Fetches the original request by ID and re-sends it to the specified URL
-         * with the original method, headers, and body. Hop-by-hop headers are stripped.
-         */
-        replay: (requestId: string, targetUrl: string) => Promise<Response>;
-        /**
-         * Stream incoming requests via SSE as an async iterator.
-         *
-         * Connects to the SSE endpoint and yields Request objects as they arrive.
-         * The connection is closed when the iterator is broken, the signal is aborted,
-         * or the timeout expires.
-         *
-         * No automatic reconnection — if the connection drops, the iterator ends.
-         */
-        subscribe: (slug: string, options?: SubscribeOptions) => AsyncIterable<Request>;
-    };
-}
+import { R as Request, P as ParsedBody, a as ParsedFormBody, S as SearchResult, V as VerifySignatureOptions, b as SignatureVerificationResult } from './diff-Dn4j4B_n.js';
+export { A as ApiError, B as BodyDiff, C as ClearRequestsOptions, c as ClientHooks, d as ClientOptions, e as CreateEndpointOptions, f as CurlExport, D as DiffRequestsOptions, g as DiffResult, E as Endpoint, h as ErrorHookInfo, i as ExportRequestsOptions, F as FormBodyValue, H as HarExport, j as HeaderDiff, J as JsonBodyDiff, L as ListPaginatedRequestsOptions, k as ListRequestsOptions, M as MockResponse, N as NotFoundError, O as OperationDescription, l as PaginatedResult, m as RateLimitError, n as RequestDifferences, o as RequestHookInfo, p as RequestsExport, q as ResponseHookInfo, r as RetryOptions, s as SDKDescription, t as SearchFilters, u as SendOptions, v as SendTemplateOptions, w as SendToOptions, x as SubscribeOptions, T as TemplateProvider, y as TemplateProviderInfo, z as TextBodyDiff, G as TimeoutError, U as UnauthorizedError, I as UpdateEndpointOptions, K as UsageInfo, Q as ValueDifference, W as VerifyProvider, X as WaitForAllOptions, Y as WaitForOptions, Z as WebhookFlowBuilder, _ as WebhookFlowResult, $ as WebhookFlowVerifyOptions, a0 as WebhooksCC, a1 as WebhooksCCError, a2 as diffRequests } from './diff-Dn4j4B_n.js';
 
 /**
  * Safely parse a JSON request body.
@@ -348,6 +28,21 @@ declare function isGitHubWebhook(request: Request): boolean;
  * ```
  */
 declare function matchJsonField(field: string, value: unknown): (request: Request) => boolean;
+/**
+ * Parse an application/x-www-form-urlencoded request body.
+ * Repeated keys are returned as string arrays.
+ */
+declare function parseFormBody(request: Request): ParsedFormBody | undefined;
+/**
+ * Parse the request body based on content-type.
+ * JSON and urlencoded bodies are decoded; other bodies are returned as raw text.
+ */
+declare function parseBody(request: Request): ParsedBody;
+/**
+ * Extract a nested JSON field from the request body using dot notation.
+ * Returns undefined if the body is missing, invalid JSON, or the path is absent.
+ */
+declare function extractJsonField<T>(request: Request, path: string): T | undefined;
 /** Check if a request looks like a Shopify webhook. */
 declare function isShopifyWebhook(request: Request): boolean;
 /** Check if a request looks like a Slack webhook. */
@@ -358,6 +53,8 @@ declare function isTwilioWebhook(request: Request): boolean;
 declare function isPaddleWebhook(request: Request): boolean;
 /** Check if a request looks like a Linear webhook. */
 declare function isLinearWebhook(request: Request): boolean;
+/** Check if a request looks like a Discord interaction webhook. */
+declare function isDiscordWebhook(request: Request): boolean;
 /**
  * Check if a request looks like a Standard Webhooks request.
  * Matches on the presence of all three Standard Webhooks headers:
@@ -369,6 +66,10 @@ declare function isStandardWebhook(request: Request): boolean;
 declare function matchMethod(method: string): (request: Request) => boolean;
 /** Match requests that have a specific header, optionally with a specific value. Header names are matched case-insensitively; values are matched with exact (case-sensitive) equality. */
 declare function matchHeader(name: string, value?: string): (request: Request) => boolean;
+/** Match request paths using glob-style wildcards. Supports `*` and `**`. */
+declare function matchPath(pattern: string): (request: Request) => boolean;
+/** Match query parameter presence or a specific query parameter value. */
+declare function matchQueryParam(key: string, value?: string): (request: Request) => boolean;
 /**
  * Match requests by a dot-notation path into the JSON body.
  * Supports array indexing with numeric path segments (e.g., `"items.0.id"`).
@@ -381,6 +82,10 @@ declare function matchHeader(name: string, value?: string): (request: Request) =
  * ```
  */
 declare function matchBodyPath(path: string, value: unknown): (request: Request) => boolean;
+/** Match a deep partial subset of the parsed JSON body. */
+declare function matchBodySubset(subset: Record<string, unknown>): (request: Request) => boolean;
+/** Match the request content type, ignoring charset parameters. */
+declare function matchContentType(type: string): (request: Request) => boolean;
 /** Match when ALL matchers return true. Requires at least one matcher. */
 declare function matchAll(first: (request: Request) => boolean, ...rest: Array<(request: Request) => boolean>): (request: Request) => boolean;
 /** Match when ANY matcher returns true. Requires at least one matcher. */
@@ -392,7 +97,7 @@ declare function matchAny(first: (request: Request) => boolean, ...rest: Array<(
  * Accepts:
  * - Numbers: passed through as-is (treated as milliseconds)
  * - Numeric strings: `"500"` → 500
- * - Duration strings: `"30s"` → 30000, `"5m"` → 300000, `"1.5s"` → 1500, `"500ms"` → 500
+ * - Duration strings: `"30s"` → 30000, `"5m"` → 300000, `"1.5s"` → 1500, `"500ms"` → 500, `"7d"` → 604800000
  *
  * @throws {Error} If the input string is not a valid duration format
  */
@@ -415,4 +120,112 @@ interface SSEFrame {
  */
 declare function parseSSE(stream: ReadableStream<Uint8Array>): AsyncGenerator<SSEFrame, void, undefined>;
 
-export { ApiError, type ClientHooks, type ClientOptions, type CreateEndpointOptions, type Endpoint, type ErrorHookInfo, type ListRequestsOptions, NotFoundError, type OperationDescription, RateLimitError, type Request, type RequestHookInfo, type ResponseHookInfo, type SDKDescription, type SSEFrame, type SendOptions, type SendTemplateOptions, type SendToOptions, type SubscribeOptions, type TemplateProvider, TimeoutError, UnauthorizedError, type UpdateEndpointOptions, type WaitForOptions, WebhooksCC, WebhooksCCError, isGitHubWebhook, isLinearWebhook, isPaddleWebhook, isShopifyWebhook, isSlackWebhook, isStandardWebhook, isStripeWebhook, isTwilioWebhook, matchAll, matchAny, matchBodyPath, matchHeader, matchJsonField, matchMethod, parseDuration, parseJsonBody, parseSSE };
+declare const TEMPLATE_METADATA: Readonly<{
+    stripe: Readonly<{
+        provider: "stripe";
+        templates: readonly ("payment_intent.succeeded" | "checkout.session.completed" | "invoice.paid")[];
+        defaultTemplate: "payment_intent.succeeded";
+        secretRequired: true;
+        signatureHeader: "stripe-signature";
+        signatureAlgorithm: "hmac-sha256";
+    }>;
+    github: Readonly<{
+        provider: "github";
+        templates: readonly ("push" | "pull_request.opened" | "ping")[];
+        defaultTemplate: "push";
+        secretRequired: true;
+        signatureHeader: "x-hub-signature-256";
+        signatureAlgorithm: "hmac-sha256";
+    }>;
+    shopify: Readonly<{
+        provider: "shopify";
+        templates: readonly ("orders/create" | "orders/paid" | "products/update" | "app/uninstalled")[];
+        defaultTemplate: "orders/create";
+        secretRequired: true;
+        signatureHeader: "x-shopify-hmac-sha256";
+        signatureAlgorithm: "hmac-sha256";
+    }>;
+    twilio: Readonly<{
+        provider: "twilio";
+        templates: readonly ("messaging.inbound" | "messaging.status_callback" | "voice.incoming_call")[];
+        defaultTemplate: "messaging.inbound";
+        secretRequired: true;
+        signatureHeader: "x-twilio-signature";
+        signatureAlgorithm: "hmac-sha1";
+    }>;
+    slack: Readonly<{
+        provider: "slack";
+        templates: readonly ("event_callback" | "slash_command" | "url_verification")[];
+        defaultTemplate: "event_callback";
+        secretRequired: true;
+        signatureHeader: "x-slack-signature";
+        signatureAlgorithm: "hmac-sha256";
+    }>;
+    paddle: Readonly<{
+        provider: "paddle";
+        templates: readonly ("transaction.completed" | "subscription.created" | "subscription.updated")[];
+        defaultTemplate: "transaction.completed";
+        secretRequired: true;
+        signatureHeader: "paddle-signature";
+        signatureAlgorithm: "hmac-sha256";
+    }>;
+    linear: Readonly<{
+        provider: "linear";
+        templates: readonly ("issue.create" | "issue.update" | "comment.create")[];
+        defaultTemplate: "issue.create";
+        secretRequired: true;
+        signatureHeader: "linear-signature";
+        signatureAlgorithm: "hmac-sha256";
+    }>;
+    "standard-webhooks": Readonly<{
+        provider: "standard-webhooks";
+        templates: readonly never[];
+        secretRequired: true;
+        signatureHeader: "webhook-signature";
+        signatureAlgorithm: "hmac-sha256";
+    }>;
+}>;
+
+type VerifyableRequest = Pick<Request, "body" | "headers"> | Pick<SearchResult, "body" | "headers">;
+/**
+ * Verify a Stripe webhook signature header against the raw request body.
+ */
+declare function verifyStripeSignature(body: string | undefined, signatureHeader: string | null | undefined, secret: string): Promise<boolean>;
+/**
+ * Verify a GitHub webhook signature header against the raw request body.
+ */
+declare function verifyGitHubSignature(body: string | undefined, signatureHeader: string | null | undefined, secret: string): Promise<boolean>;
+/**
+ * Verify a Shopify webhook signature header against the raw request body.
+ */
+declare function verifyShopifySignature(body: string | undefined, signatureHeader: string | null | undefined, secret: string): Promise<boolean>;
+/**
+ * Verify a Twilio webhook signature against the signed URL and form body.
+ */
+declare function verifyTwilioSignature(url: string, body: string | Record<string, string> | undefined, signatureHeader: string | null | undefined, secret: string): Promise<boolean>;
+/**
+ * Verify a Slack webhook signature from x-slack-signature and x-slack-request-timestamp headers.
+ */
+declare function verifySlackSignature(body: string | undefined, headers: Record<string, string>, secret: string): Promise<boolean>;
+/**
+ * Verify a Paddle webhook signature from the paddle-signature header.
+ */
+declare function verifyPaddleSignature(body: string | undefined, signatureHeader: string | null | undefined, secret: string): Promise<boolean>;
+/**
+ * Verify a Linear webhook signature against the raw request body.
+ */
+declare function verifyLinearSignature(body: string | undefined, signatureHeader: string | null | undefined, secret: string): Promise<boolean>;
+/**
+ * Verify a Discord interaction signature using the application's Ed25519 public key.
+ */
+declare function verifyDiscordSignature(body: string | undefined, headers: Record<string, string>, publicKey: string): Promise<boolean>;
+/**
+ * Verify a Standard Webhooks signature from webhook-id/timestamp/signature headers.
+ */
+declare function verifyStandardWebhookSignature(body: string | undefined, headers: Record<string, string>, secret: string): Promise<boolean>;
+/**
+ * Verify a captured request using the provider-specific signature scheme.
+ */
+declare function verifySignature(request: VerifyableRequest, options: VerifySignatureOptions): Promise<SignatureVerificationResult>;
+
+export { ParsedBody, ParsedFormBody, Request, type SSEFrame, SearchResult, SignatureVerificationResult, TEMPLATE_METADATA, VerifySignatureOptions, extractJsonField, isDiscordWebhook, isGitHubWebhook, isLinearWebhook, isPaddleWebhook, isShopifyWebhook, isSlackWebhook, isStandardWebhook, isStripeWebhook, isTwilioWebhook, matchAll, matchAny, matchBodyPath, matchBodySubset, matchContentType, matchHeader, matchJsonField, matchMethod, matchPath, matchQueryParam, parseBody, parseDuration, parseFormBody, parseJsonBody, parseSSE, verifyDiscordSignature, verifyGitHubSignature, verifyLinearSignature, verifyPaddleSignature, verifyShopifySignature, verifySignature, verifySlackSignature, verifyStandardWebhookSignature, verifyStripeSignature, verifyTwilioSignature };