@onesub/server 0.15.0 → 0.17.0

package/dist/index.cjs

@@ -83,9 +83,9 @@ var InMemoryPurchaseStore = class {
     const existing = this.byTransactionId.get(purchase.transactionId);
     if (existing) {
       if (existing.userId !== purchase.userId) {
-        const err = new Error("TRANSACTION_BELONGS_TO_OTHER_USER");
-        err.code = "TRANSACTION_BELONGS_TO_OTHER_USER";
-        throw err;
+        const err2 = new Error("TRANSACTION_BELONGS_TO_OTHER_USER");
+        err2.code = "TRANSACTION_BELONGS_TO_OTHER_USER";
+        throw err2;
       }
       return;
     }
@@ -265,6 +265,9 @@ function deterministicTransactionId(prefix, receipt) {
   const digest = crypto.createHash("sha256").update(receipt).digest("hex").slice(0, 24);
   return `${prefix}_${digest}`;
 }
+function extractBoundToken(receipt) {
+  return receipt.match(/#token=([^#]+)/)?.[1];
+}
 var HOURS = 60 * 60 * 1e3;
 var DAYS = 24 * HOURS;
 function mockValidateAppleSubscription(receipt) {
@@ -272,7 +275,7 @@ function mockValidateAppleSubscription(receipt) {
   if (!outcomePasses(outcome, "apple")) return null;
   const now = Date.now();
   const expiresAt = outcome.kind === "sandbox" ? now + 1 * HOURS : now + 30 * DAYS;
-  const tokenMatch = receipt.match(/#token=([^#]+)/);
+  const boundToken = extractBoundToken(receipt);
   return {
     userId: "",
     productId: "mock_subscription",
@@ -282,19 +285,19 @@ function mockValidateAppleSubscription(receipt) {
     originalTransactionId: deterministicTransactionId("mock_apple_orig", receipt),
     purchasedAt: new Date(now).toISOString(),
     willRenew: true,
-    ...tokenMatch ? { boundAccountId: tokenMatch[1] } : {}
+    ...boundToken ? { boundAccountId: boundToken } : {}
   };
 }
 function mockValidateAppleProduct(receipt, expectedProductId) {
   const outcome = classifyMockReceipt(receipt);
   if (!outcomePasses(outcome, "apple")) return null;
   const productId = expectedProductId ?? "mock_product";
-  const tokenMatch = receipt.match(/#token=([^#]+)/);
+  const boundToken = extractBoundToken(receipt);
   return {
     transactionId: deterministicTransactionId(`mock_apple_${productId}`, receipt),
     productId,
     purchasedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    ...tokenMatch ? { appAccountToken: tokenMatch[1] } : {}
+    ...boundToken ? { appAccountToken: boundToken } : {}
   };
 }
 function mockValidateGoogleSubscription(receipt, productId) {
@@ -302,7 +305,7 @@ function mockValidateGoogleSubscription(receipt, productId) {
   if (!outcomePasses(outcome, "google")) return null;
   const now = Date.now();
   const expiresAt = outcome.kind === "sandbox" ? now + 1 * HOURS : now + 30 * DAYS;
-  const tokenMatch = receipt.match(/#token=([^#]+)/);
+  const boundToken = extractBoundToken(receipt);
   return {
     userId: "",
     productId,
@@ -314,26 +317,32 @@ function mockValidateGoogleSubscription(receipt, productId) {
     originalTransactionId: receipt,
     purchasedAt: new Date(now).toISOString(),
     willRenew: true,
-    ...tokenMatch ? { boundAccountId: tokenMatch[1] } : {}
+    ...boundToken ? { boundAccountId: boundToken } : {}
   };
 }
 function mockValidateGoogleProduct(receipt, productId) {
   const outcome = classifyMockReceipt(receipt);
   if (!outcomePasses(outcome, "google")) return null;
-  const tokenMatch = receipt.match(/#token=([^#]+)/);
+  const boundToken = extractBoundToken(receipt);
   return {
     transactionId: deterministicTransactionId(`mock_google_${productId}`, receipt),
     purchasedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    ...tokenMatch ? { obfuscatedExternalAccountId: tokenMatch[1] } : {}
+    ...boundToken ? { obfuscatedExternalAccountId: boundToken } : {}
   };
 }
 
 // src/providers/apple.ts
-var MAX_CONSUMABLE_RECEIPT_AGE_MS = 72 * 60 * 60 * 1e3;
 function derBase64ToPem(der) {
   return "-----BEGIN CERTIFICATE-----\n" + (der.match(/.{1,64}/g) ?? []).join("\n") + "\n-----END CERTIFICATE-----";
 }
 var APPLE_ROOT_CERTS = APPLE_ROOT_CA_PEMS.map((pem) => new crypto.X509Certificate(pem));
+function assertIssuerCanSign(cert, index) {
+  if (!cert.ca) {
+    throw new Error(
+      `[onesub/apple] cert[${index}] is used as an issuer but is not a CA (basicConstraints CA=false)`
+    );
+  }
+}
 function verifyAppleCertChain(x5c) {
   if (x5c.length === 0) {
     throw new Error("[onesub/apple] empty x5c");
@@ -345,6 +354,7 @@ function verifyAppleCertChain(x5c) {
     if (new Date(cert.validFrom) > now || new Date(cert.validTo) < now) {
       throw new Error(`[onesub/apple] cert[${i}] outside validity window`);
     }
+    if (i >= 1) assertIssuerCanSign(cert, i);
     if (i + 1 < chain.length) {
       if (!cert.checkIssued(chain[i + 1]) || !cert.verify(chain[i + 1].publicKey)) {
         throw new Error(`[onesub/apple] cert[${i}] not signed by cert[${i + 1}]`);
@@ -355,6 +365,7 @@ function verifyAppleCertChain(x5c) {
   const topDer = top.raw.toString("base64");
   const trustsRoot = APPLE_ROOT_CERTS.some((root) => {
     if (root.raw.toString("base64") === topDer) return true;
+    if (!root.ca) return false;
     if (!top.checkIssued(root)) return false;
     try {
       return top.verify(root.publicKey);
@@ -400,12 +411,12 @@ async function validateAppleReceipt(receipt, config) {
   let tx;
   try {
     tx = await decodeJws(receipt, config.skipJwsVerification);
-  } catch (err) {
+  } catch (err2) {
     const preview = receipt.slice(0, 60);
     const parts = receipt.split(".").length;
     log.warn(
       "[onesub/apple] Failed to decode receipt as JWS:",
-      err?.message ?? err,
+      err2?.message ?? err2,
       `| preview: "${preview}..." (len=${receipt.length}, parts=${parts})`
     );
     return null;
@@ -442,13 +453,13 @@ async function validateAppleConsumableReceipt(signedTransaction, config, expecte
   let tx;
   try {
     tx = await decodeJws(signedTransaction, config.skipJwsVerification);
-  } catch (err) {
+  } catch (err2) {
     const preview = signedTransaction.slice(0, 60);
     const parts = signedTransaction.split(".").length;
     const looksLikeJws = parts === 3;
     log.warn(
       "[onesub/apple] Failed to decode consumable JWS:",
-      err?.message ?? err,
+      err2?.message ?? err2,
       `| receipt preview: "${preview}..." (len=${signedTransaction.length}, parts=${parts}, looksLikeJws=${looksLikeJws})`
     );
     return null;
@@ -477,8 +488,9 @@ async function validateAppleConsumableReceipt(signedTransaction, config, expecte
     log.warn("[onesub/apple] Purchase was revoked/refunded");
     return null;
   }
-  if (tx.purchaseDate && Date.now() - tx.purchaseDate > MAX_CONSUMABLE_RECEIPT_AGE_MS) {
-    log.warn("[onesub/apple] Consumable receipt too old (>72h)");
+  const maxAgeMs = (config.productReceiptMaxAgeHours ?? 72) * 60 * 60 * 1e3;
+  if (tx.purchaseDate && Date.now() - tx.purchaseDate > maxAgeMs) {
+    log.warn(`[onesub/apple] Consumable receipt too old (>${config.productReceiptMaxAgeHours ?? 72}h)`);
     return null;
   }
   const transactionId = tx.transactionId ?? tx.originalTransactionId;
@@ -561,8 +573,8 @@ async function sendAppleConsumptionResponse(transactionId, body, config, options
   let jwt;
   try {
     jwt = await makeAppleApiJwt(config);
-  } catch (err) {
-    log.warn("[onesub/apple] Cannot send consumption response \u2014 JWT mint failed:", err);
+  } catch (err2) {
+    log.warn("[onesub/apple] Cannot send consumption response \u2014 JWT mint failed:", err2);
     return;
   }
   const host = options?.sandbox ? "api.storekit-sandbox.itunes.apple.com" : "api.storekit.itunes.apple.com";
@@ -580,8 +592,8 @@ async function sendAppleConsumptionResponse(transactionId, body, config, options
       const text = await resp.text();
       log.warn(`[onesub/apple] Consumption response API error ${resp.status}: ${text}`);
     }
-  } catch (err) {
-    log.warn("[onesub/apple] Consumption response network error:", err);
+  } catch (err2) {
+    log.warn("[onesub/apple] Consumption response network error:", err2);
   }
 }
 var APPLE_SUBSCRIPTION_STATUS_CODE = {
@@ -611,8 +623,8 @@ async function fetchAppleSubscriptionStatus(originalTransactionId, config, optio
   let jwt;
   try {
     jwt = await makeAppleApiJwt(config);
-  } catch (err) {
-    log.warn("[onesub/apple] Cannot fetch subscription status \u2014 JWT mint failed:", err);
+  } catch (err2) {
+    log.warn("[onesub/apple] Cannot fetch subscription status \u2014 JWT mint failed:", err2);
     return null;
   }
   const host = options?.sandbox ? "api.storekit-sandbox.itunes.apple.com" : "api.storekit.itunes.apple.com";
@@ -628,8 +640,8 @@ async function fetchAppleSubscriptionStatus(originalTransactionId, config, optio
       return null;
     }
     body = await resp.json();
-  } catch (err) {
-    log.warn("[onesub/apple] Status API network error:", err);
+  } catch (err2) {
+    log.warn("[onesub/apple] Status API network error:", err2);
     return null;
   }
   const entry = body.data?.flatMap((g) => g.lastTransactions ?? []).find((t) => t.originalTransactionId === originalTransactionId);
@@ -640,8 +652,8 @@ async function fetchAppleSubscriptionStatus(originalTransactionId, config, optio
   let tx;
   try {
     tx = await decodeJws(entry.signedTransactionInfo, config.skipJwsVerification);
-  } catch (err) {
-    log.warn("[onesub/apple] Failed to decode signedTransactionInfo from Status API:", err);
+  } catch (err2) {
+    log.warn("[onesub/apple] Failed to decode signedTransactionInfo from Status API:", err2);
     return null;
   }
   let renewal = null;
@@ -669,18 +681,20 @@ async function fetchAppleSubscriptionStatus(originalTransactionId, config, optio
     willRenew: renewal?.autoRenewStatus === 1
   };
 }
+var MAX_HISTORY_PAGES = 50;
 async function fetchAppleTransactionHistory(originalTransactionId, config, options) {
   if (config.mockMode) return null;
   let jwt;
   try {
     jwt = await makeAppleApiJwt(config);
-  } catch (err) {
-    log.warn("[onesub/apple] Cannot fetch transaction history \u2014 JWT mint failed:", err);
+  } catch (err2) {
+    log.warn("[onesub/apple] Cannot fetch transaction history \u2014 JWT mint failed:", err2);
     return null;
   }
   const host = options?.sandbox ? "api.storekit-sandbox.itunes.apple.com" : "api.storekit.itunes.apple.com";
   const results = [];
   let revision;
+  let pageCount = 0;
   for (; ; ) {
     const url = new URL(`https://${host}/inApps/v2/history/${encodeURIComponent(originalTransactionId)}`);
     if (revision) url.searchParams.set("revision", revision);
@@ -695,8 +709,8 @@ async function fetchAppleTransactionHistory(originalTransactionId, config, optio
         return null;
       }
       page = await resp.json();
-    } catch (err) {
-      log.warn("[onesub/apple] Transaction History API network error:", err);
+    } catch (err2) {
+      log.warn("[onesub/apple] Transaction History API network error:", err2);
       return null;
     }
     for (const signed of page.signedTransactions ?? []) {
@@ -717,7 +731,20 @@ async function fetchAppleTransactionHistory(originalTransactionId, config, optio
       } catch {
       }
     }
+    pageCount++;
     if (!page.hasMore) break;
+    if (!page.revision || page.revision === revision) {
+      log.warn(
+        "[onesub/apple] Transaction History API returned hasMore without a new revision cursor \u2014 stopping pagination (partial history returned)"
+      );
+      break;
+    }
+    if (pageCount >= MAX_HISTORY_PAGES) {
+      log.warn(
+        `[onesub/apple] Transaction History pagination hit the ${MAX_HISTORY_PAGES}-page cap \u2014 stopping (partial history returned)`
+      );
+      break;
+    }
     revision = page.revision;
   }
   return results;
@@ -748,8 +775,8 @@ async function signApplePromotionalOffer(input, config) {
     sign.update(message);
     sign.end();
     signatureBuffer = sign.sign(offerPrivateKey);
-  } catch (err) {
-    throw new Error(`[onesub/apple] Failed to sign promotional offer \u2014 check that offerPrivateKey is a valid ES256 PEM key: ${err.message}`);
+  } catch (err2) {
+    throw new Error(`[onesub/apple] Failed to sign promotional offer \u2014 check that offerPrivateKey is a valid ES256 PEM key: ${err2.message}`);
   }
   const signature = signatureBuffer.toString("base64");
   return { keyId: offerKeyId, nonce, timestamp, signature };
@@ -767,7 +794,6 @@ var GOOGLE_NOTIFICATION_TYPE = {
   SUBSCRIPTION_REVOKED: 12,
   SUBSCRIPTION_EXPIRED: 13
 };
-var MAX_PRODUCT_RECEIPT_AGE_MS = 72 * 60 * 60 * 1e3;
 var refreshPromises = /* @__PURE__ */ new Map();
 function googleTokenCacheKey(serviceAccountKey) {
   let hash = 0;
@@ -865,8 +891,8 @@ async function acknowledgeGoogleSubscription(purchaseToken, productId, config) {
   let accessToken;
   try {
     accessToken = await getCachedAccessToken(config.serviceAccountKey);
-  } catch (err) {
-    log.warn("[onesub/google] Could not get access token for subscription ack:", err);
+  } catch (err2) {
+    log.warn("[onesub/google] Could not get access token for subscription ack:", err2);
     return;
   }
   const url = `https://androidpublisher.googleapis.com/androidpublisher/v3/applications/${encodeURIComponent(config.packageName)}/purchases/subscriptions/${encodeURIComponent(productId)}/tokens/${encodeURIComponent(purchaseToken)}:acknowledge`;
@@ -880,8 +906,8 @@ async function acknowledgeGoogleSubscription(purchaseToken, productId, config) {
       const body = await resp.text();
       log.warn(`[onesub/google] Subscription acknowledge API error ${resp.status}: ${body} \u2014 auto-refund risk`);
     }
-  } catch (err) {
-    log.warn("[onesub/google] Subscription acknowledge network error \u2014 auto-refund risk:", err);
+  } catch (err2) {
+    log.warn("[onesub/google] Subscription acknowledge network error \u2014 auto-refund risk:", err2);
   }
 }
 async function acknowledgeGoogleProduct(purchaseToken, productId, config) {
@@ -891,8 +917,8 @@ async function acknowledgeGoogleProduct(purchaseToken, productId, config) {
   let accessToken;
   try {
     accessToken = await getCachedAccessToken(config.serviceAccountKey);
-  } catch (err) {
-    log.warn("[onesub/google] Could not get access token for product ack:", err);
+  } catch (err2) {
+    log.warn("[onesub/google] Could not get access token for product ack:", err2);
     return;
   }
   const url = `https://androidpublisher.googleapis.com/androidpublisher/v3/applications/${encodeURIComponent(config.packageName)}/purchases/products/${encodeURIComponent(productId)}/tokens/${encodeURIComponent(purchaseToken)}:acknowledge`;
@@ -906,8 +932,8 @@ async function acknowledgeGoogleProduct(purchaseToken, productId, config) {
       const body = await resp.text();
       log.warn(`[onesub/google] Product acknowledge API error ${resp.status}: ${body} \u2014 auto-refund risk`);
     }
-  } catch (err) {
-    log.warn("[onesub/google] Product acknowledge network error \u2014 auto-refund risk:", err);
+  } catch (err2) {
+    log.warn("[onesub/google] Product acknowledge network error \u2014 auto-refund risk:", err2);
   }
 }
 async function consumeGoogleProductReceipt(purchaseToken, productId, config) {
@@ -916,8 +942,8 @@ async function consumeGoogleProductReceipt(purchaseToken, productId, config) {
   let accessToken;
   try {
     accessToken = await getCachedAccessToken(config.serviceAccountKey);
-  } catch (err) {
-    log.warn("[onesub/google] Could not get access token for consume:", err);
+  } catch (err2) {
+    log.warn("[onesub/google] Could not get access token for consume:", err2);
     return;
   }
   const url = `https://androidpublisher.googleapis.com/androidpublisher/v3/applications/${encodeURIComponent(config.packageName)}/purchases/products/${encodeURIComponent(productId)}/tokens/${encodeURIComponent(purchaseToken)}:consume`;
@@ -930,8 +956,8 @@ async function consumeGoogleProductReceipt(purchaseToken, productId, config) {
       const body = await resp.text();
       log.warn(`[onesub/google] Consume API error ${resp.status}: ${body} \u2014 auto-refund risk`);
     }
-  } catch (err) {
-    log.warn("[onesub/google] Consume network error \u2014 auto-refund risk:", err);
+  } catch (err2) {
+    log.warn("[onesub/google] Consume network error \u2014 auto-refund risk:", err2);
   }
 }
 function deriveStatusV2(state) {
@@ -968,8 +994,8 @@ async function validateGoogleReceipt(receipt, productId, config) {
   try {
     const token = await getCachedAccessToken(config.serviceAccountKey);
     purchase = await fetchSubscriptionPurchaseV2(config.packageName, receipt, token);
-  } catch (err) {
-    log.error("[onesub/google] Receipt validation failed:", err);
+  } catch (err2) {
+    log.error("[onesub/google] Receipt validation failed:", err2);
     return null;
   }
   const status = deriveStatusV2(purchase.subscriptionState);
@@ -1030,8 +1056,8 @@ async function validateGoogleProductReceipt(purchaseToken, productId, config, ty
   try {
     const token = await getCachedAccessToken(config.serviceAccountKey);
     purchase = await fetchProductPurchase(config.packageName, productId, purchaseToken, token);
-  } catch (err) {
-    log.error("[onesub/google] Product receipt validation failed:", err);
+  } catch (err2) {
+    log.error("[onesub/google] Product receipt validation failed:", err2);
     return null;
   }
   if (purchase.purchaseState !== 0) {
@@ -1044,8 +1070,9 @@ async function validateGoogleProductReceipt(purchaseToken, productId, config, ty
   }
   if (purchase.purchaseTimeMillis) {
     const purchaseTime = parseInt(purchase.purchaseTimeMillis, 10);
-    if (Date.now() - purchaseTime > MAX_PRODUCT_RECEIPT_AGE_MS) {
-      log.warn("[onesub/google] Product receipt too old (>72h)");
+    const maxAgeMs = (config.productReceiptMaxAgeHours ?? 72) * 60 * 60 * 1e3;
+    if (Date.now() - purchaseTime > maxAgeMs) {
+      log.warn(`[onesub/google] Product receipt too old (>${config.productReceiptMaxAgeHours ?? 72}h)`);
       return null;
     }
   }
@@ -1136,12 +1163,12 @@ function isGooglePriceChangeConfirmedNotification(notificationType) {
 function sendError(res, status, code, error, extra = {}) {
   res.status(status).json({ ...extra, error, errorCode: code });
 }
-function sendZodError(res, err, extra = {}) {
+function sendZodError(res, err2, extra = {}) {
   sendError(
     res,
     400,
     shared.ONESUB_ERROR_CODE.INVALID_INPUT,
-    err.issues.map((e) => e.message).join(", "),
+    err2.issues.map((e) => e.message).join(", "),
     extra
   );
 }
@@ -1163,12 +1190,12 @@ function createValidateRouter(config, store) {
     let productId;
     try {
       ({ platform, receipt, userId, productId } = validateSchema.parse(req.body));
-    } catch (err) {
-      if (err instanceof zod.z.ZodError) {
-        sendZodError(res, err, NO_SUB);
+    } catch (err2) {
+      if (err2 instanceof zod.z.ZodError) {
+        sendZodError(res, err2, NO_SUB);
         return;
       }
-      throw err;
+      throw err2;
     }
     try {
       let sub = null;
@@ -1212,8 +1239,8 @@ function createValidateRouter(config, store) {
       }
       const response = { valid: true, subscription: sub };
       res.status(200).json(response);
-    } catch (err) {
-      log.error("[onesub/validate] Unexpected error:", err);
+    } catch (err2) {
+      log.error("[onesub/validate] Unexpected error:", err2);
       sendError(res, 500, shared.ONESUB_ERROR_CODE.INTERNAL_ERROR, "Internal server error during receipt validation", NO_SUB);
     }
   });
@@ -1244,13 +1271,66 @@ function createStatusRouter(store) {
       const active = statusAllows && notYetExpired;
       const response = { active, subscription: sub };
       res.status(200).json(response);
-    } catch (err) {
-      log.error("[onesub/status] Store error:", err);
+    } catch (err2) {
+      log.error("[onesub/status] Store error:", err2);
       sendError(res, 500, shared.ONESUB_ERROR_CODE.STORE_ERROR, "Internal server error", NO_SUB2);
     }
   });
   return router;
 }
+
+// src/webhook-events.ts
+async function unmarkWebhookEvent(store, provider, eventId) {
+  if (!store?.unmark || typeof eventId !== "string") return;
+  try {
+    await store.unmark(provider, eventId);
+  } catch {
+  }
+}
+var DEFAULT_TTL_SECONDS = 7 * 24 * 60 * 60;
+var InMemoryWebhookEventStore = class {
+  constructor(ttlSeconds = DEFAULT_TTL_SECONDS) {
+    this.ttlSeconds = ttlSeconds;
+  }
+  ttlSeconds;
+  seen = /* @__PURE__ */ new Map();
+  async markIfNew(provider, eventId) {
+    this.evictExpired();
+    const key = `${provider}:${eventId}`;
+    if (this.seen.has(key)) return false;
+    this.seen.set(key, Date.now() + this.ttlSeconds * 1e3);
+    return true;
+  }
+  async unmark(provider, eventId) {
+    this.seen.delete(`${provider}:${eventId}`);
+  }
+  evictExpired() {
+    const now = Date.now();
+    for (const [key, expiresAt] of this.seen) {
+      if (expiresAt < now) this.seen.delete(key);
+    }
+  }
+};
+var CacheWebhookEventStore = class {
+  constructor(cache, ttlSeconds = DEFAULT_TTL_SECONDS) {
+    this.cache = cache;
+    this.ttlSeconds = ttlSeconds;
+  }
+  cache;
+  ttlSeconds;
+  async markIfNew(provider, eventId) {
+    const key = `webhook:event:${provider}:${eventId}`;
+    const existing = await this.cache.get(key);
+    if (existing) return false;
+    await this.cache.set(key, "1", this.ttlSeconds);
+    return true;
+  }
+  async unmark(provider, eventId) {
+    await this.cache.del(`webhook:event:${provider}:${eventId}`);
+  }
+};
+
+// src/routes/webhook-apple.ts
 var APPLE_ACTIVE_TYPES = /* @__PURE__ */ new Set(["SUBSCRIBED", "DID_RENEW", "DID_RECOVER", "OFFER_REDEEMED"]);
 var APPLE_CANCELED_TYPES = /* @__PURE__ */ new Set(["REVOKE", "REFUND"]);
 var APPLE_EXPIRED_TYPES = /* @__PURE__ */ new Set(["EXPIRED"]);
@@ -1264,36 +1344,8 @@ function mapAppleNotificationStatus(notificationType, subtype) {
   if (APPLE_ACTIVE_TYPES.has(notificationType)) return shared.SUBSCRIPTION_STATUS.ACTIVE;
   return null;
 }
-async function handleAppleWebhook(req, res, config, store, purchaseStore, webhookEventStore) {
-  const body = req.body;
-  if (!body.signedPayload) {
-    sendError(res, 400, shared.ONESUB_ERROR_CODE.MISSING_SIGNED_PAYLOAD, "Missing signedPayload");
-    return;
-  }
-  let payload;
-  try {
-    payload = await decodeJws(
-      body.signedPayload,
-      config.apple?.skipJwsVerification
-    );
-  } catch (err) {
-    log.error("[onesub/webhook/apple] Failed to decode signedPayload:", err);
-    sendError(res, 400, shared.ONESUB_ERROR_CODE.INVALID_SIGNED_PAYLOAD, "Invalid signedPayload");
-    return;
-  }
-  if (webhookEventStore && typeof payload.notificationUUID === "string") {
-    const fresh = await webhookEventStore.markIfNew("apple", payload.notificationUUID);
-    if (!fresh) {
-      log.info("[onesub/webhook/apple] dedupe: already processed", payload.notificationUUID);
-      res.status(200).json({ received: true, deduped: true });
-      return;
-    }
-  }
-  const decoded = await decodeAppleNotification(payload, config.apple?.skipJwsVerification);
-  if (!decoded) {
-    res.status(200).json({ received: true });
-    return;
-  }
+async function processAppleNotification(work, config, store, purchaseStore) {
+  const { notificationType, subtype } = work;
   const {
     originalTransactionId,
     transactionId,
@@ -1306,14 +1358,7 @@ async function handleAppleWebhook(req, res, config, store, purchaseStore, webhoo
     expiresAt,
     appAccountToken,
     inAppOwnershipType
-  } = decoded;
-  const notificationType = payload.notificationType;
-  const subtype = payload.subtype;
-  if (config.apple?.bundleId && bundleId && bundleId !== config.apple.bundleId) {
-    log.warn("[onesub/webhook/apple] Bundle ID mismatch:", bundleId, "!==", config.apple.bundleId);
-    sendError(res, 400, shared.ONESUB_ERROR_CODE.BUNDLE_ID_MISMATCH, "Bundle ID mismatch");
-    return;
-  }
+  } = work.decoded;
   const mapped = mapAppleNotificationStatus(notificationType, subtype);
   const finalStatus = mapped ?? status;
   if (notificationType === "CONSUMPTION_REQUEST" && config.apple?.consumptionInfoProvider && transactionId && productId) {
@@ -1333,75 +1378,129 @@ async function handleAppleWebhook(req, res, config, store, purchaseStore, webhoo
             sandbox: environment === "Sandbox"
           });
         }
-      } catch (err) {
-        log.warn("[onesub/webhook/apple] consumptionInfoProvider failed:", err);
+      } catch (err2) {
+        log.warn("[onesub/webhook/apple] consumptionInfoProvider failed:", err2);
       }
     })();
   }
   const isOneTimePurchase = type === "Consumable" || type === "Non-Consumable";
   const isRefundOrRevoke = APPLE_CANCELED_TYPES.has(notificationType);
   if (isOneTimePurchase && notificationType === "CONSUMPTION_REQUEST") {
-    res.status(200).json({ received: true });
     return;
   }
-  try {
-    if (isOneTimePurchase && isRefundOrRevoke) {
-      const lookupId = transactionId ?? originalTransactionId;
-      const removed = await purchaseStore.deletePurchaseByTransactionId(lookupId);
-      if (!removed) {
-        log.warn("[onesub/webhook/apple] IAP refund for unknown transaction:", lookupId);
-      }
-      res.status(200).json({ received: true });
-      return;
+  if (isOneTimePurchase && isRefundOrRevoke) {
+    const lookupId = transactionId ?? originalTransactionId;
+    const removed = await purchaseStore.deletePurchaseByTransactionId(lookupId);
+    if (!removed) {
+      log.warn("[onesub/webhook/apple] IAP refund for unknown transaction:", lookupId);
     }
-    const existing = await store.getByTransactionId(originalTransactionId);
-    if (existing) {
-      const isSubscriptionRefund = isRefundOrRevoke && !isOneTimePurchase;
-      const keepEntitlement = isSubscriptionRefund && config.refundPolicy === "until_expiry";
-      const correctedUserId = appAccountToken && existing.userId === originalTransactionId ? appAccountToken : existing.userId;
-      if (correctedUserId !== existing.userId) {
-        log.info("[onesub/webhook/apple] correcting userId from originalTransactionId to appAccountToken:", correctedUserId);
-      }
-      const updated = keepEntitlement ? { ...existing, userId: correctedUserId, willRenew: false } : {
-        ...existing,
-        userId: correctedUserId,
-        status: finalStatus,
-        willRenew,
-        expiresAt: expiresAt ?? existing.expiresAt
-      };
-      await store.save(updated);
-    } else if (config.apple?.issuerId && config.apple?.keyId && config.apple?.privateKey) {
-      const fresh = await fetchAppleSubscriptionStatus(originalTransactionId, config.apple, {
-        sandbox: environment === "Sandbox"
-      });
-      if (fresh) {
-        fresh.userId = appAccountToken ?? originalTransactionId;
-        if (inAppOwnershipType === "FAMILY_SHARED") {
-          const source = appAccountToken ? "appAccountToken" : "originalTransactionId (fallback)";
-          log.info(`[onesub/webhook/apple] FAMILY_SHARED \u2014 userId: ${fresh.userId} (source: ${source})`);
-        }
-        await store.save(fresh);
-      } else {
-        log.warn(
-          "[onesub/webhook/apple] Unknown transaction and Status API returned no record:",
-          originalTransactionId
-        );
+    return;
+  }
+  const existing = await store.getByTransactionId(originalTransactionId);
+  if (existing) {
+    const isSubscriptionRefund = isRefundOrRevoke && !isOneTimePurchase;
+    const keepEntitlement = isSubscriptionRefund && config.refundPolicy === "until_expiry";
+    const correctedUserId = appAccountToken && existing.userId === originalTransactionId ? appAccountToken : existing.userId;
+    if (correctedUserId !== existing.userId) {
+      log.info("[onesub/webhook/apple] correcting userId from originalTransactionId to appAccountToken:", correctedUserId);
+    }
+    const updated = keepEntitlement ? { ...existing, userId: correctedUserId, willRenew: false } : {
+      ...existing,
+      userId: correctedUserId,
+      status: finalStatus,
+      willRenew,
+      expiresAt: expiresAt ?? existing.expiresAt
+    };
+    await store.save(updated);
+  } else if (config.apple?.issuerId && config.apple?.keyId && config.apple?.privateKey) {
+    const fresh = await fetchAppleSubscriptionStatus(originalTransactionId, config.apple, {
+      sandbox: environment === "Sandbox"
+    });
+    if (fresh) {
+      fresh.userId = appAccountToken ?? originalTransactionId;
+      if (inAppOwnershipType === "FAMILY_SHARED") {
+        const source = appAccountToken ? "appAccountToken" : "originalTransactionId (fallback)";
+        log.info(`[onesub/webhook/apple] FAMILY_SHARED \u2014 userId: ${fresh.userId} (source: ${source})`);
       }
+      await store.save(fresh);
     } else {
       log.warn(
-        "[onesub/webhook/apple] Received notification for unknown transaction (no API creds to recover):",
+        "[onesub/webhook/apple] Unknown transaction and Status API returned no record:",
         originalTransactionId
       );
     }
+  } else {
+    log.warn(
+      "[onesub/webhook/apple] Received notification for unknown transaction (no API creds to recover):",
+      originalTransactionId
+    );
+  }
+}
+async function handleAppleWebhook(req, res, config, store, purchaseStore, webhookEventStore, webhookQueue) {
+  const body = req.body;
+  if (!body.signedPayload) {
+    sendError(res, 400, shared.ONESUB_ERROR_CODE.MISSING_SIGNED_PAYLOAD, "Missing signedPayload");
+    return;
+  }
+  let payload;
+  try {
+    payload = await decodeJws(
+      body.signedPayload,
+      config.apple?.skipJwsVerification
+    );
+  } catch (err2) {
+    log.error("[onesub/webhook/apple] Failed to decode signedPayload:", err2);
+    sendError(res, 400, shared.ONESUB_ERROR_CODE.INVALID_SIGNED_PAYLOAD, "Invalid signedPayload");
+    return;
+  }
+  let markedEventId;
+  if (webhookEventStore && typeof payload.notificationUUID === "string") {
+    const fresh = await webhookEventStore.markIfNew("apple", payload.notificationUUID);
+    if (!fresh) {
+      log.info("[onesub/webhook/apple] dedupe: already processed", payload.notificationUUID);
+      res.status(200).json({ received: true, deduped: true });
+      return;
+    }
+    markedEventId = payload.notificationUUID;
+  }
+  const decoded = await decodeAppleNotification(payload, config.apple?.skipJwsVerification);
+  if (!decoded) {
     res.status(200).json({ received: true });
-  } catch (err) {
-    log.error("[onesub/webhook/apple] Store update error:", err);
-    if (webhookEventStore?.unmark && typeof payload.notificationUUID === "string") {
-      try {
-        await webhookEventStore.unmark("apple", payload.notificationUUID);
-      } catch {
-      }
+    return;
+  }
+  if (config.apple?.bundleId && decoded.bundleId && decoded.bundleId !== config.apple.bundleId) {
+    log.warn("[onesub/webhook/apple] Bundle ID mismatch:", decoded.bundleId, "!==", config.apple.bundleId);
+    sendError(res, 400, shared.ONESUB_ERROR_CODE.BUNDLE_ID_MISMATCH, "Bundle ID mismatch");
+    return;
+  }
+  const work = {
+    decoded,
+    notificationType: payload.notificationType,
+    subtype: payload.subtype
+  };
+  if (webhookQueue) {
+    try {
+      await webhookQueue.enqueue({
+        provider: "apple",
+        // Stable job id feeds queue-level dedup (BullMQ jobId). Random
+        // fallback when Apple omits the UUID — no dedup possible anyway.
+        eventId: typeof payload.notificationUUID === "string" ? payload.notificationUUID : crypto.randomUUID(),
+        payload: work
+      });
+      res.status(200).json({ received: true, queued: true });
+    } catch (err2) {
+      log.error("[onesub/webhook/apple] Failed to enqueue webhook job:", err2);
+      await unmarkWebhookEvent(webhookEventStore, "apple", markedEventId);
+      sendError(res, 500, shared.ONESUB_ERROR_CODE.WEBHOOK_PROCESSING_FAILED, "Failed to update subscription");
     }
+    return;
+  }
+  try {
+    await processAppleNotification(work, config, store, purchaseStore);
+    res.status(200).json({ received: true });
+  } catch (err2) {
+    log.error("[onesub/webhook/apple] Store update error:", err2);
+    await unmarkWebhookEvent(webhookEventStore, "apple", markedEventId);
     sendError(res, 500, shared.ONESUB_ERROR_CODE.WEBHOOK_PROCESSING_FAILED, "Failed to update subscription");
   }
 }
@@ -1433,7 +1532,117 @@ async function verifyGooglePushToken(req, expectedAudience, expectedServiceAccou
     return false;
   }
 }
-async function handleGoogleWebhook(req, res, config, store, purchaseStore, webhookEventStore) {
+var GOOGLE_FAILURE_MESSAGES = {
+  voided: {
+    logPrefix: "[onesub/webhook/google] voided notification error:",
+    message: "Failed to process voided notification"
+  },
+  oneTimeProduct: {
+    logPrefix: "[onesub/webhook/google] oneTimeProduct error:",
+    message: "Failed to process oneTimeProduct notification"
+  },
+  subscription: {
+    logPrefix: "[onesub/webhook/google] Error handling notification:",
+    message: "Failed to process notification"
+  }
+};
+async function processGoogleNotification(work, config, store, purchaseStore) {
+  if (work.kind === "voided") {
+    const { voided } = work;
+    if (voided.productType === 1) {
+      const existing2 = await store.getByTransactionId(voided.purchaseToken);
+      if (existing2) {
+        const updated = config.refundPolicy === "until_expiry" ? { ...existing2, willRenew: false } : { ...existing2, status: shared.SUBSCRIPTION_STATUS.CANCELED };
+        await store.save(updated);
+      } else {
+        log.warn("[onesub/webhook/google] voided subscription for unknown purchaseToken:", voided.purchaseToken);
+      }
+    } else {
+      const removed = await purchaseStore.deletePurchaseByTransactionId(voided.orderId);
+      if (!removed) {
+        log.warn("[onesub/webhook/google] voided IAP for unknown orderId:", voided.orderId);
+      }
+    }
+    return;
+  }
+  if (work.kind === "oneTimeProduct") {
+    const { notificationType: notificationType2, purchaseToken: purchaseToken2, sku } = work.oneTimeProduct;
+    if (notificationType2 === 1) {
+      log.info("[onesub/webhook/google] oneTimeProduct PURCHASED:", sku);
+      if (config.google?.serviceAccountKey && config.google.packageName) {
+        void acknowledgeGoogleProduct(purchaseToken2, sku, config.google).catch(
+          (err2) => log.warn(`[onesub/webhook/google] oneTimeProduct ack failed for SKU ${sku} \u2014 3-day auto-refund risk:`, err2)
+        );
+      }
+    } else {
+      log.info("[onesub/webhook/google] oneTimeProduct CANCELED (pre-completion):", sku);
+    }
+    return;
+  }
+  const { notificationType, purchaseToken, subscriptionId, packageName } = work.notification;
+  const existing = await store.getByTransactionId(purchaseToken);
+  let finalStatus;
+  if (isGoogleActiveNotification(notificationType)) {
+    finalStatus = shared.SUBSCRIPTION_STATUS.ACTIVE;
+  } else if (isGoogleGracePeriodNotification(notificationType)) {
+    finalStatus = shared.SUBSCRIPTION_STATUS.GRACE_PERIOD;
+  } else if (isGoogleOnHoldNotification(notificationType)) {
+    finalStatus = shared.SUBSCRIPTION_STATUS.ON_HOLD;
+  } else if (isGooglePausedNotification(notificationType)) {
+    finalStatus = shared.SUBSCRIPTION_STATUS.PAUSED;
+  } else if (isGooglePriceChangeConfirmedNotification(notificationType)) {
+    finalStatus = shared.SUBSCRIPTION_STATUS.ACTIVE;
+  } else if (isGoogleCanceledNotification(notificationType)) {
+    finalStatus = shared.SUBSCRIPTION_STATUS.CANCELED;
+  } else if (isGoogleExpiredNotification(notificationType)) {
+    finalStatus = shared.SUBSCRIPTION_STATUS.EXPIRED;
+  } else {
+    finalStatus = existing?.status ?? shared.SUBSCRIPTION_STATUS.ACTIVE;
+  }
+  if (isGooglePriceChangeConfirmedNotification(notificationType) && config.google?.onPriceChangeConfirmed) {
+    const hook = config.google.onPriceChangeConfirmed;
+    void Promise.resolve().then(() => hook({ purchaseToken, subscriptionId, packageName })).catch((err2) => log.warn("[onesub/webhook/google] onPriceChangeConfirmed hook failed:", err2));
+  }
+  if (existing) {
+    let updated = { ...existing, status: finalStatus };
+    if (config.google?.serviceAccountKey) {
+      const fresh = await validateGoogleReceipt(purchaseToken, subscriptionId, config.google);
+      if (fresh) {
+        const preserveNotificationStatus = isGoogleGracePeriodNotification(notificationType) || isGoogleOnHoldNotification(notificationType);
+        updated = {
+          ...existing,
+          status: preserveNotificationStatus ? finalStatus : fresh.status,
+          expiresAt: fresh.expiresAt,
+          willRenew: fresh.willRenew,
+          autoResumeTime: fresh.autoResumeTime,
+          linkedPurchaseToken: fresh.linkedPurchaseToken ?? existing.linkedPurchaseToken
+        };
+      }
+    }
+    await store.save(updated);
+  } else {
+    if (config.google?.serviceAccountKey) {
+      const fresh = await validateGoogleReceipt(purchaseToken, subscriptionId, config.google);
+      if (fresh) {
+        const boundAccountId = fresh.boundAccountId;
+        delete fresh.boundAccountId;
+        if (fresh.linkedPurchaseToken) {
+          const previous = await store.getByTransactionId(fresh.linkedPurchaseToken);
+          fresh.userId = previous ? previous.userId : boundAccountId ?? purchaseToken;
+          if (previous) {
+            log.info(`[onesub/webhook/google] inherited userId ${previous.userId} from linkedPurchaseToken ${fresh.linkedPurchaseToken} \u2192 new token ${purchaseToken}`);
+          }
+        } else {
+          fresh.userId = boundAccountId ?? purchaseToken;
+        }
+        await store.save(fresh);
+      }
+    } else {
+      log.warn("[onesub/webhook/google] Unknown purchase token and no serviceAccountKey to re-fetch:", purchaseToken);
+    }
+  }
+}
+async function handleGoogleWebhook(req, res, config, store, purchaseStore, webhookEventStore, webhookQueue) {
   if (config.google?.pushAudience) {
     const authenticated = await verifyGooglePushToken(
       req,
@@ -1450,14 +1659,7 @@ async function handleGoogleWebhook(req, res, config, store, purchaseStore, webho
     sendError(res, 400, shared.ONESUB_ERROR_CODE.MISSING_MESSAGE_DATA, "Missing message.data");
     return;
   }
-  const unmarkEvent = async () => {
-    if (webhookEventStore?.unmark && typeof body.message?.messageId === "string") {
-      try {
-        await webhookEventStore.unmark("google", body.message.messageId);
-      } catch {
-      }
-    }
-  };
+  let markedEventId;
   if (webhookEventStore && typeof body.message.messageId === "string") {
     const fresh = await webhookEventStore.markIfNew("google", body.message.messageId);
     if (!fresh) {
@@ -1465,7 +1667,9 @@ async function handleGoogleWebhook(req, res, config, store, purchaseStore, webho
       res.status(200).json({ received: true, deduped: true });
       return;
     }
+    markedEventId = body.message.messageId;
   }
+  let work;
   const voided = decodeGoogleVoidedNotification(body);
   if (voided) {
     if (config.google?.packageName && voided.packageName !== config.google.packageName) {
@@ -1473,147 +1677,77 @@ async function handleGoogleWebhook(req, res, config, store, purchaseStore, webho
       sendError(res, 400, shared.ONESUB_ERROR_CODE.PACKAGE_NAME_MISMATCH, "Package name mismatch");
       return;
     }
-    try {
-      if (voided.productType === 1) {
-        const existing = await store.getByTransactionId(voided.purchaseToken);
-        if (existing) {
-          const updated = config.refundPolicy === "until_expiry" ? { ...existing, willRenew: false } : { ...existing, status: shared.SUBSCRIPTION_STATUS.CANCELED };
-          await store.save(updated);
-        } else {
-          log.warn("[onesub/webhook/google] voided subscription for unknown purchaseToken:", voided.purchaseToken);
-        }
-      } else {
-        const removed = await purchaseStore.deletePurchaseByTransactionId(voided.orderId);
-        if (!removed) {
-          log.warn("[onesub/webhook/google] voided IAP for unknown orderId:", voided.orderId);
-        }
+    work = { kind: "voided", voided };
+  } else {
+    const oneTimeProduct = decodeGoogleOneTimeProductNotification(body);
+    if (oneTimeProduct) {
+      if (config.google?.packageName && oneTimeProduct.packageName !== config.google.packageName) {
+        log.warn("[onesub/webhook/google] oneTimeProduct package name mismatch:", oneTimeProduct.packageName, "!==", config.google.packageName);
+        sendError(res, 400, shared.ONESUB_ERROR_CODE.PACKAGE_NAME_MISMATCH, "Package name mismatch");
+        return;
       }
-      res.status(200).json({ received: true });
-    } catch (err) {
-      log.error("[onesub/webhook/google] voided notification error:", err);
-      await unmarkEvent();
-      sendError(res, 500, shared.ONESUB_ERROR_CODE.WEBHOOK_PROCESSING_FAILED, "Failed to process voided notification");
+      work = { kind: "oneTimeProduct", oneTimeProduct };
+    } else {
+      const notification = decodeGoogleNotification(body);
+      if (!notification) {
+        res.status(200).json({ received: true });
+        return;
+      }
+      if (config.google?.packageName && notification.packageName !== config.google.packageName) {
+        log.warn("[onesub/webhook/google] Package name mismatch:", notification.packageName, "!==", config.google.packageName);
+        sendError(res, 400, shared.ONESUB_ERROR_CODE.PACKAGE_NAME_MISMATCH, "Package name mismatch");
+        return;
+      }
+      work = { kind: "subscription", notification };
     }
-    return;
   }
-  const oneTimeProduct = decodeGoogleOneTimeProductNotification(body);
-  if (oneTimeProduct) {
-    if (config.google?.packageName && oneTimeProduct.packageName !== config.google.packageName) {
-      log.warn("[onesub/webhook/google] oneTimeProduct package name mismatch:", oneTimeProduct.packageName, "!==", config.google.packageName);
-      sendError(res, 400, shared.ONESUB_ERROR_CODE.PACKAGE_NAME_MISMATCH, "Package name mismatch");
-      return;
-    }
+  if (webhookQueue) {
     try {
-      const { notificationType: notificationType2, purchaseToken: purchaseToken2, sku } = oneTimeProduct;
-      if (notificationType2 === 1) {
-        log.info("[onesub/webhook/google] oneTimeProduct PURCHASED:", sku);
-        if (config.google?.serviceAccountKey && config.google.packageName) {
-          void acknowledgeGoogleProduct(purchaseToken2, sku, config.google).catch(
-            (err) => log.warn(`[onesub/webhook/google] oneTimeProduct ack failed for SKU ${sku} \u2014 3-day auto-refund risk:`, err)
-          );
-        }
-      } else {
-        log.info("[onesub/webhook/google] oneTimeProduct CANCELED (pre-completion):", sku);
-      }
-      res.status(200).json({ received: true });
-    } catch (err) {
-      log.error("[onesub/webhook/google] oneTimeProduct error:", err);
-      await unmarkEvent();
-      sendError(res, 500, shared.ONESUB_ERROR_CODE.WEBHOOK_PROCESSING_FAILED, "Failed to process oneTimeProduct notification");
+      await webhookQueue.enqueue({
+        provider: "google",
+        // Stable job id feeds queue-level dedup (BullMQ jobId). Random
+        // fallback when the push lacks a messageId — no dedup possible anyway.
+        eventId: typeof body.message.messageId === "string" ? body.message.messageId : crypto.randomUUID(),
+        payload: work
+      });
+      res.status(200).json({ received: true, queued: true });
+    } catch (err2) {
+      log.error("[onesub/webhook/google] Failed to enqueue webhook job:", err2);
+      await unmarkWebhookEvent(webhookEventStore, "google", markedEventId);
+      sendError(res, 500, shared.ONESUB_ERROR_CODE.WEBHOOK_PROCESSING_FAILED, GOOGLE_FAILURE_MESSAGES[work.kind].message);
     }
     return;
   }
-  const notification = decodeGoogleNotification(body);
-  if (!notification) {
-    res.status(200).json({ received: true });
-    return;
-  }
-  const { notificationType, purchaseToken, subscriptionId, packageName } = notification;
-  if (config.google?.packageName && packageName !== config.google.packageName) {
-    log.warn("[onesub/webhook/google] Package name mismatch:", packageName, "!==", config.google.packageName);
-    sendError(res, 400, shared.ONESUB_ERROR_CODE.PACKAGE_NAME_MISMATCH, "Package name mismatch");
-    return;
-  }
   try {
-    const existing = await store.getByTransactionId(purchaseToken);
-    let finalStatus;
-    if (isGoogleActiveNotification(notificationType)) {
-      finalStatus = shared.SUBSCRIPTION_STATUS.ACTIVE;
-    } else if (isGoogleGracePeriodNotification(notificationType)) {
-      finalStatus = shared.SUBSCRIPTION_STATUS.GRACE_PERIOD;
-    } else if (isGoogleOnHoldNotification(notificationType)) {
-      finalStatus = shared.SUBSCRIPTION_STATUS.ON_HOLD;
-    } else if (isGooglePausedNotification(notificationType)) {
-      finalStatus = shared.SUBSCRIPTION_STATUS.PAUSED;
-    } else if (isGooglePriceChangeConfirmedNotification(notificationType)) {
-      finalStatus = shared.SUBSCRIPTION_STATUS.ACTIVE;
-    } else if (isGoogleCanceledNotification(notificationType)) {
-      finalStatus = shared.SUBSCRIPTION_STATUS.CANCELED;
-    } else if (isGoogleExpiredNotification(notificationType)) {
-      finalStatus = shared.SUBSCRIPTION_STATUS.EXPIRED;
-    } else {
-      finalStatus = existing?.status ?? shared.SUBSCRIPTION_STATUS.ACTIVE;
-    }
-    if (isGooglePriceChangeConfirmedNotification(notificationType) && config.google?.onPriceChangeConfirmed) {
-      const hook = config.google.onPriceChangeConfirmed;
-      void Promise.resolve().then(() => hook({ purchaseToken, subscriptionId, packageName })).catch((err) => log.warn("[onesub/webhook/google] onPriceChangeConfirmed hook failed:", err));
-    }
-    if (existing) {
-      let updated = { ...existing, status: finalStatus };
-      if (config.google?.serviceAccountKey) {
-        const fresh = await validateGoogleReceipt(purchaseToken, subscriptionId, config.google);
-        if (fresh) {
-          const preserveNotificationStatus = isGoogleGracePeriodNotification(notificationType) || isGoogleOnHoldNotification(notificationType);
-          updated = {
-            ...existing,
-            status: preserveNotificationStatus ? finalStatus : fresh.status,
-            expiresAt: fresh.expiresAt,
-            willRenew: fresh.willRenew,
-            autoResumeTime: fresh.autoResumeTime,
-            linkedPurchaseToken: fresh.linkedPurchaseToken ?? existing.linkedPurchaseToken
-          };
-        }
-      }
-      await store.save(updated);
-    } else {
-      if (config.google?.serviceAccountKey) {
-        const fresh = await validateGoogleReceipt(purchaseToken, subscriptionId, config.google);
-        if (fresh) {
-          const boundAccountId = fresh.boundAccountId;
-          delete fresh.boundAccountId;
-          if (fresh.linkedPurchaseToken) {
-            const previous = await store.getByTransactionId(fresh.linkedPurchaseToken);
-            fresh.userId = previous ? previous.userId : boundAccountId ?? purchaseToken;
-            if (previous) {
-              log.info(`[onesub/webhook/google] inherited userId ${previous.userId} from linkedPurchaseToken ${fresh.linkedPurchaseToken} \u2192 new token ${purchaseToken}`);
-            }
-          } else {
-            fresh.userId = boundAccountId ?? purchaseToken;
-          }
-          await store.save(fresh);
-        }
-      } else {
-        log.warn("[onesub/webhook/google] Unknown purchase token and no serviceAccountKey to re-fetch:", purchaseToken);
-      }
-    }
+    await processGoogleNotification(work, config, store, purchaseStore);
     res.status(200).json({ received: true });
-  } catch (err) {
-    log.error("[onesub/webhook/google] Error handling notification:", err);
-    await unmarkEvent();
-    sendError(res, 500, shared.ONESUB_ERROR_CODE.WEBHOOK_PROCESSING_FAILED, "Failed to process notification");
+  } catch (err2) {
+    const { logPrefix, message } = GOOGLE_FAILURE_MESSAGES[work.kind];
+    log.error(logPrefix, err2);
+    await unmarkWebhookEvent(webhookEventStore, "google", markedEventId);
+    sendError(res, 500, shared.ONESUB_ERROR_CODE.WEBHOOK_PROCESSING_FAILED, message);
   }
 }
 
 // src/routes/webhook.ts
-function createWebhookRouter(config, store, purchaseStore, webhookEventStore) {
+function createWebhookRouter(config, store, purchaseStore, webhookEventStore, webhookQueue) {
+  if (webhookQueue) {
+    webhookQueue.setHandler(async (job) => {
+      if (job.provider === "apple") {
+        await processAppleNotification(job.payload, config, store, purchaseStore);
+      } else {
+        await processGoogleNotification(job.payload, config, store, purchaseStore);
+      }
+    });
+  }
   const router = express.Router();
   router.post(
     shared.ROUTES.WEBHOOK_APPLE,
-    (req, res) => handleAppleWebhook(req, res, config, store, purchaseStore, webhookEventStore)
+    (req, res) => handleAppleWebhook(req, res, config, store, purchaseStore, webhookEventStore, webhookQueue)
   );
   router.post(
     shared.ROUTES.WEBHOOK_GOOGLE,
-    (req, res) => handleGoogleWebhook(req, res, config, store, purchaseStore, webhookEventStore)
+    (req, res) => handleGoogleWebhook(req, res, config, store, purchaseStore, webhookEventStore, webhookQueue)
   );
   return router;
 }
@@ -1635,12 +1769,12 @@ function createPurchaseRouter(config, purchaseStore) {
     let body;
     try {
       body = validatePurchaseSchema.parse(req.body);
-    } catch (err) {
-      if (err instanceof zod.z.ZodError) {
-        sendZodError(res, err, NO_PURCHASE);
+    } catch (err2) {
+      if (err2 instanceof zod.z.ZodError) {
+        sendZodError(res, err2, NO_PURCHASE);
         return;
       }
-      throw err;
+      throw err2;
     }
     const { platform, receipt, userId, productId, type } = body;
     try {
@@ -1759,8 +1893,8 @@ function createPurchaseRouter(config, purchaseStore) {
         action
       };
       res.status(200).json(response);
-    } catch (err) {
-      log.error("[onesub/purchase/validate] Unexpected error:", err);
+    } catch (err2) {
+      log.error("[onesub/purchase/validate] Unexpected error:", err2);
       sendError(res, 500, shared.ONESUB_ERROR_CODE.INTERNAL_ERROR, "Internal server error during purchase validation", NO_PURCHASE);
     }
   });
@@ -1768,12 +1902,12 @@ function createPurchaseRouter(config, purchaseStore) {
     let query;
     try {
       query = purchaseStatusQuerySchema.parse(req.query);
-    } catch (err) {
-      if (err instanceof zod.z.ZodError) {
-        sendZodError(res, err, { purchases: [] });
+    } catch (err2) {
+      if (err2 instanceof zod.z.ZodError) {
+        sendZodError(res, err2, { purchases: [] });
         return;
       }
-      throw err;
+      throw err2;
     }
     const { userId, productId } = query;
     try {
@@ -1783,8 +1917,8 @@ function createPurchaseRouter(config, purchaseStore) {
       }
       const response = { purchases };
       res.status(200).json(response);
-    } catch (err) {
-      log.error("[onesub/purchase/status] Store error:", err);
+    } catch (err2) {
+      log.error("[onesub/purchase/status] Store error:", err2);
       sendError(res, 500, shared.ONESUB_ERROR_CODE.STORE_ERROR, "Internal server error", { purchases: [] });
     }
   });
@@ -1845,8 +1979,8 @@ function createEntitlementRouter(config, store, purchaseStore) {
       const status = await evaluateEntitlement(userId, entitlement, store, purchaseStore);
       const response = { id, ...status };
       res.status(200).json(response);
-    } catch (err) {
-      log.error("[onesub/entitlement] evaluation error:", err);
+    } catch (err2) {
+      log.error("[onesub/entitlement] evaluation error:", err2);
       sendError(res, 500, shared.ONESUB_ERROR_CODE.STORE_ERROR, "Internal server error");
     }
   });
@@ -1869,13 +2003,19 @@ function createEntitlementRouter(config, store, purchaseStore) {
         entitlements: Object.fromEntries(entries)
       };
       res.status(200).json(response);
-    } catch (err) {
-      log.error("[onesub/entitlements] evaluation error:", err);
+    } catch (err2) {
+      log.error("[onesub/entitlements] evaluation error:", err2);
       sendError(res, 500, shared.ONESUB_ERROR_CODE.STORE_ERROR, "Internal server error", { entitlements: {} });
     }
   });
   return router;
 }
+function secretsEqual(provided, expected) {
+  const providedBuf = Buffer.from(provided, "utf8");
+  const expectedBuf = Buffer.from(expected, "utf8");
+  if (providedBuf.length !== expectedBuf.length) return false;
+  return crypto.timingSafeEqual(providedBuf, expectedBuf);
+}
 
 // src/routes/admin.ts
 var ADMIN_SECRET_HEADER = "x-admin-secret";
@@ -1885,7 +2025,7 @@ function createAdminRouter(config, purchaseStore, store, webhookQueue) {
   const adminSecret = config.adminSecret;
   const adminAuth = (req, res, next) => {
     const provided = req.headers[ADMIN_SECRET_HEADER];
-    if (typeof provided !== "string" || provided !== adminSecret) {
+    if (typeof provided !== "string" || !secretsEqual(provided, adminSecret)) {
       sendError(res, 401, shared.ONESUB_ERROR_CODE.INVALID_ADMIN_SECRET, "INVALID_ADMIN_SECRET");
       return;
     }
@@ -1916,12 +2056,12 @@ function createAdminRouter(config, purchaseStore, store, webhookQueue) {
     let body;
     try {
       body = transferSchema.parse(req.body);
-    } catch (err) {
-      if (err instanceof zod.z.ZodError) {
-        sendZodError(res, err);
+    } catch (err2) {
+      if (err2 instanceof zod.z.ZodError) {
+        sendZodError(res, err2);
         return;
       }
-      throw err;
+      throw err2;
     }
     const existing = await purchaseStore.getPurchaseByTransactionId(body.transactionId);
     if (!existing) {
@@ -1947,12 +2087,12 @@ function createAdminRouter(config, purchaseStore, store, webhookQueue) {
     let body;
     try {
       body = grantSchema.parse(req.body);
-    } catch (err) {
-      if (err instanceof zod.z.ZodError) {
-        sendZodError(res, err);
+    } catch (err2) {
+      if (err2 instanceof zod.z.ZodError) {
+        sendZodError(res, err2);
         return;
       }
-      throw err;
+      throw err2;
     }
     const transactionId = body.transactionId ?? `admin_grant_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
     const purchase = {
@@ -1988,12 +2128,12 @@ function createAdminRouter(config, purchaseStore, store, webhookQueue) {
     let query;
     try {
       query = listQuerySchema.parse(req.query);
-    } catch (err) {
-      if (err instanceof zod.z.ZodError) {
-        sendZodError(res, err);
+    } catch (err2) {
+      if (err2 instanceof zod.z.ZodError) {
+        sendZodError(res, err2);
         return;
       }
-      throw err;
+      throw err2;
     }
     try {
       const result = await store.listFiltered(query);
@@ -2004,8 +2144,8 @@ function createAdminRouter(config, purchaseStore, store, webhookQueue) {
         offset: result.offset
       };
       res.status(200).json(response);
-    } catch (err) {
-      sendError(res, 500, shared.ONESUB_ERROR_CODE.STORE_ERROR, err.message ?? "list error");
+    } catch (err2) {
+      sendError(res, 500, shared.ONESUB_ERROR_CODE.STORE_ERROR, err2.message ?? "list error");
     }
   });
   const detailParamsSchema = zod.z.object({
@@ -2026,8 +2166,8 @@ function createAdminRouter(config, purchaseStore, store, webhookQueue) {
         return;
       }
       res.status(200).json(sub);
-    } catch (err) {
-      sendError(res, 500, shared.ONESUB_ERROR_CODE.STORE_ERROR, err.message ?? "detail error");
+    } catch (err2) {
+      sendError(res, 500, shared.ONESUB_ERROR_CODE.STORE_ERROR, err2.message ?? "detail error");
     }
   });
   const customerParamsSchema = zod.z.object({
@@ -2060,8 +2200,8 @@ function createAdminRouter(config, purchaseStore, store, webhookQueue) {
         ...entitlements ? { entitlements } : {}
       };
       res.status(200).json(response);
-    } catch (err) {
-      sendError(res, 500, shared.ONESUB_ERROR_CODE.STORE_ERROR, err.message ?? "customer error");
+    } catch (err2) {
+      sendError(res, 500, shared.ONESUB_ERROR_CODE.STORE_ERROR, err2.message ?? "customer error");
     }
   });
   const syncAppleParamsSchema = zod.z.object({
@@ -2092,8 +2232,8 @@ function createAdminRouter(config, purchaseStore, store, webhookQueue) {
       fresh.userId = existing?.userId ?? originalTransactionId;
       await store.save(fresh);
       res.status(200).json({ ok: true, subscription: fresh });
-    } catch (err) {
-      sendError(res, 500, shared.ONESUB_ERROR_CODE.INTERNAL_ERROR, err.message ?? "sync error");
+    } catch (err2) {
+      sendError(res, 500, shared.ONESUB_ERROR_CODE.INTERNAL_ERROR, err2.message ?? "sync error");
     }
   });
   if (webhookQueue?.listDeadLetters) {
@@ -2101,8 +2241,8 @@ function createAdminRouter(config, purchaseStore, store, webhookQueue) {
       try {
         const items = await webhookQueue.listDeadLetters();
         res.status(200).json({ items });
-      } catch (err) {
-        sendError(res, 500, shared.ONESUB_ERROR_CODE.STORE_ERROR, err.message ?? "list error");
+      } catch (err2) {
+        sendError(res, 500, shared.ONESUB_ERROR_CODE.STORE_ERROR, err2.message ?? "list error");
       }
     });
   }
@@ -2119,8 +2259,8 @@ function createAdminRouter(config, purchaseStore, store, webhookQueue) {
       try {
         await webhookQueue.replayDeadLetter(params.id);
         res.status(200).json({ ok: true });
-      } catch (err) {
-        sendError(res, 500, shared.ONESUB_ERROR_CODE.STORE_ERROR, err.message ?? "replay error");
+      } catch (err2) {
+        sendError(res, 500, shared.ONESUB_ERROR_CODE.STORE_ERROR, err2.message ?? "replay error");
       }
     });
   }
@@ -2133,7 +2273,7 @@ function createMetricsRouter(config, store, purchaseStore) {
   const adminSecret = config.adminSecret;
   router.use("/onesub/metrics", (req, res, next) => {
     const provided = req.headers[ADMIN_SECRET_HEADER2];
-    if (typeof provided !== "string" || provided !== adminSecret) {
+    if (typeof provided !== "string" || !secretsEqual(provided, adminSecret)) {
       sendError(res, 401, shared.ONESUB_ERROR_CODE.INVALID_ADMIN_SECRET, "INVALID_ADMIN_SECRET");
       return;
     }
@@ -2184,8 +2324,8 @@ function createMetricsRouter(config, store, purchaseStore) {
         byPlatform
       };
       res.status(200).json(response);
-    } catch (err) {
-      log.error("[onesub/metrics/active] error:", err);
+    } catch (err2) {
+      log.error("[onesub/metrics/active] error:", err2);
       sendError(res, 500, shared.ONESUB_ERROR_CODE.STORE_ERROR, "Internal server error");
     }
   });
@@ -2194,6 +2334,8 @@ function createMetricsRouter(config, store, purchaseStore) {
     to: zod.z.string().min(1),
     groupBy: zod.z.enum(["none", "day"]).optional()
   });
+  const MAX_DAY_BUCKET_SPAN_DAYS = 366;
+  const MAX_DAY_BUCKET_SPAN_MS = MAX_DAY_BUCKET_SPAN_DAYS * 864e5;
   function parseRange(req) {
     const parsed = rangeSchema.safeParse(req.query);
     if (!parsed.success) return { error: "from and to are required (ISO 8601)" };
@@ -2203,7 +2345,13 @@ function createMetricsRouter(config, store, purchaseStore) {
       return { error: "from / to must be ISO 8601 timestamps" };
     }
     if (fromMs > toMs) return { error: "from must be \u2264 to" };
-    return { fromMs, toMs, groupBy: parsed.data.groupBy ?? "none" };
+    const groupBy = parsed.data.groupBy ?? "none";
+    if (groupBy === "day" && toMs - fromMs > MAX_DAY_BUCKET_SPAN_MS) {
+      return {
+        error: `groupBy=day supports a range of at most ${MAX_DAY_BUCKET_SPAN_DAYS} days \u2014 narrow the from/to window or omit groupBy`
+      };
+    }
+    return { fromMs, toMs, groupBy };
   }
   function utcDateKey(ms) {
     const d = new Date(ms);
@@ -2256,8 +2404,8 @@ function createMetricsRouter(config, store, purchaseStore) {
         ...buckets ? { buckets } : {}
       };
       res.status(200).json(response);
-    } catch (err) {
-      log.error("[onesub/metrics/started] error:", err);
+    } catch (err2) {
+      log.error("[onesub/metrics/started] error:", err2);
       sendError(res, 500, shared.ONESUB_ERROR_CODE.STORE_ERROR, "Internal server error");
     }
   });
@@ -2295,8 +2443,8 @@ function createMetricsRouter(config, store, purchaseStore) {
         ...buckets ? { buckets } : {}
       };
       res.status(200).json(response);
-    } catch (err) {
-      log.error("[onesub/metrics/expired] error:", err);
+    } catch (err2) {
+      log.error("[onesub/metrics/expired] error:", err2);
       sendError(res, 500, shared.ONESUB_ERROR_CODE.STORE_ERROR, "Internal server error");
     }
   });
@@ -2334,8 +2482,8 @@ function createMetricsRouter(config, store, purchaseStore) {
         ...buckets ? { buckets } : {}
       };
       res.status(200).json(response);
-    } catch (err) {
-      log.error("[onesub/metrics/purchases/started] error:", err);
+    } catch (err2) {
+      log.error("[onesub/metrics/purchases/started] error:", err2);
       sendError(res, 500, shared.ONESUB_ERROR_CODE.STORE_ERROR, "Internal server error");
     }
   });
@@ -2354,7 +2502,7 @@ function createAppleOfferRouter(config) {
   router.post("/onesub/apple/offer-signature", async (req, res) => {
     if (config.adminSecret) {
       const provided = req.headers[OFFER_SECRET_HEADER];
-      if (typeof provided !== "string" || provided !== config.adminSecret) {
+      if (typeof provided !== "string" || !secretsEqual(provided, config.adminSecret)) {
         sendError(res, 401, shared.ONESUB_ERROR_CODE.UNAUTHORIZED, "Unauthorized");
         return;
       }
@@ -2362,12 +2510,12 @@ function createAppleOfferRouter(config) {
     let body;
     try {
       body = offerBodySchema.parse(req.body);
-    } catch (err) {
-      if (err instanceof zod.z.ZodError) {
-        sendZodError(res, err);
+    } catch (err2) {
+      if (err2 instanceof zod.z.ZodError) {
+        sendZodError(res, err2);
         return;
       }
-      throw err;
+      throw err2;
     }
     if (!apple.bundleId) {
       sendError(res, 400, shared.ONESUB_ERROR_CODE.APPLE_CONFIG_MISSING, "config.apple.bundleId is required for offer signing");
@@ -2384,8 +2532,8 @@ function createAppleOfferRouter(config) {
         apple
       );
       res.status(200).json(result);
-    } catch (err) {
-      sendError(res, 500, shared.ONESUB_ERROR_CODE.INTERNAL_ERROR, err.message ?? "Offer signing failed");
+    } catch (err2) {
+      sendError(res, 500, shared.ONESUB_ERROR_CODE.INTERNAL_ERROR, err2.message ?? "Offer signing failed");
     }
   });
   return router;
@@ -2449,6 +2597,17 @@ CREATE UNIQUE INDEX IF NOT EXISTS idx_onesub_purchases_non_consumable
 `.trim();
 
 // src/stores/postgres.ts
+async function createPgPool(connectionString, label) {
+  const pg = await import('pg').catch(() => {
+    throw new Error(`[onesub] ${label} requires the \`pg\` package. Run: npm install pg`);
+  });
+  const Pool = pg.default?.Pool ?? pg.Pool;
+  const pool = new Pool({ connectionString, max: 10 });
+  pool.on("error", (err2) => {
+    log.error(`[onesub] ${label} pool error (idle client):`, err2);
+  });
+  return pool;
+}
 var PostgresSubscriptionStore = class {
   constructor(connectionString) {
     this.connectionString = connectionString;
@@ -2458,19 +2617,7 @@ var PostgresSubscriptionStore = class {
   poolPromise = null;
   getPool() {
     if (!this.poolPromise) {
-      this.poolPromise = (async () => {
-        const pg = await import('pg').catch(() => {
-          throw new Error(
-            "[onesub] PostgresSubscriptionStore requires the `pg` package. Run: npm install pg"
-          );
-        });
-        const Pool = pg.default?.Pool ?? pg.Pool;
-        const pool = new Pool({ connectionString: this.connectionString, max: 10 });
-        pool.on("error", (err) => {
-          log.error("[onesub] PostgresSubscriptionStore pool error (idle client):", err);
-        });
-        return pool;
-      })();
+      this.poolPromise = createPgPool(this.connectionString, "PostgresSubscriptionStore");
     }
     return this.poolPromise;
   }
@@ -2634,19 +2781,7 @@ var PostgresPurchaseStore = class {
   poolPromise = null;
   getPool() {
     if (!this.poolPromise) {
-      this.poolPromise = (async () => {
-        const pg = await import('pg').catch(() => {
-          throw new Error(
-            "[onesub] PostgresPurchaseStore requires the `pg` package. Run: npm install pg"
-          );
-        });
-        const Pool = pg.default?.Pool ?? pg.Pool;
-        const pool = new Pool({ connectionString: this.connectionString, max: 10 });
-        pool.on("error", (err) => {
-          log.error("[onesub] PostgresPurchaseStore pool error (idle client):", err);
-        });
-        return pool;
-      })();
+      this.poolPromise = createPgPool(this.connectionString, "PostgresPurchaseStore");
     }
     return this.poolPromise;
   }
@@ -2683,9 +2818,9 @@ var PostgresPurchaseStore = class {
     );
     const owner = existing.rows[0]?.user_id;
     if (owner !== void 0 && owner !== purchase.userId) {
-      const err = new Error("TRANSACTION_BELONGS_TO_OTHER_USER");
-      err.code = "TRANSACTION_BELONGS_TO_OTHER_USER";
-      throw err;
+      const err2 = new Error("TRANSACTION_BELONGS_TO_OTHER_USER");
+      err2.code = "TRANSACTION_BELONGS_TO_OTHER_USER";
+      throw err2;
     }
   }
   async getPurchasesByUserId(userId) {
@@ -2786,6 +2921,7 @@ function rowToPurchaseInfo(row) {
 
 // src/stores/redis.ts
 var SUB_TX_PREFIX = "onesub:sub:tx:";
+var SUB_OWNER_PREFIX = "onesub:sub:owner:";
 var SUB_USER_PREFIX = "onesub:sub:user:";
 var SUB_ALL_SORTED = "onesub:sub:all:sorted";
 var PUR_TX_PREFIX = "onesub:purchase:tx:";
@@ -2800,11 +2936,16 @@ var RedisSubscriptionStore = class {
   async save(sub) {
     const score = Date.now();
     const txKey = SUB_TX_PREFIX + sub.originalTransactionId;
+    const ownerKey = SUB_OWNER_PREFIX + sub.originalTransactionId;
     const userKey = SUB_USER_PREFIX + sub.userId;
-    const prevRaw = await this.redis.get(txKey);
-    const prevUserId = prevRaw ? JSON.parse(prevRaw).userId : null;
+    let prevUserId = await this.redis.get(ownerKey);
+    if (prevUserId === null) {
+      const prevRaw = await this.redis.get(txKey);
+      prevUserId = prevRaw ? JSON.parse(prevRaw).userId : null;
+    }
     const pipeline = this.redis.multi();
     pipeline.set(txKey, JSON.stringify(sub));
+    pipeline.set(ownerKey, sub.userId);
     if (prevUserId !== null && prevUserId !== sub.userId) {
       pipeline.zrem(SUB_USER_PREFIX + prevUserId, sub.originalTransactionId);
     }
@@ -2885,9 +3026,9 @@ var RedisPurchaseStore = class {
       const existing = await this.redis.get(txKey);
       const owner = existing ? JSON.parse(existing).userId : null;
       if (owner !== null && owner !== purchase.userId) {
-        const err = new Error("TRANSACTION_BELONGS_TO_OTHER_USER");
-        err.code = "TRANSACTION_BELONGS_TO_OTHER_USER";
-        throw err;
+        const err2 = new Error("TRANSACTION_BELONGS_TO_OTHER_USER");
+        err2.code = "TRANSACTION_BELONGS_TO_OTHER_USER";
+        throw err2;
       }
     }
     const score = Date.parse(purchase.purchasedAt) || Date.now();
@@ -3007,50 +3148,6 @@ var RedisWebhookEventStore = class {
   }
 };
 
-// src/webhook-events.ts
-var DEFAULT_TTL_SECONDS = 7 * 24 * 60 * 60;
-var InMemoryWebhookEventStore = class {
-  constructor(ttlSeconds = DEFAULT_TTL_SECONDS) {
-    this.ttlSeconds = ttlSeconds;
-  }
-  ttlSeconds;
-  seen = /* @__PURE__ */ new Map();
-  async markIfNew(provider, eventId) {
-    this.evictExpired();
-    const key = `${provider}:${eventId}`;
-    if (this.seen.has(key)) return false;
-    this.seen.set(key, Date.now() + this.ttlSeconds * 1e3);
-    return true;
-  }
-  async unmark(provider, eventId) {
-    this.seen.delete(`${provider}:${eventId}`);
-  }
-  evictExpired() {
-    const now = Date.now();
-    for (const [key, expiresAt] of this.seen) {
-      if (expiresAt < now) this.seen.delete(key);
-    }
-  }
-};
-var CacheWebhookEventStore = class {
-  constructor(cache, ttlSeconds = DEFAULT_TTL_SECONDS) {
-    this.cache = cache;
-    this.ttlSeconds = ttlSeconds;
-  }
-  cache;
-  ttlSeconds;
-  async markIfNew(provider, eventId) {
-    const key = `webhook:event:${provider}:${eventId}`;
-    const existing = await this.cache.get(key);
-    if (existing) return false;
-    await this.cache.set(key, "1", this.ttlSeconds);
-    return true;
-  }
-  async unmark(provider, eventId) {
-    await this.cache.del(`webhook:event:${provider}:${eventId}`);
-  }
-};
-
 // src/webhook-queue.ts
 var InProcessWebhookQueue = class {
   handler = null;
@@ -3075,6 +3172,13 @@ var BullMQWebhookQueue = class {
   queuePromise = null;
   workerPromise = null;
   handler = null;
+  /**
+   * Captured worker-startup failure (e.g. `bullmq` not installed). `setHandler`
+   * is synchronous, so it can't reject — the error is surfaced on the next
+   * `enqueue()` instead of becoming an unhandled rejection that kills the
+   * process.
+   */
+  workerStartupError = null;
   constructor(opts) {
     this.connection = opts.connection;
     this.queueName = opts.queueName ?? "onesub-webhooks";
@@ -3091,7 +3195,11 @@ var BullMQWebhookQueue = class {
     if (!this.queuePromise) {
       this.queuePromise = (async () => {
         const { Queue } = await this.getBullMQ();
-        return new Queue(this.queueName, { connection: this.connection });
+        const queue = new Queue(this.queueName, { connection: this.connection });
+        queue.on?.("error", (err2) => {
+          log.error("[onesub] BullMQ queue error:", err2);
+        });
+        return queue;
       })();
     }
     return this.queuePromise;
@@ -3101,7 +3209,7 @@ var BullMQWebhookQueue = class {
     if (!this.workerPromise) {
       this.workerPromise = (async () => {
         const { Worker } = await this.getBullMQ();
-        return new Worker(
+        const worker = new Worker(
           this.queueName,
           async (job) => {
             if (!this.handler) throw new Error("[onesub] handler not set");
@@ -3112,10 +3220,19 @@ var BullMQWebhookQueue = class {
             concurrency: this.concurrency
           }
         );
+        worker.on?.("error", (err2) => {
+          log.error("[onesub] BullMQ worker error:", err2);
+        });
+        return worker;
       })();
+      this.workerPromise.catch((err2) => {
+        this.workerStartupError = err2 instanceof Error ? err2 : new Error(String(err2));
+        log.error("[onesub] BullMQ worker failed to start:", err2);
+      });
     }
   }
   async enqueue(job) {
+    if (this.workerStartupError) throw this.workerStartupError;
     const queue = await this.getQueue();
     await queue.add("webhook", job, {
       attempts: this.maxAttempts,
@@ -3144,26 +3261,42 @@ var BullMQWebhookQueue = class {
   }
   async close() {
     if (this.workerPromise) {
-      const worker = await this.workerPromise;
-      await worker.close();
+      const worker = await this.workerPromise.catch(() => null);
+      if (worker) await worker.close();
     }
     if (this.queuePromise) {
-      const queue = await this.queuePromise;
-      await queue.close();
+      const queue = await this.queuePromise.catch(() => null);
+      if (queue) await queue.close();
     }
   }
 };
+var ERROR_CONTENT = {
+  "application/json": { schema: { $ref: "#/components/schemas/ErrorResponse" } }
+};
+var err = (description) => ({ description, content: ERROR_CONTENT });
+var ADMIN_SECRET_PARAM = {
+  in: "header",
+  name: "X-Admin-Secret",
+  required: true,
+  schema: { type: "string" }
+};
+var METRICS_RANGE_PARAMS = [
+  { in: "query", name: "from", required: true, schema: { type: "string", format: "date-time" }, description: "Window start (ISO 8601)." },
+  { in: "query", name: "to", required: true, schema: { type: "string", format: "date-time" }, description: "Window end (ISO 8601)." },
+  { in: "query", name: "groupBy", schema: { type: "string", enum: ["none", "day"] }, description: "'day' adds a zero-filled daily `buckets` series to the response." }
+];
 var ONESUB_OPENAPI = {
   openapi: "3.1.0",
   info: {
     title: "onesub HTTP API",
     version: "1.0.0",
-    description: "Receipt validation, subscription status, webhooks, and admin endpoints exposed by `createOneSubMiddleware`."
+    description: "Receipt validation, subscription status, one-time purchases, entitlements, webhooks, metrics, and admin endpoints exposed by `createOneSubMiddleware`."
   },
   servers: [
     { url: "http://localhost:4100", description: "Local dev (examples/server)" }
   ],
   paths: {
+    // ── public: subscriptions ────────────────────────────────────────────────
     [shared.ROUTES.VALIDATE]: {
       post: {
         summary: "Validate an Apple/Google receipt and persist subscription state.",
@@ -3173,7 +3306,9 @@ var ONESUB_OPENAPI = {
         },
         responses: {
           200: { description: "Validation succeeded; subscription state persisted.", content: { "application/json": { schema: { $ref: "#/components/schemas/ValidateResponse" } } } },
-          400: { description: "Bad request \u2014 missing fields, malformed receipt, package mismatch." }
+          400: err("Bad request \u2014 missing fields, malformed receipt, package mismatch."),
+          409: err("Receipt is account-bound to a different userId (TRANSACTION_BELONGS_TO_OTHER_USER)."),
+          422: err("Receipt validation failed (RECEIPT_VALIDATION_FAILED).")
         }
       }
     },
@@ -3182,17 +3317,49 @@ var ONESUB_OPENAPI = {
         summary: "Fetch the most recent subscription state for a user.",
         parameters: [{ in: "query", name: "userId", required: true, schema: { type: "string" } }],
         responses: {
-          200: { description: "OK", content: { "application/json": { schema: { $ref: "#/components/schemas/StatusResponse" } } } }
+          200: { description: "OK", content: { "application/json": { schema: { $ref: "#/components/schemas/StatusResponse" } } } },
+          400: err("Missing userId or userId too long (INVALID_INPUT / USER_ID_TOO_LONG).")
+        }
+      }
+    },
+    // ── public: one-time purchases ───────────────────────────────────────────
+    [shared.ROUTES.VALIDATE_PURCHASE]: {
+      post: {
+        summary: "Validate a consumable / non-consumable receipt and record the purchase.",
+        description: 'Non-consumables are idempotent: an already-owned product returns the stored purchase with `action: "restored"`. Consumable receipts can only be redeemed once.',
+        requestBody: {
+          required: true,
+          content: { "application/json": { schema: { $ref: "#/components/schemas/ValidatePurchaseRequest" } } }
+        },
+        responses: {
+          200: { description: 'Purchase validated \u2014 freshly recorded (`action: "new"`) or restored.', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidatePurchaseResponse" } } } },
+          400: err("Bad request \u2014 missing/invalid fields (INVALID_INPUT)."),
+          409: err("Receipt is account-bound or already redeemed by another user (TRANSACTION_BELONGS_TO_OTHER_USER)."),
+          422: err("Receipt validation failed (RECEIPT_VALIDATION_FAILED).")
         }
       }
     },
+    [shared.ROUTES.PURCHASE_STATUS]: {
+      get: {
+        summary: "List all recorded purchases for a user, optionally filtered by product.",
+        parameters: [
+          { in: "query", name: "userId", required: true, schema: { type: "string" } },
+          { in: "query", name: "productId", schema: { type: "string" } }
+        ],
+        responses: {
+          200: { description: "OK", content: { "application/json": { schema: { $ref: "#/components/schemas/PurchaseStatusResponse" } } } },
+          400: err("Missing/invalid userId (INVALID_INPUT).")
+        }
+      }
+    },
+    // ── webhooks ─────────────────────────────────────────────────────────────
     [shared.ROUTES.WEBHOOK_APPLE]: {
       post: {
         summary: "Apple App Store Server Notification V2 receiver.",
         description: "Apple POSTs `{ signedPayload }`. JWS-verified, idempotent when `webhookEventStore` is configured.",
         responses: {
           200: { description: "Acknowledged." },
-          400: { description: "Missing or invalid signedPayload." }
+          400: err("Missing or invalid signedPayload.")
         }
       }
     },
@@ -3201,8 +3368,23 @@ var ONESUB_OPENAPI = {
         summary: "Google Play Real-Time Developer Notification (Pub/Sub push) receiver.",
         responses: {
           200: { description: "Acknowledged." },
-          400: { description: "Missing message.data or package mismatch." },
-          401: { description: "pushAudience configured and JWT verification failed." }
+          400: err("Missing message.data or package mismatch."),
+          401: err("pushAudience configured and JWT verification failed.")
+        }
+      }
+    },
+    // ── entitlements (mounted when config.entitlements is set) ──────────────
+    [shared.ROUTES.ENTITLEMENT]: {
+      get: {
+        summary: "Evaluate a single configured entitlement for a user.",
+        parameters: [
+          { in: "query", name: "userId", required: true, schema: { type: "string" } },
+          { in: "query", name: "id", required: true, schema: { type: "string" }, description: "Entitlement id from `config.entitlements`." }
+        ],
+        responses: {
+          200: { description: "OK", content: { "application/json": { schema: { $ref: "#/components/schemas/EntitlementResponse" } } } },
+          400: err("userId and id are required (INVALID_INPUT)."),
+          404: err("Unknown entitlement id (ENTITLEMENT_NOT_FOUND).")
         }
       }
     },
@@ -3211,15 +3393,17 @@ var ONESUB_OPENAPI = {
         summary: "Evaluate every configured entitlement for a user.",
         parameters: [{ in: "query", name: "userId", required: true, schema: { type: "string" } }],
         responses: {
-          200: { description: "Map of entitlementId \u2192 { granted, source }." }
+          200: { description: "Map of entitlementId \u2192 EntitlementStatus.", content: { "application/json": { schema: { $ref: "#/components/schemas/EntitlementsResponse" } } } },
+          400: err("userId is required (INVALID_INPUT).")
         }
       }
     },
+    // ── admin (mounted when config.adminSecret is set) ───────────────────────
     [shared.ROUTES.ADMIN_SUBSCRIPTIONS]: {
       get: {
         summary: "Filtered, paginated subscription list (admin).",
         parameters: [
-          { in: "header", name: "X-Admin-Secret", required: true, schema: { type: "string" } },
+          ADMIN_SECRET_PARAM,
           { in: "query", name: "userId", schema: { type: "string" } },
           { in: "query", name: "status", schema: { type: "string", enum: ["active", "grace_period", "on_hold", "paused", "expired", "canceled", "none"] } },
           { in: "query", name: "productId", schema: { type: "string" } },
@@ -3227,39 +3411,203 @@ var ONESUB_OPENAPI = {
           { in: "query", name: "limit", schema: { type: "integer", minimum: 1, maximum: 200 } },
           { in: "query", name: "offset", schema: { type: "integer", minimum: 0 } }
         ],
-        responses: { 200: { description: "OK" }, 401: { description: "Invalid admin secret" } }
+        responses: {
+          200: { description: "OK", content: { "application/json": { schema: { $ref: "#/components/schemas/ListSubscriptionsResponse" } } } },
+          400: err("Invalid filter/pagination params (INVALID_INPUT)."),
+          401: err("Invalid admin secret (INVALID_ADMIN_SECRET).")
+        }
+      }
+    },
+    "/onesub/admin/subscriptions/{transactionId}": {
+      get: {
+        summary: "Single subscription record by originalTransactionId (admin).",
+        parameters: [
+          ADMIN_SECRET_PARAM,
+          { in: "path", name: "transactionId", required: true, schema: { type: "string" } }
+        ],
+        responses: {
+          200: { description: "OK", content: { "application/json": { schema: { $ref: "#/components/schemas/SubscriptionInfo" } } } },
+          400: err("transactionId required (INVALID_INPUT)."),
+          401: err("Invalid admin secret (INVALID_ADMIN_SECRET)."),
+          404: err("No record for this transactionId (TRANSACTION_NOT_FOUND).")
+        }
       }
     },
     "/onesub/admin/customers/{userId}": {
       get: {
         summary: "Customer profile bundle: subscriptions + purchases + entitlements (admin).",
         parameters: [
-          { in: "header", name: "X-Admin-Secret", required: true, schema: { type: "string" } },
+          ADMIN_SECRET_PARAM,
           { in: "path", name: "userId", required: true, schema: { type: "string" } }
         ],
-        responses: { 200: { description: "OK" }, 401: { description: "Invalid admin secret" } }
+        responses: {
+          200: { description: 'OK \u2014 empty arrays mean "no record of this user" (never 404).', content: { "application/json": { schema: { $ref: "#/components/schemas/CustomerProfileResponse" } } } },
+          400: err("userId required (INVALID_INPUT)."),
+          401: err("Invalid admin secret (INVALID_ADMIN_SECRET).")
+        }
+      }
+    },
+    "/onesub/admin/sync-apple/{originalTransactionId}": {
+      post: {
+        summary: "Reconcile one subscription from the Apple Status API into the local store (admin).",
+        parameters: [
+          ADMIN_SECRET_PARAM,
+          { in: "path", name: "originalTransactionId", required: true, schema: { type: "string" } },
+          { in: "query", name: "sandbox", schema: { type: "string", enum: ["true"] }, description: "Force the sandbox Status API host (otherwise inferred from the stored record)." }
+        ],
+        responses: {
+          200: { description: "Fresh state fetched and upserted.", content: { "application/json": { schema: { type: "object", properties: { ok: { type: "boolean" }, subscription: { $ref: "#/components/schemas/SubscriptionInfo" } } } } } },
+          400: err("originalTransactionId missing or Apple API credentials not configured (INVALID_INPUT / APPLE_CONFIG_MISSING)."),
+          401: err("Invalid admin secret (INVALID_ADMIN_SECRET)."),
+          404: err("Apple Status API returned no record (TRANSACTION_NOT_FOUND).")
+        }
+      }
+    },
+    "/onesub/purchase/admin/{userId}/{productId}": {
+      delete: {
+        summary: "Reset a purchase so the user can test the flow again (admin).",
+        parameters: [
+          ADMIN_SECRET_PARAM,
+          { in: "path", name: "userId", required: true, schema: { type: "string" } },
+          { in: "path", name: "productId", required: true, schema: { type: "string" } }
+        ],
+        responses: {
+          200: { description: "OK", content: { "application/json": { schema: { type: "object", properties: { ok: { type: "boolean" }, deleted: { type: "integer", description: "Number of purchase rows removed." } } } } } },
+          400: err("userId and productId required (INVALID_INPUT)."),
+          401: err("Invalid admin secret (INVALID_ADMIN_SECRET).")
+        }
+      }
+    },
+    "/onesub/purchase/admin/transfer": {
+      post: {
+        summary: "Reassign a transactionId to a new userId \u2014 device/account migration (admin).",
+        parameters: [ADMIN_SECRET_PARAM],
+        requestBody: {
+          required: true,
+          content: { "application/json": { schema: { type: "object", required: ["transactionId", "newUserId"], properties: { transactionId: { type: "string" }, newUserId: { type: "string" } } } } }
+        },
+        responses: {
+          200: { description: "Transferred.", content: { "application/json": { schema: { type: "object", properties: { ok: { type: "boolean" }, purchase: { $ref: "#/components/schemas/PurchaseInfo" } } } } } },
+          400: err("Missing/invalid body fields (INVALID_INPUT)."),
+          401: err("Invalid admin secret (INVALID_ADMIN_SECRET)."),
+          404: err("No purchase with this transactionId (TRANSACTION_NOT_FOUND).")
+        }
+      }
+    },
+    "/onesub/purchase/admin/grant": {
+      post: {
+        summary: "Manually insert a purchase record, skipping store verification (admin).",
+        parameters: [ADMIN_SECRET_PARAM],
+        requestBody: {
+          required: true,
+          content: { "application/json": { schema: { $ref: "#/components/schemas/GrantPurchaseRequest" } } }
+        },
+        responses: {
+          200: { description: "Granted.", content: { "application/json": { schema: { type: "object", properties: { ok: { type: "boolean" }, purchase: { $ref: "#/components/schemas/PurchaseInfo" } } } } } },
+          400: err("Missing/invalid body fields (INVALID_INPUT)."),
+          401: err("Invalid admin secret (INVALID_ADMIN_SECRET).")
+        }
       }
     },
     "/onesub/admin/webhook-deadletters": {
       get: {
         summary: "List failed webhook jobs (when a queue with DLQ support is configured).",
-        parameters: [{ in: "header", name: "X-Admin-Secret", required: true, schema: { type: "string" } }],
-        responses: { 200: { description: "OK" }, 401: { description: "Invalid admin secret" } }
+        parameters: [ADMIN_SECRET_PARAM],
+        responses: {
+          200: { description: "OK", content: { "application/json": { schema: { type: "object", properties: { items: { type: "array", items: { type: "object", description: "DeadLetterRecord: { id, job, attemptsMade, lastError, failedAt }." } } } } } } },
+          401: err("Invalid admin secret (INVALID_ADMIN_SECRET).")
+        }
       }
     },
     "/onesub/admin/webhook-replay/{id}": {
       post: {
         summary: "Replay a dead-letter job through the webhook handler.",
         parameters: [
-          { in: "header", name: "X-Admin-Secret", required: true, schema: { type: "string" } },
+          ADMIN_SECRET_PARAM,
           { in: "path", name: "id", required: true, schema: { type: "string" } }
         ],
-        responses: { 200: { description: "OK" }, 401: { description: "Invalid admin secret" } }
+        responses: {
+          200: { description: "OK" },
+          400: err("id required (INVALID_INPUT)."),
+          401: err("Invalid admin secret (INVALID_ADMIN_SECRET).")
+        }
+      }
+    },
+    // ── metrics (mounted when config.adminSecret is set) ─────────────────────
+    [shared.ROUTES.METRICS_ACTIVE]: {
+      get: {
+        summary: "Snapshot of currently-entitled users (active subs + non-consumable owners).",
+        parameters: [ADMIN_SECRET_PARAM],
+        responses: {
+          200: { description: "OK", content: { "application/json": { schema: { $ref: "#/components/schemas/MetricsActiveResponse" } } } },
+          401: err("Invalid admin secret (INVALID_ADMIN_SECRET).")
+        }
+      }
+    },
+    [shared.ROUTES.METRICS_STARTED]: {
+      get: {
+        summary: "Subscriptions started (purchasedAt) within a window.",
+        parameters: [ADMIN_SECRET_PARAM, ...METRICS_RANGE_PARAMS],
+        responses: {
+          200: { description: "OK", content: { "application/json": { schema: { $ref: "#/components/schemas/MetricsCountResponse" } } } },
+          400: err("from/to missing, non-ISO, or from > to (INVALID_INPUT)."),
+          401: err("Invalid admin secret (INVALID_ADMIN_SECRET).")
+        }
+      }
+    },
+    [shared.ROUTES.METRICS_EXPIRED]: {
+      get: {
+        summary: "Subscriptions expired/canceled (expiresAt) within a window.",
+        parameters: [ADMIN_SECRET_PARAM, ...METRICS_RANGE_PARAMS],
+        responses: {
+          200: { description: "OK", content: { "application/json": { schema: { $ref: "#/components/schemas/MetricsCountResponse" } } } },
+          400: err("from/to missing, non-ISO, or from > to (INVALID_INPUT)."),
+          401: err("Invalid admin secret (INVALID_ADMIN_SECRET).")
+        }
+      }
+    },
+    [shared.ROUTES.METRICS_PURCHASES_STARTED]: {
+      get: {
+        summary: "Non-consumable purchases started (purchasedAt) within a window.",
+        parameters: [ADMIN_SECRET_PARAM, ...METRICS_RANGE_PARAMS],
+        responses: {
+          200: { description: "OK", content: { "application/json": { schema: { $ref: "#/components/schemas/MetricsCountResponse" } } } },
+          400: err("from/to missing, non-ISO, or from > to (INVALID_INPUT)."),
+          401: err("Invalid admin secret (INVALID_ADMIN_SECRET).")
+        }
+      }
+    },
+    // ── Apple Promotional Offer signing (mounted when offerKeyId + offerPrivateKey set) ──
+    [shared.ROUTES.APPLE_OFFER_SIGNATURE]: {
+      post: {
+        summary: "Sign an Apple Promotional Offer payload server-side (ES256).",
+        description: "The client passes the returned `{ keyId, nonce, timestamp, signature }` to StoreKit to redeem the offer. When `config.adminSecret` is set, the request must carry `X-Onesub-Offer-Secret` with the same value.",
+        parameters: [
+          { in: "header", name: "X-Onesub-Offer-Secret", required: false, schema: { type: "string" }, description: "Required (must equal config.adminSecret) when adminSecret is configured." }
+        ],
+        requestBody: {
+          required: true,
+          content: { "application/json": { schema: { $ref: "#/components/schemas/OfferSignatureRequest" } } }
+        },
+        responses: {
+          200: { description: "Signed.", content: { "application/json": { schema: { $ref: "#/components/schemas/OfferSignatureResponse" } } } },
+          400: err("Missing/invalid body fields or apple.bundleId not configured (INVALID_INPUT / APPLE_CONFIG_MISSING)."),
+          401: err("Offer secret missing or wrong (UNAUTHORIZED).")
+        }
       }
     }
   },
   components: {
     schemas: {
+      ErrorResponse: {
+        type: "object",
+        required: ["error", "errorCode"],
+        description: "Canonical error body \u2014 every onesub 4xx/5xx carries it. Some routes append shape-compat fields (e.g. `valid: false`, `subscription: null`, `purchases: []`).",
+        properties: {
+          error: { type: "string", description: "Human-readable message." },
+          errorCode: { type: "string", enum: Object.values(shared.ONESUB_ERROR_CODE), description: "Machine-readable canonical code." }
+        }
+      },
       ValidateRequest: {
         type: "object",
         required: ["userId", "platform", "productId", "receipt"],
@@ -3279,6 +3627,31 @@ var ONESUB_OPENAPI = {
           purchase: { $ref: "#/components/schemas/PurchaseInfo" }
         }
       },
+      ValidatePurchaseRequest: {
+        type: "object",
+        required: ["userId", "platform", "productId", "receipt", "type"],
+        properties: {
+          userId: { type: "string" },
+          platform: { type: "string", enum: ["apple", "google"] },
+          productId: { type: "string" },
+          receipt: { type: "string", description: "Apple JWS or Google purchaseToken" },
+          type: { type: "string", enum: ["consumable", "non_consumable"] }
+        }
+      },
+      ValidatePurchaseResponse: {
+        type: "object",
+        properties: {
+          valid: { type: "boolean" },
+          purchase: { $ref: "#/components/schemas/PurchaseInfo" },
+          action: { type: "string", enum: ["new", "restored"], description: 'Present on valid:true \u2014 "restored" means the transactionId was already recorded (idempotent retry or reassignment).' }
+        }
+      },
+      PurchaseStatusResponse: {
+        type: "object",
+        properties: {
+          purchases: { type: "array", items: { $ref: "#/components/schemas/PurchaseInfo" } }
+        }
+      },
       StatusResponse: {
         type: "object",
         properties: {
@@ -3310,6 +3683,106 @@ var ONESUB_OPENAPI = {
           quantity: { type: "integer" },
           purchasedAt: { type: "string", format: "date-time" }
         }
+      },
+      EntitlementStatus: {
+        type: "object",
+        required: ["active", "source"],
+        properties: {
+          active: { type: "boolean" },
+          source: { type: ["string", "null"], enum: ["subscription", "purchase", null], description: "Where the entitlement came from when active; null when not active." },
+          productId: { type: "string", description: "Matched productId (only when active)." },
+          expiresAt: { type: "string", format: "date-time", description: 'Only when source === "subscription".' }
+        }
+      },
+      EntitlementResponse: {
+        allOf: [
+          { $ref: "#/components/schemas/EntitlementStatus" },
+          { type: "object", required: ["id"], properties: { id: { type: "string", description: "The entitlement id queried, echoed back." } } }
+        ]
+      },
+      EntitlementsResponse: {
+        type: "object",
+        properties: {
+          entitlements: { type: "object", additionalProperties: { $ref: "#/components/schemas/EntitlementStatus" } }
+        }
+      },
+      ListSubscriptionsResponse: {
+        type: "object",
+        properties: {
+          items: { type: "array", items: { $ref: "#/components/schemas/SubscriptionInfo" } },
+          total: { type: "integer", description: "Total matches before limit/offset." },
+          limit: { type: "integer" },
+          offset: { type: "integer" }
+        }
+      },
+      CustomerProfileResponse: {
+        type: "object",
+        properties: {
+          userId: { type: "string" },
+          subscriptions: { type: "array", items: { $ref: "#/components/schemas/SubscriptionInfo" } },
+          purchases: { type: "array", items: { $ref: "#/components/schemas/PurchaseInfo" } },
+          entitlements: { type: "object", additionalProperties: { $ref: "#/components/schemas/EntitlementStatus" }, description: "Omitted when the server has no entitlements config." }
+        }
+      },
+      GrantPurchaseRequest: {
+        type: "object",
+        required: ["userId", "productId", "platform"],
+        properties: {
+          userId: { type: "string" },
+          productId: { type: "string" },
+          platform: { type: "string", enum: ["apple", "google"] },
+          type: { type: "string", enum: ["consumable", "non_consumable"], default: "non_consumable" },
+          transactionId: { type: "string", description: "Auto-generated `admin_grant_*` id when omitted." }
+        }
+      },
+      MetricsActiveResponse: {
+        type: "object",
+        properties: {
+          total: { type: "integer", description: "Active subs + grace_period subs + non-consumable owners." },
+          activeSubscriptions: { type: "integer" },
+          gracePeriodSubscriptions: { type: "integer" },
+          nonConsumablePurchases: { type: "integer" },
+          byProduct: { type: "object", additionalProperties: { type: "integer" }, description: "Subscription product distribution (subs only)." },
+          byProductPurchases: { type: "object", additionalProperties: { type: "integer" }, description: "Non-consumable purchase distribution." },
+          byPlatform: { type: "object", additionalProperties: { type: "integer" } }
+        }
+      },
+      MetricsBucket: {
+        type: "object",
+        properties: {
+          date: { type: "string", description: "UTC calendar day, YYYY-MM-DD." },
+          count: { type: "integer" }
+        }
+      },
+      MetricsCountResponse: {
+        type: "object",
+        properties: {
+          from: { type: "string", format: "date-time" },
+          to: { type: "string", format: "date-time" },
+          total: { type: "integer" },
+          byProduct: { type: "object", additionalProperties: { type: "integer" } },
+          byPlatform: { type: "object", additionalProperties: { type: "integer" } },
+          buckets: { type: "array", items: { $ref: "#/components/schemas/MetricsBucket" }, description: "Only present with ?groupBy=day \u2014 zero-filled, sorted ascending." }
+        }
+      },
+      OfferSignatureRequest: {
+        type: "object",
+        required: ["productId", "offerId", "applicationUsername"],
+        properties: {
+          productId: { type: "string" },
+          offerId: { type: "string", description: "Promotional offer id defined in App Store Connect." },
+          applicationUsername: { type: "string", description: "Unique per-request UUID (the nonce seed)." }
+        }
+      },
+      OfferSignatureResponse: {
+        type: "object",
+        required: ["keyId", "nonce", "timestamp", "signature"],
+        properties: {
+          keyId: { type: "string" },
+          nonce: { type: "string" },
+          timestamp: { type: "integer", description: "Milliseconds since epoch." },
+          signature: { type: "string", description: "Base64 ES256 signature for StoreKit." }
+        }
       }
     },
     securitySchemes: {
@@ -3359,10 +3832,10 @@ async function withSpan(name, attributes, fn) {
       const result = await fn(span);
       span.setStatus({ code: 1 });
       return result;
-    } catch (err) {
-      span.recordException(err);
-      span.setStatus({ code: 2, message: err.message });
-      throw err;
+    } catch (err2) {
+      span.recordException(err2);
+      span.setStatus({ code: 2, message: err2.message });
+      throw err2;
     } finally {
       span.end();
     }
@@ -3384,7 +3857,7 @@ function createOneSubMiddleware(config) {
   router.use(express__default.default.json({ limit: "50kb" }));
   router.use(createValidateRouter(config, store));
   router.use(createStatusRouter(store));
-  router.use(createWebhookRouter(config, store, purchaseStore, config.webhookEventStore));
+  router.use(createWebhookRouter(config, store, purchaseStore, config.webhookEventStore, config.webhookQueue));
   router.use(createPurchaseRouter(config, purchaseStore));
   const adminRouter = createAdminRouter(config, purchaseStore, store, config.webhookQueue);
   if (adminRouter) router.use(adminRouter);
@@ -3451,9 +3924,12 @@ exports.fetchAppleTransactionHistory = fetchAppleTransactionHistory;
 exports.getDefaultCache = getDefaultCache;
 exports.log = log;
 exports.openapiHandler = openapiHandler;
+exports.processAppleNotification = processAppleNotification;
+exports.processGoogleNotification = processGoogleNotification;
 exports.setDefaultCache = setDefaultCache;
 exports.setLogger = setLogger;
 exports.signApplePromotionalOffer = signApplePromotionalOffer;
+exports.unmarkWebhookEvent = unmarkWebhookEvent;
 exports.validateAppleReceipt = validateAppleReceipt;
 exports.validateGoogleReceipt = validateGoogleReceipt;
 exports.withSpan = withSpan;