@alexasomba/better-auth-paystack 2.2.0 → 2.4.1

package/dist/{types-B5ZnlFrq.d.mts → types-CNI2ur0p.d.mts}

@@ -1,5 +1,21 @@
-import { GenericEndpointContext, Session, User } from "better-auth";
+import { GenericEndpointContext, InferOptionSchema, Session, User } from "better-auth";
 import { PaystackCustomerClient, PaystackPlanClient, PaystackProductClient, PaystackSubscriptionClient, PaystackTransactionClient, PaystackWebhookEvent, components } from "@alexasomba/paystack-node";
+import { BetterAuthPluginDBSchema, DBFieldAttribute } from "better-auth/db";
+//#region src/schema.d.ts
+type PluginSchemaTable<TableName extends string, FieldName extends string> = Record<TableName, {
+  fields: Record<FieldName, DBFieldAttribute>;
+  disableMigration?: boolean;
+  modelName?: string;
+}>;
+type TransactionsSchema = PluginSchemaTable<"paystackTransaction", "reference" | "paystackId" | "referenceId" | "userId" | "amount" | "currency" | "status" | "plan" | "product" | "metadata" | "createdAt" | "updatedAt">;
+type SubscriptionsSchema = PluginSchemaTable<"subscription", "plan" | "referenceId" | "paystackCustomerCode" | "paystackSubscriptionCode" | "paystackTransactionReference" | "paystackAuthorizationCode" | "paystackEmailToken" | "status" | "periodStart" | "periodEnd" | "trialStart" | "trialEnd" | "cancelAtPeriodEnd" | "groupId" | "seats" | "pendingPlan">;
+type UserSchema = PluginSchemaTable<"user", "paystackCustomerCode">;
+type OrganizationSchema = PluginSchemaTable<"organization", "paystackCustomerCode" | "email">;
+type ProductsSchema = PluginSchemaTable<"paystackProduct", "name" | "description" | "price" | "currency" | "quantity" | "unlimited" | "paystackId" | "slug" | "metadata" | "createdAt" | "updatedAt">;
+type PlansSchema = PluginSchemaTable<"paystackPlan", "name" | "description" | "amount" | "currency" | "interval" | "planCode" | "paystackId" | "metadata" | "createdAt" | "updatedAt">;
+type PaystackPluginSchema = SubscriptionsSchema & TransactionsSchema & UserSchema & OrganizationSchema & ProductsSchema & PlansSchema;
+declare const getSchema: (options: PaystackOptions) => BetterAuthPluginDBSchema;
+//#endregion
 //#region src/types.d.ts
 type PaystackCheckoutChannel = "card" | "bank" | "ussd" | "qr" | "mobile_money" | "bank_transfer" | "eft" | "apple_pay";
 /**
@@ -32,8 +48,8 @@ interface PaystackProduct {
   paystackId?: string;
   slug?: string;
   metadata?: string | null;
-  createdAt: Date;
-  updatedAt: Date;
+  createdAt?: Date;
+  updatedAt?: Date;
 }
 interface PaystackPlan {
   id?: string;
@@ -200,10 +216,7 @@ interface PaystackOptions<TPaystackClient extends PaystackClientLike = PaystackC
   /**
    * Custom database schema / model names
    */
-  schema?: Record<string, {
-    modelName?: string;
-    fields?: Record<string, string>;
-  }>;
+  schema?: InferOptionSchema<PaystackPluginSchema>;
 }
 interface Subscription {
   id: string;
@@ -254,5 +267,5 @@ interface PaystackClientLike {
   plan: Pick<PaystackPlanClient, "list" | "create">;
 }
 //#endregion
-export { PaystackOptions as a, PaystackSyncResult as c, Subscription as d, SubscriptionOptions as f, PaystackClientLike as i, PaystackTransaction as l, ChargeRecurringSubscriptionInput as n, PaystackPlan as o, ChargeRecurringSubscriptionResult as r, PaystackProduct as s, AnyPaystackOptions as t, PaystackTransactionResponse as u };
-//# sourceMappingURL=types-B5ZnlFrq.d.mts.map
+export { PaystackOptions as a, PaystackSyncResult as c, Subscription as d, SubscriptionOptions as f, PaystackClientLike as i, PaystackTransaction as l, ChargeRecurringSubscriptionInput as n, PaystackPlan as o, getSchema as p, ChargeRecurringSubscriptionResult as r, PaystackProduct as s, AnyPaystackOptions as t, PaystackTransactionResponse as u };
+//# sourceMappingURL=types-CNI2ur0p.d.mts.map

package/dist/types-CNI2ur0p.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-CNI2ur0p.d.mts","names":["GenericEndpointContext","InferOptionSchema","Session","User","Organization","Member","PaystackPaths","PaystackResponse","PaystackWebhookEvent","PaystackClient","PaystackCustomerClient","PaystackPlanClient","PaystackProductClient","PaystackSubscriptionClient","PaystackTransactionClient","components","PaystackPluginSchema","PaystackCurrency","PaystackCheckoutChannel","PaystackTransaction","Date","id","reference","paystackId","referenceId","userId","amount","currency","status","plan","product","metadata","createdAt","updatedAt","PaystackProduct","name","description","price","quantity","unlimited","slug","InputPaystackProduct","PaystackUser","paystackCustomerCode","PaystackOrganization","PaystackPlan","Subscription","Promise","Record","interval","planCode","seatAmount","seatPriceId","seatPlanCode","invoiceLimit","freeTrial","days","onTrialStart","subscription","limits","features","PaystackWebhookPayload","PaystackTransactionResponse","PaystackPlanResponse","PaystackCustomerResponse","PaystackSubscriptionResponse","PaystackProductResponse","SubscriptionOptions","enabled","plans","autoSyncQuantity","cancelBehavior","onSubscriptionComplete","event","data","ctx","onSubscriptionCreated","onSubscriptionCancel","authorizeReference","user","session","action","requireEmailVerification","allowedPaymentChannels","PaystackOptions","TPaystackClient","PaystackClientLike","secretKey","paystackWebhookSecret","paystackClient","webhook","secret","verifyIP","trustedIPs","billingPattern","onEvent","organization","getCustomerCreateParams","email","org","onCustomerCreate","paystackCustomer","products","createCustomerOnSignUp","schema","organizationId","pendingPlan","paystackSubscriptionCode","paystackPlanCode","paystackAuthorizationCode","paystackTransactionReference","paystackEmailToken","seats","periodStart","periodEnd","cancelAtPeriodEnd","trialStart","trialEnd","groupId","ChargeRecurringSubscriptionInput","subscriptionId","ChargeRecurringSubscriptionResult","PaystackSyncResult","count","AnyPaystackOptions","Pick","transaction","customer"],"sources":["../src/schema.ts","../src/types.d.ts"],"mappings":"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"}

package/dist/version-DpVME9MV.mjs

@@ -0,0 +1,6 @@
+//#region src/version.ts
+const PACKAGE_VERSION = "2.4.1";
+//#endregion
+export { PACKAGE_VERSION as t };
+
+//# sourceMappingURL=version-DpVME9MV.mjs.map

package/dist/version-DpVME9MV.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-DpVME9MV.mjs","names":[],"sources":["../src/version.ts"],"sourcesContent":["export const PACKAGE_VERSION = \"2.4.1\"; // x-release-please-version\n"],"mappings":";AAAA,MAAa,kBAAkB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexasomba/better-auth-paystack",
-  "version": "2.2.0",
+  "version": "2.4.1",
   "description": "Production-ready Paystack billing plugin for Better Auth. Supports subscriptions, one-time payments, organization billing, secure webhooks and more",
   "keywords": [
     "africa",
@@ -24,6 +24,7 @@
     "saas",
     "south-africa",
     "subscriptions",
+    "tanstack-intent",
     "usd",
     "zar"
   ],
@@ -44,7 +45,8 @@
     }
   ],
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "type": "module",
   "sideEffects": false,
@@ -66,38 +68,38 @@
   },
   "dependencies": {
     "@alexasomba/paystack-node": "^1.9.4",
-    "better-call": "^1.3.5",
+    "better-call": "~1.3.5",
     "defu": "^6.1.7",
-    "zod": "^4.3.6"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
-    "@better-auth/core": "1.7.0-beta.1",
     "@better-fetch/fetch": "^1.1.21",
-    "@commitlint/cli": "^20.5.0",
-    "@commitlint/config-conventional": "^20.5.0",
-    "@eslint/compat": "^2.0.5",
+    "@commitlint/cli": "^21.0.0",
+    "@commitlint/config-conventional": "^21.0.0",
+    "@eslint/compat": "^2.1.0",
     "@eslint/js": "^10.0.1",
-    "@types/node": "^24.12.2",
-    "@typescript-eslint/eslint-plugin": "^8.58.2",
-    "@typescript-eslint/parser": "^8.58.2",
-    "@vitest/coverage-v8": "^4.1.4",
-    "better-auth": "1.7.0-beta.1",
+    "@tanstack/intent": "^0.0.40",
+    "@types/node": "^24.12.3",
+    "@typescript-eslint/eslint-plugin": "^8.59.2",
+    "@typescript-eslint/parser": "^8.59.2",
+    "@vitest/coverage-v8": "^4.1.5",
+    "better-auth": "^1.6.9",
     "eslint-plugin-import-x": "^4.16.2",
-    "eslint-plugin-promise": "^7.2.1",
+    "eslint-plugin-promise": "^7.3.0",
     "eslint-plugin-react-hooks": "^7.1.1",
     "eslint-plugin-unicorn": "^64.0.0",
-    "publint": "^0.3.18",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.58.2",
-    "vite-plus": "^0.1.18",
-    "vitest": "npm:@voidzero-dev/vite-plus-test@^0.1.18"
+    "publint": "^0.3.20",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.59.2",
+    "vite-plus": "^0.1.20",
+    "vitest": "npm:@voidzero-dev/vite-plus-test@^0.1.20"
   },
   "peerDependencies": {
-    "better-auth": "^1.6.5"
+    "better-auth": "^1.6.9"
   },
   "optionalDependencies": {
-    "@rollup/rollup-linux-x64-gnu": "^4.60.2"
+    "@rollup/rollup-linux-x64-gnu": "^4.60.3"
   },
   "engines": {
     "node": ">=24.0.0"

package/skills/billing-catalog-and-limits/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: billing-catalog-and-limits
+description: >
+  Configure products, Paystack-native plans, local-managed plans, free trials, seat billing, resource limits, and catalog sync in @alexasomba/better-auth-paystack. Use when tasks mention planCode, freeTrial, trial eligibility, seatAmount, seatPlanCode, limits, products, syncPaystackProducts, or syncPaystackPlans.
+type: core
+library: "@alexasomba/better-auth-paystack"
+library_version: "2.4.1" # x-release-please-version
+sources:
+  - "alexasomba/better-auth-paystack:README.md"
+  - "alexasomba/better-auth-paystack:src/types.ts"
+  - "alexasomba/better-auth-paystack:src/routes.ts"
+  - "alexasomba/better-auth-paystack:src/operations.ts"
+  - "alexasomba/better-auth-paystack:src/utils.ts"
+---
+
+## Setup
+
+Configure catalog data on the server plugin. Products are one-time purchasable catalog items. Plans are subscription catalog items.
+
+```ts
+import { paystack } from "@alexasomba/better-auth-paystack";
+
+export const paystackPlugin = paystack({
+  secretKey: process.env.PAYSTACK_SECRET_KEY!,
+  webhook: {
+    secret: process.env.PAYSTACK_WEBHOOK_SECRET!,
+  },
+  products: {
+    products: [
+      {
+        name: "credits_50",
+        amount: 200_000,
+        currency: "NGN",
+      },
+    ],
+  },
+  subscription: {
+    enabled: true,
+    plans: [
+      {
+        name: "pro",
+        amount: 500_000,
+        currency: "NGN",
+        interval: "monthly",
+        planCode: "PLN_pro_monthly",
+        paystackId: "1001",
+        freeTrial: {
+          days: 14,
+        },
+        limits: {
+          seats: 10,
+          teams: 5,
+        },
+      },
+    ],
+  },
+});
+```
+
+## Core Patterns
+
+### Choose Paystack-native plans for simple recurring billing
+
+Use `planCode` from the Paystack Dashboard when Paystack should manage the recurring subscription.
+
+```ts
+{
+  name: "pro",
+  amount: 500_000,
+  currency: "NGN",
+  interval: "monthly",
+  planCode: "PLN_pro_monthly",
+  paystackId: "1001",
+}
+```
+
+Paystack-native plans are the right default for fixed-price recurring billing. Do not use native plans for flows that require local seat proration or locally managed renewals.
+
+### Omit planCode for local-managed subscriptions
+
+Local-managed plans are tracked in your database and renewed from stored Paystack authorizations by trusted backend code.
+
+```ts
+{
+  name: "local-team",
+  amount: 1_000_000,
+  currency: "NGN",
+  interval: "monthly",
+  seatAmount: 100_000,
+  limits: {
+    seats: 10,
+    teams: 3,
+  },
+}
+```
+
+For local-managed subscriptions, no `planCode` means the plugin captures and stores the authorization code after transaction verification. Trigger renewals from server code with `chargeSubscriptionRenewal`.
+
+### Configure trials on plans
+
+Trials are declared per plan:
+
+```ts
+{
+  name: "starter",
+  amount: 250_000,
+  currency: "NGN",
+  interval: "monthly",
+  planCode: "PLN_starter",
+  paystackId: "1002",
+  freeTrial: {
+    days: 7,
+    onTrialStart: async (subscription) => {
+      await notifyTrialStarted(subscription.referenceId);
+    },
+  },
+}
+```
+
+The plugin checks previous subscription history for the `referenceId`. If a trial was ever used, expired, or marked `trialing`, another trial is denied for that reference. Do not build UI that promises repeat trials for the same user or organization.
+
+### Configure seats and resource limits
+
+Use `limits` for app resource enforcement and `seatAmount` for local seat billing amounts:
+
+```ts
+{
+  name: "team",
+  amount: 1_000_000,
+  currency: "NGN",
+  interval: "monthly",
+  seatAmount: 100_000,
+  seatPlanCode: "PLN_extra_seat",
+  limits: {
+    seats: 10,
+    teams: 3,
+  },
+}
+```
+
+`seatPriceId` is a deprecated alias. Use `seatAmount` in new code. `seatPlanCode` is only useful when a Paystack plan code exists for extra seats.
+
+### Sync products and plans from trusted server jobs
+
+Use server-only helpers to mirror Paystack catalog data into local tables:
+
+```ts
+import { syncPaystackPlans, syncPaystackProducts } from "@alexasomba/better-auth-paystack";
+
+export async function syncCatalog(ctx: unknown, options: unknown) {
+  await syncPaystackProducts(ctx, options);
+  await syncPaystackPlans(ctx, options);
+}
+```
+
+These operations are not browser client actions. Run them from cron, admin-only server functions, CI jobs, or deployment tasks.
+
+## Common Mistakes
+
+### Using native planCode for local seat/proration behavior
+
+Wrong:
+
+```ts
+{
+  name: "team",
+  planCode: "PLN_team",
+  seatAmount: 100_000,
+}
+```
+
+Correct: omit `planCode` when the plan needs local seat billing, local renewals, or prorated seat changes.
+
+### Treating products like subscription plans
+
+Products are one-time purchases. Plans are subscriptions. Use transaction initialization for product purchases and subscription actions for plans.
+
+### Expecting product and plan tables to be optional
+
+`paystackProduct` and `paystackPlan` schema tables are always included by the plugin. Do not remove them in compatibility-preserving releases.
+
+### Trusting trial state without verification
+
+Trial metadata is created during subscription checkout and finalized through transaction/webhook handling. Always verify the Paystack reference and rely on persisted subscription state before granting paid access.

package/skills/organization-billing/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: organization-billing
+description: >
+  Configure organization billing in @alexasomba/better-auth-paystack. Use for organization.enabled, Better Auth organization plugin setup, owner/admin default billing authorization, subscription.authorizeReference, organization Paystack customers, seats, invitations, members, and team limits.
+type: core
+library: "@alexasomba/better-auth-paystack"
+library_version: "2.4.1" # x-release-please-version
+sources:
+  - "alexasomba/better-auth-paystack:README.md"
+  - "alexasomba/better-auth-paystack:src/index.ts"
+  - "alexasomba/better-auth-paystack:src/utils.ts"
+  - "alexasomba/better-auth-paystack:src/limits.ts"
+---
+
+## Setup
+
+Install the Better Auth organization plugin and enable Paystack organization billing:
+
+```ts
+import { betterAuth } from "better-auth";
+import { organization } from "better-auth/plugins/organization";
+import { paystack } from "@alexasomba/better-auth-paystack";
+
+export const auth = betterAuth({
+  plugins: [
+    organization(),
+    paystack({
+      secretKey: process.env.PAYSTACK_SECRET_KEY!,
+      webhook: {
+        secret: process.env.PAYSTACK_WEBHOOK_SECRET!,
+      },
+      subscription: {
+        enabled: true,
+        plans: [
+          {
+            name: "team",
+            amount: 1_000_000,
+            currency: "NGN",
+            interval: "monthly",
+            planCode: "PLN_team",
+            paystackId: "1002",
+            limits: {
+              seats: 10,
+              teams: 3,
+            },
+          },
+        ],
+      },
+      organization: {
+        enabled: true,
+      },
+    }),
+  ],
+});
+```
+
+## Core Patterns
+
+### Rely on the safe default for billing authorization
+
+When `subscription.authorizeReference` is not supplied, organization billing actions require membership role `owner` or `admin`.
+
+Ordinary members are rejected by default. Do not write UI or tests that assume any member can create, upgrade, cancel, or restore organization subscriptions.
+
+### Override authorization explicitly for custom workflows
+
+Use `subscription.authorizeReference` when a product intentionally allows non-owner/admin billing access:
+
+```ts
+paystack({
+  secretKey: process.env.PAYSTACK_SECRET_KEY!,
+  subscription: {
+    enabled: true,
+    plans: [],
+    authorizeReference: async ({ user, referenceId }, ctx) => {
+      if (referenceId === user.id) return true;
+
+      const memberships = await ctx.context.adapter.findMany({
+        model: "member",
+        where: [
+          { field: "userId", value: user.id },
+          { field: "organizationId", value: referenceId },
+        ],
+      });
+
+      return memberships.some((membership) => {
+        const role = (membership as { role?: string }).role;
+        return role === "owner" || role === "admin" || role === "billing";
+      });
+    },
+  },
+  organization: {
+    enabled: true,
+  },
+});
+```
+
+When supplied, `authorizeReference` is authoritative. Include all user and organization cases you want to allow.
+
+### Create organization Paystack customers
+
+When organization billing is enabled and the organization plugin is present, the plugin wires organization creation hooks. It tries to create a Paystack customer for the organization and stores `paystackCustomerCode`.
+
+Customize creation params when needed:
+
+```ts
+organization: {
+  enabled: true,
+  getCustomerCreateParams: async (org) => ({
+    metadata: JSON.stringify({
+      organizationId: org.id,
+      billingSource: "better-auth-paystack",
+    }),
+  }),
+  onCustomerCreate: async ({ paystackCustomer, organization }, ctx) => {
+    await ctx.context.adapter.update({
+      model: "organization",
+      where: [{ field: "id", value: organization.id }],
+      update: {
+        paystackCustomerCode: paystackCustomer.customer_code,
+      },
+    });
+  },
+}
+```
+
+## Common Mistakes
+
+### Enabling organization billing without the organization plugin
+
+If `organization.enabled` is true but Better Auth's organization plugin is missing, Paystack logs a clear error and skips organization hook wiring. Add `organization()` before relying on organization customer creation, members, invitations, seats, or team hooks.
+
+### Assuming member limits apply without subscription plans
+
+Seat and team limits come from subscription plan limits. If a plan has no relevant `limits` value, the plugin cannot enforce that limit.
+
+### Forgetting seat sync after membership changes
+
+The plugin hooks member/invitation lifecycle events when the organization plugin is present. If you implement custom membership mutation routes outside Better Auth's adapter hooks, explicitly re-check or sync seat state in that custom path.

package/skills/setup/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: setup
+description: >
+  Configure @alexasomba/better-auth-paystack with Better Auth. Use when adding the paystack() server plugin, paystackClient() client plugin, schema overrides, products/plans, webhook secrets, or canonical authClient.paystack/subscription/transaction actions.
+type: core
+library: "@alexasomba/better-auth-paystack"
+library_version: "2.4.1" # x-release-please-version
+sources:
+  - "alexasomba/better-auth-paystack:README.md"
+  - "alexasomba/better-auth-paystack:src/index.ts"
+  - "alexasomba/better-auth-paystack:src/client.ts"
+  - "alexasomba/better-auth-paystack:src/schema.ts"
+---
+
+## Setup
+
+Install the package alongside Better Auth and a Paystack client:
+
+```ts
+import { betterAuth } from "better-auth";
+import { createPaystack } from "@alexasomba/paystack-node";
+import { paystack } from "@alexasomba/better-auth-paystack";
+
+const paystackSdk = createPaystack({
+  secretKey: process.env.PAYSTACK_SECRET_KEY!,
+});
+
+export const auth = betterAuth({
+  database: {
+    provider: "sqlite",
+    url: process.env.DATABASE_URL!,
+  },
+  plugins: [
+    paystack({
+      paystackClient: paystackSdk,
+      secretKey: process.env.PAYSTACK_SECRET_KEY!,
+      webhook: {
+        secret: process.env.PAYSTACK_WEBHOOK_SECRET!,
+      },
+      subscription: {
+        enabled: true,
+        plans: [
+          {
+            name: "pro",
+            amount: 500_000,
+            currency: "NGN",
+            interval: "monthly",
+            planCode: "PLN_pro_monthly",
+            paystackId: "123456",
+          },
+        ],
+      },
+    }),
+  ],
+});
+```
+
+Add the client plugin in browser-safe code:
+
+```ts
+import { createAuthClient } from "better-auth/client";
+import { paystackClient } from "@alexasomba/better-auth-paystack/client";
+
+export const authClient = createAuthClient({
+  plugins: [paystackClient()],
+});
+```
+
+## Core Patterns
+
+### Use canonical client namespaces
+
+The client plugin exposes these namespaces:
+
+```ts
+await authClient.paystack.getConfig();
+await authClient.transaction.initialize({ amount: 500_000, email: "user@example.com" });
+await authClient.transaction.verify({ reference: "trx_ref" });
+await authClient.transaction.list();
+await authClient.subscription.create({ plan: "pro" });
+await authClient.subscription.upgrade({ plan: "team" });
+await authClient.subscription.cancel({ subscriptionId: "sub_id" });
+await authClient.subscription.restore({ subscriptionId: "sub_id" });
+await authClient.subscription.list();
+await authClient.subscription.billingPortal();
+```
+
+`subscription.disable` and `subscription.enable` still exist as deprecated aliases in the 2.x line. Prefer `cancel` and `restore` in new code.
+
+### Keep schema behavior stable
+
+The plugin always contributes Paystack product and plan tables:
+
+- `paystackProduct`
+- `paystackPlan`
+
+Subscription tables are included when `subscription.enabled` is true. User and transaction tables are always included. Organization fields are included when `organization.enabled` is true.
+
+Use Better Auth-style schema overrides only to rename models or fields. Do not remove the Paystack product/plan tables unless you are making a breaking major release.
+
+### Use public Better Auth imports in package code
+
+Runtime code should import from public Better Auth entrypoints:
+
+```ts
+import { betterAuth } from "better-auth";
+import { createAuthClient } from "better-auth/client";
+import type { BetterAuthPluginDBSchema } from "better-auth/db";
+```
+
+Do not add runtime imports from `@better-auth/core/*` in this package. Tests can use internals only if no public API covers the case.
+
+## Common Mistakes
+
+### Calling server-only helpers from the browser
+
+Wrong:
+
+```ts
+import { syncPaystackPlans } from "@alexasomba/better-auth-paystack";
+
+await syncPaystackPlans(auth.$context, options);
+```
+
+Correct: call admin helpers from server jobs, cron handlers, CLI scripts, or trusted server routes only.
+
+### Forgetting webhook secret normalization
+
+Prefer the `webhook.secret` option:
+
+```ts
+paystack({
+  secretKey: process.env.PAYSTACK_SECRET_KEY!,
+  webhook: {
+    secret: process.env.PAYSTACK_WEBHOOK_SECRET!,
+  },
+});
+```
+
+`paystackWebhookSecret` is a compatibility alias. New code should not introduce it.
+
+### Treating plans as just display data
+
+Plans are used to validate billing operations and map Paystack plan codes. Include stable `name`, `amount`, `currency`, `interval`, `planCode`, and `paystackId` values when subscriptions are enabled.