@webhooks-cc/sdk 0.5.0 → 0.6.0

package/dist/index.d.mts

@@ -199,6 +199,7 @@ interface SDKDescription {
     version: string;
     endpoints: Record<string, OperationDescription>;
     sendTo: OperationDescription;
+    buildRequest: OperationDescription;
     requests: Record<string, OperationDescription>;
 }
 
@@ -275,6 +276,21 @@ declare class WebhooksCC {
         send: (slug: string, options?: SendOptions) => Promise<Response>;
         sendTemplate: (slug: string, options: SendTemplateOptions) => Promise<Response>;
     };
+    /**
+     * Build a request without sending it. Returns the computed method, URL,
+     * headers, and body — including any provider signatures. Useful for
+     * debugging what sendTo would actually send.
+     *
+     * @param url - Target URL (http or https)
+     * @param options - Same options as sendTo
+     * @returns The computed request details
+     */
+    buildRequest: (url: string, options?: SendToOptions) => Promise<{
+        url: string;
+        method: string;
+        headers: Record<string, string>;
+        body?: string;
+    }>;
     /**
      * Send a webhook directly to any URL with optional provider signing.
      * Use this for local integration testing — send properly signed webhooks

package/dist/index.d.ts

@@ -199,6 +199,7 @@ interface SDKDescription {
     version: string;
     endpoints: Record<string, OperationDescription>;
     sendTo: OperationDescription;
+    buildRequest: OperationDescription;
     requests: Record<string, OperationDescription>;
 }
 
@@ -275,6 +276,21 @@ declare class WebhooksCC {
         send: (slug: string, options?: SendOptions) => Promise<Response>;
         sendTemplate: (slug: string, options: SendTemplateOptions) => Promise<Response>;
     };
+    /**
+     * Build a request without sending it. Returns the computed method, URL,
+     * headers, and body — including any provider signatures. Useful for
+     * debugging what sendTo would actually send.
+     *
+     * @param url - Target URL (http or https)
+     * @param options - Same options as sendTo
+     * @returns The computed request details
+     */
+    buildRequest: (url: string, options?: SendToOptions) => Promise<{
+        url: string;
+        method: string;
+        headers: Record<string, string>;
+        body?: string;
+    }>;
     /**
      * Send a webhook directly to any URL with optional provider signing.
      * Use this for local integration testing — send properly signed webhooks

package/dist/index.js

@@ -768,10 +768,17 @@ async function buildTemplateSendOptions(endpointUrl, options) {
     const timestamp = options.timestamp ?? Math.floor(Date.now() / 1e3);
     const signingInput = `${msgId}.${timestamp}.${body}`;
     let rawSecret = options.secret;
-    if (rawSecret.startsWith("whsec_")) {
+    const hadPrefix = rawSecret.startsWith("whsec_");
+    if (hadPrefix) {
       rawSecret = rawSecret.slice(6);
     }
-    const secretBytes = fromBase64(rawSecret);
+    let secretBytes;
+    try {
+      secretBytes = fromBase64(rawSecret);
+    } catch {
+      const raw = hadPrefix ? options.secret : rawSecret;
+      secretBytes = new TextEncoder().encode(raw);
+    }
     const signature = await hmacSignRaw("SHA-256", secretBytes, signingInput);
     return {
       method: method2,
@@ -833,7 +840,7 @@ async function buildTemplateSendOptions(endpointUrl, options) {
 var DEFAULT_BASE_URL = "https://webhooks.cc";
 var DEFAULT_WEBHOOK_URL = "https://go.webhooks.cc";
 var DEFAULT_TIMEOUT = 3e4;
-var SDK_VERSION = "0.5.0";
+var SDK_VERSION = "0.6.0";
 var MIN_POLL_INTERVAL = 10;
 var MAX_POLL_INTERVAL = 6e4;
 var ALLOWED_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"]);
@@ -956,6 +963,64 @@ var WebhooksCC = class {
         return this.endpoints.send(slug, sendOptions);
       }
     };
+    /**
+     * Build a request without sending it. Returns the computed method, URL,
+     * headers, and body — including any provider signatures. Useful for
+     * debugging what sendTo would actually send.
+     *
+     * @param url - Target URL (http or https)
+     * @param options - Same options as sendTo
+     * @returns The computed request details
+     */
+    this.buildRequest = async (url, options = {}) => {
+      let parsed;
+      try {
+        parsed = new URL(url);
+      } catch {
+        throw new Error(`Invalid URL: "${url}" is not a valid URL`);
+      }
+      if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error("Invalid URL: only http and https protocols are supported");
+      }
+      if (options.provider) {
+        if (!options.secret || typeof options.secret !== "string") {
+          throw new Error("buildRequest with a provider requires a non-empty secret");
+        }
+        const sendOptions = await buildTemplateSendOptions(url, {
+          provider: options.provider,
+          template: options.template,
+          secret: options.secret,
+          event: options.event,
+          body: options.body,
+          method: options.method,
+          headers: options.headers,
+          timestamp: options.timestamp
+        });
+        return {
+          url,
+          method: (sendOptions.method ?? "POST").toUpperCase(),
+          headers: sendOptions.headers ?? {},
+          body: sendOptions.body !== void 0 ? typeof sendOptions.body === "string" ? sendOptions.body : JSON.stringify(sendOptions.body) : void 0
+        };
+      }
+      const method = (options.method ?? "POST").toUpperCase();
+      if (!ALLOWED_METHODS.has(method)) {
+        throw new Error(
+          `Invalid HTTP method: "${options.method}". Must be one of: ${[...ALLOWED_METHODS].join(", ")}`
+        );
+      }
+      const headers = { ...options.headers ?? {} };
+      const hasContentType = Object.keys(headers).some((k) => k.toLowerCase() === "content-type");
+      if (options.body !== void 0 && !hasContentType) {
+        headers["Content-Type"] = "application/json";
+      }
+      return {
+        url,
+        method,
+        headers,
+        body: options.body !== void 0 ? typeof options.body === "string" ? options.body : JSON.stringify(options.body) : void 0
+      };
+    };
     /**
      * Send a webhook directly to any URL with optional provider signing.
      * Use this for local integration testing — send properly signed webhooks
@@ -1380,6 +1445,16 @@ var WebhooksCC = class {
           headers: "Record<string, string>?"
         }
       },
+      buildRequest: {
+        description: "Build a request without sending it \u2014 returns computed method, URL, headers, and body including provider signatures",
+        params: {
+          url: "string",
+          provider: '"stripe"|"github"|"shopify"|"twilio"|"standard-webhooks"?',
+          secret: "string?",
+          body: "unknown?",
+          headers: "Record<string, string>?"
+        }
+      },
       requests: {
         list: {
           description: "List captured requests",

package/dist/index.mjs

@@ -719,10 +719,17 @@ async function buildTemplateSendOptions(endpointUrl, options) {
     const timestamp = options.timestamp ?? Math.floor(Date.now() / 1e3);
     const signingInput = `${msgId}.${timestamp}.${body}`;
     let rawSecret = options.secret;
-    if (rawSecret.startsWith("whsec_")) {
+    const hadPrefix = rawSecret.startsWith("whsec_");
+    if (hadPrefix) {
       rawSecret = rawSecret.slice(6);
     }
-    const secretBytes = fromBase64(rawSecret);
+    let secretBytes;
+    try {
+      secretBytes = fromBase64(rawSecret);
+    } catch {
+      const raw = hadPrefix ? options.secret : rawSecret;
+      secretBytes = new TextEncoder().encode(raw);
+    }
     const signature = await hmacSignRaw("SHA-256", secretBytes, signingInput);
     return {
       method: method2,
@@ -784,7 +791,7 @@ async function buildTemplateSendOptions(endpointUrl, options) {
 var DEFAULT_BASE_URL = "https://webhooks.cc";
 var DEFAULT_WEBHOOK_URL = "https://go.webhooks.cc";
 var DEFAULT_TIMEOUT = 3e4;
-var SDK_VERSION = "0.5.0";
+var SDK_VERSION = "0.6.0";
 var MIN_POLL_INTERVAL = 10;
 var MAX_POLL_INTERVAL = 6e4;
 var ALLOWED_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"]);
@@ -907,6 +914,64 @@ var WebhooksCC = class {
         return this.endpoints.send(slug, sendOptions);
       }
     };
+    /**
+     * Build a request without sending it. Returns the computed method, URL,
+     * headers, and body — including any provider signatures. Useful for
+     * debugging what sendTo would actually send.
+     *
+     * @param url - Target URL (http or https)
+     * @param options - Same options as sendTo
+     * @returns The computed request details
+     */
+    this.buildRequest = async (url, options = {}) => {
+      let parsed;
+      try {
+        parsed = new URL(url);
+      } catch {
+        throw new Error(`Invalid URL: "${url}" is not a valid URL`);
+      }
+      if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error("Invalid URL: only http and https protocols are supported");
+      }
+      if (options.provider) {
+        if (!options.secret || typeof options.secret !== "string") {
+          throw new Error("buildRequest with a provider requires a non-empty secret");
+        }
+        const sendOptions = await buildTemplateSendOptions(url, {
+          provider: options.provider,
+          template: options.template,
+          secret: options.secret,
+          event: options.event,
+          body: options.body,
+          method: options.method,
+          headers: options.headers,
+          timestamp: options.timestamp
+        });
+        return {
+          url,
+          method: (sendOptions.method ?? "POST").toUpperCase(),
+          headers: sendOptions.headers ?? {},
+          body: sendOptions.body !== void 0 ? typeof sendOptions.body === "string" ? sendOptions.body : JSON.stringify(sendOptions.body) : void 0
+        };
+      }
+      const method = (options.method ?? "POST").toUpperCase();
+      if (!ALLOWED_METHODS.has(method)) {
+        throw new Error(
+          `Invalid HTTP method: "${options.method}". Must be one of: ${[...ALLOWED_METHODS].join(", ")}`
+        );
+      }
+      const headers = { ...options.headers ?? {} };
+      const hasContentType = Object.keys(headers).some((k) => k.toLowerCase() === "content-type");
+      if (options.body !== void 0 && !hasContentType) {
+        headers["Content-Type"] = "application/json";
+      }
+      return {
+        url,
+        method,
+        headers,
+        body: options.body !== void 0 ? typeof options.body === "string" ? options.body : JSON.stringify(options.body) : void 0
+      };
+    };
     /**
      * Send a webhook directly to any URL with optional provider signing.
      * Use this for local integration testing — send properly signed webhooks
@@ -1331,6 +1396,16 @@ var WebhooksCC = class {
           headers: "Record<string, string>?"
         }
       },
+      buildRequest: {
+        description: "Build a request without sending it \u2014 returns computed method, URL, headers, and body including provider signatures",
+        params: {
+          url: "string",
+          provider: '"stripe"|"github"|"shopify"|"twilio"|"standard-webhooks"?',
+          secret: "string?",
+          body: "unknown?",
+          headers: "Record<string, string>?"
+        }
+      },
       requests: {
         list: {
           description: "List captured requests",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webhooks-cc/sdk",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "TypeScript SDK for webhooks.cc — create endpoints, capture requests, assert in tests",
   "main": "dist/index.js",
   "module": "dist/index.mjs",