@webhooks-cc/sdk 1.0.0 → 1.1.0

package/dist/index.mjs

@@ -91,7 +91,12 @@ var DEFAULT_TEMPLATE_BY_PROVIDER = {
   twilio: "messaging.inbound",
   slack: "event_callback",
   paddle: "transaction.completed",
-  linear: "issue.create"
+  linear: "issue.create",
+  sendgrid: "delivered",
+  clerk: "user.created",
+  discord: "interaction_create",
+  vercel: "deployment.created",
+  gitlab: "push"
 };
 var PROVIDER_TEMPLATES = {
   stripe: ["payment_intent.succeeded", "checkout.session.completed", "invoice.paid"],
@@ -100,7 +105,12 @@ var PROVIDER_TEMPLATES = {
   twilio: ["messaging.inbound", "messaging.status_callback", "voice.incoming_call"],
   slack: ["event_callback", "slash_command", "url_verification"],
   paddle: ["transaction.completed", "subscription.created", "subscription.updated"],
-  linear: ["issue.create", "issue.update", "comment.create"]
+  linear: ["issue.create", "issue.update", "comment.create"],
+  sendgrid: ["delivered", "open", "bounce", "spam_report"],
+  clerk: ["user.created", "user.updated", "user.deleted", "session.created"],
+  discord: ["interaction_create", "message_component", "ping"],
+  vercel: ["deployment.created", "deployment.succeeded", "deployment.error"],
+  gitlab: ["push", "merge_request"]
 };
 var TEMPLATE_PROVIDERS = [
   "stripe",
@@ -110,6 +120,11 @@ var TEMPLATE_PROVIDERS = [
   "slack",
   "paddle",
   "linear",
+  "sendgrid",
+  "clerk",
+  "discord",
+  "vercel",
+  "gitlab",
   "standard-webhooks"
 ];
 var TEMPLATE_METADATA = Object.freeze({
@@ -169,6 +184,42 @@ var TEMPLATE_METADATA = Object.freeze({
     signatureHeader: "linear-signature",
     signatureAlgorithm: "hmac-sha256"
   }),
+  sendgrid: Object.freeze({
+    provider: "sendgrid",
+    templates: Object.freeze([...PROVIDER_TEMPLATES.sendgrid]),
+    defaultTemplate: DEFAULT_TEMPLATE_BY_PROVIDER.sendgrid,
+    secretRequired: false
+  }),
+  clerk: Object.freeze({
+    provider: "clerk",
+    templates: Object.freeze([...PROVIDER_TEMPLATES.clerk]),
+    defaultTemplate: DEFAULT_TEMPLATE_BY_PROVIDER.clerk,
+    secretRequired: true,
+    signatureHeader: "webhook-signature",
+    signatureAlgorithm: "hmac-sha256"
+  }),
+  discord: Object.freeze({
+    provider: "discord",
+    templates: Object.freeze([...PROVIDER_TEMPLATES.discord]),
+    defaultTemplate: DEFAULT_TEMPLATE_BY_PROVIDER.discord,
+    secretRequired: false
+  }),
+  vercel: Object.freeze({
+    provider: "vercel",
+    templates: Object.freeze([...PROVIDER_TEMPLATES.vercel]),
+    defaultTemplate: DEFAULT_TEMPLATE_BY_PROVIDER.vercel,
+    secretRequired: true,
+    signatureHeader: "x-vercel-signature",
+    signatureAlgorithm: "hmac-sha1"
+  }),
+  gitlab: Object.freeze({
+    provider: "gitlab",
+    templates: Object.freeze([...PROVIDER_TEMPLATES.gitlab]),
+    defaultTemplate: DEFAULT_TEMPLATE_BY_PROVIDER.gitlab,
+    secretRequired: true,
+    signatureHeader: "x-gitlab-token",
+    signatureAlgorithm: "token"
+  }),
   "standard-webhooks": Object.freeze({
     provider: "standard-webhooks",
     templates: Object.freeze([]),
@@ -754,6 +805,228 @@ function buildTemplatePayload(provider, template, event, now, bodyOverride) {
         }
       };
     }
+    if (provider === "clerk") {
+      const userId = `user_${randomHex(24)}`;
+      const payloadByTemplate = {
+        "user.created": {
+          data: {
+            id: userId,
+            object: "user",
+            email_addresses: [
+              {
+                id: `idn_${randomHex(24)}`,
+                email_address: "user@example.com",
+                verification: { status: "verified", strategy: "email_code" }
+              }
+            ],
+            first_name: "Jane",
+            last_name: "Doe",
+            created_at: nowSec * 1e3,
+            updated_at: nowSec * 1e3
+          },
+          object: "event",
+          type: "user.created",
+          timestamp: nowSec * 1e3
+        },
+        "user.updated": {
+          data: {
+            id: userId,
+            object: "user",
+            email_addresses: [
+              {
+                id: `idn_${randomHex(24)}`,
+                email_address: "user@example.com",
+                verification: { status: "verified", strategy: "email_code" }
+              }
+            ],
+            first_name: "Jane",
+            last_name: "Smith",
+            created_at: nowSec * 1e3,
+            updated_at: nowSec * 1e3
+          },
+          object: "event",
+          type: "user.updated",
+          timestamp: nowSec * 1e3
+        },
+        "user.deleted": {
+          data: {
+            id: userId,
+            object: "user",
+            deleted: true
+          },
+          object: "event",
+          type: "user.deleted",
+          timestamp: nowSec * 1e3
+        },
+        "session.created": {
+          data: {
+            id: `sess_${randomHex(24)}`,
+            object: "session",
+            user_id: userId,
+            status: "active",
+            created_at: nowSec * 1e3,
+            updated_at: nowSec * 1e3,
+            expire_at: (nowSec + 86400) * 1e3
+          },
+          object: "event",
+          type: "session.created",
+          timestamp: nowSec * 1e3
+        }
+      };
+      const payload = bodyOverride ?? payloadByTemplate[template];
+      const body = typeof payload === "string" ? payload : JSON.stringify(payload);
+      return {
+        body,
+        contentType: "application/json",
+        headers: {
+          "user-agent": "Svix-Webhooks/1.0"
+        }
+      };
+    }
+    if (provider === "vercel") {
+      const deploymentId = `dpl_${randomHex(20)}`;
+      const projectId = `prj_${randomHex(20)}`;
+      const teamId = `team_${randomHex(20)}`;
+      const payloadByTemplate = {
+        "deployment.created": {
+          id: randomUuid(),
+          type: "deployment.created",
+          createdAt: nowSec * 1e3,
+          payload: {
+            deployment: {
+              id: deploymentId,
+              name: "webhooks-cc-web",
+              url: `webhooks-cc-web-${randomHex(8)}.vercel.app`,
+              meta: {
+                githubCommitRef: "main",
+                githubCommitSha: randomHex(40),
+                githubCommitMessage: "Update webhook templates"
+              }
+            },
+            project: { id: projectId, name: "webhooks-cc-web" },
+            team: { id: teamId, name: "webhooks-cc" }
+          }
+        },
+        "deployment.succeeded": {
+          id: randomUuid(),
+          type: "deployment.succeeded",
+          createdAt: nowSec * 1e3,
+          payload: {
+            deployment: {
+              id: deploymentId,
+              name: "webhooks-cc-web",
+              url: `webhooks-cc-web-${randomHex(8)}.vercel.app`,
+              readyState: "READY"
+            },
+            project: { id: projectId, name: "webhooks-cc-web" },
+            team: { id: teamId, name: "webhooks-cc" }
+          }
+        },
+        "deployment.error": {
+          id: randomUuid(),
+          type: "deployment.error",
+          createdAt: nowSec * 1e3,
+          payload: {
+            deployment: {
+              id: deploymentId,
+              name: "webhooks-cc-web",
+              url: `webhooks-cc-web-${randomHex(8)}.vercel.app`,
+              readyState: "ERROR",
+              errorMessage: "Build failed: exit code 1"
+            },
+            project: { id: projectId, name: "webhooks-cc-web" },
+            team: { id: teamId, name: "webhooks-cc" }
+          }
+        }
+      };
+      const payload = bodyOverride ?? payloadByTemplate[template];
+      const body = typeof payload === "string" ? payload : JSON.stringify(payload);
+      return {
+        body,
+        contentType: "application/json",
+        headers: {
+          "user-agent": "Vercel/1.0"
+        }
+      };
+    }
+    if (provider === "gitlab") {
+      const projectId = Number(randomDigits(7));
+      const payloadByTemplate = {
+        push: {
+          object_kind: "push",
+          event_name: "push",
+          before: randomHex(40),
+          after: randomHex(40),
+          ref: "refs/heads/main",
+          checkout_sha: randomHex(40),
+          user_id: Number(randomDigits(5)),
+          user_name: "webhooks-cc-bot",
+          user_email: "bot@webhooks.cc",
+          project_id: projectId,
+          project: {
+            id: projectId,
+            name: "demo-repo",
+            web_url: "https://gitlab.com/webhooks-cc/demo-repo",
+            namespace: "webhooks-cc",
+            default_branch: "main"
+          },
+          commits: [
+            {
+              id: randomHex(40),
+              message: "Update webhook integration tests",
+              title: "Update webhook integration tests",
+              timestamp: nowIso,
+              url: `https://gitlab.com/webhooks-cc/demo-repo/-/commit/${randomHex(40)}`,
+              author: { name: "webhooks-cc-bot", email: "bot@webhooks.cc" },
+              added: [],
+              modified: ["src/webhooks.ts"],
+              removed: []
+            }
+          ],
+          total_commits_count: 1
+        },
+        merge_request: {
+          object_kind: "merge_request",
+          event_type: "merge_request",
+          user: {
+            id: Number(randomDigits(5)),
+            name: "webhooks-cc-bot",
+            username: "webhooks-cc-bot",
+            email: "bot@webhooks.cc"
+          },
+          project: {
+            id: projectId,
+            name: "demo-repo",
+            web_url: "https://gitlab.com/webhooks-cc/demo-repo",
+            namespace: "webhooks-cc",
+            default_branch: "main"
+          },
+          object_attributes: {
+            id: Number(randomDigits(7)),
+            iid: 42,
+            title: "Add webhook retry logic",
+            description: "This MR improves retry handling for inbound webhooks.",
+            state: "opened",
+            action: "open",
+            source_branch: "feature/webhook-retries",
+            target_branch: "main",
+            created_at: nowIso,
+            updated_at: nowIso,
+            url: `https://gitlab.com/webhooks-cc/demo-repo/-/merge_requests/42`
+          }
+        }
+      };
+      const payload = bodyOverride ?? payloadByTemplate[template];
+      const body = typeof payload === "string" ? payload : JSON.stringify(payload);
+      return {
+        body,
+        contentType: "application/json",
+        headers: {
+          "x-gitlab-event": template === "merge_request" ? "Merge Request Hook" : "Push Hook",
+          "user-agent": "GitLab/1.0"
+        }
+      };
+    }
     throw new Error(`Unsupported provider: ${provider}`);
   }
   const defaultTwilioParamsByTemplate = {
@@ -939,6 +1212,142 @@ async function buildTemplateSendOptions(endpointUrl, options) {
       body
     };
   }
+  if (options.provider === "sendgrid") {
+    const method2 = (options.method ?? "POST").toUpperCase();
+    const supported = PROVIDER_TEMPLATES.sendgrid;
+    const template2 = options.template ?? DEFAULT_TEMPLATE_BY_PROVIDER.sendgrid;
+    if (!supported.some((item) => item === template2)) {
+      throw new Error(
+        `Unsupported template "${template2}" for provider "sendgrid". Supported templates: ${supported.join(", ")}`
+      );
+    }
+    const nowSec = Math.floor(Date.now() / 1e3);
+    const payloadByTemplate = {
+      delivered: [
+        {
+          sg_event_id: randomHex(22),
+          sg_message_id: `${randomHex(20)}.${randomDigits(4)}`,
+          email: "recipient@example.com",
+          timestamp: nowSec,
+          event: "delivered",
+          smtp_id: `<${randomHex(20)}@example.com>`,
+          ip: "168.1.1.1",
+          response: "250 OK",
+          category: ["webhooks-cc-test"]
+        }
+      ],
+      open: [
+        {
+          sg_event_id: randomHex(22),
+          sg_message_id: `${randomHex(20)}.${randomDigits(4)}`,
+          email: "recipient@example.com",
+          timestamp: nowSec,
+          event: "open",
+          ip: "72.14.199.28",
+          useragent: "Mozilla/5.0",
+          category: ["webhooks-cc-test"]
+        }
+      ],
+      bounce: [
+        {
+          sg_event_id: randomHex(22),
+          sg_message_id: `${randomHex(20)}.${randomDigits(4)}`,
+          email: "bounced@example.com",
+          timestamp: nowSec,
+          event: "bounce",
+          type: "bounce",
+          status: "5.1.1",
+          reason: "550 5.1.1 The email account does not exist.",
+          ip: "168.1.1.1",
+          category: ["webhooks-cc-test"]
+        }
+      ],
+      spam_report: [
+        {
+          sg_event_id: randomHex(22),
+          sg_message_id: `${randomHex(20)}.${randomDigits(4)}`,
+          email: "complainant@example.com",
+          timestamp: nowSec,
+          event: "spamreport",
+          category: ["webhooks-cc-test"]
+        }
+      ]
+    };
+    const payload = options.body ?? payloadByTemplate[template2];
+    const body = typeof payload === "string" ? payload : JSON.stringify(payload);
+    return {
+      method: method2,
+      headers: {
+        "content-type": "application/json",
+        "user-agent": "SendGrid/1.0",
+        "x-webhooks-cc-template-provider": "sendgrid",
+        "x-webhooks-cc-template-template": template2,
+        "x-webhooks-cc-template-event": template2,
+        ...options.headers ?? {}
+      },
+      body
+    };
+  }
+  if (options.provider === "discord") {
+    const method2 = (options.method ?? "POST").toUpperCase();
+    const supported = PROVIDER_TEMPLATES.discord;
+    const template2 = options.template ?? DEFAULT_TEMPLATE_BY_PROVIDER.discord;
+    if (!supported.some((item) => item === template2)) {
+      throw new Error(
+        `Unsupported template "${template2}" for provider "discord". Supported templates: ${supported.join(", ")}`
+      );
+    }
+    const timestamp = options.timestamp ?? Math.floor(Date.now() / 1e3);
+    const payloadByTemplate = {
+      interaction_create: {
+        id: randomHex(18),
+        application_id: randomHex(18),
+        type: 2,
+        data: {
+          id: randomHex(18),
+          name: "webhook-test",
+          type: 1
+        },
+        guild_id: randomHex(18),
+        channel_id: randomHex(18),
+        token: randomHex(40),
+        version: 1
+      },
+      message_component: {
+        id: randomHex(18),
+        application_id: randomHex(18),
+        type: 3,
+        data: {
+          custom_id: "click_me",
+          component_type: 2
+        },
+        guild_id: randomHex(18),
+        channel_id: randomHex(18),
+        token: randomHex(40),
+        version: 1
+      },
+      ping: {
+        id: randomHex(18),
+        application_id: randomHex(18),
+        type: 1,
+        version: 1
+      }
+    };
+    const payload = options.body ?? payloadByTemplate[template2];
+    const body = typeof payload === "string" ? payload : JSON.stringify(payload);
+    return {
+      method: method2,
+      headers: {
+        "content-type": "application/json",
+        "x-signature-timestamp": String(timestamp),
+        "x-webhooks-cc-template-provider": "discord",
+        "x-webhooks-cc-template-template": template2,
+        "x-webhooks-cc-template-event": template2,
+        ...options.headers ?? {}
+      },
+      body
+    };
+  }
   const provider = options.provider;
   const method = (options.method ?? "POST").toUpperCase();
   const template = ensureTemplate(provider, options.template);
@@ -988,6 +1397,29 @@ async function buildTemplateSendOptions(endpointUrl, options) {
     const signature = await hmacSign("SHA-256", options.secret, built.body);
     headers["linear-signature"] = `sha256=${toHex(signature)}`;
   }
+  if (provider === "clerk") {
+    const msgId = `msg_${randomHex(16)}`;
+    const timestamp = options.timestamp ?? Math.floor(Date.now() / 1e3);
+    const signingInput = `${msgId}.${timestamp}.${built.body}`;
+    const secretBytes = decodeStandardWebhookSecret(options.secret);
+    const signature = await hmacSignRaw("SHA-256", secretBytes, signingInput);
+    const sig = `v1,${toBase64(signature)}`;
+    headers["webhook-id"] = msgId;
+    headers["webhook-timestamp"] = String(timestamp);
+    headers["webhook-signature"] = sig;
+    headers["svix-id"] = msgId;
+    headers["svix-timestamp"] = String(timestamp);
+    headers["svix-signature"] = sig;
+  }
+  if (provider === "vercel") {
+    const signature = await hmacSign("SHA-1", options.secret, built.body);
+    headers["x-vercel-signature"] = toHex(signature);
+  }
+  if (provider === "gitlab") {
+    headers["x-gitlab-token"] = options.secret;
+    const gitlabEvent = template === "merge_request" ? "Merge Request Hook" : "Push Hook";
+    headers["x-gitlab-event"] = gitlabEvent;
+  }
   return {
     method,
     headers: {
@@ -1333,6 +1765,32 @@ async function verifyLinearSignature(body, signatureHeader, secret) {
   const expected = toHex(await hmacSign("SHA-256", secret, normalizeBody(body))).toLowerCase();
   return timingSafeEqual(match[1].toLowerCase(), expected);
 }
+async function verifyVercelSignature(body, signatureHeader, secret) {
+  requireSecret(secret, "verifyVercelSignature");
+  if (!signatureHeader) {
+    return false;
+  }
+  const expected = toHex(await hmacSign("SHA-1", secret, normalizeBody(body))).toLowerCase();
+  return timingSafeEqual(signatureHeader.trim().toLowerCase(), expected);
+}
+async function verifyGitLabSignature(_body, tokenHeader, secret) {
+  requireSecret(secret, "verifyGitLabSignature");
+  if (!tokenHeader) {
+    return false;
+  }
+  return timingSafeEqual(tokenHeader, secret);
+}
+async function verifyClerkSignature(body, headers, secret) {
+  const normalized = { ...headers };
+  const svixId = getHeader(headers, "svix-id");
+  const svixTs = getHeader(headers, "svix-timestamp");
+  const svixSig = getHeader(headers, "svix-signature");
+  if (svixId && !getHeader(headers, "webhook-id")) normalized["webhook-id"] = svixId;
+  if (svixTs && !getHeader(headers, "webhook-timestamp")) normalized["webhook-timestamp"] = svixTs;
+  if (svixSig && !getHeader(headers, "webhook-signature"))
+    normalized["webhook-signature"] = svixSig;
+  return verifyStandardWebhookSignature(body, normalized, secret);
+}
 async function verifyDiscordSignature(body, headers, publicKey) {
   if (!publicKey || typeof publicKey !== "string") {
     throw new Error("verifyDiscordSignature requires a non-empty public key");
@@ -1439,6 +1897,28 @@ async function verifySignature(request, options) {
       options.secret
     );
   }
+  if (options.provider === "clerk") {
+    valid = await verifyClerkSignature(request.body, request.headers, options.secret);
+  }
+  if (options.provider === "vercel") {
+    valid = await verifyVercelSignature(
+      request.body,
+      getHeader(request.headers, "x-vercel-signature"),
+      options.secret
+    );
+  }
+  if (options.provider === "gitlab") {
+    valid = await verifyGitLabSignature(
+      request.body,
+      getHeader(request.headers, "x-gitlab-token"),
+      options.secret
+    );
+  }
+  if (options.provider === "sendgrid") {
+    throw new Error(
+      "SendGrid does not use signature verification. SendGrid webhooks are verified via IP allowlisting."
+    );
+  }
   if (options.provider === "discord") {
     valid = await verifyDiscordSignature(request.body, request.headers, options.publicKey);
   }
@@ -1815,10 +2295,13 @@ async function collectMatchingRequests(fetchRequests, options) {
   throw new TimeoutError(timeout);
 }
 function validateMockResponse(mockResponse, fieldName) {
-  const { status } = mockResponse;
+  const { status, delay } = mockResponse;
   if (!Number.isInteger(status) || status < 100 || status > 599) {
     throw new Error(`Invalid ${fieldName} status: ${status}. Must be an integer 100-599.`);
   }
+  if (delay !== void 0 && (!Number.isInteger(delay) || delay < 0 || delay > 3e4)) {
+    throw new Error(`Invalid ${fieldName} delay: ${delay}. Must be an integer 0-30000.`);
+  }
 }
 var WebhooksCC = class {
   constructor(options) {
@@ -2756,6 +3239,26 @@ function isDiscordWebhook(request) {
   const keys = Object.keys(request.headers).map((k) => k.toLowerCase());
   return keys.includes("x-signature-ed25519") && keys.includes("x-signature-timestamp");
 }
+function isSendGridWebhook(request) {
+  if (!request.body) return false;
+  try {
+    const parsed = JSON.parse(request.body);
+    return Array.isArray(parsed) && parsed.length > 0 && typeof parsed[0] === "object" && parsed[0] !== null && "sg_event_id" in parsed[0];
+  } catch {
+    return false;
+  }
+}
+function isClerkWebhook(request) {
+  return Object.keys(request.headers).some((k) => k.toLowerCase() === "svix-id");
+}
+function isVercelWebhook(request) {
+  return Object.keys(request.headers).some((k) => k.toLowerCase() === "x-vercel-signature");
+}
+function isGitLabWebhook(request) {
+  return Object.keys(request.headers).some(
+    (k) => k.toLowerCase() === "x-gitlab-event" || k.toLowerCase() === "x-gitlab-token"
+  );
+}
 function isStandardWebhook(request) {
   const keys = Object.keys(request.headers).map((k) => k.toLowerCase());
   return keys.includes("webhook-id") && keys.includes("webhook-timestamp") && keys.includes("webhook-signature");
@@ -2892,15 +3395,19 @@ export {
   WebhooksCCError,
   diffRequests,
   extractJsonField,
+  isClerkWebhook,
   isDiscordWebhook,
   isGitHubWebhook,
+  isGitLabWebhook,
   isLinearWebhook,
   isPaddleWebhook,
+  isSendGridWebhook,
   isShopifyWebhook,
   isSlackWebhook,
   isStandardWebhook,
   isStripeWebhook,
   isTwilioWebhook,
+  isVercelWebhook,
   matchAll,
   matchAny,
   matchBodyPath,
@@ -2916,8 +3423,10 @@ export {
   parseFormBody,
   parseJsonBody,
   parseSSE,
+  verifyClerkSignature,
   verifyDiscordSignature,
   verifyGitHubSignature,
+  verifyGitLabSignature,
   verifyLinearSignature,
   verifyPaddleSignature,
   verifyShopifySignature,
@@ -2925,5 +3434,6 @@ export {
   verifySlackSignature,
   verifyStandardWebhookSignature,
   verifyStripeSignature,
-  verifyTwilioSignature
+  verifyTwilioSignature,
+  verifyVercelSignature
 };

package/dist/testing.d.mts

@@ -1,4 +1,4 @@
-import { g as DiffResult, e as CreateEndpointOptions, R as Request, a0 as WebhooksCC, E as Endpoint } from './diff-Dn4j4B_n.mjs';
+import { g as DiffResult, e as CreateEndpointOptions, R as Request, a0 as WebhooksCC, E as Endpoint } from './diff-C6vrhcEq.mjs';
 
 type TestingClient = Pick<WebhooksCC, "endpoints" | "requests">;
 interface AssertRequestExpectation {

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { g as DiffResult, e as CreateEndpointOptions, R as Request, a0 as WebhooksCC, E as Endpoint } from './diff-Dn4j4B_n.js';
+import { g as DiffResult, e as CreateEndpointOptions, R as Request, a0 as WebhooksCC, E as Endpoint } from './diff-C6vrhcEq.js';
 
 type TestingClient = Pick<WebhooksCC, "endpoints" | "requests">;
 interface AssertRequestExpectation {

package/package.json

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