@waffo/pancake-ts 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -8,10 +8,13 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), version
 
 ### Added
 
-- **Custom webhook public key** — `WaffoPancakeConfig` accepts optional `webhookPublicKey` to override built-in Waffo public keys for webhook signature verification. Useful for self-hosted deployments or custom key rotation.
-- **`client.webhooks.verify()`** — New resource namespace on the client instance. Uses the configured `webhookPublicKey` automatically; supports per-call override via `options.publicKey`.
-- **`VerifyWebhookOptions.publicKey`** — The standalone `verifyWebhook()` function also accepts a custom public key per call, taking precedence over built-in keys and the `environment` option.
-- **Public key normalization** — `normalizePublicKey()` handles the same flexible input formats as `normalizePrivateKey`: literal `\n` from environment variables, Windows `\r\n` line endings, raw base64 without PEM headers, single-line base64, and PKCS#1 (`BEGIN RSA PUBLIC KEY`) format. Applied automatically when a custom public key is used.
+- **Custom webhook public key** — `WaffoPancakeConfig.webhookPublicKey` accepts `string` (shared) or `{ test?, prod? }` (per-environment) to override built-in keys.
+- **Multi-level key resolution** — Webhook public key is resolved per environment: `options.publicKey` (per-call) → config key → `WAFFO_WEBHOOK_{TEST|PROD}_PUBLIC_KEY` env var → `WAFFO_WEBHOOK_PUBLIC_KEY` env var → built-in hardcoded key.
+- **`client.webhooks.verify()`** — New resource namespace on the client instance. Injects config-level keys into the resolution chain automatically; supports per-call override via `options.publicKey`.
+- **`VerifyWebhookOptions.publicKey`** — Per-call override for the standalone `verifyWebhook()` function (highest priority, skips all resolution).
+- **`VerifyWebhookOptions.publicKeys`** — Config-level key(s) for the resolution chain (typically injected by `client.webhooks.verify()`).
+- **`WebhookPublicKeys` type** — `string | { test?: string; prod?: string }`, exported from the package.
+- **Public key normalization** — `normalizePublicKey()` handles the same flexible input formats as `normalizePrivateKey`: literal `\n` from environment variables, Windows `\r\n` line endings, raw base64 without PEM headers, single-line base64, and PKCS#1 (`BEGIN RSA PUBLIC KEY`) format. Applied automatically at every level of the resolution chain.
 
 ## [0.1.6] - 2026-03-18
 

package/README.md

@@ -59,7 +59,7 @@ const result = await client.graphql.query<{ stores: Array<{ id: string; name: st
 | `privateKey` | `string` | Yes | RSA private key (see [Private Key Formats](#private-key-formats) below) |
 | `baseUrl` | `string` | No | API base URL (default: `https://waffo-pancake-auth-service.vercel.app`) |
 | `fetch` | `typeof fetch` | No | Custom fetch implementation |
-| `webhookPublicKey` | `string` | No | Custom RSA public key for webhook verification (see [Public Key Formats](#public-key-formats) below). Overrides built-in keys when set. |
+| `webhookPublicKey` | `string \| { test?, prod? }` | No | Custom webhook public key(s) (see [Webhook Public Key Resolution](#webhook-public-key-resolution) below) |
 
 ### Private Key Formats
 
@@ -83,9 +83,43 @@ new WaffoPancake({ merchantId: "m_1", privateKey: fs.readFileSync("key.pem", "ut
 new WaffoPancake({ merchantId: "m_1", privateKey: rawBase64String });                   // raw base64
 ```
 
+### Webhook Public Key Resolution
+
+The SDK resolves the webhook verification public key per environment using a multi-level fallback chain:
+
+| Priority | Source | Description |
+|----------|--------|-------------|
+| 1 | `options.publicKey` | Per-call override (highest priority, skips all resolution) |
+| 2 | `config.webhookPublicKey[env]` | Config object per-environment key |
+| 3 | `config.webhookPublicKey` (string) | Config shared key (both environments) |
+| 4 | `WAFFO_WEBHOOK_TEST_PUBLIC_KEY` / `WAFFO_WEBHOOK_PROD_PUBLIC_KEY` | Environment variable per-environment |
+| 5 | `WAFFO_WEBHOOK_PUBLIC_KEY` | Environment variable shared |
+| 6 | Built-in hardcoded key | SDK-embedded Waffo public key (default) |
+
+```typescript
+// Shared key for both environments
+new WaffoPancake({ merchantId: "m_1", privateKey: "...", webhookPublicKey: "MIIBIjAN..." });
+
+// Per-environment keys
+new WaffoPancake({
+  merchantId: "m_1",
+  privateKey: "...",
+  webhookPublicKey: {
+    test: process.env.WAFFO_TEST_PUB_KEY!,
+    prod: process.env.WAFFO_PROD_PUB_KEY!,
+  },
+});
+
+// Or rely on environment variables (no config needed)
+// export WAFFO_WEBHOOK_TEST_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n..."
+// export WAFFO_WEBHOOK_PROD_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n..."
+new WaffoPancake({ merchantId: "m_1", privateKey: "..." });
+// => SDK auto-reads from env vars, falls back to built-in keys
+```
+
 ### Public Key Formats
 
-The `webhookPublicKey` option (and the `publicKey` field in `VerifyWebhookOptions`) accepts the same flexible formats as private keys:
+All public key inputs (config, env vars, per-call) accept the same flexible formats as private keys:
 
 | Format | Example | Notes |
 |--------|---------|-------|
@@ -462,33 +496,34 @@ const event = verifyWebhook(body, sig, { environment: "prod" });
 const event = verifyWebhook(body, sig, { toleranceMs: 0 }); // disable replay check
 ```
 
-### Option B — Client Instance Method (custom public key)
+### Option B — Client Instance Method (multi-level key resolution)
 
-When you provide a `webhookPublicKey` in the client config, `client.webhooks.verify()` uses that key automatically. Useful for self-hosted deployments or custom key rotation.
+`client.webhooks.verify()` uses the [multi-level fallback chain](#webhook-public-key-resolution) automatically: config keys → env vars → built-in keys.
 
 ```typescript
+// Per-environment keys via config
 const client = new WaffoPancake({
   merchantId: process.env.WAFFO_MERCHANT_ID!,
   privateKey: process.env.WAFFO_PRIVATE_KEY!,
-  webhookPublicKey: process.env.WAFFO_WEBHOOK_PUBLIC_KEY!, // any format accepted
+  webhookPublicKey: {
+    test: process.env.WAFFO_TEST_PUB_KEY!,
+    prod: process.env.WAFFO_PROD_PUB_KEY!,
+  },
 });
+const event = client.webhooks.verify(rawBody, sig, { environment: "prod" });
 
-// Uses the configured public key — no need to pass it per call
-const event = client.webhooks.verify(rawBody, signatureHeader);
-
-// You can still override per call if needed
-const event = client.webhooks.verify(rawBody, sig, { publicKey: anotherKey });
-```
-
-### Standalone Function with Custom Key
-
-You can also pass a custom key directly to the standalone function without creating a client:
+// Or rely on env vars (WAFFO_WEBHOOK_TEST_PUBLIC_KEY / WAFFO_WEBHOOK_PROD_PUBLIC_KEY)
+const client2 = new WaffoPancake({
+  merchantId: process.env.WAFFO_MERCHANT_ID!,
+  privateKey: process.env.WAFFO_PRIVATE_KEY!,
+});
+const event2 = client2.webhooks.verify(rawBody, sig); // auto-detect environment
 
-```typescript
-const event = verifyWebhook(body, sig, { publicKey: process.env.MY_PUBLIC_KEY! });
+// Per-call override (highest priority, skips all resolution)
+const event3 = client.webhooks.verify(rawBody, sig, { publicKey: oneOffKey });
 ```
 
-See [Webhook Guide](docs/webhook-guide.md) for all 10 event types, signature algorithm, and best practices.
+See [Webhook Guide](docs/webhook-guide.md) for event types, signature algorithm, public key resolution, and best practices.
 
 ## Error Handling
 
@@ -547,7 +582,7 @@ Runtime-accessible values. Both `Enum.Value` and string literal syntax are suppo
 
 ### Types
 
-See [API Reference — Types](docs/api-reference.md#types) for the full list of 40+ exported interfaces.
+Key types: `WaffoPancakeConfig`, `WebhookPublicKeys`, `VerifyWebhookOptions`, `WebhookEvent<T>`, `Store`, `OnetimeProductDetail`, `SubscriptionProductDetail`, `CheckoutSessionResult`, `GraphQLResponse<T>`, and 30+ more. See [API Reference — Types](docs/api-reference.md#types) for the full list.
 
 ## Development
 

package/dist/index.cjs

@@ -654,6 +654,23 @@ function rsaVerify(signatureInput, v1, publicKey) {
   verifier.update(signatureInput);
   return verifier.verify(publicKey, v1, "base64");
 }
+function resolveKeyForEnv(env, configKeys) {
+  if (typeof configKeys === "string") {
+    return normalizePublicKey(configKeys);
+  }
+  if (configKeys?.[env]) {
+    return normalizePublicKey(configKeys[env]);
+  }
+  const envSpecific = env === "test" ? process.env.WAFFO_WEBHOOK_TEST_PUBLIC_KEY : process.env.WAFFO_WEBHOOK_PROD_PUBLIC_KEY;
+  if (envSpecific) {
+    return normalizePublicKey(envSpecific);
+  }
+  const generic = process.env.WAFFO_WEBHOOK_PUBLIC_KEY;
+  if (generic) {
+    return normalizePublicKey(generic);
+  }
+  return env === "test" ? TEST_PUBLIC_KEY : PROD_PUBLIC_KEY;
+}
 function verifyWebhook(payload, signatureHeader, options) {
   if (!signatureHeader) {
     throw new Error("Missing X-Waffo-Signature header");
@@ -673,27 +690,25 @@ function verifyWebhook(payload, signatureHeader, options) {
     }
   }
   const signatureInput = `${t}.${payload}`;
-  const customKey = options?.publicKey;
-  if (customKey) {
-    const normalizedKey = normalizePublicKey(customKey);
+  const directKey = options?.publicKey;
+  if (directKey) {
+    const normalizedKey = normalizePublicKey(directKey);
     if (!rsaVerify(signatureInput, v1, normalizedKey)) {
       throw new Error("Invalid webhook signature (custom key)");
     }
   } else {
+    const configKeys = options?.publicKeys;
     const env = options?.environment;
-    if (env === "test") {
-      if (!rsaVerify(signatureInput, v1, TEST_PUBLIC_KEY)) {
-        throw new Error("Invalid webhook signature (test key)");
-      }
-    } else if (env === "prod") {
-      if (!rsaVerify(signatureInput, v1, PROD_PUBLIC_KEY)) {
-        throw new Error("Invalid webhook signature (prod key)");
+    if (env === "test" || env === "prod") {
+      const key = resolveKeyForEnv(env, configKeys);
+      if (!rsaVerify(signatureInput, v1, key)) {
+        throw new Error(`Invalid webhook signature (${env} key)`);
       }
     } else {
-      const prodValid = rsaVerify(signatureInput, v1, PROD_PUBLIC_KEY);
-      if (!prodValid) {
-        const testValid = rsaVerify(signatureInput, v1, TEST_PUBLIC_KEY);
-        if (!testValid) {
+      const prodKey = resolveKeyForEnv("prod", configKeys);
+      if (!rsaVerify(signatureInput, v1, prodKey)) {
+        const testKey = resolveKeyForEnv("test", configKeys);
+        if (!rsaVerify(signatureInput, v1, testKey)) {
           throw new Error("Invalid webhook signature (tried both prod and test keys)");
         }
       }
@@ -704,15 +719,19 @@ function verifyWebhook(payload, signatureHeader, options) {
 
 // src/resources/webhooks.ts
 var WebhooksResource = class {
-  /** @param publicKey - Optional custom RSA public key (PEM or raw base64) */
-  constructor(publicKey) {
-    this.publicKey = publicKey;
+  /** @param publicKeys - Optional config-level public key(s) from WaffoPancakeConfig */
+  constructor(publicKeys) {
+    this.publicKeys = publicKeys;
   }
   /**
    * Verify and parse an incoming webhook event.
    *
-   * When the client was created with a `webhookPublicKey`, that key is used
-   * automatically. You can still override per-call via `options.publicKey`.
+   * Key resolution order:
+   * 1. `options.publicKey` — per-call override (highest priority)
+   * 2. `config.webhookPublicKey[env]` or `config.webhookPublicKey` (string)
+   * 3. `WAFFO_WEBHOOK_{TEST|PROD}_PUBLIC_KEY` environment variable
+   * 4. `WAFFO_WEBHOOK_PUBLIC_KEY` environment variable
+   * 5. Built-in hardcoded key
    *
    * @param payload - Raw request body string (must be unparsed)
    * @param signatureHeader - Value of the `X-Waffo-Signature` header
@@ -724,13 +743,17 @@ var WebhooksResource = class {
    * const event = client.webhooks.verify(rawBody, signatureHeader);
    *
    * @example
-   * // Override tolerance per call
-   * const event = client.webhooks.verify(rawBody, sig, { toleranceMs: 0 });
+   * // Specify environment
+   * const event = client.webhooks.verify(rawBody, sig, { environment: "test" });
+   *
+   * @example
+   * // Per-call key override
+   * const event = client.webhooks.verify(rawBody, sig, { publicKey: oneOffKey });
    */
   verify(payload, signatureHeader, options) {
     const mergedOptions = {
       ...options,
-      publicKey: options?.publicKey ?? this.publicKey
+      publicKeys: options?.publicKeys ?? this.publicKeys
     };
     return verifyWebhook(payload, signatureHeader, mergedOptions);
   }