@alexasomba/better-auth-paystack 1.2.1 → 2.2.0

package/README.md

@@ -2,6 +2,17 @@
 
 A TypeScript-first plugin that integrates Paystack into [Better Auth](https://www.better-auth.com), providing a production-ready billing system with support for subscriptions (native & local), one-time payments, trials, organization billing, and secure webhooks.
 
+<div align="center">
+
+![npm downloads](https://img.shields.io/npm/dm/@alexasomba/better-auth-paystack.svg)
+[![GitHub stars](https://img.shields.io/github/stars/alexasomba/better-auth-paystack.svg?style=social&label=Star)](https://github.com/alexasomba/better-auth-paystack/stargazers)
+[![GitHub release](https://img.shields.io/github/v/release/alexasomba/better-auth-paystack)](https://github.com/alexasomba/better-auth-paystack/releases)
+[![bundlephobia](https://img.shields.io/bundlephobia/minzip/@alexasomba/better-auth-paystack)](https://bundlephobia.com/result?p=@alexasomba/better-auth-paystack)
+[![Follow on Twitter](https://img.shields.io/twitter/follow/alexasomba?style=social)](https://twitter.com/alexasomba)
+![GitHub License](https://img.shields.io/github/license/alexasomba/better-auth-paystack)
+
+</div>
+
 [**Live Demo (Tanstack Start)**](https://better-auth-paystack.gittech.workers.dev) | [**Source Code**](https://github.com/alexasomba/better-auth-paystack/tree/main/examples/tanstack)
 
 ## Features
@@ -10,17 +21,23 @@ A TypeScript-first plugin that integrates Paystack into [Better Auth](https://ww
 - [x] **Auto Customer Creation**: Optional Paystack customer creation on user sign up or organization creation.
 - [x] **Trial Management**: Configurable trial periods with built-in abuse prevention logic.
 - [x] **Organization Billing**: Associate subscriptions with organizations and authorize access via roles.
+- [x] **Subscription Channel Controls**: Restrict subscription checkout to specific Paystack payment channels such as card-only.
 - [x] **Enforced Limits & Seats**: Automatic enforcement of member seat upgrades and resource limits (teams).
 - [x] **Scheduled Changes**: Defer subscription updates or cancellations to the end of the billing cycle.
-- [x] **Proration**: Immediate mid-cycle prorated charges for seat and plan upgrades.
-- [x] **Popup Modal Flow**: Optional support for Paystack's inline checkout experience via `@alexasomba/paystack-browser`.
-- [x] **Webhook Security**: Pre-configured signature verification (HMAC-SHA512).
+- [x] **Proration**: Immediate mid-cycle prorated upgrades for local plans, using saved-card charges when possible and checkout fallback when interactive payment is required.
+- [x] **Popup Modal Flow**: Optional support for Paystack's inline checkout experience via `@alexasomba/paystack-inline`.
+- [x] **Webhook Security**: Pre-configured signature verification (HMAC-SHA512) and optional IP whitelisting.
 - [x] **Transaction History**: Built-in support for listing and viewing local transaction records.
 
 ---
 
 ## Quick Start
 
+### Prerequisites
+
+- **Node.js**: `v24.0.0` or higher.
+- **Better Auth**: `v1.6.5` or higher.
+
 ### 1. Install Plugin & SDKs
 
 ```bash
@@ -30,7 +47,7 @@ npm install better-auth @alexasomba/better-auth-paystack @alexasomba/paystack-no
 #### Optional: Browser SDK (for Popup Modals)
 
 ```bash
-npm install @alexasomba/paystack-browser
+npm install @alexasomba/paystack-inline
 ```
 
 ### 2. Configure Environment Variables
@@ -48,6 +65,7 @@ BETTER_AUTH_URL=http://localhost:8787
 import { betterAuth } from "better-auth";
 import { paystack } from "@alexasomba/better-auth-paystack";
 import { createPaystack } from "@alexasomba/paystack-node";
+import { admin } from "better-auth/plugins";
 
 const paystackClient = createPaystack({
   secretKey: process.env.PAYSTACK_SECRET_KEY!,
@@ -55,12 +73,14 @@ const paystackClient = createPaystack({
 
 export const auth = betterAuth({
   plugins: [
+    admin(),
     paystack({
       paystackClient,
-      paystackWebhookSecret: process.env.PAYSTACK_WEBHOOK_SECRET!,
+      webhook: { secret: process.env.PAYSTACK_WEBHOOK_SECRET! },
       createCustomerOnSignUp: true,
       subscription: {
         enabled: true,
+        allowedPaymentChannels: ["card"], // Optional: enforce card-only subscriptions
         plans: [
           {
             name: "pro",
@@ -84,14 +104,21 @@ export const auth = betterAuth({
 });
 ```
 
+`webhook.secret` is the preferred webhook-signing config.
+If you still have older code using top-level `paystackWebhookSecret`, it is treated as a deprecated alias and falls back to the same signature check.
+
 ### 4. Configure Client Plugin
 
 ```ts title="client.ts"
 import { createAuthClient } from "better-auth/client";
 import { paystackClient } from "@alexasomba/better-auth-paystack/client";
+import { adminClient } from "better-auth/client/plugins";
 
 export const client = createAuthClient({
-  plugins: [paystackClient({ subscription: true })],
+  plugins: [
+    adminClient(),
+    paystackClient({ subscription: true })
+  ],
 });
 ```
 
@@ -103,6 +130,62 @@ npx better-auth migrate
 
 ---
 
+## Migration Guide
+
+Version `2.0.0` contains a security-focused breaking change.
+
+- Removed public/client operator actions:
+  - `authClient.paystack.syncProducts()`
+  - `authClient.paystack.syncPlans()`
+  - `authClient.paystack.chargeRecurringSubscription(...)`
+- Removed public Better Auth endpoints for:
+  - `/paystack/sync-products`
+  - `/paystack/sync-plans`
+  - `/paystack/charge-recurring`
+- Added trusted server operations:
+  - `chargeSubscriptionRenewal`
+  - `syncPaystackProducts`
+  - `syncPaystackPlans`
+
+### Old
+
+```ts
+await authClient.paystack.syncProducts();
+await authClient.paystack.syncPlans();
+await authClient.paystack.chargeRecurringSubscription({
+  subscriptionId: "sub_123",
+});
+```
+
+### New
+
+```ts
+import {
+  chargeSubscriptionRenewal,
+  syncPaystackPlans,
+  syncPaystackProducts,
+  type ChargeRecurringSubscriptionResult,
+  type PaystackSyncResult,
+} from "@alexasomba/better-auth-paystack";
+
+const ctx = { context: await auth.$context } as any;
+const paystackOptions = {
+  secretKey: process.env.PAYSTACK_SECRET_KEY!,
+  webhook: { secret: process.env.PAYSTACK_WEBHOOK_SECRET! },
+  paystackClient,
+};
+
+await syncPaystackProducts(ctx, paystackOptions);
+await syncPaystackPlans(ctx, paystackOptions);
+await chargeSubscriptionRenewal(ctx, paystackOptions, {
+  subscriptionId: "sub_123",
+});
+```
+
+These operations are intentionally server-only. Do not expose them through browser-triggered auth client calls.
+
+---
+
 ## Billing Patterns
 
 ### 1. Subscriptions
@@ -195,7 +278,7 @@ Enable `organization.enabled` to bill organizations instead of users.
 
 ### Inline Popup Modal
 
-Use `@alexasomba/paystack-browser` for a seamless UI.
+Use `@alexasomba/paystack-inline` for a seamless UI.
 
 ```ts
 const { data } = await authClient.subscription.upgrade({ plan: "pro" });
@@ -203,8 +286,7 @@ if (data?.accessCode) {
   const paystack = createPaystack({ publicKey: "pk_test_..." });
   paystack.checkout({
     accessCode: data.accessCode,
-    onSuccess: (res) =>
-      authClient.paystack.transaction.verify({ reference: res.reference }),
+    onSuccess: (res) => authClient.paystack.transaction.verify({ reference: res.reference }),
   });
 }
 ```
@@ -212,22 +294,63 @@ if (data?.accessCode) {
 ### Scheduled Changes & Cancellation
 
 Defer changes to the end of the current billing cycle:
+
 - **Upgrades**: Pass `scheduleAtPeriodEnd: true` in `initializeTransaction()`.
-- **Cancellations**: Use `authClient.subscription.cancel({ atPeriodEnd: true })` to keep the subscription active until the period ends.
+- **Cancellations**: Use `authClient.subscription.cancel({ subscriptionCode, atPeriodEnd: true })` to keep the subscription active until the period ends.
 
 ### Mid-Cycle Proration (`prorateAndCharge`)
 
 The plugin can dynamically calculate the cost difference for immediate mid-cycle upgrades (like adding more seats).
-If the user has a saved Paystack authorization code, the plugin will execute a prorated charge for the remaining cycle days and immediately sync the new amount/seats.
+For locally managed plans:
+
+- If the subscription already has a reusable Paystack authorization code, the plugin charges the prorated delta off-session, records a local `paystackTransaction`, and immediately updates the subscription.
+- If there is no reusable authorization code available (for example, transfer-based payments), the plugin initializes a new checkout for the prorated delta instead of silently upgrading without payment.
+- If the prorated amount is below Paystack's minimum charge for the currency, the request is rejected so you can schedule the change for period end instead of undercharging.
 
 ```ts
 await authClient.paystack.transaction.initialize({
   plan: "pro",
   quantity: 5, // Upgrading seats
-  prorateAndCharge: true, // Will calculate and charge the prorated amount instantly
+  prorateAndCharge: true, // Charges saved authorization or returns a checkout redirect for the delta
+});
+```
+
+When the flow falls back to checkout, verify the returned transaction reference after payment. The plugin uses the stored proration metadata to apply the pending plan/seat change only after successful verification.
+
+### Restricting Subscription Payment Channels
+
+Use `subscription.allowedPaymentChannels` to constrain which Paystack checkout channels can be used for subscription flows.
+This applies to standard subscription checkout, trial authorization flows, and interactive proration checkout fallbacks.
+
+```ts
+paystack({
+  subscription: {
+    enabled: true,
+    allowedPaymentChannels: ["card"],
+    plans: [{ name: "starter", amount: 50000, currency: "NGN", interval: "monthly" }],
+  },
+});
+```
+
+If a subscription payment is later verified with a disallowed channel, the plugin rejects activation instead of silently creating the subscription.
+
+### Webhook Security
+
+The plugin automatically verifies the `x-paystack-signature` header to ensure events are authentic. For an extra layer of security, you can enable **IP Whitelisting** to restrict processing to Paystack's official servers.
+
+```ts
+paystack({
+  webhook: {
+    secret: process.env.PAYSTACK_WEBHOOK_SECRET!,
+    verifyIP: true, // Enable IP whitelisting (defaults to false for flexible proxy support)
+    trustedIPs: ["52.31.139.75", "52.49.173.169", "52.214.14.220"], // Optional: override trusted IPs
+  },
 });
 ```
 
+Resolution order for webhook signature verification is:
+`webhook.secret` -> `paystackWebhookSecret` (deprecated) -> `secretKey`.
+
 ### Trial Abuse Prevention
 
 The plugin checks the `referenceId` history. If a trial was ever used (active, expired, or trialing), it will not be granted again, preventing resubscribe-abuse.
@@ -240,9 +363,7 @@ React to billing events on the server by providing callbacks in your configurati
 
 - `onSubscriptionComplete`: Called after successful transaction verification (Native or Local).
 - `onSubscriptionCreated`: Called when a subscription record is first initialized in the DB.
-- `onSubscriptionUpdate`: Called whenever a subscription's status or period is updated.
 - `onSubscriptionCancel`: Called when a user or organization cancels their subscription.
-- `onSubscriptionDelete`: Called when a subscription record is deleted.
 
 #### Customer Hooks (`top-level` or `organization.*`)
 
@@ -252,12 +373,33 @@ React to billing events on the server by providing callbacks in your configurati
 #### Trial Hooks (`subscription.plans[].freeTrial.*`)
 
 - `onTrialStart`: Called when a new trial period begins.
-- `onTrialEnd`: Called when a trial period ends naturally or via manual upgrade.
 
 #### Global Hook
 
 - `onEvent`: Receives every webhook event payload sent from Paystack for custom processing.
 
+### Trusted Server Operations
+
+Recurring renewals and Paystack catalog sync are intentionally not exposed through the browser auth client.
+Invoke them from trusted backend code only:
+
+```ts
+import {
+  chargeSubscriptionRenewal,
+  syncPaystackPlans,
+  syncPaystackProducts,
+} from "@alexasomba/better-auth-paystack";
+
+const ctx = { context: await auth.$context } as any;
+
+await chargeSubscriptionRenewal(ctx, paystackOptions, {
+  subscriptionId: "sub_123",
+});
+
+await syncPaystackProducts(ctx, paystackOptions);
+await syncPaystackPlans(ctx, paystackOptions);
+```
+
 ### Authorization & Security
 
 #### `authorizeReference`
@@ -320,7 +462,7 @@ type upgradeSubscription = {
   /**
    * Additional metadata to store with the transaction.
    */
-  metadata?: Record<string, any>;
+  metadata?: Record<string, unknown>;
   /**
    * Reference ID for the subscription owner (User ID or Org ID).
    * Defaults to the current user's ID.
@@ -351,6 +493,11 @@ type initializeTransaction = {
    * Amount to charge (if sending raw amount).
    */
   amount?: number;
+  /**
+   * For existing locally managed subscriptions, calculate a mid-cycle delta and either
+   * charge the saved authorization or return a checkout redirect for interactive payment.
+   */
+  prorateAndCharge?: boolean;
   // ... same as upgradeSubscription
 };
 ```
@@ -379,6 +526,10 @@ Cancel or restore a subscription.
 
 ```ts
 type cancelSubscription = {
+  /**
+   * Optional reference owner (user ID or org ID) when managing another billing entity.
+   */
+  referenceId?: string;
   /**
    * The Paystack subscription code (e.g. SUB_...)
    */
@@ -388,6 +539,10 @@ type cancelSubscription = {
    * Optional: The server will try to fetch it if omitted.
    */
   emailToken?: string;
+  /**
+   * When true, keep the subscription active until the current period ends.
+   */
+  atPeriodEnd?: boolean;
 };
 ```
 
@@ -428,36 +583,36 @@ The plugin extends your database with the following fields and tables.
 
 ### `paystackTransaction`
 
-| Field         | Type     | Required | Description                                       |
-| :------------ | :------- | :------- | :------------------------------------------------ |
-| `reference`   | `string` | Yes      | Unique transaction reference.                     |
-| `referenceId` | `string` | Yes      | Associated User ID or Organization ID.            |
-| `userId`      | `string` | Yes      | The ID of the user who initiated the transaction. |
-| `amount`      | `number` | Yes      | Transaction amount in smallest currency unit.     |
-| `currency`    | `string` | Yes      | Currency code (e.g., "NGN").                      |
-| `status`      | `string` | Yes      | `success`, `pending`, `failed`, `abandoned`.      |
-| `plan`        | `string` | No       | Name of the plan associated with the transaction. |
+| Field         | Type     | Required | Description                                          |
+| :------------ | :------- | :------- | :--------------------------------------------------- |
+| `reference`   | `string` | Yes      | Unique transaction reference.                        |
+| `referenceId` | `string` | Yes      | Associated User ID or Organization ID.               |
+| `userId`      | `string` | Yes      | The ID of the user who initiated the transaction.    |
+| `amount`      | `number` | Yes      | Transaction amount in smallest currency unit.        |
+| `currency`    | `string` | Yes      | Currency code (e.g., "NGN").                         |
+| `status`      | `string` | Yes      | `success`, `pending`, `failed`, `abandoned`.         |
+| `plan`        | `string` | No       | Name of the plan associated with the transaction.    |
 | `product`     | `string` | No       | Name of the product associated with the transaction. |
-| `metadata`    | `string` | No       | JSON string of extra transaction metadata.        |
-| `paystackId`  | `string` | No       | The internal Paystack ID for the transaction.     |
-| `createdAt`   | `Date`   | Yes      | Transaction creation timestamp.                   |
-| `updatedAt`   | `Date`   | Yes      | Transaction last update timestamp.                |
+| `metadata`    | `string` | No       | JSON string of extra transaction metadata.           |
+| `paystackId`  | `string` | No       | The internal Paystack ID for the transaction.        |
+| `createdAt`   | `Date`   | Yes      | Transaction creation timestamp.                      |
+| `updatedAt`   | `Date`   | Yes      | Transaction last update timestamp.                   |
 
 ### `paystackProduct`
 
-| Field         | Type      | Required | Description                                       |
-| :------------ | :-------- | :------- | :------------------------------------------------ |
-| `name`        | `string`  | Yes      | Product name.                                     |
-| `description` | `string`  | No       | Product description.                              |
-| `price`       | `number`  | Yes      | Price in smallest currency unit.                  |
-| `currency`    | `string`  | Yes      | Currency code (e.g., "NGN").                      |
-| `quantity`    | `number`  | No       | Available stock quantity.                         |
-| `unlimited`   | `boolean` | No       | Whether the product has unlimited stock.          |
-| `paystackId`  | `string`  | No       | The internal Paystack Product ID.                 |
-| `slug`        | `string`  | Yes      | Unique slug for the product.                      |
-| `metadata`    | `string`  | No       | JSON string of extra product metadata.            |
-| `createdAt`   | `Date`    | Yes      | Product creation timestamp.                       |
-| `updatedAt`   | `Date`    | Yes      | Product last update timestamp.                    |
+| Field         | Type      | Required | Description                              |
+| :------------ | :-------- | :------- | :--------------------------------------- |
+| `name`        | `string`  | Yes      | Product name.                            |
+| `description` | `string`  | No       | Product description.                     |
+| `price`       | `number`  | Yes      | Price in smallest currency unit.         |
+| `currency`    | `string`  | Yes      | Currency code (e.g., "NGN").             |
+| `quantity`    | `number`  | No       | Available stock quantity.                |
+| `unlimited`   | `boolean` | No       | Whether the product has unlimited stock. |
+| `paystackId`  | `string`  | No       | The internal Paystack Product ID.        |
+| `slug`        | `string`  | Yes      | Unique slug for the product.             |
+| `metadata`    | `string`  | No       | JSON string of extra product metadata.   |
+| `createdAt`   | `Date`    | Yes      | Product creation timestamp.              |
+| `updatedAt`   | `Date`    | Yes      | Product last update timestamp.           |
 
 ---
 
@@ -474,43 +629,61 @@ The plugin extends your database with the following fields and tables.
 The plugin's schema definition includes recommended indexes and uniqueness constraints for performance. When you run `npx better-auth migrate`, these will be automatically applied to your database.
 
 The following fields are indexed:
+
 - **`paystackTransaction`**: `reference` (unique), `userId`, `referenceId`.
 - **`subscription`**: `paystackSubscriptionCode` (unique), `referenceId`, `paystackTransactionReference`, `paystackCustomerCode`, `plan`.
 - **`user` & `organization`**: `paystackCustomerCode`.
 - **`paystackProduct`**: `slug` (unique), `paystackId` (unique).
 
+Proration upgrades and trusted renewal charges also persist `paystackTransaction` rows, so local transaction history stays aligned with successful off-session charges.
+
 ### Syncing Products
 
-The plugin provides two ways to keep your product inventory in sync with Paystack:
+The plugin provides two ways to keep your product inventory aligned with Paystack:
+
+#### 1. Automated Inventory Sync
 
-#### 1. Automated Inventory Sync (New)
 Whenever a successful one-time payment is made (via webhook or manual verification), the plugin automatically calls **`syncProductQuantityFromPaystack`**. This fetches the real-time remaining quantity from the Paystack API and updates your local database record, ensuring your inventory is always accurate.
 
-#### 2. Manual Bulk Sync
-You can synchronize all products with your local database using the `/paystack/sync-products` endpoint.
+#### 2. Trusted Manual Bulk Sync
 
-```bash
-POST /api/auth/paystack/sync-products
+The public `/paystack/sync-products` endpoint was removed in `2.0.0`.
+Run the trusted server operation from backend code instead:
+
+```ts
+import { syncPaystackProducts } from "@alexasomba/better-auth-paystack";
+
+const ctx = { context: await auth.$context } as any;
+
+await syncPaystackProducts(ctx, paystackOptions);
 ```
 
+### SDK Compatibility Note
+
+The plugin now targets the official `@alexasomba/paystack-node` grouped client surface directly.
+If you inject a custom client, it should match the real SDK methods used by the plugin such as `transaction.initialize`, `transaction.verify`, `transaction.chargeAuthorization`, `subscription.create`, `subscription.disable`, and `subscription.enable`.
+
 ---
 
 ## 🏗️ Development & Contributing
 
-This repository is set up as a pnpm workspace. You can run and build examples via `--filter`.
+This repository is powered by **Vite+**. You use the `vp` CLI to manage the entire workspace.
 
 ```bash
-# Install everything
-pnpm install
+# Install dependencies
+vp i
+
+# Check project health (format, lint, types)
+vp check --fix
 
 # Build the core library
-pnpm --filter "@alexasomba/better-auth-paystack" build
+vp build
 
-# Run Next.js example (Next.js + Better Auth)
-pnpm --filter nextjs-better-auth-paystack dev
+# Run tests
+vp test
 
-# Run TanStack Start example (TanStack Start + Better Auth)
-pnpm --filter tanstack-start-better-auth-paystack dev
+# Run the TanStack Start example
+vp run examples/tanstack dev
 ```
 
 Contributions are welcome! Please open an issue or pull request.
@@ -526,11 +699,11 @@ Future features planned for upcoming versions:
 ### v1.1.0 - Manual Recurring Subscriptions (Available Now)
 
 - [x] **Stored Authorization Codes**: Securely store Paystack authorization codes from verified transactions.
-- [x] **Charge Authorization Endpoint**: Server-side endpoint (`/charge-recurring`) to charge stored cards for renewals.
+- [x] **Trusted Renewal Operation**: Server-side helper to charge stored cards for renewals.
 - [ ] **Card Management UI**: Let users view/delete saved payment methods (masked card data only) - _Upcoming_
 - [ ] **Renewal Scheduler Integration**: Documentation for integrating with Cloudflare Workers Cron, Vercel Cron, etc. - _Upcoming_
 
-> **Note**: For local-managed subscriptions (no `planCode`), the plugin now automatically captures and stores the `authorization_code`. You can trigger renewals using `authClient.paystack.chargeRecurringSubscription({ subscriptionId })`.
+> **Note**: For local-managed subscriptions (no `planCode`), the plugin automatically captures and stores the `authorization_code`. Trigger renewals from trusted backend code with `chargeSubscriptionRenewal(...)`.
 
 ### Future Considerations
 
@@ -542,7 +715,7 @@ Future features planned for upcoming versions:
 
 - GitHub Repository: [alexasomba/better-auth-paystack](https://github.com/alexasomba/better-auth-paystack)
 - Comprehensive and up-to-date Paystack Node SDK: [alexasomba/paystack-node](https://github.com/alexasomba/paystack-node)
-- Comprehensive and up-to-date Paystack Browser SDK: [alexasomba/paystack-browser](https://github.com/alexasomba/paystack-browser)
+- Comprehensive and up-to-date Paystack Inline SDK: [alexasomba/paystack-inline](https://github.com/alexasomba/paystack-inline)
 - [TanStack Start Example Implementation](https://github.com/alexasomba/better-auth-paystack/tree/main/examples/tanstack)
 - Paystack Webhooks: https://paystack.com/docs/payments/webhooks/
 - Paystack Transaction API: https://paystack.com/docs/api/transaction/