@alexasomba/better-auth-paystack 2.4.3 → 2.5.0

package/dist/{types-DHZSS1K6.d.mts → types-D-iIbe9E.d.mts}

@@ -193,6 +193,13 @@ interface PaystackOptions<TPaystackClient extends PaystackClientLike = PaystackC
    */
   organization?: {
     enabled?: boolean;
+    /**
+     * Organization member roles allowed to manage billing when `subscription.authorizeReference`
+     * is not provided.
+     *
+     * @default ["owner", "admin"]
+     */
+    billingRoles?: string[];
     getCustomerCreateParams?: (org: {
       id: string;
       name: string;
@@ -268,5 +275,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, getSchema as p, ChargeRecurringSubscriptionResult as r, PaystackProduct as s, AnyPaystackOptions as t, PaystackTransactionResponse as u };
-//# sourceMappingURL=types-DHZSS1K6.d.mts.map
+export { PaystackOptions as a, PaystackSyncResult as c, Session as d, Subscription as f, getSchema as h, PaystackClientLike as i, PaystackTransaction as l, User as m, ChargeRecurringSubscriptionInput as n, PaystackPlan as o, SubscriptionOptions as p, ChargeRecurringSubscriptionResult as r, PaystackProduct as s, AnyPaystackOptions as t, PaystackTransactionResponse as u };
+//# sourceMappingURL=types-D-iIbe9E.d.mts.map

package/dist/types-D-iIbe9E.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-D-iIbe9E.d.mts","names":["GenericEndpointContext","InferOptionSchema","Session","User","Organization","Member","PaystackPaths","PaystackResponse","PaystackWebhookEvent","PaystackClient","PaystackCustomerClient","PaystackPlanClient","PaystackProductClient","PaystackSubscriptionClient","PaystackTransactionClient","TransactionChargeAuthorizationResponseData","TransactionVerifyResponseData","PlanListResponseData","CustomerCreateResponseData","SubscriptionListResponseData","ProductFetchResponseData","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","PaystackChargeAuthorizationResponse","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","billingRoles","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-DRyh6Dnz.mjs

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

package/dist/version-DRyh6Dnz.mjs.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexasomba/better-auth-paystack",
-  "version": "2.4.3",
+  "version": "2.5.0",
   "description": "Production-ready Paystack billing plugin for Better Auth. Supports subscriptions, one-time payments, organization billing, secure webhooks and more",
   "keywords": [
     "africa",
@@ -66,53 +66,57 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test run",
+    "test:integration": "RUN_INTEGRATION_TESTS=1 vp test run",
+    "coverage": "vp test run --coverage",
+    "lint": "vp lint src",
+    "lint:package": "publint run --strict",
+    "lint:types": "attw --profile esm-only --pack .",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "skills:install": "skills-npm --cwd examples/tanstack --yes --force",
+    "skills:dry-run": "skills-npm --cwd examples/tanstack --dry-run --yes --agents universal --force"
+  },
   "dependencies": {
-    "@alexasomba/paystack-node": "^1.10.1",
-    "better-call": "~1.3.5",
-    "defu": "^6.1.7",
-    "zod": "^4.4.3"
+    "@alexasomba/paystack-node": "catalog:",
+    "better-call": "catalog:",
+    "defu": "catalog:",
+    "zod": "catalog:"
   },
   "devDependencies": {
-    "@arethetypeswrong/cli": "^0.18.2",
-    "@better-fetch/fetch": "^1.1.21",
+    "@arethetypeswrong/cli": "catalog:",
+    "@better-fetch/fetch": "catalog:",
     "@commitlint/cli": "^21.0.0",
     "@commitlint/config-conventional": "^21.0.0",
-    "@eslint/compat": "^2.1.0",
-    "@eslint/js": "^10.0.1",
+    "@eslint/compat": "catalog:",
+    "@eslint/js": "catalog:",
     "@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.3.0",
-    "eslint-plugin-react-hooks": "^7.1.1",
-    "eslint-plugin-unicorn": "^64.0.0",
-    "publint": "^0.3.20",
-    "typescript": "^6.0.3",
-    "typescript-eslint": "^8.59.2",
-    "vite-plus": "^0.1.20",
+    "@types/node": "catalog:",
+    "@typescript-eslint/eslint-plugin": "catalog:",
+    "@typescript-eslint/parser": "catalog:",
+    "@vitest/coverage-v8": "catalog:",
+    "better-auth": "catalog:",
+    "eslint-plugin-import-x": "catalog:",
+    "eslint-plugin-promise": "catalog:",
+    "eslint-plugin-react-hooks": "catalog:",
+    "eslint-plugin-unicorn": "catalog:",
+    "publint": "catalog:",
+    "skills-npm": "^1.1.1",
+    "typescript": "catalog:",
+    "typescript-eslint": "catalog:",
+    "vite-plus": "catalog:",
     "vitest": "npm:@voidzero-dev/vite-plus-test@^0.1.20"
   },
   "peerDependencies": {
     "better-auth": "^1.6.9"
   },
   "optionalDependencies": {
-    "@rollup/rollup-linux-x64-gnu": "^4.60.3"
+    "@rollup/rollup-linux-x64-gnu": "catalog:"
   },
   "engines": {
-    "node": ">=24.0.0"
+    "node": ">=22.0.0"
   },
-  "scripts": {
-    "build": "vp pack",
-    "dev": "vp pack --watch",
-    "test": "vp test run",
-    "test:integration": "RUN_INTEGRATION_TESTS=1 vp test run",
-    "coverage": "vp test run --coverage",
-    "lint": "vp lint src",
-    "lint:package": "publint run --strict",
-    "lint:types": "attw --profile esm-only --pack .",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
-  }
-}
+  "packageManager": "pnpm@11.0.9"
+}

package/skills/{setup → better-auth-paystack-setup}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: setup
+name: better-auth-paystack-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.3" # x-release-please-version
+library_version: "2.5.0" # x-release-please-version
 license: "MIT"
 compatibility: "Node.js >=24.0.0; better-auth ^1.6.9; @alexasomba/paystack-node 1.10.x; @alexasomba/better-auth-paystack >=2.4.2 <3.0.0"
 sources:

package/skills/better-auth-paystack-setup/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Better Auth Paystack Setup"
+  short_description: "Server and client plugin setup guidance"
+  default_prompt: "Use $better-auth-paystack-setup to configure the Better Auth Paystack server and client plugins."
+policy:
+  allow_implicit_invocation: true

package/skills/{subscriptions-and-transactions → paystack-billing-flows}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: subscriptions-and-transactions
+name: paystack-billing-flows
 description: >
-  Build Paystack transaction and subscription flows with @alexasomba/better-auth-paystack. Use for initialize/verify transaction, create/upgrade/cancel/restore/list subscriptions, products/plans, billing portal links, webhooks, chargeSubscriptionRenewal, syncPaystackProducts, and syncPaystackPlans.
+  Build Paystack transaction and subscription flows with @alexasomba/better-auth-paystack. Use for initialize/verify transaction, create/upgrade/cancel/restore/list subscriptions, products/plans, billing portal links, webhooks, reconcilePaystackTransaction, chargeSubscriptionRenewal, syncPaystackProducts, and syncPaystackPlans.
 type: core
 library: "@alexasomba/better-auth-paystack"
-library_version: "2.4.3" # x-release-please-version
+library_version: "2.5.0" # x-release-please-version
 license: "MIT"
 compatibility: "Node.js >=24.0.0; better-auth ^1.6.9; @alexasomba/paystack-node 1.10.x; @alexasomba/better-auth-paystack >=2.4.2 <3.0.0"
 sources:
@@ -115,11 +115,17 @@ These helpers are exported by the server package and are intentionally not clien
 ```ts
 import {
   chargeSubscriptionRenewal,
+  reconcilePaystackTransaction,
   syncPaystackPlans,
   syncPaystackProducts,
 } from "@alexasomba/better-auth-paystack";
 
 export async function runBillingJob(ctx: unknown, options: unknown) {
+  await reconcilePaystackTransaction(ctx, options, {
+    reference: "paystack_reference",
+    source: "queue",
+    referenceId: "user_or_org_id",
+  });
   await syncPaystackProducts(ctx, options);
   await syncPaystackPlans(ctx, options);
   await chargeSubscriptionRenewal(ctx, options, {
@@ -130,6 +136,8 @@ export async function runBillingJob(ctx: unknown, options: unknown) {
 
 Use cron, background jobs, or trusted server functions. Do not call these from a browser component.
 
+`reconcilePaystackTransaction` verifies the Paystack reference and applies the same local transaction, customer, product, subscription, trial, and proration side effects used by the browser verify endpoint. Use it for webhook handlers, queue retries, cron jobs, and admin repair actions.
+
 ## Common Mistakes
 
 ### Mutating Paystack-managed subscriptions like local subscriptions

package/skills/paystack-billing-flows/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Better Auth Paystack Billing Flows"
+  short_description: "Transactions, subscriptions, and billing flows"
+  default_prompt: "Use $paystack-billing-flows to build Paystack transaction, subscription, product, and billing portal flows."
+policy:
+  allow_implicit_invocation: true

package/skills/{billing-catalog-and-limits → paystack-catalog-limits}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: billing-catalog-and-limits
+name: paystack-catalog-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.3" # x-release-please-version
+library_version: "2.5.0" # x-release-please-version
 license: "MIT"
 compatibility: "Node.js >=24.0.0; better-auth ^1.6.9; @alexasomba/paystack-node 1.10.x; @alexasomba/better-auth-paystack >=2.4.2 <3.0.0"
 sources:

package/skills/paystack-catalog-limits/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Better Auth Paystack Catalog"
+  short_description: "Products, plans, trials, seats, and limits"
+  default_prompt: "Use $paystack-catalog-limits to configure Paystack products, subscription plans, free trials, seat billing, and resource limits."
+policy:
+  allow_implicit_invocation: true

package/skills/paystack-client-api/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: paystack-client-api
+description: >
+  Modify or use the @alexasomba/better-auth-paystack browser client API. Use for paystackClient(), authClient.paystack, authClient.transaction, authClient.subscription, initializeTransaction, verifyTransaction, listTransactions, listSubscriptions, listProducts, listPlans, subscription billingPortal/manageLink, cancel/restore aliases, BetterFetch throw option return types, and deprecated disable/enable behavior.
+type: core
+library: "@alexasomba/better-auth-paystack"
+library_version: "2.5.0" # x-release-please-version
+license: "MIT"
+compatibility: "Node.js >=24.0.0; better-auth ^1.6.9; @alexasomba/paystack-node 1.10.x; @alexasomba/better-auth-paystack >=2.4.2 <3.0.0"
+sources:
+  - "alexasomba/better-auth-paystack:src/client.ts"
+  - "alexasomba/better-auth-paystack:src/routes.ts"
+  - "alexasomba/better-auth-paystack:test/typesafety.test.ts"
+  - "alexasomba/better-auth-paystack:examples/tanstack/src/lib/paystack-client.ts"
+---
+
+## Client Contract
+
+Install the browser plugin from the client entrypoint:
+
+```ts
+import { createAuthClient } from "better-auth/client";
+import { paystackClient } from "@alexasomba/better-auth-paystack/client";
+
+export const authClient = createAuthClient({
+  plugins: [paystackClient({ subscription: true })],
+});
+```
+
+The plugin exposes three public surfaces:
+
+- `authClient.paystack`: top-level Paystack actions
+- `authClient.transaction`: transaction namespace
+- `authClient.subscription`: subscription namespace
+
+`authClient.paystack.paystack` points back to the same actions object for compatibility.
+
+## Core Patterns
+
+### Prefer stable names in examples
+
+Use these methods in new examples and application code:
+
+```ts
+await authClient.paystack.config();
+await authClient.paystack.listProducts();
+await authClient.paystack.listPlans();
+await authClient.paystack.initializeTransaction({ amount: 500_000 });
+await authClient.paystack.verifyTransaction({ reference: "REF" });
+await authClient.paystack.listTransactions();
+
+await authClient.transaction.initialize({ amount: 500_000 });
+await authClient.transaction.verify({ reference: "REF" });
+await authClient.transaction.list();
+
+await authClient.subscription.create({ plan: "starter" });
+await authClient.subscription.upgrade({ plan: "team" });
+await authClient.subscription.list();
+await authClient.subscription.billingPortal({ subscriptionCode: "SUB_code" });
+await authClient.subscription.cancel({ subscriptionCode: "SUB_code", atPeriodEnd: true });
+await authClient.subscription.restore({ subscriptionCode: "SUB_code" });
+```
+
+`subscription.manageLink` is an alias for `subscription.billingPortal`.
+
+### Preserve deprecated aliases
+
+`subscription.disable` maps to `subscription.cancel`.
+`subscription.enable` maps to `subscription.restore`.
+
+Keep these aliases in the 2.x line for compatibility, but do not introduce them in new examples.
+
+### Respect BetterFetch return typing
+
+Methods use `FetchResult<T, O>`:
+
+- with `{ throw: true }`, the promise resolves to `T`
+- without `{ throw: true }`, the promise resolves to `BetterFetchResponse<T>`
+
+When changing method signatures, update both the interface and implementation, then run type tests.
+
+## Common Mistakes
+
+### Using old `getConfig`
+
+The stable method is `authClient.paystack.config()`. Do not add new examples that call
+`authClient.paystack.getConfig()`.
+
+### Passing query data in the body for list endpoints
+
+List endpoints use GET with query data:
+
+```ts
+await authClient.subscription.list({ query: { referenceId: "org_123" } });
+await authClient.transaction.list({ query: { referenceId: "org_123" } });
+```
+
+### Importing the server package in browser code
+
+Browser code should import only `@alexasomba/better-auth-paystack/client`. Server helpers such as
+`syncPaystackPlans` and `chargeSubscriptionRenewal` belong in server functions, cron jobs, or trusted
+routes.
+
+## Verification
+
+Run these after client API changes:
+
+```bash
+vp test test/typesafety.test.ts
+vp test test/paystack.test.ts
+```
+
+Run TanStack example tests when examples or client usage are changed:
+
+```bash
+pnpm --filter ./examples/tanstack test
+```

package/skills/paystack-client-api/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Better Auth Paystack Client API"
+  short_description: "Browser client methods and return contracts"
+  default_prompt: "Use $paystack-client-api to wire or review authClient Paystack, transaction, and subscription browser APIs."
+policy:
+  allow_implicit_invocation: true

package/skills/paystack-local-subscriptions/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: paystack-local-subscriptions
+description: >
+  Implement, debug, or test local-managed subscription behavior in @alexasomba/better-auth-paystack. Use for local plans without planCode, saved authorization renewal, chargeSubscriptionRenewal, seat billing, prorateAndCharge, pendingPlan, LOC_ subscription codes, trial transitions, schedule-at-period-end upgrades, and Paystack-managed vs local-managed behavior.
+type: core
+library: "@alexasomba/better-auth-paystack"
+library_version: "2.5.0" # x-release-please-version
+license: "MIT"
+compatibility: "Node.js >=24.0.0; better-auth ^1.6.9; @alexasomba/paystack-node 1.10.x; @alexasomba/better-auth-paystack >=2.4.2 <3.0.0"
+sources:
+  - "alexasomba/better-auth-paystack:src/subscription-lifecycle.ts"
+  - "alexasomba/better-auth-paystack:src/operations.ts"
+  - "alexasomba/better-auth-paystack:src/routes.ts"
+  - "alexasomba/better-auth-paystack:src/utils.ts"
+  - "alexasomba/better-auth-paystack:test/local_subscription.test.ts"
+  - "alexasomba/better-auth-paystack:test/seat_billing.test.ts"
+---
+
+## Local Subscription Model
+
+A plan without `planCode` is locally managed. The plugin stores subscription state in the Better Auth
+database and charges future renewals with a saved Paystack authorization code.
+
+Local-managed subscriptions are required for:
+
+- seat-based local billing
+- prorated mid-cycle seat or plan upgrades
+- trusted backend renewal jobs through `chargeSubscriptionRenewal`
+- local trial and pending plan transitions
+
+Use Paystack-native `planCode` plans for simple fixed recurring billing.
+
+## Core Patterns
+
+### Capture reusable authorization during verification
+
+Local subscriptions become renewable after transaction verification or webhook reconciliation stores
+`authorization.authorization_code` on the subscription. If the authorization is absent, renewal must
+fail with a clear error instead of inventing a charge path.
+
+### Use server-only renewal helpers
+
+`chargeSubscriptionRenewal(ctx, options, { subscriptionId })` is for cron jobs, admin server
+functions, or trusted server routes. Never expose it directly as a browser action.
+
+Before charging, verify the caller can manage the subscription reference. For organization billing,
+only owners/admins should trigger renewals.
+
+### Prorate only local active subscriptions
+
+`prorateAndCharge` is handled by `handleProratedUpgrade`.
+
+The existing active subscription must have:
+
+- status `active`
+- a Paystack or local subscription code
+- `periodStart` and `periodEnd`
+- local-management compatibility for plan or seat changes
+
+If a saved authorization exists, the prorated amount is charged immediately. If not, the code creates
+a checkout transaction and applies the upgrade after the reference is verified.
+
+Paystack minimum charge behavior matters. If the prorated amount is below the supported minimum,
+surface a BAD_REQUEST and advise scheduling the change for period end.
+
+### Preserve pending plan semantics
+
+Scheduled changes should use `pendingPlan` rather than silently changing the active plan. Immediate
+local changes should update `plan`, `seats`, and transaction reference consistently.
+
+## Common Mistakes
+
+### Adding `planCode` to a local billing plan
+
+Do not add `planCode` to a plan that needs local seat billing, prorated upgrades, or local renewals.
+That turns the plan into a Paystack-managed subscription path.
+
+### Updating seats for Paystack-managed subscriptions
+
+Seat and proration helpers intentionally reject Paystack-managed subscriptions. Use local-managed
+plans for seat-aware billing.
+
+### Charging renewals from client components
+
+The client may trigger checkout. Renewal jobs require trusted server code and a validated session or
+job context.
+
+## Verification
+
+Run focused tests after lifecycle changes:
+
+```bash
+vp test test/local_subscription.test.ts
+vp test test/seat_billing.test.ts
+```
+
+Run `vp test test/paystack.test.ts` when route behavior, trials, or organization billing are touched.

package/skills/paystack-local-subscriptions/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Better Auth Paystack Local Subs"
+  short_description: "Local subscriptions, renewals, and proration"
+  default_prompt: "Use $paystack-local-subscriptions to implement or debug local-managed Paystack subscription lifecycle behavior."
+policy:
+  allow_implicit_invocation: true

package/skills/{organization-billing → paystack-organization-billing}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: organization-billing
+name: paystack-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.
+  Configure organization billing in @alexasomba/better-auth-paystack. Use for organization.enabled, Better Auth organization plugin setup, owner/admin default billing authorization, organization.billingRoles, subscription.authorizeReference, organization Paystack customers, seats, invitations, members, and team limits.
 type: core
 library: "@alexasomba/better-auth-paystack"
-library_version: "2.4.3" # x-release-please-version
+library_version: "2.5.0" # x-release-please-version
 license: "MIT"
 compatibility: "Node.js >=24.0.0; better-auth ^1.6.9; @alexasomba/paystack-node 1.10.x; @alexasomba/better-auth-paystack >=2.4.2 <3.0.0"
 sources:
@@ -50,6 +50,7 @@ export const auth = betterAuth({
       },
       organization: {
         enabled: true,
+        billingRoles: ["owner", "admin", "billing"],
       },
     }),
   ],
@@ -64,9 +65,29 @@ When `subscription.authorizeReference` is not supplied, organization billing act
 
 Ordinary members are rejected by default. Do not write UI or tests that assume any member can create, upgrade, cancel, or restore organization subscriptions.
 
+### Add trusted billing roles without replacing the default
+
+Use `organization.billingRoles` when a product needs a role such as `billing`, `finance`, or `accounting` to manage organization billing while preserving the built-in user self-access, organization membership lookup, and action scoping.
+
+```ts
+paystack({
+  secretKey: process.env.PAYSTACK_SECRET_KEY!,
+  subscription: {
+    enabled: true,
+    plans: [],
+  },
+  organization: {
+    enabled: true,
+    billingRoles: ["owner", "admin", "billing"],
+  },
+});
+```
+
+Role matching supports Better Auth string roles, comma-separated role strings like `"member,billing"`, and array roles like `["member", "billing"]`.
+
 ### Override authorization explicitly for custom workflows
 
-Use `subscription.authorizeReference` when a product intentionally allows non-owner/admin billing access:
+Use `subscription.authorizeReference` when a product needs lower-level policy checks that cannot be represented as organization roles:
 
 ```ts
 paystack({

package/skills/paystack-organization-billing/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Better Auth Paystack Org Billing"
+  short_description: "Organization billing, seats, and access"
+  default_prompt: "Use $paystack-organization-billing to configure Paystack billing for Better Auth organizations, seats, and admin access."
+policy:
+  allow_implicit_invocation: true

package/skills/paystack-schema-migrations/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: paystack-schema-migrations
+description: >
+  Modify or review @alexasomba/better-auth-paystack database schema behavior. Use for paystackProduct, paystackPlan, paystackTransaction, subscription, user.paystackCustomerCode, organization.paystackCustomerCode/email, Better Auth schema overrides, mergeSchema behavior, migrations, indexes, unique fields, and backward-compatible table or field changes.
+type: core
+library: "@alexasomba/better-auth-paystack"
+library_version: "2.5.0" # x-release-please-version
+license: "MIT"
+compatibility: "Node.js >=24.0.0; better-auth ^1.6.9; @alexasomba/paystack-node 1.10.x; @alexasomba/better-auth-paystack >=2.4.2 <3.0.0"
+sources:
+  - "alexasomba/better-auth-paystack:src/schema.ts"
+  - "alexasomba/better-auth-paystack:src/types.ts"
+  - "alexasomba/better-auth-paystack:test/paystack.test.ts"
+  - "alexasomba/better-auth-paystack:test/typesafety.test.ts"
+---
+
+## Schema Contract
+
+The plugin contributes Better Auth schema through `getSchema(options)`.
+
+Always included:
+
+- `user.paystackCustomerCode`
+- `paystackTransaction`
+- `paystackProduct`
+- `paystackPlan`
+
+Included when `subscription.enabled` is true:
+
+- `subscription`
+
+Included when `organization.enabled` is true:
+
+- `organization.paystackCustomerCode`
+- `organization.email`
+
+Product and plan tables are intentionally always present. Do not make them optional in a
+compatibility-preserving release.
+
+## Core Patterns
+
+### Use schema overrides only for Better Auth-supported customization
+
+Consumers can pass `options.schema` and the plugin merges it with the default schema via
+`mergeSchema`. Use this for model/field naming and migration metadata, not for removing core billing
+state.
+
+When subscriptions are disabled, `getSchema` strips a user-provided `subscription` override before
+merging so the subscription model is not reintroduced accidentally.
+
+### Preserve field compatibility
+
+Schema changes affect persisted billing state. Treat these as migration-sensitive:
+
+- changing required fields
+- changing uniqueness or indexes
+- renaming `paystack*` identity fields
+- changing transaction `reference` uniqueness
+- changing subscription `paystackSubscriptionCode` uniqueness
+- changing product/plan `paystackId` or `planCode` uniqueness
+
+Prefer additive optional fields in minor releases. Required field changes need clear migrations and
+major-version scrutiny.
+
+### Keep TypeScript schema exports aligned
+
+`PaystackPluginSchema`, individual schema exports, and `PaystackOptions["schema"]` should stay in
+sync. If a field is added to a schema table, update the corresponding TypeScript table type in
+`src/schema.ts`.
+
+## Common Mistakes
+
+### Removing catalog tables when products are unused
+
+The package supports catalog sync and discovery. `paystackProduct` and `paystackPlan` remain part of
+the plugin schema even if a specific app only uses subscriptions or only uses transactions.
+
+### Reintroducing subscription schema when subscriptions are disabled
+
+Keep the guard in `getSchema` that removes `options.schema.subscription` unless
+`subscription.enabled` is true.
+
+### Forgetting organization schema conditions
+
+Organization billing fields should only be added when `organization.enabled` is true.
+
+## Verification
+
+Run schema and type tests after schema changes:
+
+```bash
+vp test test/paystack.test.ts test/typesafety.test.ts
+vp check
+```

package/skills/paystack-schema-migrations/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Better Auth Paystack Schema"
+  short_description: "Database schema and migration guidance"
+  default_prompt: "Use $paystack-schema-migrations to review or change Better Auth Paystack schema and migration behavior."
+policy:
+  allow_implicit_invocation: true

package/skills/{tanstack-start → paystack-tanstack-start}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: tanstack-start
+name: paystack-tanstack-start
 description: >
   Integrate @alexasomba/better-auth-paystack in TanStack Start. Use for Better Auth API routes, tanstackStartCookies(), server functions, getRequestHeaders(), authClient Paystack actions, admin billing server functions, and Cloudflare Workers deployment.
 type: composition
 library: "@alexasomba/better-auth-paystack"
-library_version: "2.4.3" # x-release-please-version
+library_version: "2.5.0" # x-release-please-version
 license: "MIT"
 compatibility: "Node.js >=24.0.0; better-auth ^1.6.9; @alexasomba/paystack-node 1.10.x; @alexasomba/better-auth-paystack >=2.4.2 <3.0.0"
 sources: