@webhooks-cc/sdk 0.3.0 → 0.4.0

package/dist/index.mjs

@@ -145,6 +145,588 @@ async function* parseSSE(stream) {
   }
 }
 
+// src/templates.ts
+var DEFAULT_TEMPLATE_BY_PROVIDER = {
+  stripe: "payment_intent.succeeded",
+  github: "push",
+  shopify: "orders/create",
+  twilio: "messaging.inbound"
+};
+var PROVIDER_TEMPLATES = {
+  stripe: ["payment_intent.succeeded", "checkout.session.completed", "invoice.paid"],
+  github: ["push", "pull_request.opened", "ping"],
+  shopify: ["orders/create", "orders/paid", "products/update", "app/uninstalled"],
+  twilio: ["messaging.inbound", "messaging.status_callback", "voice.incoming_call"]
+};
+function randomHex(length) {
+  const bytes = new Uint8Array(Math.ceil(length / 2));
+  globalThis.crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("").slice(0, length);
+}
+function randomToken(prefix) {
+  return `${prefix}_${randomHex(8)}`;
+}
+function randomDigits(length) {
+  const bytes = new Uint8Array(length);
+  globalThis.crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => (b % 10).toString()).join("");
+}
+function randomSid(prefix) {
+  return `${prefix}${randomHex(32)}`;
+}
+function randomUuid() {
+  if (typeof globalThis.crypto?.randomUUID === "function") {
+    return globalThis.crypto.randomUUID();
+  }
+  return `${randomHex(8)}-${randomHex(4)}-${randomHex(4)}-${randomHex(4)}-${randomHex(12)}`;
+}
+function repositoryPayload() {
+  return {
+    id: Number(randomDigits(9)),
+    name: "demo-repo",
+    full_name: "webhooks-cc/demo-repo",
+    private: false,
+    default_branch: "main",
+    html_url: "https://github.com/webhooks-cc/demo-repo"
+  };
+}
+function githubSender() {
+  return {
+    login: "webhooks-cc-bot",
+    id: 987654,
+    type: "Bot"
+  };
+}
+function ensureTemplate(provider, template) {
+  const resolved = template ?? DEFAULT_TEMPLATE_BY_PROVIDER[provider];
+  const supported = PROVIDER_TEMPLATES[provider];
+  if (!supported.some((item) => item === resolved)) {
+    throw new Error(
+      `Unsupported template "${resolved}" for provider "${provider}". Supported templates: ${supported.join(", ")}`
+    );
+  }
+  return resolved;
+}
+function defaultEvent(provider, template) {
+  if (provider === "github" && template === "pull_request.opened") {
+    return "pull_request";
+  }
+  return template;
+}
+function formEncode(params) {
+  const form = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    form.append(key, value);
+  }
+  return form.toString();
+}
+function asStringRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (v == null) {
+      out[k] = "";
+      continue;
+    }
+    out[k] = typeof v === "string" ? v : String(v);
+  }
+  return out;
+}
+function buildTemplatePayload(provider, template, event, now, bodyOverride) {
+  const nowSec = Math.floor(now.getTime() / 1e3);
+  const nowIso = now.toISOString();
+  if (provider === "stripe") {
+    const paymentIntentId = randomToken("pi");
+    const checkoutSessionId = `cs_test_${randomHex(24)}`;
+    const payloadByTemplate = {
+      "payment_intent.succeeded": {
+        id: randomToken("evt"),
+        object: "event",
+        api_version: "2025-01-27.acacia",
+        created: nowSec,
+        data: {
+          object: {
+            id: paymentIntentId,
+            object: "payment_intent",
+            amount: 2e3,
+            amount_received: 2e3,
+            currency: "usd",
+            status: "succeeded",
+            created: nowSec,
+            metadata: {
+              order_id: randomToken("order")
+            }
+          }
+        },
+        livemode: false,
+        pending_webhooks: 1,
+        request: {
+          id: `req_${randomHex(24)}`,
+          idempotency_key: null
+        },
+        type: event
+      },
+      "checkout.session.completed": {
+        id: randomToken("evt"),
+        object: "event",
+        api_version: "2025-01-27.acacia",
+        created: nowSec,
+        data: {
+          object: {
+            id: checkoutSessionId,
+            object: "checkout.session",
+            mode: "payment",
+            payment_status: "paid",
+            amount_total: 2e3,
+            amount_subtotal: 2e3,
+            currency: "usd",
+            customer: `cus_${randomHex(14)}`,
+            payment_intent: paymentIntentId,
+            status: "complete",
+            success_url: "https://example.com/success",
+            cancel_url: "https://example.com/cancel",
+            created: nowSec
+          }
+        },
+        livemode: false,
+        pending_webhooks: 1,
+        request: {
+          id: `req_${randomHex(24)}`,
+          idempotency_key: null
+        },
+        type: event
+      },
+      "invoice.paid": {
+        id: randomToken("evt"),
+        object: "event",
+        api_version: "2025-01-27.acacia",
+        created: nowSec,
+        data: {
+          object: {
+            id: `in_${randomHex(14)}`,
+            object: "invoice",
+            account_country: "US",
+            account_name: "webhooks.cc demo",
+            amount_due: 2e3,
+            amount_paid: 2e3,
+            amount_remaining: 0,
+            billing_reason: "subscription_cycle",
+            currency: "usd",
+            customer: `cus_${randomHex(14)}`,
+            paid: true,
+            status: "paid",
+            hosted_invoice_url: "https://invoice.stripe.com/demo",
+            created: nowSec
+          }
+        },
+        livemode: false,
+        pending_webhooks: 1,
+        request: {
+          id: `req_${randomHex(24)}`,
+          idempotency_key: null
+        },
+        type: event
+      }
+    };
+    const payload = bodyOverride ?? payloadByTemplate[template];
+    const body = typeof payload === "string" ? payload : JSON.stringify(payload);
+    return {
+      body,
+      contentType: "application/json",
+      headers: {
+        "user-agent": "Stripe/1.0 (+https://stripe.com/docs/webhooks)"
+      }
+    };
+  }
+  if (provider === "github") {
+    const before = randomHex(40);
+    const after = randomHex(40);
+    const baseRepo = repositoryPayload();
+    const payloadByTemplate = {
+      push: {
+        ref: "refs/heads/main",
+        before,
+        after,
+        repository: baseRepo,
+        pusher: {
+          name: "webhooks-cc-bot",
+          email: "bot@webhooks.cc"
+        },
+        sender: githubSender(),
+        created: false,
+        deleted: false,
+        forced: false,
+        compare: `https://github.com/${baseRepo.full_name}/compare/${before}...${after}`,
+        commits: [
+          {
+            id: after,
+            message: "Update webhook integration tests",
+            timestamp: nowIso,
+            url: `https://github.com/${baseRepo.full_name}/commit/${after}`,
+            author: {
+              name: "webhooks-cc-bot",
+              email: "bot@webhooks.cc"
+            },
+            committer: {
+              name: "webhooks-cc-bot",
+              email: "bot@webhooks.cc"
+            },
+            added: [],
+            removed: [],
+            modified: ["src/webhooks.ts"]
+          }
+        ],
+        head_commit: {
+          id: after,
+          message: "Update webhook integration tests",
+          timestamp: nowIso,
+          url: `https://github.com/${baseRepo.full_name}/commit/${after}`,
+          author: {
+            name: "webhooks-cc-bot",
+            email: "bot@webhooks.cc"
+          },
+          committer: {
+            name: "webhooks-cc-bot",
+            email: "bot@webhooks.cc"
+          },
+          added: [],
+          removed: [],
+          modified: ["src/webhooks.ts"]
+        }
+      },
+      "pull_request.opened": {
+        action: "opened",
+        number: 42,
+        pull_request: {
+          id: Number(randomDigits(9)),
+          number: 42,
+          state: "open",
+          title: "Add webhook retry logic",
+          body: "This PR improves retry handling for inbound webhooks.",
+          created_at: nowIso,
+          updated_at: nowIso,
+          html_url: `https://github.com/${baseRepo.full_name}/pull/42`,
+          user: {
+            login: "webhooks-cc-bot",
+            id: 987654,
+            type: "Bot"
+          },
+          draft: false,
+          head: {
+            label: "webhooks-cc:feature/webhook-retries",
+            ref: "feature/webhook-retries",
+            sha: randomHex(40),
+            repo: baseRepo
+          },
+          base: {
+            label: "webhooks-cc:main",
+            ref: "main",
+            sha: randomHex(40),
+            repo: baseRepo
+          }
+        },
+        repository: baseRepo,
+        sender: githubSender()
+      },
+      ping: {
+        zen: "Keep it logically awesome.",
+        hook_id: Number(randomDigits(7)),
+        hook: {
+          type: "Repository",
+          id: Number(randomDigits(7)),
+          name: "web",
+          active: true,
+          events: ["push", "pull_request"],
+          config: {
+            content_type: "json",
+            insecure_ssl: "0",
+            url: "https://go.webhooks.cc/w/demo"
+          }
+        },
+        repository: baseRepo,
+        sender: githubSender()
+      }
+    };
+    const payload = bodyOverride ?? payloadByTemplate[template];
+    const body = typeof payload === "string" ? payload : JSON.stringify(payload);
+    return {
+      body,
+      contentType: "application/json",
+      headers: {
+        "user-agent": "GitHub-Hookshot/8f03f6d"
+      }
+    };
+  }
+  if (provider === "shopify") {
+    const payloadByTemplate = {
+      "orders/create": {
+        id: Number(randomDigits(10)),
+        admin_graphql_api_id: `gid://shopify/Order/${randomDigits(10)}`,
+        email: "customer@example.com",
+        created_at: nowIso,
+        updated_at: nowIso,
+        currency: "USD",
+        financial_status: "pending",
+        fulfillment_status: null,
+        total_price: "19.99",
+        subtotal_price: "19.99",
+        total_tax: "0.00",
+        line_items: [
+          {
+            id: Number(randomDigits(10)),
+            admin_graphql_api_id: `gid://shopify/LineItem/${randomDigits(10)}`,
+            title: "Demo Item",
+            quantity: 1,
+            sku: "DEMO-001",
+            price: "19.99"
+          }
+        ]
+      },
+      "orders/paid": {
+        id: Number(randomDigits(10)),
+        admin_graphql_api_id: `gid://shopify/Order/${randomDigits(10)}`,
+        email: "customer@example.com",
+        created_at: nowIso,
+        updated_at: nowIso,
+        currency: "USD",
+        financial_status: "paid",
+        fulfillment_status: null,
+        total_price: "49.00",
+        subtotal_price: "49.00",
+        total_tax: "0.00",
+        line_items: [
+          {
+            id: Number(randomDigits(10)),
+            admin_graphql_api_id: `gid://shopify/LineItem/${randomDigits(10)}`,
+            title: "Webhook Pro Plan",
+            quantity: 1,
+            sku: "WHK-PRO",
+            price: "49.00"
+          }
+        ]
+      },
+      "products/update": {
+        id: Number(randomDigits(10)),
+        admin_graphql_api_id: `gid://shopify/Product/${randomDigits(10)}`,
+        title: "Webhook Tester Hoodie",
+        body_html: "<strong>Updated product details</strong>",
+        vendor: "webhooks.cc",
+        product_type: "Apparel",
+        handle: "webhook-tester-hoodie",
+        status: "active",
+        created_at: nowIso,
+        updated_at: nowIso,
+        variants: [
+          {
+            id: Number(randomDigits(10)),
+            product_id: Number(randomDigits(10)),
+            title: "Default Title",
+            price: "39.00",
+            sku: "WHK-HOODIE",
+            position: 1,
+            inventory_policy: "deny",
+            fulfillment_service: "manual",
+            inventory_management: "shopify"
+          }
+        ]
+      },
+      "app/uninstalled": {
+        id: Number(randomDigits(10)),
+        name: "Demo Shop",
+        email: "owner@example.com",
+        domain: "demo-shop.myshopify.com",
+        myshopify_domain: "demo-shop.myshopify.com",
+        country_name: "United States",
+        currency: "USD",
+        plan_name: "basic",
+        created_at: nowIso,
+        updated_at: nowIso
+      }
+    };
+    const payload = bodyOverride ?? payloadByTemplate[template];
+    const body = typeof payload === "string" ? payload : JSON.stringify(payload);
+    return {
+      body,
+      contentType: "application/json",
+      headers: {
+        "x-shopify-shop-domain": "demo-shop.myshopify.com",
+        "x-shopify-api-version": "2025-10",
+        "x-shopify-webhook-id": randomUuid(),
+        "x-shopify-event-id": randomUuid(),
+        "x-shopify-triggered-at": nowIso
+      }
+    };
+  }
+  if (provider !== "twilio") {
+    throw new Error(`Unsupported provider: ${provider}`);
+  }
+  const defaultTwilioParamsByTemplate = {
+    "messaging.inbound": {
+      AccountSid: randomSid("AC"),
+      ApiVersion: "2010-04-01",
+      MessageSid: randomSid("SM"),
+      SmsSid: randomSid("SM"),
+      SmsMessageSid: randomSid("SM"),
+      From: "+14155550123",
+      To: "+14155559876",
+      Body: "Hello from webhooks.cc",
+      NumMedia: "0",
+      NumSegments: "1",
+      MessageStatus: "received",
+      SmsStatus: "received",
+      FromCity: "SAN FRANCISCO",
+      FromState: "CA",
+      FromCountry: "US",
+      FromZip: "94105",
+      ToCity: "",
+      ToState: "",
+      ToCountry: "US",
+      ToZip: ""
+    },
+    "messaging.status_callback": {
+      AccountSid: randomSid("AC"),
+      ApiVersion: "2010-04-01",
+      MessageSid: randomSid("SM"),
+      SmsSid: randomSid("SM"),
+      MessageStatus: "delivered",
+      SmsStatus: "delivered",
+      To: "+14155559876",
+      From: "+14155550123",
+      ErrorCode: ""
+    },
+    "voice.incoming_call": {
+      AccountSid: randomSid("AC"),
+      ApiVersion: "2010-04-01",
+      CallSid: randomSid("CA"),
+      CallStatus: "ringing",
+      Direction: "inbound",
+      From: "+14155550123",
+      To: "+14155559876",
+      CallerCity: "SAN FRANCISCO",
+      CallerState: "CA",
+      CallerCountry: "US",
+      CallerZip: "94105",
+      CalledCity: "",
+      CalledState: "",
+      CalledCountry: "US",
+      CalledZip: ""
+    }
+  };
+  let twilioParams;
+  if (bodyOverride !== void 0) {
+    if (typeof bodyOverride === "string") {
+      const entries = Array.from(new URLSearchParams(bodyOverride).entries());
+      return {
+        body: bodyOverride,
+        contentType: "application/x-www-form-urlencoded",
+        headers: {
+          "user-agent": "TwilioProxy/1.1"
+        },
+        twilioParams: entries
+      };
+    }
+    const overrideParams = asStringRecord(bodyOverride);
+    if (!overrideParams) {
+      throw new Error("Twilio template body override must be a string or an object");
+    }
+    twilioParams = overrideParams;
+  } else {
+    twilioParams = defaultTwilioParamsByTemplate[template];
+  }
+  return {
+    body: formEncode(twilioParams),
+    contentType: "application/x-www-form-urlencoded",
+    headers: {
+      "user-agent": "TwilioProxy/1.1"
+    },
+    twilioParams: Object.entries(twilioParams)
+  };
+}
+async function hmacSign(algorithm, secret, payload) {
+  if (!globalThis.crypto?.subtle) {
+    throw new Error("crypto.subtle is required for template signature generation");
+  }
+  const key = await globalThis.crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: algorithm },
+    false,
+    ["sign"]
+  );
+  const signature = await globalThis.crypto.subtle.sign(
+    "HMAC",
+    key,
+    new TextEncoder().encode(payload)
+  );
+  return new Uint8Array(signature);
+}
+function toHex(bytes) {
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function toBase64(bytes) {
+  if (typeof btoa !== "function") {
+    return Buffer.from(bytes).toString("base64");
+  }
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+function buildTwilioSignaturePayload(endpointUrl, params) {
+  const sortedParams = params.map(([key, value], index) => ({ key, value, index })).sort(
+    (a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : a.value < b.value ? -1 : a.value > b.value ? 1 : 0
+  );
+  let payload = endpointUrl;
+  for (const { key, value } of sortedParams) {
+    payload += `${key}${value}`;
+  }
+  return payload;
+}
+async function buildTemplateSendOptions(endpointUrl, options) {
+  const method = (options.method ?? "POST").toUpperCase();
+  const template = ensureTemplate(options.provider, options.template);
+  const event = options.event ?? defaultEvent(options.provider, template);
+  const now = /* @__PURE__ */ new Date();
+  const built = buildTemplatePayload(options.provider, template, event, now, options.body);
+  const headers = {
+    "content-type": built.contentType,
+    "x-webhooks-cc-template-provider": options.provider,
+    "x-webhooks-cc-template-template": template,
+    "x-webhooks-cc-template-event": event,
+    ...built.headers
+  };
+  if (options.provider === "stripe") {
+    const timestamp = options.timestamp ?? Math.floor(Date.now() / 1e3);
+    const signature = await hmacSign("SHA-256", options.secret, `${timestamp}.${built.body}`);
+    headers["stripe-signature"] = `t=${timestamp},v1=${toHex(signature)}`;
+  }
+  if (options.provider === "github") {
+    headers["x-github-event"] = event;
+    headers["x-github-delivery"] = randomUuid();
+    const signature = await hmacSign("SHA-256", options.secret, built.body);
+    headers["x-hub-signature-256"] = `sha256=${toHex(signature)}`;
+  }
+  if (options.provider === "shopify") {
+    headers["x-shopify-topic"] = event;
+    const signature = await hmacSign("SHA-256", options.secret, built.body);
+    headers["x-shopify-hmac-sha256"] = toBase64(signature);
+  }
+  if (options.provider === "twilio") {
+    const signaturePayload = built.twilioParams ? buildTwilioSignaturePayload(endpointUrl, built.twilioParams) : `${endpointUrl}${built.body}`;
+    const signature = await hmacSign("SHA-1", options.secret, signaturePayload);
+    headers["x-twilio-signature"] = toBase64(signature);
+  }
+  return {
+    method,
+    headers: {
+      ...headers,
+      ...options.headers ?? {}
+    },
+    body: built.body
+  };
+}
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://webhooks.cc";
 var DEFAULT_WEBHOOK_URL = "https://go.webhooks.cc";
@@ -164,6 +746,19 @@ var HOP_BY_HOP_HEADERS = /* @__PURE__ */ new Set([
   "upgrade"
 ]);
 var SENSITIVE_HEADERS = /* @__PURE__ */ new Set(["authorization", "cookie", "proxy-authorization", "set-cookie"]);
+var PROXY_HEADERS = /* @__PURE__ */ new Set([
+  "cdn-loop",
+  "cf-connecting-ip",
+  "cf-ipcountry",
+  "cf-ray",
+  "cf-visitor",
+  "via",
+  "x-forwarded-for",
+  "x-forwarded-host",
+  "x-forwarded-proto",
+  "x-real-ip",
+  "true-client-ip"
+]);
 var ApiError = WebhooksCCError;
 function mapStatusToError(status, message, response) {
   const isGeneric = message.length < 30;
@@ -248,6 +843,15 @@ var WebhooksCC = class {
           body: body !== void 0 ? typeof body === "string" ? body : JSON.stringify(body) : void 0,
           signal: AbortSignal.timeout(this.timeout)
         });
+      },
+      sendTemplate: async (slug, options) => {
+        validatePathSegment(slug, "slug");
+        if (!options.secret || typeof options.secret !== "string") {
+          throw new Error("sendTemplate requires a non-empty secret");
+        }
+        const endpointUrl = `${this.webhookUrl}/w/${slug}`;
+        const sendOptions = await buildTemplateSendOptions(endpointUrl, options);
+        return this.endpoints.send(slug, sendOptions);
       }
     };
     this.requests = {
@@ -342,7 +946,7 @@ var WebhooksCC = class {
         const headers = {};
         for (const [key, val] of Object.entries(captured.headers)) {
           const lower = key.toLowerCase();
-          if (!HOP_BY_HOP_HEADERS.has(lower) && !SENSITIVE_HEADERS.has(lower)) {
+          if (!HOP_BY_HOP_HEADERS.has(lower) && !SENSITIVE_HEADERS.has(lower) && !PROXY_HEADERS.has(lower)) {
             headers[key] = val;
           }
         }
@@ -419,7 +1023,8 @@ var WebhooksCC = class {
               controller.signal.addEventListener(
                 "abort",
                 () => {
-                  response.body?.cancel();
+                  response.body?.cancel().catch(() => {
+                  });
                 },
                 { once: true }
               );
@@ -592,6 +1197,16 @@ var WebhooksCC = class {
         send: {
           description: "Send a test webhook to endpoint",
           params: { slug: "string", method: "string?", headers: "object?", body: "unknown?" }
+        },
+        sendTemplate: {
+          description: "Send a provider template webhook with signed headers",
+          params: {
+            slug: "string",
+            provider: '"stripe"|"github"|"shopify"|"twilio"',
+            template: "string?",
+            secret: "string",
+            event: "string?"
+          }
         }
       },
       requests: {

package/package.json

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