@webhooks-cc/sdk 0.1.1 → 0.3.0

package/dist/index.d.ts

@@ -49,6 +49,30 @@ 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;
+}
 /**
  * Options for listing captured requests.
  */
@@ -62,13 +86,50 @@ interface ListRequestsOptions {
  * Options for waitFor() polling behavior.
  */
 interface WaitForOptions {
-    /** Maximum time to wait in milliseconds (default: 30000) */
-    timeout?: number;
-    /** Interval between polls in milliseconds (default: 500, min: 10, max: 60000) */
-    pollInterval?: number;
+    /** 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.
  */
@@ -77,8 +138,50 @@ interface ClientOptions {
     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>;
+}
+/** Self-describing schema returned by client.describe(). */
+interface SDKDescription {
+    version: string;
+    endpoints: Record<string, 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);
 }
 
 /**
@@ -86,23 +189,21 @@ interface ClientOptions {
  *
  * @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: 10000,
- *   match: (r) => r.method === 'POST'
+ *   timeout: '30s',
+ *   match: matchMethod('POST'),
  * });
  * ```
  */
 
 /**
- * Error thrown when an API request fails with a specific HTTP status code.
- * Allows callers to distinguish between different error types.
+ * @deprecated Use {@link WebhooksCCError} instead. Kept for backward compatibility.
  */
-declare class ApiError extends Error {
-    readonly statusCode: number;
-    constructor(statusCode: number, message: string);
-}
+declare const ApiError: typeof WebhooksCCError;
 /**
  * Client for the webhooks.cc API.
  *
@@ -113,14 +214,20 @@ declare class ApiError extends Error {
 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>;
     };
     requests: {
         list: (endpointSlug: string, options?: ListRequestsOptions) => Promise<Request[]>;
@@ -138,7 +245,112 @@ declare class WebhooksCC {
          * @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>;
     };
 }
 
-export { ApiError, type ClientOptions, type CreateEndpointOptions, type Endpoint, type ListRequestsOptions, type Request, type WaitForOptions, WebhooksCC };
+/**
+ * Safely parse a JSON request body.
+ * Returns undefined if the body is empty or not valid JSON.
+ */
+declare function parseJsonBody(request: Request): unknown | undefined;
+/**
+ * Check if a request looks like a Stripe webhook.
+ * Matches on the `stripe-signature` header being present.
+ */
+declare function isStripeWebhook(request: Request): boolean;
+/**
+ * Check if a request looks like a GitHub webhook.
+ * Matches on the `x-github-event` header being present.
+ */
+declare function isGitHubWebhook(request: Request): boolean;
+/**
+ * Returns a match function that checks whether a JSON field in the
+ * request body equals the expected value.
+ *
+ * @example
+ * ```ts
+ * const req = await client.requests.waitFor(slug, {
+ *   match: matchJsonField("type", "checkout.session.completed"),
+ * });
+ * ```
+ */
+declare function matchJsonField(field: string, value: unknown): (request: Request) => boolean;
+/** Check if a request looks like a Shopify webhook. */
+declare function isShopifyWebhook(request: Request): boolean;
+/** Check if a request looks like a Slack webhook. */
+declare function isSlackWebhook(request: Request): boolean;
+/** Check if a request looks like a Twilio webhook. */
+declare function isTwilioWebhook(request: Request): boolean;
+/** Check if a request looks like a Paddle webhook. */
+declare function isPaddleWebhook(request: Request): boolean;
+/** Check if a request looks like a Linear webhook. */
+declare function isLinearWebhook(request: Request): boolean;
+
+/** Match requests by HTTP method (case-insensitive). */
+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 requests by a dot-notation path into the JSON body.
+ * Supports array indexing with numeric path segments (e.g., `"items.0.id"`).
+ *
+ * @example
+ * ```ts
+ * matchBodyPath("data.object.id", "obj_123")
+ * matchBodyPath("type", "checkout.session.completed")
+ * matchBodyPath("items.0.name", "Widget")
+ * ```
+ */
+declare function matchBodyPath(path: string, value: unknown): (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. */
+declare function matchAny(first: (request: Request) => boolean, ...rest: Array<(request: Request) => boolean>): (request: Request) => boolean;
+
+/**
+ * Parse a duration value into milliseconds.
+ *
+ * Accepts:
+ * - Numbers: passed through as-is (treated as milliseconds)
+ * - Numeric strings: `"500"` → 500
+ * - Duration strings: `"30s"` → 30000, `"5m"` → 300000, `"1.5s"` → 1500, `"500ms"` → 500
+ *
+ * @throws {Error} If the input string is not a valid duration format
+ */
+declare function parseDuration(input: number | string): number;
+
+/** A parsed SSE frame with event type and data. */
+interface SSEFrame {
+    event: string;
+    data: string;
+}
+/**
+ * Async generator that parses SSE frames from a ReadableStream.
+ *
+ * Handles:
+ * - Multi-line `data:` fields (joined with newlines)
+ * - `event:` type fields
+ * - Comment lines (`: ...`) — yielded with event "comment"
+ * - Empty data fields
+ * - Frames terminated by blank lines
+ */
+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 };