@webhooks-cc/sdk 0.3.1 → 0.5.0

package/dist/index.d.mts

@@ -73,6 +73,28 @@ interface SendOptions {
     /** 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.
  */
@@ -150,10 +172,33 @@ 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>;
 }
 
@@ -228,7 +273,18 @@ declare class WebhooksCC {
         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>;
@@ -302,6 +358,12 @@ 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 Standard Webhooks request.
+ * Matches on the presence of all three Standard Webhooks headers:
+ * webhook-id, webhook-timestamp, and webhook-signature.
+ */
+declare function isStandardWebhook(request: Request): boolean;
 
 /** Match requests by HTTP method (case-insensitive). */
 declare function matchMethod(method: string): (request: Request) => boolean;
@@ -353,4 +415,4 @@ 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 SubscribeOptions, TimeoutError, UnauthorizedError, type UpdateEndpointOptions, type WaitForOptions, WebhooksCC, WebhooksCCError, isGitHubWebhook, isLinearWebhook, isPaddleWebhook, isShopifyWebhook, isSlackWebhook, isStripeWebhook, isTwilioWebhook, matchAll, matchAny, matchBodyPath, matchHeader, matchJsonField, matchMethod, parseDuration, parseJsonBody, parseSSE };
+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 };

package/dist/index.d.ts

@@ -73,6 +73,28 @@ interface SendOptions {
     /** 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.
  */
@@ -150,10 +172,33 @@ 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>;
 }
 
@@ -228,7 +273,18 @@ declare class WebhooksCC {
         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>;
@@ -302,6 +358,12 @@ 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 Standard Webhooks request.
+ * Matches on the presence of all three Standard Webhooks headers:
+ * webhook-id, webhook-timestamp, and webhook-signature.
+ */
+declare function isStandardWebhook(request: Request): boolean;
 
 /** Match requests by HTTP method (case-insensitive). */
 declare function matchMethod(method: string): (request: Request) => boolean;
@@ -353,4 +415,4 @@ 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 SubscribeOptions, TimeoutError, UnauthorizedError, type UpdateEndpointOptions, type WaitForOptions, WebhooksCC, WebhooksCCError, isGitHubWebhook, isLinearWebhook, isPaddleWebhook, isShopifyWebhook, isSlackWebhook, isStripeWebhook, isTwilioWebhook, matchAll, matchAny, matchBodyPath, matchHeader, matchJsonField, matchMethod, parseDuration, parseJsonBody, parseSSE };
+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 };