recur-tw 0.15.0 → 0.16.0

package/dist/server.cjs

@@ -1,5 +1,11 @@
 'use strict';
 
+var crypto = require('crypto');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var crypto__default = /*#__PURE__*/_interopDefault(crypto);
+
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
@@ -21,6 +27,12 @@ var RecurAPIError = class extends Error {
     this.details = error.details;
   }
 };
+var WebhookSignatureVerificationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "WebhookSignatureVerificationError";
+  }
+};
 
 // package.json
 var package_default = {
@@ -277,6 +289,80 @@ var Entitlements = class {
     return { entitlements };
   }
 };
+var Webhooks = class {
+  // Accept config for consistency with other resources (future API methods)
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  constructor(_config) {
+  }
+  /**
+   * Verify a webhook signature and return the parsed event
+   *
+   * @param payload - The raw request body as a string (use `await request.text()`, NOT `JSON.stringify(await request.json())`)
+   * @param signature - The value of the `X-Recur-Signature` header
+   * @param secret - The webhook signing secret from your dashboard
+   * @returns The parsed webhook event
+   * @throws {WebhookSignatureVerificationError} If the signature is missing or invalid
+   *
+   * @example
+   * ```typescript
+   * import { Recur } from 'recur-tw/server';
+   *
+   * const recur = new Recur(process.env.RECUR_SECRET_KEY!);
+   *
+   * export async function POST(request: Request) {
+   *   const payload = await request.text();
+   *   const signature = request.headers.get('x-recur-signature');
+   *
+   *   try {
+   *     const event = recur.webhooks.verify(
+   *       payload,
+   *       signature,
+   *       process.env.RECUR_WEBHOOK_SECRET!,
+   *     );
+   *     // Handle event based on event.type
+   *     switch (event.type) {
+   *       case 'checkout.completed':
+   *         break;
+   *       case 'subscription.cancelled':
+   *         break;
+   *     }
+   *     return new Response('OK', { status: 200 });
+   *   } catch (err) {
+   *     return new Response('Invalid signature', { status: 401 });
+   *   }
+   * }
+   * ```
+   */
+  verify(payload, signature, secret) {
+    if (!signature) {
+      throw new WebhookSignatureVerificationError(
+        "Missing webhook signature. Expected the `X-Recur-Signature` header."
+      );
+    }
+    if (!secret) {
+      throw new WebhookSignatureVerificationError(
+        "Missing webhook secret. Pass your webhook signing secret as the third argument."
+      );
+    }
+    const expectedSignature = crypto__default.default.createHmac("sha256", secret).update(payload).digest("base64");
+    let isValid;
+    try {
+      isValid = crypto__default.default.timingSafeEqual(
+        Buffer.from(signature),
+        Buffer.from(expectedSignature)
+      );
+    } catch {
+      isValid = false;
+    }
+    if (!isValid) {
+      throw new WebhookSignatureVerificationError(
+        "Webhook signature verification failed. Ensure you are using the raw request body and the correct signing secret."
+      );
+    }
+    const event = JSON.parse(payload);
+    return event;
+  }
+};
 
 // src/server/recur.ts
 var Recur = class {
@@ -292,6 +378,19 @@ var Recur = class {
      * Portal resource for managing customer portal sessions
      */
     __publicField(this, "portal");
+    /**
+     * Webhooks resource for verifying webhook signatures
+     *
+     * @example
+     * ```typescript
+     * const event = recur.webhooks.verify(
+     *   payload,
+     *   signature,
+     *   process.env.RECUR_WEBHOOK_SECRET!,
+     * );
+     * ```
+     */
+    __publicField(this, "webhooks");
     /**
      * Entitlements resource for checking customer subscription access
      *
@@ -325,9 +424,11 @@ var Recur = class {
       baseUrl: options?.baseUrl || "https://api.recur.tw"
     };
     this.portal = new Portal(this.config);
+    this.webhooks = new Webhooks(this.config);
     this.entitlements = new Entitlements(this.config);
   }
 };
 
 exports.Recur = Recur;
 exports.RecurAPIError = RecurAPIError;
+exports.WebhookSignatureVerificationError = WebhookSignatureVerificationError;

package/dist/server.d.cts

@@ -250,6 +250,40 @@ interface EntitlementListResult {
      */
     entitlements: Entitlement[];
 }
+/**
+ * Known webhook event types
+ *
+ * Uses a union with `(string & {})` to allow unknown event types
+ * while still providing autocomplete for known ones.
+ */
+type WebhookEventType = 'checkout.completed' | 'subscription.created' | 'subscription.activated' | 'subscription.updated' | 'subscription.cancelled' | 'subscription.expired' | 'subscription.trial_ending' | 'subscription.payment_failed' | 'invoice.created' | 'invoice.paid' | 'invoice.payment_failed' | 'invoice.refunded' | 'customer.created' | 'customer.updated' | 'order.paid' | (string & {});
+/**
+ * A webhook event received from Recur
+ */
+interface WebhookEvent {
+    /**
+     * Unique event identifier
+     */
+    id: string;
+    /**
+     * Event type
+     */
+    type: WebhookEventType;
+    /**
+     * ISO 8601 timestamp of when the event was created
+     */
+    timestamp: string;
+    /**
+     * Event-specific data payload
+     */
+    data: Record<string, unknown>;
+}
+/**
+ * Error thrown when webhook signature verification fails
+ */
+declare class WebhookSignatureVerificationError extends Error {
+    constructor(message: string);
+}
 
 /**
  * Portal Sessions Resource
@@ -415,6 +449,57 @@ declare class Entitlements {
     list(options: EntitlementListOptions): Promise<EntitlementListResult>;
 }
 
+/**
+ * Webhooks Resource
+ *
+ * Provides webhook signature verification for securing webhook endpoints.
+ * Uses HMAC-SHA256 with Base64 encoding, matching the Recur webhook infrastructure.
+ */
+
+declare class Webhooks {
+    constructor(_config: RecurConfig);
+    /**
+     * Verify a webhook signature and return the parsed event
+     *
+     * @param payload - The raw request body as a string (use `await request.text()`, NOT `JSON.stringify(await request.json())`)
+     * @param signature - The value of the `X-Recur-Signature` header
+     * @param secret - The webhook signing secret from your dashboard
+     * @returns The parsed webhook event
+     * @throws {WebhookSignatureVerificationError} If the signature is missing or invalid
+     *
+     * @example
+     * ```typescript
+     * import { Recur } from 'recur-tw/server';
+     *
+     * const recur = new Recur(process.env.RECUR_SECRET_KEY!);
+     *
+     * export async function POST(request: Request) {
+     *   const payload = await request.text();
+     *   const signature = request.headers.get('x-recur-signature');
+     *
+     *   try {
+     *     const event = recur.webhooks.verify(
+     *       payload,
+     *       signature,
+     *       process.env.RECUR_WEBHOOK_SECRET!,
+     *     );
+     *     // Handle event based on event.type
+     *     switch (event.type) {
+     *       case 'checkout.completed':
+     *         break;
+     *       case 'subscription.cancelled':
+     *         break;
+     *     }
+     *     return new Response('OK', { status: 200 });
+     *   } catch (err) {
+     *     return new Response('Invalid signature', { status: 401 });
+     *   }
+     * }
+     * ```
+     */
+    verify(payload: string, signature: string | null, secret: string): WebhookEvent;
+}
+
 /**
  * Recur Server SDK
  *
@@ -441,6 +526,19 @@ declare class Recur {
      * Portal resource for managing customer portal sessions
      */
     readonly portal: Portal;
+    /**
+     * Webhooks resource for verifying webhook signatures
+     *
+     * @example
+     * ```typescript
+     * const event = recur.webhooks.verify(
+     *   payload,
+     *   signature,
+     *   process.env.RECUR_WEBHOOK_SECRET!,
+     * );
+     * ```
+     */
+    readonly webhooks: Webhooks;
     /**
      * Entitlements resource for checking customer subscription access
      *
@@ -468,4 +566,4 @@ declare class Recur {
     constructor(secretKey: string, options?: Omit<RecurConfig, 'secretKey'>);
 }
 
-export { type ApiErrorCode, type CustomerIdentifier, type DuplicateSubscriptionDetails, type Entitlement, type EntitlementCheckOptions, type EntitlementCheckResult, type EntitlementListOptions, type EntitlementListResult, type EntitlementStatus, type EntitlementSubscription, type PortalSession, type PortalSessionCreateParams, Recur, RecurAPIError, type RecurConfig, type RecurError };
+export { type ApiErrorCode, type CustomerIdentifier, type DuplicateSubscriptionDetails, type Entitlement, type EntitlementCheckOptions, type EntitlementCheckResult, type EntitlementListOptions, type EntitlementListResult, type EntitlementStatus, type EntitlementSubscription, type PortalSession, type PortalSessionCreateParams, Recur, RecurAPIError, type RecurConfig, type RecurError, type WebhookEvent, type WebhookEventType, WebhookSignatureVerificationError };

package/dist/server.d.ts

@@ -250,6 +250,40 @@ interface EntitlementListResult {
      */
     entitlements: Entitlement[];
 }
+/**
+ * Known webhook event types
+ *
+ * Uses a union with `(string & {})` to allow unknown event types
+ * while still providing autocomplete for known ones.
+ */
+type WebhookEventType = 'checkout.completed' | 'subscription.created' | 'subscription.activated' | 'subscription.updated' | 'subscription.cancelled' | 'subscription.expired' | 'subscription.trial_ending' | 'subscription.payment_failed' | 'invoice.created' | 'invoice.paid' | 'invoice.payment_failed' | 'invoice.refunded' | 'customer.created' | 'customer.updated' | 'order.paid' | (string & {});
+/**
+ * A webhook event received from Recur
+ */
+interface WebhookEvent {
+    /**
+     * Unique event identifier
+     */
+    id: string;
+    /**
+     * Event type
+     */
+    type: WebhookEventType;
+    /**
+     * ISO 8601 timestamp of when the event was created
+     */
+    timestamp: string;
+    /**
+     * Event-specific data payload
+     */
+    data: Record<string, unknown>;
+}
+/**
+ * Error thrown when webhook signature verification fails
+ */
+declare class WebhookSignatureVerificationError extends Error {
+    constructor(message: string);
+}
 
 /**
  * Portal Sessions Resource
@@ -415,6 +449,57 @@ declare class Entitlements {
     list(options: EntitlementListOptions): Promise<EntitlementListResult>;
 }
 
+/**
+ * Webhooks Resource
+ *
+ * Provides webhook signature verification for securing webhook endpoints.
+ * Uses HMAC-SHA256 with Base64 encoding, matching the Recur webhook infrastructure.
+ */
+
+declare class Webhooks {
+    constructor(_config: RecurConfig);
+    /**
+     * Verify a webhook signature and return the parsed event
+     *
+     * @param payload - The raw request body as a string (use `await request.text()`, NOT `JSON.stringify(await request.json())`)
+     * @param signature - The value of the `X-Recur-Signature` header
+     * @param secret - The webhook signing secret from your dashboard
+     * @returns The parsed webhook event
+     * @throws {WebhookSignatureVerificationError} If the signature is missing or invalid
+     *
+     * @example
+     * ```typescript
+     * import { Recur } from 'recur-tw/server';
+     *
+     * const recur = new Recur(process.env.RECUR_SECRET_KEY!);
+     *
+     * export async function POST(request: Request) {
+     *   const payload = await request.text();
+     *   const signature = request.headers.get('x-recur-signature');
+     *
+     *   try {
+     *     const event = recur.webhooks.verify(
+     *       payload,
+     *       signature,
+     *       process.env.RECUR_WEBHOOK_SECRET!,
+     *     );
+     *     // Handle event based on event.type
+     *     switch (event.type) {
+     *       case 'checkout.completed':
+     *         break;
+     *       case 'subscription.cancelled':
+     *         break;
+     *     }
+     *     return new Response('OK', { status: 200 });
+     *   } catch (err) {
+     *     return new Response('Invalid signature', { status: 401 });
+     *   }
+     * }
+     * ```
+     */
+    verify(payload: string, signature: string | null, secret: string): WebhookEvent;
+}
+
 /**
  * Recur Server SDK
  *
@@ -441,6 +526,19 @@ declare class Recur {
      * Portal resource for managing customer portal sessions
      */
     readonly portal: Portal;
+    /**
+     * Webhooks resource for verifying webhook signatures
+     *
+     * @example
+     * ```typescript
+     * const event = recur.webhooks.verify(
+     *   payload,
+     *   signature,
+     *   process.env.RECUR_WEBHOOK_SECRET!,
+     * );
+     * ```
+     */
+    readonly webhooks: Webhooks;
     /**
      * Entitlements resource for checking customer subscription access
      *
@@ -468,4 +566,4 @@ declare class Recur {
     constructor(secretKey: string, options?: Omit<RecurConfig, 'secretKey'>);
 }
 
-export { type ApiErrorCode, type CustomerIdentifier, type DuplicateSubscriptionDetails, type Entitlement, type EntitlementCheckOptions, type EntitlementCheckResult, type EntitlementListOptions, type EntitlementListResult, type EntitlementStatus, type EntitlementSubscription, type PortalSession, type PortalSessionCreateParams, Recur, RecurAPIError, type RecurConfig, type RecurError };
+export { type ApiErrorCode, type CustomerIdentifier, type DuplicateSubscriptionDetails, type Entitlement, type EntitlementCheckOptions, type EntitlementCheckResult, type EntitlementListOptions, type EntitlementListResult, type EntitlementStatus, type EntitlementSubscription, type PortalSession, type PortalSessionCreateParams, Recur, RecurAPIError, type RecurConfig, type RecurError, type WebhookEvent, type WebhookEventType, WebhookSignatureVerificationError };

package/dist/server.js

@@ -1,3 +1,5 @@
+import crypto from 'crypto';
+
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
@@ -19,6 +21,12 @@ var RecurAPIError = class extends Error {
     this.details = error.details;
   }
 };
+var WebhookSignatureVerificationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "WebhookSignatureVerificationError";
+  }
+};
 
 // package.json
 var package_default = {
@@ -275,6 +283,80 @@ var Entitlements = class {
     return { entitlements };
   }
 };
+var Webhooks = class {
+  // Accept config for consistency with other resources (future API methods)
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  constructor(_config) {
+  }
+  /**
+   * Verify a webhook signature and return the parsed event
+   *
+   * @param payload - The raw request body as a string (use `await request.text()`, NOT `JSON.stringify(await request.json())`)
+   * @param signature - The value of the `X-Recur-Signature` header
+   * @param secret - The webhook signing secret from your dashboard
+   * @returns The parsed webhook event
+   * @throws {WebhookSignatureVerificationError} If the signature is missing or invalid
+   *
+   * @example
+   * ```typescript
+   * import { Recur } from 'recur-tw/server';
+   *
+   * const recur = new Recur(process.env.RECUR_SECRET_KEY!);
+   *
+   * export async function POST(request: Request) {
+   *   const payload = await request.text();
+   *   const signature = request.headers.get('x-recur-signature');
+   *
+   *   try {
+   *     const event = recur.webhooks.verify(
+   *       payload,
+   *       signature,
+   *       process.env.RECUR_WEBHOOK_SECRET!,
+   *     );
+   *     // Handle event based on event.type
+   *     switch (event.type) {
+   *       case 'checkout.completed':
+   *         break;
+   *       case 'subscription.cancelled':
+   *         break;
+   *     }
+   *     return new Response('OK', { status: 200 });
+   *   } catch (err) {
+   *     return new Response('Invalid signature', { status: 401 });
+   *   }
+   * }
+   * ```
+   */
+  verify(payload, signature, secret) {
+    if (!signature) {
+      throw new WebhookSignatureVerificationError(
+        "Missing webhook signature. Expected the `X-Recur-Signature` header."
+      );
+    }
+    if (!secret) {
+      throw new WebhookSignatureVerificationError(
+        "Missing webhook secret. Pass your webhook signing secret as the third argument."
+      );
+    }
+    const expectedSignature = crypto.createHmac("sha256", secret).update(payload).digest("base64");
+    let isValid;
+    try {
+      isValid = crypto.timingSafeEqual(
+        Buffer.from(signature),
+        Buffer.from(expectedSignature)
+      );
+    } catch {
+      isValid = false;
+    }
+    if (!isValid) {
+      throw new WebhookSignatureVerificationError(
+        "Webhook signature verification failed. Ensure you are using the raw request body and the correct signing secret."
+      );
+    }
+    const event = JSON.parse(payload);
+    return event;
+  }
+};
 
 // src/server/recur.ts
 var Recur = class {
@@ -290,6 +372,19 @@ var Recur = class {
      * Portal resource for managing customer portal sessions
      */
     __publicField(this, "portal");
+    /**
+     * Webhooks resource for verifying webhook signatures
+     *
+     * @example
+     * ```typescript
+     * const event = recur.webhooks.verify(
+     *   payload,
+     *   signature,
+     *   process.env.RECUR_WEBHOOK_SECRET!,
+     * );
+     * ```
+     */
+    __publicField(this, "webhooks");
     /**
      * Entitlements resource for checking customer subscription access
      *
@@ -323,8 +418,9 @@ var Recur = class {
       baseUrl: options?.baseUrl || "https://api.recur.tw"
     };
     this.portal = new Portal(this.config);
+    this.webhooks = new Webhooks(this.config);
     this.entitlements = new Entitlements(this.config);
   }
 };
 
-export { Recur, RecurAPIError };
+export { Recur, RecurAPIError, WebhookSignatureVerificationError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recur-tw",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "React & Vanilla JS SDK for embedding subscription checkout flows (Taiwan / PAYUNi)",
   "type": "module",
   "private": false,