@dojocoding/whatsapp-sdk 0.8.0

package/dist/index.js

@@ -0,0 +1,2183 @@
+import { randomUUID } from 'crypto';
+import { trace, SpanStatusCode } from '@opentelemetry/api';
+
+// src/types/errors.ts
+var WhatsAppError = class extends Error {
+  code;
+  constructor(code, message, options) {
+    super(message);
+    this.name = "WhatsAppError";
+    this.code = code;
+    if (options?.cause !== void 0) {
+      this.cause = options.cause;
+    }
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  toJSON() {
+    return { name: this.name, code: this.code, message: this.message };
+  }
+};
+var MissingCredentialsError = class extends WhatsAppError {
+  code = "MISSING_CREDENTIALS";
+  missingFields;
+  constructor(missingFields, options) {
+    super(
+      "MISSING_CREDENTIALS",
+      `WhatsAppClient is missing required credential field(s): ${missingFields.join(", ")}`,
+      options
+    );
+    this.name = "MissingCredentialsError";
+    this.missingFields = missingFields;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      missingFields: this.missingFields
+    };
+  }
+};
+var RateLimitError = class extends WhatsAppError {
+  code = "RATE_LIMIT";
+  metaCode;
+  retryAfterMs;
+  constructor(message, meta = {}, options) {
+    super("RATE_LIMIT", message, options);
+    this.name = "RateLimitError";
+    this.metaCode = meta.metaCode;
+    this.retryAfterMs = meta.retryAfterMs;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var WindowClosedError = class extends WhatsAppError {
+  code = "WINDOW_CLOSED";
+  customerWaId;
+  constructor(customerWaId, options) {
+    super(
+      "WINDOW_CLOSED",
+      `24-hour customer-service window is closed for ${customerWaId}; only approved templates may be sent.`,
+      options
+    );
+    this.name = "WindowClosedError";
+    this.customerWaId = customerWaId;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var WebhookSignatureError = class extends WhatsAppError {
+  code = "WEBHOOK_SIGNATURE";
+  constructor(message = "Webhook signature verification failed", options) {
+    super("WEBHOOK_SIGNATURE", message, options);
+    this.name = "WebhookSignatureError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var TemplateError = class extends WhatsAppError {
+  code = "TEMPLATE";
+  templateName;
+  constructor(message, templateName, options) {
+    super("TEMPLATE", message, options);
+    this.name = "TemplateError";
+    this.templateName = templateName;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var MockModeError = class extends WhatsAppError {
+  code = "MOCK_MODE";
+  constructor(message, options) {
+    super("MOCK_MODE", message, options);
+    this.name = "MockModeError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AuthenticationError = class extends WhatsAppError {
+  code = "AUTHENTICATION";
+  metaCode;
+  subcode;
+  constructor(message, meta = {}, options) {
+    super("AUTHENTICATION", message, options);
+    this.name = "AuthenticationError";
+    this.metaCode = meta.metaCode;
+    this.subcode = meta.subcode;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var PermissionError = class extends WhatsAppError {
+  code = "PERMISSION";
+  metaCode;
+  constructor(message, meta = {}, options) {
+    super("PERMISSION", message, options);
+    this.name = "PermissionError";
+    this.metaCode = meta.metaCode;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var CapabilityError = class extends WhatsAppError {
+  code = "CAPABILITY";
+  metaCode;
+  constructor(message, meta = {}, options) {
+    super("CAPABILITY", message, options);
+    this.name = "CapabilityError";
+    this.metaCode = meta.metaCode;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/templates/placeholders.ts
+var PLACEHOLDER_RE = /\{\{\s*(\d+)\s*\}\}/g;
+function countTemplatePlaceholders(text) {
+  if (typeof text !== "string" || text.length === 0) return 0;
+  const indices = /* @__PURE__ */ new Set();
+  let match;
+  PLACEHOLDER_RE.lastIndex = 0;
+  while ((match = PLACEHOLDER_RE.exec(text)) !== null) {
+    const raw = match[1] ?? "";
+    const idx = Number.parseInt(raw, 10);
+    if (!Number.isFinite(idx) || idx < 0) {
+      throw new TemplateError(
+        `Invalid template placeholder "{{${raw}}}": must be a non-negative integer.`
+      );
+    }
+    if (idx === 0) {
+      throw new TemplateError("Template placeholders are 1-indexed; `{{0}}` is invalid.");
+    }
+    indices.add(idx);
+  }
+  if (indices.size === 0) return 0;
+  const max = Math.max(...indices);
+  for (let i = 1; i <= max; i += 1) {
+    if (!indices.has(i)) {
+      throw new TemplateError(
+        `Template placeholders must be contiguous; missing \`{{${i}}}\` between {{1}} and {{${max}}}.`
+      );
+    }
+  }
+  return max;
+}
+
+// src/templates/validate.ts
+function validateTemplateSend(payload, definition) {
+  if (payload.template.name !== definition.name) {
+    throw new TemplateError(
+      `Template name mismatch: payload="${payload.template.name}" vs definition="${definition.name}".`,
+      definition.name
+    );
+  }
+  if (payload.template.language.code !== definition.language) {
+    throw new TemplateError(
+      `Template language mismatch: payload="${payload.template.language.code}" vs definition="${definition.language}".`,
+      definition.name
+    );
+  }
+  for (const payloadComp of payload.template.components ?? []) {
+    if (payloadComp.type === "button") {
+      validateButtonComponent(payloadComp, definition);
+      continue;
+    }
+    if (payloadComp.type === "carousel" || payloadComp.type === "limited_time_offer") {
+      continue;
+    }
+    const defComp = findDefinitionComponent(definition, payloadComp.type);
+    if (defComp === void 0) {
+      throw new TemplateError(
+        `Template component "${payloadComp.type}" not present in definition "${definition.name}".`,
+        definition.name
+      );
+    }
+    const expected = countTemplatePlaceholders(defComp.text);
+    const actual = payloadComp.parameters?.length ?? 0;
+    if (expected !== actual) {
+      throw new TemplateError(
+        `Template component "${payloadComp.type}" expects ${expected} parameter(s) but payload provided ${actual}.`,
+        definition.name
+      );
+    }
+  }
+}
+function findDefinitionComponent(definition, payloadType) {
+  const wantUpper = payloadType.toUpperCase();
+  return definition.components.find((c) => c.type === wantUpper);
+}
+function validateButtonComponent(payloadComp, definition) {
+  const buttons = definition.components.find((c) => c.type === "BUTTONS");
+  if (buttons === void 0) {
+    throw new TemplateError(
+      `Template payload includes a button component but definition "${definition.name}" has no BUTTONS component.`,
+      definition.name
+    );
+  }
+  const idxRaw = payloadComp.index;
+  const idx = typeof idxRaw === "string" ? Number.parseInt(idxRaw, 10) : Number.NaN;
+  if (!Number.isFinite(idx) || idx < 0) {
+    throw new TemplateError(
+      `Button component requires a numeric \`index\` string; received "${String(idxRaw)}".`,
+      definition.name
+    );
+  }
+  const button = buttons.buttons?.[idx];
+  if (button === void 0) {
+    throw new TemplateError(
+      `Button component index ${idx} is out of range for definition "${definition.name}".`,
+      definition.name
+    );
+  }
+  const subType = (payloadComp.sub_type ?? "").toUpperCase();
+  if (subType !== "" && button.type.toUpperCase() !== subTypeToButtonType(subType)) {
+    throw new TemplateError(
+      `Button component sub_type "${payloadComp.sub_type ?? ""}" does not match definition's "${button.type}".`,
+      definition.name
+    );
+  }
+}
+function subTypeToButtonType(subType) {
+  switch (subType) {
+    case "QUICK_REPLY":
+      return "QUICK_REPLY";
+    case "URL":
+      return "URL";
+    case "COPY_CODE":
+      return "COPY_CODE";
+    default:
+      return subType;
+  }
+}
+
+// src/messages/builders.ts
+var BASE_PAYLOAD = {
+  messaging_product: "whatsapp",
+  recipient_type: "individual"
+};
+function fail(message, cause) {
+  throw new WhatsAppError("UNKNOWN", message, void 0 );
+}
+function failTemplate(message, templateName, cause) {
+  throw new TemplateError(message, templateName, void 0 );
+}
+function ensureRecipient(to) {
+  if (typeof to !== "string" || to.trim().length === 0) {
+    fail("Invalid recipient: `to` must be a non-empty string.");
+  }
+  return to;
+}
+function ensureReplyTo(replyTo) {
+  if (replyTo === void 0) return void 0;
+  if (typeof replyTo !== "string" || replyTo.length === 0) {
+    fail("Invalid `replyTo`: must be a non-empty wamid string.");
+  }
+  return replyTo;
+}
+function withReplyTo(payload, replyTo) {
+  if (replyTo === void 0) return payload;
+  return { ...payload, context: { message_id: replyTo } };
+}
+function exactlyOne(a, b, label) {
+  const haveA = typeof a === "string" && a.length > 0;
+  const haveB = typeof b === "string" && b.length > 0;
+  if (haveA === haveB) {
+    fail(`${label}: provide exactly one of \`id\` or \`link\` (not both, not neither).`);
+  }
+}
+function ensureNumberInRange(value, min, max, label) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < min || value > max) {
+    fail(`${label}: must be a finite number in [${min}, ${max}].`);
+  }
+  return value;
+}
+function buildText(input) {
+  const to = ensureRecipient(input.to);
+  const replyTo = ensureReplyTo(input.replyTo);
+  if (typeof input.body !== "string" || input.body.length === 0) {
+    fail("buildText: `body` must be a non-empty string.");
+  }
+  const text = input.previewUrl === void 0 ? { body: input.body } : { body: input.body, preview_url: input.previewUrl };
+  return withReplyTo({ ...BASE_PAYLOAD, to, type: "text", text }, replyTo);
+}
+function mediaSource(input, label) {
+  exactlyOne(input.id, input.link, label);
+  const out = {};
+  if (typeof input.id === "string" && input.id.length > 0) out.id = input.id;
+  if (typeof input.link === "string" && input.link.length > 0) out.link = input.link;
+  if (input.caption !== void 0) out.caption = input.caption;
+  if (input.filename !== void 0) out.filename = input.filename;
+  return out;
+}
+function buildImage(input) {
+  const to = ensureRecipient(input.to);
+  const replyTo = ensureReplyTo(input.replyTo);
+  const src = mediaSource(input, "buildImage");
+  delete src.filename;
+  return withReplyTo({ ...BASE_PAYLOAD, to, type: "image", image: src }, replyTo);
+}
+function buildVideo(input) {
+  const to = ensureRecipient(input.to);
+  const replyTo = ensureReplyTo(input.replyTo);
+  const src = mediaSource(input, "buildVideo");
+  delete src.filename;
+  return withReplyTo({ ...BASE_PAYLOAD, to, type: "video", video: src }, replyTo);
+}
+function buildAudio(input) {
+  const to = ensureRecipient(input.to);
+  const replyTo = ensureReplyTo(input.replyTo);
+  const src = mediaSource(input, "buildAudio");
+  return withReplyTo(
+    {
+      ...BASE_PAYLOAD,
+      to,
+      type: "audio",
+      audio: src.id !== void 0 ? { id: src.id } : { link: src.link }
+    },
+    replyTo
+  );
+}
+function buildDocument(input) {
+  const to = ensureRecipient(input.to);
+  const replyTo = ensureReplyTo(input.replyTo);
+  const src = mediaSource(input, "buildDocument");
+  return withReplyTo({ ...BASE_PAYLOAD, to, type: "document", document: src }, replyTo);
+}
+function buildSticker(input) {
+  const to = ensureRecipient(input.to);
+  const replyTo = ensureReplyTo(input.replyTo);
+  const src = mediaSource(input, "buildSticker");
+  return withReplyTo(
+    {
+      ...BASE_PAYLOAD,
+      to,
+      type: "sticker",
+      sticker: src.id !== void 0 ? { id: src.id } : { link: src.link }
+    },
+    replyTo
+  );
+}
+function buildLocation(input) {
+  const to = ensureRecipient(input.to);
+  const replyTo = ensureReplyTo(input.replyTo);
+  const latitude = ensureNumberInRange(input.latitude, -90, 90, "buildLocation.latitude");
+  const longitude = ensureNumberInRange(input.longitude, -180, 180, "buildLocation.longitude");
+  const location = { latitude, longitude };
+  if (input.name !== void 0) location.name = input.name;
+  if (input.address !== void 0) location.address = input.address;
+  return withReplyTo({ ...BASE_PAYLOAD, to, type: "location", location }, replyTo);
+}
+function buildContacts(input) {
+  const to = ensureRecipient(input.to);
+  const replyTo = ensureReplyTo(input.replyTo);
+  const list = Array.isArray(input.contacts) ? input.contacts : [input.contacts];
+  if (list.length === 0) fail("buildContacts: at least one contact is required.");
+  for (const c of list) {
+    const formatted = c.name.formatted_name;
+    if (typeof formatted !== "string" || formatted.length === 0) {
+      fail("buildContacts: every contact must include `name.formatted_name`.");
+    }
+  }
+  return withReplyTo({ ...BASE_PAYLOAD, to, type: "contacts", contacts: list }, replyTo);
+}
+function buildInteractiveButton(input) {
+  const to = ensureRecipient(input.to);
+  const replyTo = ensureReplyTo(input.replyTo);
+  if (typeof input.body !== "string" || input.body.length === 0) {
+    fail("buildInteractiveButton: `body` must be a non-empty string.");
+  }
+  if (input.buttons.length < 1 || input.buttons.length > 3) {
+    fail("buildInteractiveButton: `buttons` must contain 1 to 3 entries.");
+  }
+  for (const b of input.buttons) {
+    if (typeof b.id !== "string" || b.id.length === 0 || typeof b.title !== "string" || b.title.length === 0) {
+      fail("buildInteractiveButton: every button needs a non-empty `id` and `title`.");
+    }
+  }
+  const interactive = {
+    type: "button",
+    body: { text: input.body },
+    action: {
+      buttons: input.buttons.map((b) => ({
+        type: "reply",
+        reply: { id: b.id, title: b.title }
+      }))
+    }
+  };
+  if (input.header !== void 0) interactive.header = input.header;
+  if (input.footer !== void 0) interactive.footer = { text: input.footer };
+  return withReplyTo({ ...BASE_PAYLOAD, to, type: "interactive", interactive }, replyTo);
+}
+function buildInteractiveList(input) {
+  const to = ensureRecipient(input.to);
+  const replyTo = ensureReplyTo(input.replyTo);
+  if (typeof input.body !== "string" || input.body.length === 0) {
+    fail("buildInteractiveList: `body` must be a non-empty string.");
+  }
+  if (typeof input.button !== "string" || input.button.length === 0) {
+    fail("buildInteractiveList: `button` must be a non-empty string.");
+  }
+  if (input.sections.length < 1 || input.sections.length > 10) {
+    fail("buildInteractiveList: `sections` must contain 1 to 10 entries.");
+  }
+  for (const s of input.sections) {
+    if (typeof s.title !== "string" || s.title.length === 0) {
+      fail("buildInteractiveList: every section needs a non-empty `title`.");
+    }
+    if (s.rows.length < 1 || s.rows.length > 10) {
+      fail("buildInteractiveList: every section must have 1 to 10 rows.");
+    }
+    for (const r of s.rows) {
+      if (typeof r.id !== "string" || r.id.length === 0) {
+        fail("buildInteractiveList: every row needs a non-empty `id`.");
+      }
+      if (typeof r.title !== "string" || r.title.length === 0) {
+        fail("buildInteractiveList: every row needs a non-empty `title`.");
+      }
+    }
+  }
+  const interactive = {
+    type: "list",
+    body: { text: input.body },
+    action: { button: input.button, sections: input.sections }
+  };
+  if (input.header !== void 0) interactive.header = input.header;
+  if (input.footer !== void 0) interactive.footer = { text: input.footer };
+  return withReplyTo({ ...BASE_PAYLOAD, to, type: "interactive", interactive }, replyTo);
+}
+function buildInteractiveCtaUrl(input) {
+  const to = ensureRecipient(input.to);
+  const replyTo = ensureReplyTo(input.replyTo);
+  if (typeof input.body !== "string" || input.body.length === 0) {
+    fail("buildInteractiveCtaUrl: `body` must be a non-empty string.");
+  }
+  if (typeof input.cta?.displayText !== "string" || input.cta.displayText.length === 0) {
+    fail("buildInteractiveCtaUrl: `cta.displayText` must be non-empty.");
+  }
+  try {
+    new URL(input.cta.url);
+  } catch {
+    fail("buildInteractiveCtaUrl: `cta.url` must be a valid URL.");
+  }
+  const interactive = {
+    type: "cta_url",
+    body: { text: input.body },
+    action: {
+      name: "cta_url",
+      parameters: { display_text: input.cta.displayText, url: input.cta.url }
+    }
+  };
+  if (input.header !== void 0) interactive.header = input.header;
+  if (input.footer !== void 0) interactive.footer = { text: input.footer };
+  return withReplyTo({ ...BASE_PAYLOAD, to, type: "interactive", interactive }, replyTo);
+}
+function buildInteractive(input) {
+  switch (input.kind) {
+    case "button":
+      return buildInteractiveButton(input);
+    case "list":
+      return buildInteractiveList(input);
+    case "cta_url":
+      return buildInteractiveCtaUrl(input);
+    default: {
+      const exhaustive = input;
+      fail(
+        `buildInteractive: unknown kind "${exhaustive.kind}". v1 supports button | list | cta_url.`
+      );
+    }
+  }
+}
+function buildTemplate(input) {
+  const to = ensureRecipient(input.to);
+  const replyTo = ensureReplyTo(input.replyTo);
+  if (typeof input.name !== "string" || input.name.length === 0) {
+    failTemplate("buildTemplate: `name` must be a non-empty string.", input.name);
+  }
+  if (typeof input.language !== "string" || input.language.length === 0) {
+    failTemplate("buildTemplate: `language` must be a non-empty BCP-47 code.", input.name);
+  }
+  if (input.components) {
+    for (const c of input.components) {
+      if (!["header", "body", "button", "footer", "carousel", "limited_time_offer"].includes(c.type)) {
+        failTemplate(`buildTemplate: invalid component.type "${c.type}".`, input.name);
+      }
+      if (c.type === "button" && c.sub_type === void 0) {
+        failTemplate(
+          "buildTemplate: button components require a `sub_type` (quick_reply | url | copy_code).",
+          input.name
+        );
+      }
+    }
+  }
+  const template = {
+    name: input.name,
+    language: { code: input.language }
+  };
+  if (input.components !== void 0) template.components = input.components;
+  const payload = withReplyTo(
+    { ...BASE_PAYLOAD, to, type: "template", template },
+    replyTo
+  );
+  if (input.validateAgainst !== void 0) {
+    validateTemplateSend(payload, input.validateAgainst);
+  }
+  return payload;
+}
+function buildReaction(input) {
+  const to = ensureRecipient(input.to);
+  const replyTo = ensureReplyTo(input.replyTo);
+  if (typeof input.messageId !== "string" || input.messageId.length === 0) {
+    fail("buildReaction: `messageId` (wamid) must be a non-empty string.");
+  }
+  if (typeof input.emoji !== "string") {
+    fail('buildReaction: `emoji` must be a string (use "" to clear).');
+  }
+  return withReplyTo(
+    {
+      ...BASE_PAYLOAD,
+      to,
+      type: "reaction",
+      reaction: { message_id: input.messageId, emoji: input.emoji }
+    },
+    replyTo
+  );
+}
+function buildAuthTemplate(input) {
+  const to = ensureRecipient(input.to);
+  const replyTo = ensureReplyTo(input.replyTo);
+  if (typeof input.name !== "string" || input.name.length === 0) {
+    failTemplate("buildAuthTemplate: `name` must be a non-empty string.", input.name);
+  }
+  if (typeof input.language !== "string" || input.language.length === 0) {
+    failTemplate("buildAuthTemplate: `language` must be a non-empty BCP-47 code.", input.name);
+  }
+  if (typeof input.otp !== "string" || input.otp.length === 0) {
+    failTemplate("buildAuthTemplate: `otp` must be a non-empty string.", input.name);
+  }
+  if (input.otp.length > 15) {
+    failTemplate(
+      `buildAuthTemplate: \`otp\` exceeds Meta's 15-character maximum (got ${input.otp.length}).`,
+      input.name
+    );
+  }
+  const buttonIndex = input.otpButtonIndex ?? "0";
+  const components = [
+    { type: "body", parameters: [{ type: "text", text: input.otp }] },
+    {
+      type: "button",
+      sub_type: "url",
+      index: buttonIndex,
+      parameters: [{ type: "text", text: input.otp }]
+    }
+  ];
+  return withReplyTo(
+    {
+      ...BASE_PAYLOAD,
+      to,
+      type: "template",
+      template: { name: input.name, language: { code: input.language }, components }
+    },
+    replyTo
+  );
+}
+function buildVoice(input) {
+  const to = ensureRecipient(input.to);
+  const replyTo = ensureReplyTo(input.replyTo);
+  exactlyOne(input.id, input.link, "buildVoice");
+  const audio = typeof input.id === "string" && input.id.length > 0 ? { id: input.id, voice: true } : { link: input.link, voice: true };
+  return withReplyTo({ ...BASE_PAYLOAD, to, type: "audio", audio }, replyTo);
+}
+var CAROUSEL_MAX_CARDS = 10;
+function buildCarouselTemplate(input) {
+  const to = ensureRecipient(input.to);
+  const replyTo = ensureReplyTo(input.replyTo);
+  if (typeof input.name !== "string" || input.name.length === 0) {
+    failTemplate("buildCarouselTemplate: `name` must be a non-empty string.", input.name);
+  }
+  if (typeof input.language !== "string" || input.language.length === 0) {
+    failTemplate("buildCarouselTemplate: `language` must be a non-empty BCP-47 code.", input.name);
+  }
+  const cards = input.cards;
+  if (cards === null || typeof cards !== "object" || typeof cards.length !== "number") {
+    failTemplate("buildCarouselTemplate: `cards` must be a non-empty array.", input.name);
+  }
+  if (cards.length === 0) {
+    failTemplate("buildCarouselTemplate: `cards` must be a non-empty array.", input.name);
+  }
+  if (cards.length > CAROUSEL_MAX_CARDS) {
+    failTemplate(
+      `buildCarouselTemplate: cards.length (${cards.length}) exceeds Meta's ${CAROUSEL_MAX_CARDS}-card maximum.`,
+      input.name
+    );
+  }
+  const topLevelComponents = [];
+  if (input.bodyParameters !== void 0 && input.bodyParameters.length > 0) {
+    topLevelComponents.push({
+      type: "body",
+      parameters: input.bodyParameters.map((text) => ({ type: "text", text }))
+    });
+  }
+  topLevelComponents.push({
+    type: "carousel",
+    cards: cards.map((card, cardIndex) => buildCarouselCard(card, cardIndex, input.name))
+  });
+  return withReplyTo(
+    {
+      ...BASE_PAYLOAD,
+      to,
+      type: "template",
+      template: {
+        name: input.name,
+        language: { code: input.language },
+        components: topLevelComponents
+      }
+    },
+    replyTo
+  );
+}
+function buildCarouselCard(card, cardIndex, templateName) {
+  const headerSource = card.header;
+  if (typeof headerSource?.type !== "string" || !["image", "video"].includes(headerSource.type)) {
+    failTemplate(
+      `buildCarouselTemplate: card[${cardIndex}].header.type must be "image" or "video".`,
+      templateName
+    );
+  }
+  exactlyOne(
+    headerSource.mediaId,
+    headerSource.link,
+    `buildCarouselTemplate: card[${cardIndex}].header`
+  );
+  const mediaParam = typeof headerSource.mediaId === "string" && headerSource.mediaId.length > 0 ? { id: headerSource.mediaId } : { link: headerSource.link };
+  const headerParam = headerSource.type === "image" ? { type: "image", image: mediaParam } : { type: "video", video: mediaParam };
+  const components = [{ type: "header", parameters: [headerParam] }];
+  if (card.bodyParameters !== void 0 && card.bodyParameters.length > 0) {
+    components.push({
+      type: "body",
+      parameters: card.bodyParameters.map((text) => ({ type: "text", text }))
+    });
+  }
+  if (card.buttons !== void 0) {
+    card.buttons.forEach((btn, btnIndex) => {
+      if (btn.subType === "quick_reply") {
+        components.push({
+          type: "button",
+          sub_type: "quick_reply",
+          index: btnIndex,
+          parameters: [{ type: "payload", payload: btn.payload }]
+        });
+      } else {
+        components.push({
+          type: "button",
+          sub_type: "url",
+          index: btnIndex,
+          parameters: [{ type: "text", text: btn.text }]
+        });
+      }
+    });
+  }
+  return { card_index: cardIndex, components };
+}
+
+// src/messages/send.ts
+function sendMessage(client, payload, options) {
+  const path = `/${client.phoneNumberId}/messages`;
+  return client.request("POST", path, payload, options);
+}
+
+// src/templates/api.ts
+function listTemplates(client, query = {}, options) {
+  const path = `/${client.wabaId}/message_templates${buildQuery(query)}`;
+  return client.request("GET", path, void 0, options);
+}
+function getTemplate(client, templateId, options) {
+  if (typeof templateId !== "string" || templateId.length === 0) {
+    throw new TypeError("getTemplate: templateId must be a non-empty string.");
+  }
+  const path = `/${templateId}`;
+  return client.request("GET", path, void 0, options);
+}
+function buildQuery(query) {
+  const entries = [];
+  if (query.name !== void 0) entries.push(["name", query.name]);
+  if (query.language !== void 0) entries.push(["language", query.language]);
+  if (query.status !== void 0) entries.push(["status", query.status]);
+  if (query.category !== void 0) entries.push(["category", query.category]);
+  if (query.limit !== void 0) entries.push(["limit", String(query.limit)]);
+  if (query.after !== void 0) entries.push(["after", query.after]);
+  if (query.before !== void 0) entries.push(["before", query.before]);
+  if (entries.length === 0) return "";
+  return "?" + entries.map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join("&");
+}
+
+// src/types/constants.ts
+var GRAPH_API_VERSION = "v25.0";
+var META_GRAPH_BASE_URL = "https://graph.facebook.com";
+var WEBHOOK_ACK_DEADLINE_MS = 3e4;
+var WINDOW_TTL_MS = 24 * 60 * 60 * 1e3;
+var WEBHOOK_DEDUPE_TTL_MS = 24 * 60 * 60 * 1e3;
+
+// src/observability/redact.ts
+var redactSalt = "@dojocoding/whatsapp:dev-default-salt";
+var encoder = new TextEncoder();
+function setRedactSalt(salt) {
+  if (typeof salt !== "string" || salt.length === 0) {
+    throw new TypeError("setRedactSalt: salt must be a non-empty string.");
+  }
+  redactSalt = salt;
+}
+async function hashPhoneNumberId(value) {
+  const input = encoder.encode(`${redactSalt}:${value}`);
+  const digest = await crypto.subtle.digest("SHA-256", input);
+  const bytes = new Uint8Array(digest);
+  let out = "";
+  for (let i = 0; i < 8; i++) {
+    out += bytes[i].toString(16).padStart(2, "0");
+  }
+  return out;
+}
+var TRACER_NAME = "@dojocoding/whatsapp";
+var TRACER_VERSION = "0.0.0";
+function getTracer() {
+  return trace.getTracer(TRACER_NAME, TRACER_VERSION);
+}
+async function withSpan(name, fn, attributes) {
+  const tracer = getTracer();
+  return tracer.startActiveSpan(name, async (span) => {
+    if (attributes !== void 0) {
+      span.setAttributes(attributes);
+    }
+    try {
+      const result = await fn();
+      span.end();
+      return result;
+    } catch (err) {
+      if (err instanceof Error) {
+        span.recordException(err);
+        span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+      } else {
+        span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
+      }
+      span.end();
+      throw err;
+    }
+  });
+}
+
+// src/client/errors.ts
+var RETRYABLE_RATE_LIMIT_CODES = /* @__PURE__ */ new Set([
+  130429,
+  // Generic rate limit
+  131048,
+  // Spam-detection rate limit
+  131056,
+  // Pair rate limit
+  131053
+  // Media-upload throttle
+]);
+var WINDOW_CLOSED_CODE = 131026;
+var AUTH_CODES = /* @__PURE__ */ new Set([
+  190
+  // Invalid OAuth access token (subcodes: 463 expired, 467 invalid, 492 changed)
+]);
+var PERMISSION_CODES = /* @__PURE__ */ new Set([
+  200,
+  // Permissions error (general)
+  210,
+  // User not visible / phone-level permission
+  230,
+  // Permission disabled
+  294,
+  // Permission for this action is required
+  299
+  // Permission denied for this action
+]);
+var CAPABILITY_CODES = /* @__PURE__ */ new Set([
+  100
+  // Invalid parameter / API Unknown — request shape problem
+]);
+function isMetaErrorEnvelope(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  if (typeof v.error !== "object" || v.error === null) return false;
+  const e = v.error;
+  return typeof e.code === "number" && typeof e.message === "string";
+}
+function looksLikeTemplateCode(code) {
+  return code >= 132e3 && code < 133e3;
+}
+function mapMetaError(httpStatus, body) {
+  if (!isMetaErrorEnvelope(body)) {
+    const fallbackMessage = typeof body === "string" && body.length > 0 ? `Graph API ${httpStatus}: ${body.slice(0, 200)}` : `Graph API ${httpStatus} with non-Meta-shaped error body`;
+    return new WhatsAppError("UNKNOWN", fallbackMessage);
+  }
+  const { code, message } = body.error;
+  if (RETRYABLE_RATE_LIMIT_CODES.has(code)) {
+    return new RateLimitError(message, { metaCode: code });
+  }
+  if (code === WINDOW_CLOSED_CODE) {
+    const recipient = extractRecipientFromMetaError(body);
+    return new WindowClosedError(recipient ?? "<unknown>");
+  }
+  if (AUTH_CODES.has(code)) {
+    const subcode = body.error.error_subcode;
+    return new AuthenticationError(message, {
+      metaCode: code,
+      ...typeof subcode === "number" ? { subcode } : {}
+    });
+  }
+  if (PERMISSION_CODES.has(code)) {
+    return new PermissionError(message, { metaCode: code });
+  }
+  if (CAPABILITY_CODES.has(code)) {
+    return new CapabilityError(message, { metaCode: code });
+  }
+  if (looksLikeTemplateCode(code)) {
+    return new TemplateError(message);
+  }
+  return new WhatsAppError("UNKNOWN", `Graph API ${httpStatus} (#${code}): ${message}`);
+}
+function extractRecipientFromMetaError(body) {
+  const data = body.error.error_data;
+  if (!data) return void 0;
+  const candidate = data["recipient_phone_number"] ?? data["customer_wa_id"];
+  if (typeof candidate === "string" && candidate.length > 0) {
+    return candidate;
+  }
+  return void 0;
+}
+function isRetryableError(err) {
+  if (err instanceof RateLimitError && typeof err.metaCode === "number") {
+    return RETRYABLE_RATE_LIMIT_CODES.has(err.metaCode);
+  }
+  return false;
+}
+function isRetryableHttpStatus(status) {
+  return status === 408 || status === 429 || status >= 500 && status < 600;
+}
+
+// src/client/retry.ts
+var DEFAULT_RETRY_POLICY = {
+  maxAttempts: 4,
+  baseDelayMs: 250,
+  maxDelayMs: 8e3,
+  jitter: "full",
+  floorMs: 50
+};
+var TransientHttpError = class extends Error {
+  retryAfterMs;
+  constructor(message, retryAfterMs) {
+    super(message);
+    this.name = "TransientHttpError";
+    this.retryAfterMs = retryAfterMs;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function fullJitterDelay(attempt, policy, random = Math.random) {
+  const exp = policy.baseDelayMs * 2 ** Math.max(0, attempt - 1);
+  const cap = Math.min(policy.maxDelayMs, exp);
+  const sample = random() * cap;
+  return Math.max(policy.floorMs, sample);
+}
+function parseRetryAfter(headerValue, now = Date.now()) {
+  if (typeof headerValue !== "string") return void 0;
+  const trimmed = headerValue.trim();
+  if (trimmed.length === 0) return void 0;
+  const asNumber = Number(trimmed);
+  if (Number.isFinite(asNumber) && asNumber >= 0) {
+    return Math.floor(asNumber * 1e3);
+  }
+  const parsedDate = Date.parse(trimmed);
+  if (Number.isFinite(parsedDate)) {
+    return Math.max(0, parsedDate - now);
+  }
+  return void 0;
+}
+async function retry(fn, policy = DEFAULT_RETRY_POLICY, hooks = {}) {
+  const sleep2 = hooks.sleep ?? defaultSleep;
+  const random = hooks.random ?? Math.random;
+  let lastError;
+  for (let attempt = 1; attempt <= policy.maxAttempts; attempt += 1) {
+    try {
+      return await fn(attempt);
+    } catch (err) {
+      lastError = err;
+      if (attempt === policy.maxAttempts || !shouldRetry(err)) {
+        throw err;
+      }
+      const hint = err instanceof TransientHttpError ? err.retryAfterMs : void 0;
+      const baseDelay = fullJitterDelay(attempt, policy, random);
+      const delay = typeof hint === "number" ? Math.min(policy.maxDelayMs, Math.max(policy.floorMs, hint)) : baseDelay;
+      await sleep2(delay);
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error("retry: exhausted");
+}
+function shouldRetry(err) {
+  if (err instanceof TransientHttpError) return true;
+  if (isRetryableError(err)) return true;
+  if (err instanceof TypeError && /fetch failed/i.test(err.message)) return true;
+  if (err instanceof Error && err.name === "AbortError") return true;
+  return false;
+}
+
+// src/client/transport.ts
+var IDEMPOTENCY_HEADER = "X-Dojo-Idempotency-Key";
+function buildGraphUrl(version, path) {
+  const cleanPath = path.startsWith("/") ? path.slice(1) : path;
+  return `${META_GRAPH_BASE_URL}/${version}/${cleanPath}`;
+}
+async function request(client, method, path, body, options = {}) {
+  const idempotencyKey = options.idempotencyKey ?? randomUUID();
+  const version = options.graphApiVersion ?? client.graphApiVersion;
+  const url = buildGraphUrl(version, path);
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  const hashedPhoneNumberId = await hashPhoneNumberId(client.phoneNumberId);
+  const bearerToken = await client._resolveBearerToken();
+  return withSpan(
+    "whatsapp.request",
+    async () => {
+      try {
+        return await retry(
+          async () => doFetch(fetchImpl, bearerToken, method, url, body, idempotencyKey, options.signal),
+          options.retryPolicy ?? DEFAULT_RETRY_POLICY,
+          options.retryHooks ?? {}
+        );
+      } catch (err) {
+        attachErrorAttributesToActiveSpan(err);
+        throw err;
+      }
+    },
+    {
+      "whatsapp.method": method,
+      "whatsapp.path": path.startsWith("/") ? path : `/${path}`,
+      "whatsapp.phone_number_id": hashedPhoneNumberId,
+      "whatsapp.idempotency_key": idempotencyKey
+    }
+  );
+}
+function attachErrorAttributesToActiveSpan(err) {
+  const span = trace.getActiveSpan();
+  if (span === void 0) return;
+  if (typeof err === "object" && err !== null && "code" in err) {
+    const code = err.code;
+    if (typeof code === "string") {
+      span.setAttribute("whatsapp.error.code", code);
+    }
+  }
+  const metaCode = extractMetaCode(err);
+  if (metaCode !== void 0) {
+    span.setAttribute("whatsapp.error.meta_code", metaCode);
+  }
+}
+function extractMetaCode(err) {
+  if (err instanceof RateLimitError && typeof err.metaCode === "number") return err.metaCode;
+  if (err instanceof AuthenticationError && typeof err.metaCode === "number") return err.metaCode;
+  if (err instanceof PermissionError && typeof err.metaCode === "number") return err.metaCode;
+  if (err instanceof CapabilityError && typeof err.metaCode === "number") return err.metaCode;
+  return void 0;
+}
+async function doFetch(fetchImpl, bearerToken, method, url, body, idempotencyKey, signal) {
+  const headers = {
+    Authorization: `Bearer ${bearerToken}`,
+    Accept: "application/json",
+    [IDEMPOTENCY_HEADER]: idempotencyKey
+  };
+  let serializedBody;
+  if (body !== void 0) {
+    headers["Content-Type"] = "application/json";
+    serializedBody = JSON.stringify(body);
+  }
+  const init = { method, headers };
+  if (serializedBody !== void 0) {
+    init.body = serializedBody;
+  }
+  if (signal !== void 0) {
+    init.signal = signal;
+  }
+  const response = await fetchImpl(url, init);
+  if (response.status >= 200 && response.status < 300) {
+    if (response.status === 204) {
+      return void 0;
+    }
+    return await response.json();
+  }
+  const parsedBody = await safeReadBody(response);
+  if (isRetryableHttpStatus(response.status)) {
+    const hint = parseRetryAfter(response.headers.get("retry-after"));
+    throw new TransientHttpError(`Graph API ${response.status} (transient)`, hint);
+  }
+  throw mapMetaError(response.status, parsedBody);
+}
+async function safeReadBody(response) {
+  const contentType = response.headers.get("content-type") ?? "";
+  try {
+    if (contentType.includes("application/json")) {
+      return await response.json();
+    }
+    return await response.text();
+  } catch {
+    return void 0;
+  }
+}
+
+// src/client/health.ts
+async function healthCheck(client, options = {}) {
+  const token = await client._resolveBearerToken();
+  const path = `/debug_token?input_token=${encodeURIComponent(token)}`;
+  const response = await request(client, "GET", path, void 0, options);
+  const data = response.data;
+  if (!data || data.is_valid !== true) {
+    const message = data?.error?.message ?? "Token validation failed: Meta /debug_token returned is_valid=false";
+    throw new WhatsAppError("UNKNOWN", message);
+  }
+  return {
+    valid: true,
+    expiresAt: typeof data.expires_at === "number" && data.expires_at > 0 ? data.expires_at * 1e3 : null,
+    appId: data.app_id ?? null,
+    userId: data.user_id ?? null,
+    scopes: data.scopes ?? []
+  };
+}
+
+// src/client/whatsapp-client.ts
+var STRING_CREDENTIAL_FIELDS = [
+  "phoneNumberId",
+  "wabaId",
+  "appSecret"
+];
+function isValidTokenOption(value) {
+  if (typeof value === "function") return true;
+  return typeof value === "string" && value.length > 0;
+}
+var WhatsAppClient = class {
+  phoneNumberId;
+  wabaId;
+  graphApiVersion;
+  #tokenProvider;
+  #appSecret;
+  #windowTracker;
+  constructor(options) {
+    const missing = STRING_CREDENTIAL_FIELDS.filter((field) => {
+      const value = options[field];
+      return typeof value !== "string" || value.length === 0;
+    });
+    if (!isValidTokenOption(options.token)) {
+      missing.push("token");
+    }
+    if (missing.length > 0) {
+      throw new MissingCredentialsError(missing);
+    }
+    this.phoneNumberId = options.phoneNumberId;
+    this.wabaId = options.wabaId;
+    this.#tokenProvider = typeof options.token === "function" ? options.token : () => options.token;
+    this.#appSecret = options.appSecret;
+    this.graphApiVersion = options.graphApiVersion ?? GRAPH_API_VERSION;
+    this.#windowTracker = options.windowTracker;
+  }
+  /**
+   * Whether the 24h customer-service window is currently open for `to`.
+   * Returns `true` when no window tracker is configured (preserving the
+   * pre-Phase-4 "ungated" behaviour); otherwise delegates to the tracker.
+   */
+  isWindowOpen(to) {
+    if (this.#windowTracker === void 0) return Promise.resolve(true);
+    return this.#windowTracker.isWindowOpen(to);
+  }
+  async #assertWindowOpen(to) {
+    if (this.#windowTracker === void 0) return;
+    const open = await this.#windowTracker.isWindowOpen(to);
+    if (!open) {
+      throw new WindowClosedError(to);
+    }
+  }
+  /**
+   * @internal — exposed for capability slices that need the bearer
+   * token. Resolves the configured `TokenProvider` exactly once per
+   * call; surfaces provider failures as `AuthenticationError` before
+   * the HTTP request is made.
+   */
+  async _resolveBearerToken() {
+    let resolved;
+    try {
+      resolved = await this.#tokenProvider();
+    } catch (err) {
+      throw new AuthenticationError(
+        "WhatsApp token provider threw an error before the request could be made.",
+        {},
+        { cause: err }
+      );
+    }
+    if (typeof resolved !== "string") {
+      throw new AuthenticationError(
+        `WhatsApp token provider returned a non-string value (typeof ${typeof resolved}).`
+      );
+    }
+    if (resolved.length === 0) {
+      throw new AuthenticationError("WhatsApp token provider returned an empty string.");
+    }
+    return resolved;
+  }
+  /** @internal — exposed for the webhook receiver capability (Phase 3). */
+  _getAppSecret() {
+    return this.#appSecret;
+  }
+  /**
+   * Issue an authenticated Graph API request.
+   *
+   * @internal — public-API surface for sends, templates, etc. lands in
+   * later phases (Phase 2 message-builders, Phase 5 template-management).
+   */
+  request(method, path, body, options) {
+    return request(this, method, path, body, options);
+  }
+  /**
+   * Verify the bearer token via Meta's `/debug_token` endpoint.
+   *
+   * Resolves with the parsed token info; throws `WhatsAppError` if the
+   * token is invalid or the call fails.
+   */
+  healthCheck(options) {
+    return healthCheck(this, options ?? {});
+  }
+  // ───────────── Convenience send methods ─────────────
+  async sendText(input, options) {
+    await this.#assertWindowOpen(input.to);
+    return sendMessage(this, buildText(input), options);
+  }
+  async sendImage(input, options) {
+    await this.#assertWindowOpen(input.to);
+    return sendMessage(this, buildImage(input), options);
+  }
+  async sendVideo(input, options) {
+    await this.#assertWindowOpen(input.to);
+    return sendMessage(this, buildVideo(input), options);
+  }
+  async sendAudio(input, options) {
+    await this.#assertWindowOpen(input.to);
+    return sendMessage(this, buildAudio(input), options);
+  }
+  async sendDocument(input, options) {
+    await this.#assertWindowOpen(input.to);
+    return sendMessage(this, buildDocument(input), options);
+  }
+  async sendSticker(input, options) {
+    await this.#assertWindowOpen(input.to);
+    return sendMessage(this, buildSticker(input), options);
+  }
+  async sendLocation(input, options) {
+    await this.#assertWindowOpen(input.to);
+    return sendMessage(this, buildLocation(input), options);
+  }
+  async sendContacts(input, options) {
+    await this.#assertWindowOpen(input.to);
+    return sendMessage(this, buildContacts(input), options);
+  }
+  async sendInteractive(input, options) {
+    await this.#assertWindowOpen(input.to);
+    return sendMessage(this, buildInteractive(input), options);
+  }
+  /**
+   * Window-exempt: templates are the escape hatch when the window is closed.
+   * Async so any synchronous error from `buildTemplate` (e.g.,
+   * `validateAgainst` mismatch) surfaces as a rejected promise rather
+   * than a synchronous throw.
+   */
+  async sendTemplate(input, options) {
+    return sendMessage(this, buildTemplate(input), options);
+  }
+  /** Window-exempt: authentication templates are the canonical out-of-window send. */
+  async sendAuthTemplate(input, options) {
+    return sendMessage(this, buildAuthTemplate(input), options);
+  }
+  /**
+   * Send a voice note (audio with `voice: true`). Window-gated like
+   * any other free-form media send. Voice notes trigger transcription
+   * support, auto-download, and a "played" status when the recipient
+   * listens.
+   */
+  async sendVoice(input, options) {
+    await this.#assertWindowOpen(input.to);
+    return sendMessage(this, buildVoice(input), options);
+  }
+  /** Window-exempt: carousel sends are template sends. */
+  async sendCarouselTemplate(input, options) {
+    return sendMessage(this, buildCarouselTemplate(input), options);
+  }
+  // ───────────── Template management (Phase 5) ─────────────
+  listTemplates(query, options) {
+    return listTemplates(this, query ?? {}, options);
+  }
+  getTemplate(templateId, options) {
+    return getTemplate(this, templateId, options);
+  }
+  /** Window-exempt: reactions are part of an existing thread. */
+  sendReaction(input, options) {
+    return sendMessage(this, buildReaction(input), options);
+  }
+  /**
+   * Send any pre-built `WhatsAppMessage` payload as a reply to a previous
+   * message identified by its wamid. Sets `context.message_id` and posts.
+   * Window-gated for non-template, non-reaction payloads.
+   */
+  async sendReply(replyTo, payload, options) {
+    if (typeof replyTo !== "string" || replyTo.length === 0) {
+      throw new Error("sendReply: `replyTo` must be a non-empty wamid string.");
+    }
+    if (payload.type !== "template" && payload.type !== "reaction") {
+      await this.#assertWindowOpen(payload.to);
+    }
+    const withContext = { ...payload, context: { message_id: replyTo } };
+    return sendMessage(this, withContext, options);
+  }
+};
+
+// src/mock/client.ts
+var MockWhatsAppClient = class {
+  phoneNumberId;
+  wabaId;
+  graphApiVersion;
+  #windowTracker;
+  #now;
+  #templates;
+  #sentMessages = [];
+  #counter = 0;
+  constructor(options) {
+    this.phoneNumberId = options.phoneNumberId;
+    this.wabaId = options.wabaId;
+    this.graphApiVersion = options.graphApiVersion ?? GRAPH_API_VERSION;
+    this.#windowTracker = options.windowTracker;
+    this.#now = options.now ?? Date.now;
+    this.#templates = options.templates ?? [];
+  }
+  get sentMessages() {
+    return this.#sentMessages;
+  }
+  reset() {
+    this.#sentMessages = [];
+    this.#counter = 0;
+  }
+  isWindowOpen(to) {
+    if (this.#windowTracker === void 0) return Promise.resolve(true);
+    return this.#windowTracker.isWindowOpen(to);
+  }
+  /**
+   * Synthesise a webhook event into a `WebhookReceiver`. Bypasses
+   * signature verification — the receiver dispatches handlers directly.
+   */
+  simulateInbound(receiver, event) {
+    return receiver._dispatchEvents([event]);
+  }
+  // ───────────── send* (mirror WhatsAppClient) ─────────────
+  async sendText(input) {
+    await this.#assertWindowOpen(input.to);
+    return this.#record(buildText(input));
+  }
+  async sendImage(input) {
+    await this.#assertWindowOpen(input.to);
+    return this.#record(buildImage(input));
+  }
+  async sendVideo(input) {
+    await this.#assertWindowOpen(input.to);
+    return this.#record(buildVideo(input));
+  }
+  async sendAudio(input) {
+    await this.#assertWindowOpen(input.to);
+    return this.#record(buildAudio(input));
+  }
+  async sendDocument(input) {
+    await this.#assertWindowOpen(input.to);
+    return this.#record(buildDocument(input));
+  }
+  async sendSticker(input) {
+    await this.#assertWindowOpen(input.to);
+    return this.#record(buildSticker(input));
+  }
+  async sendLocation(input) {
+    await this.#assertWindowOpen(input.to);
+    return this.#record(buildLocation(input));
+  }
+  async sendContacts(input) {
+    await this.#assertWindowOpen(input.to);
+    return this.#record(buildContacts(input));
+  }
+  async sendInteractive(input) {
+    await this.#assertWindowOpen(input.to);
+    return this.#record(buildInteractive(input));
+  }
+  sendTemplate(input) {
+    return Promise.resolve(this.#record(buildTemplate(input)));
+  }
+  sendAuthTemplate(input) {
+    return Promise.resolve(this.#record(buildAuthTemplate(input)));
+  }
+  async sendVoice(input) {
+    await this.#assertWindowOpen(input.to);
+    return this.#record(buildVoice(input));
+  }
+  sendCarouselTemplate(input) {
+    return Promise.resolve(this.#record(buildCarouselTemplate(input)));
+  }
+  sendReaction(input) {
+    return Promise.resolve(this.#record(buildReaction(input)));
+  }
+  async sendReply(replyTo, payload) {
+    if (typeof replyTo !== "string" || replyTo.length === 0) {
+      throw new Error("sendReply: `replyTo` must be a non-empty wamid string.");
+    }
+    if (payload.type !== "template" && payload.type !== "reaction") {
+      await this.#assertWindowOpen(payload.to);
+    }
+    const withContext = { ...payload, context: { message_id: replyTo } };
+    return this.#record(withContext);
+  }
+  // ───────────── template management (Phase 5 mirror) ─────────────
+  listTemplates(query, _options) {
+    let data = this.#templates;
+    if (query?.name !== void 0) data = data.filter((t) => t.name === query.name);
+    if (query?.language !== void 0) data = data.filter((t) => t.language === query.language);
+    if (query?.status !== void 0) data = data.filter((t) => t.status === query.status);
+    if (query?.category !== void 0) data = data.filter((t) => t.category === query.category);
+    if (typeof query?.limit === "number" && query.limit >= 0) data = data.slice(0, query.limit);
+    return Promise.resolve({ data });
+  }
+  getTemplate(templateId, _options) {
+    if (typeof templateId !== "string" || templateId.length === 0) {
+      return Promise.reject(new TypeError("getTemplate: templateId must be a non-empty string."));
+    }
+    const found = this.#templates.find((t) => t.id === templateId);
+    if (found !== void 0) return Promise.resolve(found);
+    return Promise.reject(
+      new TemplateError(
+        this.#templates.length === 0 ? `MockWhatsAppClient has no template registry; pass options.templates or stub via your test harness.` : `Template "${templateId}" not in MockWhatsAppClient registry.`,
+        templateId
+      )
+    );
+  }
+  // ───────────── internals ─────────────
+  async #assertWindowOpen(to) {
+    if (this.#windowTracker === void 0) return;
+    const open = await this.#windowTracker.isWindowOpen(to);
+    if (!open) throw new WindowClosedError(to);
+  }
+  #record(payload) {
+    this.#counter += 1;
+    const wamid = `wamid.mock-${this.#counter}`;
+    this.#sentMessages.push({ wamid, payload, sentAt: this.#now() });
+    return {
+      messaging_product: "whatsapp",
+      contacts: [{ input: payload.to, wa_id: payload.to }],
+      messages: [{ id: wamid }]
+    };
+  }
+};
+
+// src/mock/factory.ts
+function pickWhatsAppClient(options) {
+  if (options.forceMock === true) {
+    return makeMock(options);
+  }
+  if (options.forceReal === true) {
+    return new WhatsAppClient(options);
+  }
+  if (typeof process !== "undefined" && process.env?.["WHATSAPP_MODE"] === "mock") {
+    return makeMock(options);
+  }
+  return new WhatsAppClient(options);
+}
+function makeMock(options) {
+  const mockOpts = {
+    phoneNumberId: options.phoneNumberId,
+    wabaId: options.wabaId
+  };
+  if (options.graphApiVersion !== void 0) mockOpts.graphApiVersion = options.graphApiVersion;
+  if (options.windowTracker !== void 0) mockOpts.windowTracker = options.windowTracker;
+  if (options.templates !== void 0) mockOpts.templates = options.templates;
+  return new MockWhatsAppClient(mockOpts);
+}
+
+// src/queue/token-bucket.ts
+var TokenBucket = class {
+  #capacity;
+  #refillPerMs;
+  #now;
+  #tokens;
+  #lastRefillAt;
+  #lastAccessAt;
+  /** Tail of the single-flight wait chain. `undefined` when no waiter is queued. */
+  #waitTail;
+  constructor(options) {
+    if (!Number.isFinite(options.capacity) || options.capacity <= 0) {
+      throw new RangeError("TokenBucket: capacity must be a positive finite number.");
+    }
+    if (!Number.isFinite(options.refillPerMs) || options.refillPerMs <= 0) {
+      throw new RangeError("TokenBucket: refillPerMs must be a positive finite number.");
+    }
+    this.#capacity = options.capacity;
+    this.#refillPerMs = options.refillPerMs;
+    this.#now = options.now ?? Date.now;
+    this.#tokens = options.capacity;
+    const t = this.#now();
+    this.#lastRefillAt = t;
+    this.#lastAccessAt = t;
+  }
+  /** Current token count after applying any pending refill. Pure read. */
+  peek() {
+    this.#refill();
+    return this.#tokens;
+  }
+  /** Last access timestamp (epoch ms). Used by `BucketMap` eviction. */
+  lastAccessAt() {
+    return this.#lastAccessAt;
+  }
+  /** Whether the bucket currently has its full capacity worth of tokens. */
+  isFull() {
+    return this.peek() >= this.#capacity;
+  }
+  /**
+   * Acquire `count` tokens. Resolves once the tokens are reserved
+   * for this caller. Concurrent acquires queue behind the previous
+   * waiter so the refill is consumed in arrival order.
+   */
+  acquire(count = 1) {
+    if (!Number.isFinite(count) || count <= 0) {
+      return Promise.reject(new RangeError("TokenBucket.acquire: count must be > 0."));
+    }
+    if (count > this.#capacity) {
+      return Promise.reject(
+        new RangeError(
+          `TokenBucket.acquire: count (${count}) exceeds bucket capacity (${this.#capacity}).`
+        )
+      );
+    }
+    this.#lastAccessAt = this.#now();
+    if (this.#waitTail === void 0) {
+      this.#refill();
+      if (this.#tokens >= count) {
+        this.#tokens -= count;
+        return Promise.resolve();
+      }
+    }
+    const tail = this.#waitTail ?? Promise.resolve();
+    const ours = tail.then(() => this.#consumeAfterWait(count));
+    this.#waitTail = ours.catch(() => void 0);
+    return ours;
+  }
+  async #consumeAfterWait(count) {
+    for (; ; ) {
+      this.#refill();
+      if (this.#tokens >= count) {
+        this.#tokens -= count;
+        if (this.#waitTail !== void 0) {
+          await Promise.resolve();
+          this.#maybeClearTail();
+        }
+        return;
+      }
+      const deficit = count - this.#tokens;
+      const waitMs = Math.max(1, Math.ceil(deficit / this.#refillPerMs));
+      await sleep(waitMs);
+    }
+  }
+  #maybeClearTail() {
+    this.#waitTail = void 0;
+  }
+  #refill() {
+    const now = this.#now();
+    const elapsed = Math.max(0, now - this.#lastRefillAt);
+    if (elapsed === 0) return;
+    this.#tokens = Math.min(this.#capacity, this.#tokens + elapsed * this.#refillPerMs);
+    this.#lastRefillAt = now;
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+// src/queue/bucket-map.ts
+var BucketMap = class {
+  #factory;
+  #now;
+  #evictAfterMs;
+  #buckets = /* @__PURE__ */ new Map();
+  constructor(options) {
+    const evictAfterMs = options.evictAfterMs ?? 6e4;
+    if (!Number.isFinite(evictAfterMs) || evictAfterMs <= 0) {
+      throw new RangeError("BucketMap: evictAfterMs must be a positive finite number.");
+    }
+    this.#evictAfterMs = evictAfterMs;
+    this.#now = options.now ?? Date.now;
+    this.#factory = () => new TokenBucket({
+      capacity: options.capacity,
+      refillPerMs: options.refillPerMs,
+      ...options.now !== void 0 ? { now: options.now } : {}
+    });
+  }
+  acquire(key, count = 1) {
+    this.#evictStale();
+    let bucket = this.#buckets.get(key);
+    if (bucket === void 0) {
+      bucket = this.#factory();
+      this.#buckets.set(key, bucket);
+    }
+    return bucket.acquire(count);
+  }
+  size() {
+    return this.#buckets.size;
+  }
+  #evictStale() {
+    const cutoff = this.#now() - this.#evictAfterMs;
+    for (const [key, bucket] of this.#buckets) {
+      if (bucket.isFull() && bucket.lastAccessAt() < cutoff) {
+        this.#buckets.delete(key);
+      }
+    }
+  }
+};
+
+// src/queue/with-rate-limit.ts
+var DEFAULT_PER_PAIR = { messages: 1, per: 6e3 };
+var DEFAULT_PER_WABA = { mps: 80 };
+function withRateLimit(client, options = {}) {
+  const perPair = options.perPair ?? DEFAULT_PER_PAIR;
+  const perWaba = options.perWaba ?? DEFAULT_PER_WABA;
+  const perPairBuckets = new BucketMap({
+    capacity: perPair.messages,
+    refillPerMs: perPair.messages / perPair.per,
+    ...options.now !== void 0 ? { now: options.now } : {},
+    ...options.evictAfterMs !== void 0 ? { evictAfterMs: options.evictAfterMs } : {}
+  });
+  const perWabaBuckets = new BucketMap({
+    capacity: perWaba.mps,
+    refillPerMs: perWaba.mps / 1e3,
+    ...options.now !== void 0 ? { now: options.now } : {},
+    ...options.evictAfterMs !== void 0 ? { evictAfterMs: options.evictAfterMs } : {}
+  });
+  async function gate(to) {
+    const pairKey = `${client.phoneNumberId}:${to}`;
+    const wabaKey = client.wabaId;
+    const start = (options.now ?? Date.now)();
+    const hashedRecipient = await hashPhoneNumberId(to);
+    await withSpan(
+      "whatsapp.queue.acquire",
+      async () => {
+        await perPairBuckets.acquire(pairKey);
+        await perWabaBuckets.acquire(wabaKey);
+        const end = (options.now ?? Date.now)();
+        void end;
+        void start;
+      },
+      {
+        "whatsapp.queue.pair_recipient": hashedRecipient,
+        "whatsapp.queue.waba_id": await hashPhoneNumberId(client.wabaId)
+      }
+    );
+  }
+  const wrapped = {
+    get phoneNumberId() {
+      return client.phoneNumberId;
+    },
+    get wabaId() {
+      return client.wabaId;
+    },
+    get graphApiVersion() {
+      return client.graphApiVersion;
+    },
+    isWindowOpen: (to) => client.isWindowOpen(to),
+    sendText: async (input, opts) => {
+      await gate(input.to);
+      return client.sendText(input, opts);
+    },
+    sendImage: async (input, opts) => {
+      await gate(input.to);
+      return client.sendImage(input, opts);
+    },
+    sendVideo: async (input, opts) => {
+      await gate(input.to);
+      return client.sendVideo(input, opts);
+    },
+    sendAudio: async (input, opts) => {
+      await gate(input.to);
+      return client.sendAudio(input, opts);
+    },
+    sendDocument: async (input, opts) => {
+      await gate(input.to);
+      return client.sendDocument(input, opts);
+    },
+    sendSticker: async (input, opts) => {
+      await gate(input.to);
+      return client.sendSticker(input, opts);
+    },
+    sendLocation: async (input, opts) => {
+      await gate(input.to);
+      return client.sendLocation(input, opts);
+    },
+    sendContacts: async (input, opts) => {
+      await gate(input.to);
+      return client.sendContacts(input, opts);
+    },
+    sendInteractive: async (input, opts) => {
+      await gate(input.to);
+      return client.sendInteractive(input, opts);
+    },
+    sendTemplate: async (input, opts) => {
+      await gate(input.to);
+      return client.sendTemplate(input, opts);
+    },
+    sendAuthTemplate: async (input, opts) => {
+      await gate(input.to);
+      return client.sendAuthTemplate(input, opts);
+    },
+    sendVoice: async (input, opts) => {
+      await gate(input.to);
+      return client.sendVoice(input, opts);
+    },
+    sendCarouselTemplate: async (input, opts) => {
+      await gate(input.to);
+      return client.sendCarouselTemplate(input, opts);
+    },
+    sendReaction: async (input, opts) => {
+      await gate(input.to);
+      return client.sendReaction(input, opts);
+    },
+    sendReply: async (replyTo, payload, opts) => {
+      await gate(payload.to);
+      return client.sendReply(replyTo, payload, opts);
+    },
+    listTemplates: (query, opts) => client.listTemplates(query, opts),
+    getTemplate: (templateId, opts) => client.getTemplate(templateId, opts)
+  };
+  return wrapped;
+}
+
+// src/webhooks/dedupe.ts
+var WebhookDeduper = class {
+  #storage;
+  #ttlMs;
+  constructor(storage, ttlMs = WEBHOOK_DEDUPE_TTL_MS) {
+    this.#storage = storage;
+    this.#ttlMs = ttlMs;
+  }
+  markIfNew(eventKey) {
+    return this.#storage.setIfAbsent(eventKey, true, this.#ttlMs);
+  }
+};
+
+// src/webhooks/handshake.ts
+var encoder2 = new TextEncoder();
+function verifyHandshake({
+  mode,
+  verifyToken,
+  challenge,
+  expectedToken
+}) {
+  if (mode !== "subscribe") return null;
+  if (typeof verifyToken !== "string" || typeof expectedToken !== "string") return null;
+  if (verifyToken.length === 0 || expectedToken.length === 0) return null;
+  if (verifyToken.length !== expectedToken.length) return null;
+  const a = encoder2.encode(verifyToken);
+  const b = encoder2.encode(expectedToken);
+  if (a.length !== b.length) return null;
+  if (!constantTimeEqual(a, b)) return null;
+  return typeof challenge === "string" ? challenge : null;
+}
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a[i] ^ b[i];
+  }
+  return diff === 0;
+}
+
+// src/webhooks/parser.ts
+var KNOWN_INCOMING_KINDS = /* @__PURE__ */ new Set([
+  "text",
+  "image",
+  "video",
+  "audio",
+  "document",
+  "sticker",
+  "location",
+  "contacts",
+  "button",
+  "order",
+  "reaction",
+  "system",
+  "unsupported",
+  "interactive"
+]);
+function parseWebhookPayload(body) {
+  const envelope = body;
+  if (envelope === null || envelope === void 0 || typeof envelope !== "object") return [];
+  const entries = Array.isArray(envelope.entry) ? envelope.entry : [];
+  if (entries.length === 0) return [];
+  const out = [];
+  for (const entry of entries) {
+    if (entry === null || typeof entry !== "object") continue;
+    const wabaId = typeof entry.id === "string" ? entry.id : "";
+    const changes = Array.isArray(entry.changes) ? entry.changes : [];
+    for (const change of changes) {
+      if (change === null || typeof change !== "object") continue;
+      const field = typeof change.field === "string" ? change.field : "";
+      const value = change.value ?? {};
+      out.push(...parseChange(wabaId, field, value));
+    }
+  }
+  return out;
+}
+function parseChange(wabaId, field, value) {
+  const metadata = value["metadata"] ?? {};
+  const phoneNumberId = typeof metadata["phone_number_id"] === "string" ? metadata["phone_number_id"] : void 0;
+  const displayPhoneNumber = typeof metadata["display_phone_number"] === "string" ? metadata["display_phone_number"] : void 0;
+  const baseTimestamp = Date.now();
+  switch (field) {
+    case "messages":
+      return parseMessagesField(value, {
+        wabaId,
+        phoneNumberId,
+        displayPhoneNumber,
+        baseTimestamp
+      });
+    case "message_template_status_update":
+      return [parseTemplateStatus(value, wabaId, baseTimestamp)];
+    case "message_template_quality_update":
+      return [parseTemplateQuality(value, wabaId, baseTimestamp)];
+    case "template_category_update":
+      return [parseTemplateCategory(value, wabaId, baseTimestamp)];
+    case "phone_number_quality_update":
+      return [parsePhoneNumberQuality(value, wabaId, phoneNumberId, baseTimestamp)];
+    case "account_alerts":
+      return [parseAccountAlert(value, wabaId, baseTimestamp)];
+    case "account_review_update":
+      return [parseAccountReview(value, wabaId, baseTimestamp)];
+    default: {
+      const ev = {
+        kind: "unknown",
+        wabaId,
+        timestamp: baseTimestamp,
+        field,
+        value
+      };
+      return [ev];
+    }
+  }
+}
+function parseMessagesField(value, ctx) {
+  const out = [];
+  const messages = Array.isArray(value["messages"]) ? value["messages"] : [];
+  for (const m of messages) {
+    out.push(parseInboundMessage(m, ctx));
+  }
+  const statuses = Array.isArray(value["statuses"]) ? value["statuses"] : [];
+  for (const s of statuses) {
+    out.push(parseStatus(s, ctx));
+  }
+  return out;
+}
+function parseInboundMessage(m, ctx) {
+  const id = typeof m["id"] === "string" ? m["id"] : "";
+  const from = typeof m["from"] === "string" ? m["from"] : "";
+  const rawType = typeof m["type"] === "string" ? m["type"] : "unsupported";
+  const type = normaliseIncomingType(rawType, m);
+  const timestamp = parseTimestamp(m["timestamp"]) ?? ctx.baseTimestamp;
+  const context = m["context"];
+  const contextId = context && typeof context["id"] === "string" ? context["id"] : void 0;
+  const ev = {
+    kind: "message",
+    wabaId: ctx.wabaId,
+    timestamp,
+    id,
+    from,
+    type,
+    body: m
+  };
+  if (ctx.phoneNumberId !== void 0) ev.phoneNumberId = ctx.phoneNumberId;
+  if (ctx.displayPhoneNumber !== void 0) ev.displayPhoneNumber = ctx.displayPhoneNumber;
+  if (contextId !== void 0) ev.contextId = contextId;
+  return ev;
+}
+function normaliseIncomingType(rawType, m) {
+  if (rawType === "interactive") {
+    const interactive = m["interactive"];
+    const subType = interactive && typeof interactive["type"] === "string" ? interactive["type"] : void 0;
+    if (subType === "button_reply") return "interactive_button_reply";
+    if (subType === "list_reply") return "interactive_list_reply";
+    return "unsupported";
+  }
+  if (KNOWN_INCOMING_KINDS.has(rawType)) {
+    return rawType;
+  }
+  return "unsupported";
+}
+function parseStatus(s, ctx) {
+  const id = typeof s["id"] === "string" ? s["id"] : "";
+  const status = typeof s["status"] === "string" ? s["status"] : "unknown";
+  const timestamp = parseTimestamp(s["timestamp"]) ?? ctx.baseTimestamp;
+  const recipientId = typeof s["recipient_id"] === "string" ? s["recipient_id"] : void 0;
+  const conversation = s["conversation"];
+  const conversationId = conversation && typeof conversation["id"] === "string" ? conversation["id"] : void 0;
+  const pricing = s["pricing"];
+  const pricingCategory = pricing && typeof pricing["category"] === "string" ? pricing["category"] : void 0;
+  const errors = Array.isArray(s["errors"]) ? s["errors"] : void 0;
+  const ev = {
+    kind: "status",
+    wabaId: ctx.wabaId,
+    timestamp,
+    id,
+    status
+  };
+  if (ctx.phoneNumberId !== void 0) ev.phoneNumberId = ctx.phoneNumberId;
+  if (ctx.displayPhoneNumber !== void 0) ev.displayPhoneNumber = ctx.displayPhoneNumber;
+  if (recipientId !== void 0) ev.recipientId = recipientId;
+  if (conversationId !== void 0) ev.conversationId = conversationId;
+  if (pricingCategory !== void 0) ev.pricingCategory = pricingCategory;
+  if (errors !== void 0) {
+    ev.errors = errors;
+  }
+  return ev;
+}
+function parseTemplateStatus(value, wabaId, ts) {
+  const ev = {
+    kind: "template_status",
+    wabaId,
+    timestamp: ts,
+    templateId: pickString(value, "message_template_id") ?? pickString(value, "template_id") ?? "",
+    event: pickString(value, "event") ?? ""
+  };
+  const name = pickString(value, "message_template_name") ?? pickString(value, "template_name");
+  if (name !== void 0) ev.templateName = name;
+  const language = pickString(value, "message_template_language") ?? pickString(value, "language");
+  if (language !== void 0) ev.language = language;
+  const reason = pickString(value, "reason");
+  if (reason !== void 0) ev.reason = reason;
+  return ev;
+}
+function parseTemplateQuality(value, wabaId, ts) {
+  const ev = {
+    kind: "template_quality",
+    wabaId,
+    timestamp: ts,
+    templateId: pickString(value, "message_template_id") ?? "",
+    newQualityScore: pickString(value, "new_quality_score") ?? ""
+  };
+  const previous = pickString(value, "previous_quality_score");
+  if (previous !== void 0) ev.previousQualityScore = previous;
+  const name = pickString(value, "message_template_name");
+  if (name !== void 0) ev.templateName = name;
+  return ev;
+}
+function parseTemplateCategory(value, wabaId, ts) {
+  const ev = {
+    kind: "template_category",
+    wabaId,
+    timestamp: ts,
+    templateId: pickString(value, "message_template_id") ?? "",
+    newCategory: pickString(value, "new_category") ?? ""
+  };
+  const previous = pickString(value, "previous_category");
+  if (previous !== void 0) ev.previousCategory = previous;
+  const name = pickString(value, "message_template_name");
+  if (name !== void 0) ev.templateName = name;
+  return ev;
+}
+function parsePhoneNumberQuality(value, wabaId, phoneNumberId, ts) {
+  const ev = {
+    kind: "phone_number_quality",
+    wabaId,
+    timestamp: ts,
+    newQualityScore: pickString(value, "new_quality_score") ?? ""
+  };
+  if (phoneNumberId !== void 0) ev.phoneNumberId = phoneNumberId;
+  return ev;
+}
+function parseAccountAlert(value, wabaId, ts) {
+  const ev = {
+    kind: "account_alert",
+    wabaId,
+    timestamp: ts,
+    raw: value
+  };
+  const severity = pickString(value, "alert_severity");
+  if (severity !== void 0) ev.alertSeverity = severity;
+  const type = pickString(value, "alert_type");
+  if (type !== void 0) ev.alertType = type;
+  return ev;
+}
+function parseAccountReview(value, wabaId, ts) {
+  const decision = pickString(value, "decision") ?? "";
+  return {
+    kind: "account_review",
+    wabaId,
+    timestamp: ts,
+    decision,
+    raw: value
+  };
+}
+function pickString(obj, key) {
+  const v = obj[key];
+  return typeof v === "string" ? v : void 0;
+}
+function parseTimestamp(raw) {
+  if (typeof raw === "number" && Number.isFinite(raw)) return raw * (raw > 1e12 ? 1 : 1e3);
+  if (typeof raw === "string") {
+    const asNum = Number(raw);
+    if (Number.isFinite(asNum)) return asNum * (asNum > 1e12 ? 1 : 1e3);
+  }
+  return void 0;
+}
+
+// src/storage/index.ts
+var InMemoryStorage = class {
+  #map = /* @__PURE__ */ new Map();
+  #now;
+  constructor(options = {}) {
+    this.#now = options.now ?? Date.now;
+  }
+  get(key) {
+    const entry = this.#map.get(key);
+    if (entry === void 0) {
+      return Promise.resolve(void 0);
+    }
+    if (this.#now() >= entry.expiresAt) {
+      this.#map.delete(key);
+      return Promise.resolve(void 0);
+    }
+    return Promise.resolve(entry.value);
+  }
+  set(key, value, ttlMs) {
+    const expiresAt = ttlMs <= 0 ? Number.POSITIVE_INFINITY : this.#now() + ttlMs;
+    this.#map.set(key, { value, expiresAt });
+    return Promise.resolve();
+  }
+  setIfAbsent(key, value, ttlMs) {
+    const existing = this.#map.get(key);
+    if (existing !== void 0 && this.#now() < existing.expiresAt) {
+      return Promise.resolve(false);
+    }
+    const expiresAt = ttlMs <= 0 ? Number.POSITIVE_INFINITY : this.#now() + ttlMs;
+    this.#map.set(key, { value, expiresAt });
+    return Promise.resolve(true);
+  }
+  delete(key) {
+    this.#map.delete(key);
+    return Promise.resolve();
+  }
+  /** Test-only — returns the current map size (including expired entries). */
+  _rawSize() {
+    return this.#map.size;
+  }
+};
+
+// src/webhooks/signature.ts
+var HEX_PREFIX = "sha256=";
+var HEX_RE = /^[0-9a-fA-F]+$/;
+var encoder3 = new TextEncoder();
+async function verifySignature({
+  rawBody,
+  signatureHeader,
+  appSecret
+}) {
+  if (typeof signatureHeader !== "string" || signatureHeader.length === 0) {
+    return false;
+  }
+  const provided = signatureHeader.startsWith(HEX_PREFIX) ? signatureHeader.slice(HEX_PREFIX.length) : signatureHeader;
+  if (!HEX_RE.test(provided) || provided.length % 2 !== 0) {
+    return false;
+  }
+  const expectedBytes = await computeSignatureBytes(rawBody, appSecret);
+  if (provided.length !== expectedBytes.length * 2) {
+    return false;
+  }
+  const providedBytes = hexToBytes(provided);
+  return constantTimeEqual2(providedBytes, expectedBytes);
+}
+async function verifySignatureOrThrow(input) {
+  const ok = await verifySignature(input);
+  if (!ok) {
+    throw new WebhookSignatureError();
+  }
+}
+async function computeSignature(rawBody, appSecret) {
+  return bytesToHex(await computeSignatureBytes(rawBody, appSecret));
+}
+async function computeSignatureBytes(rawBody, appSecret) {
+  const bodyBytes = typeof rawBody === "string" ? encoder3.encode(rawBody) : toUint8Array(rawBody);
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder3.encode(appSecret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const signature = await crypto.subtle.sign("HMAC", key, bodyBytes);
+  return new Uint8Array(signature);
+}
+function toUint8Array(buf) {
+  return buf instanceof Uint8Array ? buf : new Uint8Array(buf);
+}
+function hexToBytes(hex) {
+  const lower = hex.toLowerCase();
+  const out = new Uint8Array(lower.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = parseInt(lower.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+function bytesToHex(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    out += bytes[i].toString(16).padStart(2, "0");
+  }
+  return out;
+}
+function constantTimeEqual2(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a[i] ^ b[i];
+  }
+  return diff === 0;
+}
+
+// src/webhooks/receiver.ts
+var WebhookReceiver = class {
+  #appSecret;
+  #verifyToken;
+  #deduper;
+  #onError;
+  #handlers = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.#appSecret = options.appSecret;
+    this.#verifyToken = options.verifyToken;
+    this.#deduper = new WebhookDeduper(
+      options.storage ?? new InMemoryStorage(),
+      options.dedupeTtlMs
+    );
+    this.#onError = options.onError;
+  }
+  on(kind, handler) {
+    let set = this.#handlers.get(kind);
+    if (set === void 0) {
+      set = /* @__PURE__ */ new Set();
+      this.#handlers.set(kind, set);
+    }
+    set.add(handler);
+    return this;
+  }
+  off(kind, handler) {
+    this.#handlers.get(kind)?.delete(handler);
+    return this;
+  }
+  verify(rawBody, signatureHeader) {
+    return verifySignature({ rawBody, signatureHeader, appSecret: this.#appSecret });
+  }
+  handleVerifyRequest(input) {
+    const challenge = verifyHandshake({
+      mode: input.mode,
+      verifyToken: input.verifyToken,
+      challenge: input.challenge,
+      expectedToken: this.#verifyToken
+    });
+    if (challenge === null) return { status: 403 };
+    return { status: 200, body: challenge };
+  }
+  async handlePayload(rawBody, signatureHeader, parsedBody) {
+    if (!await this.verify(rawBody, signatureHeader)) {
+      return { status: 401 };
+    }
+    const events = parseWebhookPayload(parsedBody);
+    return { status: 200, dispatchPromise: this.#dispatch(events) };
+  }
+  /** @internal — used by mock-mode (Phase 6) to inject synthetic events. */
+  _dispatchEvents(events) {
+    return this.#dispatch(events);
+  }
+  async #dispatch(events) {
+    const tasks = [];
+    for (const event of events) {
+      const dedupeKey = makeDedupeKey(event);
+      if (dedupeKey !== void 0) {
+        const fresh = await this.#deduper.markIfNew(dedupeKey);
+        if (!fresh) continue;
+      }
+      const handlers = this.#handlers.get(event.kind);
+      if (handlers) {
+        for (const h of handlers) {
+          tasks.push(this.#runHandler(h, event));
+        }
+      }
+    }
+    await Promise.allSettled(tasks);
+  }
+  async #runHandler(h, event) {
+    try {
+      await withSpan(
+        "whatsapp.webhook.dispatch",
+        () => Promise.resolve(h(event)),
+        await spanAttributes(event)
+      );
+    } catch (err) {
+      this.#onError?.(err, event);
+      const errorHandlers = this.#handlers.get("error");
+      if (errorHandlers) {
+        for (const eh of errorHandlers) {
+          try {
+            await eh(err, event);
+          } catch {
+          }
+        }
+      }
+    }
+  }
+};
+async function spanAttributes(event) {
+  const attrs = {
+    "whatsapp.event.kind": event.kind,
+    "whatsapp.waba_id": await hashPhoneNumberId(event.wabaId)
+  };
+  if (event.phoneNumberId !== void 0) {
+    attrs["whatsapp.phone_number_id"] = await hashPhoneNumberId(event.phoneNumberId);
+  }
+  if (event.kind === "message" || event.kind === "status") {
+    attrs["whatsapp.event.id"] = event.id;
+  }
+  return attrs;
+}
+function makeDedupeKey(event) {
+  switch (event.kind) {
+    case "message":
+      return `msg:${event.id}`;
+    case "status":
+      return `status:${event.id}:${event.status}`;
+    default:
+      return void 0;
+  }
+}
+
+// src/window/tracker.ts
+var WindowTracker = class {
+  phoneNumberId;
+  #storage;
+  #ttlMs;
+  constructor(options) {
+    this.phoneNumberId = options.phoneNumberId;
+    this.#storage = options.storage;
+    this.#ttlMs = options.ttlMs ?? WINDOW_TTL_MS;
+  }
+  get ttlMs() {
+    return this.#ttlMs;
+  }
+  notifyInbound(customerWaId, _atMs) {
+    return this.#storage.set(this.#key(customerWaId), true, this.#ttlMs);
+  }
+  async isWindowOpen(customerWaId) {
+    const seen = await this.#storage.get(this.#key(customerWaId));
+    return seen === true;
+  }
+  /** @internal — exposed so consumers can clear a window after a hard error. */
+  clear(customerWaId) {
+    return this.#storage.delete(this.#key(customerWaId));
+  }
+  #key(customerWaId) {
+    return `window:${this.phoneNumberId}:${customerWaId}`;
+  }
+};
+
+export { AuthenticationError, BucketMap, CapabilityError, DEFAULT_RETRY_POLICY, GRAPH_API_VERSION, InMemoryStorage, META_GRAPH_BASE_URL, MissingCredentialsError, MockModeError, MockWhatsAppClient, PermissionError, RateLimitError, TemplateError, TokenBucket, TransientHttpError, WEBHOOK_ACK_DEADLINE_MS, WEBHOOK_DEDUPE_TTL_MS, WINDOW_TTL_MS, WebhookDeduper, WebhookReceiver, WebhookSignatureError, WhatsAppClient, WhatsAppError, WindowClosedError, WindowTracker, buildAudio, buildAuthTemplate, buildCarouselTemplate, buildContacts, buildDocument, buildImage, buildInteractive, buildInteractiveButton, buildInteractiveCtaUrl, buildInteractiveList, buildLocation, buildReaction, buildSticker, buildTemplate, buildText, buildVideo, buildVoice, computeSignature, countTemplatePlaceholders, getTemplate, getTracer, hashPhoneNumberId, listTemplates, parseWebhookPayload, pickWhatsAppClient, sendMessage, setRedactSalt, validateTemplateSend, verifyHandshake, verifySignature, verifySignatureOrThrow, withRateLimit, withSpan };