@polar-sh/sdk 1.0.0-alpha.11 → 1.0.0-alpha.13

package/README.md

@@ -4,14 +4,16 @@ The official TypeScript client for the [Polar API](https://polar.sh/docs/api-ref
 
 ## Installation
 
+The SDK is currently available under the `next` pre-release tag.
+
 ```bash
-pnpm add @polar-sh/sdk
+pnpm add @polar-sh/sdk@next
 ```
 
 or, with `npm`:
 
 ```bash
-npm install @polar-sh/sdk
+npm install @polar-sh/sdk@next
 ```
 
 ## Quick Start
@@ -52,3 +54,57 @@ const polar = createPolarCore({
 const customerState = await getStateExternalCustomers(polar)("customer_external_id");
 console.log(customerState);
 ```
+
+## Webhooks
+
+Use `webhooks.validateEvent` to verify that a webhook was sent by Polar and parse it into a typed
+payload for the selected API version. Pass the raw request body, the request headers, and your
+webhook signing secret:
+
+```typescript
+import express from "express";
+import { webhooks } from "@polar-sh/sdk/2026-04";
+
+const app = express();
+const webhookSecret = process.env.POLAR_WEBHOOK_SECRET;
+
+if (!webhookSecret) {
+    throw new Error("POLAR_WEBHOOK_SECRET is required");
+}
+
+const rawBody = express.raw({ type: "application/json" });
+app.post("/webhooks/polar", rawBody, async (request, response) => {
+    try {
+        const event = await webhooks.validateEvent(
+            request.body,
+            {
+                "webhook-id": request.header("webhook-id") ?? "",
+                "webhook-timestamp": request.header("webhook-timestamp") ?? "",
+                "webhook-signature": request.header("webhook-signature") ?? "",
+            },
+            webhookSecret,
+        );
+
+        if (event.type === "order.created") {
+            console.log(event.data.id);
+        }
+
+        response.status(200).json({ received: true });
+    } catch (error) {
+        if (error instanceof webhooks.PolarWebhookVerificationError) {
+            response.status(403).json({ error: "Invalid webhook signature" });
+            return;
+        }
+        if (error instanceof webhooks.PolarWebhookError) {
+            response.status(400).json({ error: "Invalid webhook payload" });
+            return;
+        }
+        throw error;
+    }
+});
+```
+
+The `express.raw` middleware is required because the signature must be checked against the body
+before it is parsed. `validateEvent` throws `PolarWebhookVerificationError` for invalid signatures
+and `PolarWebhookUnknownTypeError` when the event is not supported by the selected API version.
+Both inherit from `PolarWebhookError`.

package/dist/2026-04/index.cjs

@@ -76,6 +76,132 @@ function createPolar(options) {
 //#region src/2026-04/models.ts
 var models_exports = /* @__PURE__ */ require_errors.__exportAll({});
 //#endregion
+//#region src/webhooks.ts
+const webhookToleranceSeconds = 300;
+var PolarWebhookError = class extends require_base.PolarError {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "PolarWebhookError";
+	}
+};
+var PolarWebhookVerificationError = class extends PolarWebhookError {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "PolarWebhookVerificationError";
+	}
+};
+var PolarWebhookUnknownTypeError = class extends PolarWebhookError {
+	eventType;
+	constructor(eventType) {
+		super(`Unknown webhook event type: ${JSON.stringify(eventType)}`);
+		this.eventType = eventType;
+		this.name = "PolarWebhookUnknownTypeError";
+	}
+};
+const validateWebhook = async (body, headers, secret, eventTypes) => {
+	const bodyText = typeof body === "string" ? body : new TextDecoder().decode(body);
+	await verifySignature(bodyText, headers, secret);
+	let parsed;
+	try {
+		parsed = JSON.parse(bodyText);
+	} catch (error) {
+		throw new PolarWebhookError("Failed to parse webhook payload", { cause: error });
+	}
+	const eventType = typeof parsed === "object" && parsed !== null && "type" in parsed && typeof parsed.type === "string" ? parsed.type : null;
+	if (eventType === null || !eventTypes.has(eventType)) throw new PolarWebhookUnknownTypeError(eventType);
+	return parsed;
+};
+const verifySignature = async (body, headers, secret) => {
+	if (secret.length === 0) throw new PolarWebhookVerificationError("Secret can't be empty");
+	const normalizedHeaders = Object.fromEntries(Object.entries(headers).map(([key, value]) => [key.toLowerCase(), value]));
+	const webhookId = normalizedHeaders["webhook-id"];
+	const webhookTimestamp = normalizedHeaders["webhook-timestamp"];
+	const webhookSignature = normalizedHeaders["webhook-signature"];
+	if (!webhookId || !webhookTimestamp || !webhookSignature) throw new PolarWebhookVerificationError("Missing required headers");
+	const timestamp = Number(webhookTimestamp);
+	if (!Number.isFinite(timestamp)) throw new PolarWebhookVerificationError("Invalid signature headers");
+	const now = Date.now() / 1e3;
+	if (timestamp < now - webhookToleranceSeconds) throw new PolarWebhookVerificationError("Message timestamp too old");
+	if (timestamp > now + webhookToleranceSeconds) throw new PolarWebhookVerificationError("Message timestamp too new");
+	const signedContent = `${webhookId}.${Math.floor(timestamp)}.${body}`;
+	const textEncoder = new TextEncoder();
+	const signedContentBytes = textEncoder.encode(signedContent);
+	const signingKey = await globalThis.crypto.subtle.importKey("raw", textEncoder.encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["verify"]);
+	for (const versionedSignature of webhookSignature.split(" ")) {
+		const [version, signature] = versionedSignature.split(",", 2);
+		if (version !== "v1" || signature === void 0) continue;
+		const decodedSignature = decodeBase64(signature);
+		if (decodedSignature !== null && await globalThis.crypto.subtle.verify("HMAC", signingKey, decodedSignature, signedContentBytes)) return;
+	}
+	throw new PolarWebhookVerificationError("No matching signature found");
+};
+const decodeBase64 = (value) => {
+	try {
+		const decodedValue = globalThis.atob(value);
+		const bytes = new Uint8Array(new ArrayBuffer(decodedValue.length));
+		for (let index = 0; index < decodedValue.length; index++) bytes[index] = decodedValue.charCodeAt(index);
+		return bytes;
+	} catch {
+		return null;
+	}
+};
+//#endregion
+//#region src/2026-04/webhooks.ts
+var webhooks_exports = /* @__PURE__ */ require_errors.__exportAll({
+	PolarWebhookError: () => PolarWebhookError,
+	PolarWebhookUnknownTypeError: () => PolarWebhookUnknownTypeError,
+	PolarWebhookVerificationError: () => PolarWebhookVerificationError,
+	validateEvent: () => validateEvent
+});
+const knownEventTypes = /* @__PURE__ */ new Set([
+	"benefit.created",
+	"benefit.updated",
+	"benefit_grant.created",
+	"benefit_grant.cycled",
+	"benefit_grant.revoked",
+	"benefit_grant.updated",
+	"checkout.created",
+	"checkout.expired",
+	"checkout.updated",
+	"customer.created",
+	"customer.deleted",
+	"customer.state_changed",
+	"customer.updated",
+	"customer_seat.assigned",
+	"customer_seat.claimed",
+	"customer_seat.revoked",
+	"member.created",
+	"member.deleted",
+	"member.updated",
+	"order.created",
+	"order.paid",
+	"order.refunded",
+	"order.updated",
+	"organization.updated",
+	"product.created",
+	"product.updated",
+	"refund.created",
+	"refund.updated",
+	"subscription.active",
+	"subscription.canceled",
+	"subscription.created",
+	"subscription.past_due",
+	"subscription.paused",
+	"subscription.resumed",
+	"subscription.revoked",
+	"subscription.uncanceled",
+	"subscription.updated"
+]);
+/**
+* Verify a raw Polar webhook request and return its typed payload.
+*/
+const validateEvent = (body, headers, secret) => {
+	return validateWebhook(body, headers, secret, knownEventTypes);
+};
+//#endregion
 exports.createPolar = createPolar;
 exports.createPolarCore = createPolarCore;
 Object.defineProperty(exports, "errors", {
@@ -90,5 +216,11 @@ Object.defineProperty(exports, "models", {
 		return models_exports;
 	}
 });
+Object.defineProperty(exports, "webhooks", {
+	enumerable: true,
+	get: function() {
+		return webhooks_exports;
+	}
+});
 
 //# sourceMappingURL=index.cjs.map