@alexasomba/better-auth-paystack 2.4.3 → 2.4.4

package/README.md

@@ -17,11 +17,12 @@ A TypeScript-first plugin that integrates Paystack into [Better Auth](https://ww
 
 ## AI Agent Skills
 
-This package publishes [TanStack Intent](https://www.npmjs.com/package/@tanstack/intent) skills so AI coding agents can load package-specific guidance for setup, subscriptions, organization billing, and TanStack Start integration.
+This package publishes [TanStack Intent](https://www.npmjs.com/package/@tanstack/intent) skills so AI coding agents can load package-specific guidance for setup, subscriptions, organization billing, TanStack Start integration, client APIs, webhooks, local subscription lifecycle, schema changes, and testing.
 
 ```bash
 npx @tanstack/intent@latest list
 npx @tanstack/intent@latest load @alexasomba/better-auth-paystack#setup
+npx @tanstack/intent@latest load @alexasomba/better-auth-paystack#testing-and-fixtures
 ```
 
 If you use an AI agent, run `npx @tanstack/intent@latest install` in your project so the agent knows how to discover package skills.

package/dist/client.mjs

@@ -1,4 +1,4 @@
-import { t as PACKAGE_VERSION } from "./version-GQ15aLQo.mjs";
+import { t as PACKAGE_VERSION } from "./version-LjwMcXaE.mjs";
 //#region src/client.ts
 /**
 * Better Auth Paystack Client Plugin

package/dist/index.d.mts

@@ -329,7 +329,7 @@ declare const getConfig: <P extends string = "/get-config">(options: AnyPaystack
 }>;
 //#endregion
 //#region src/version.d.ts
-declare const PACKAGE_VERSION = "2.4.3";
+declare const PACKAGE_VERSION = "2.4.4";
 //#endregion
 //#region src/operations.d.ts
 declare function syncPaystackProducts(ctx: GenericEndpointContext, options: AnyPaystackOptions): Promise<PaystackSyncResult>;

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { t as PACKAGE_VERSION } from "./version-GQ15aLQo.mjs";
+import { t as PACKAGE_VERSION } from "./version-LjwMcXaE.mjs";
 import { HIDE_METADATA, defineErrorCodes } from "better-auth";
 import { defu } from "defu";
 import { APIError, createAuthEndpoint, createAuthMiddleware, getSessionFromCtx, originCheck, sessionMiddleware } from "better-auth/api";

package/dist/version-LjwMcXaE.mjs

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

package/dist/version-LjwMcXaE.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-LjwMcXaE.mjs","names":[],"sources":["../src/version.ts"],"sourcesContent":["export const PACKAGE_VERSION = \"2.4.4\"; // 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.4.4",
   "description": "Production-ready Paystack billing plugin for Better Auth. Supports subscriptions, one-time payments, organization billing, secure webhooks and more",
   "keywords": [
     "africa",

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

@@ -4,7 +4,7 @@ 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.4.4" # 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/client-api-contract/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: client-api-contract
+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.4.3" # 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/local-subscription-lifecycle/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: local-subscription-lifecycle
+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.4.3" # 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/organization-billing/SKILL.md

@@ -4,7 +4,7 @@ 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.3" # x-release-please-version
+library_version: "2.4.4" # 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/schema-and-migrations/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: schema-and-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.4.3" # 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/setup/SKILL.md

@@ -4,7 +4,7 @@ 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.4.4" # 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/subscriptions-and-transactions/SKILL.md

@@ -4,7 +4,7 @@ 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.
 type: core
 library: "@alexasomba/better-auth-paystack"
-library_version: "2.4.3" # x-release-please-version
+library_version: "2.4.4" # 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/tanstack-start/SKILL.md

@@ -4,7 +4,7 @@ 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.4.4" # 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/testing-and-fixtures/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: testing-and-fixtures
+description: >
+  Test @alexasomba/better-auth-paystack changes. Use for choosing focused vp test commands, Better Auth test clients, in-memory adapters, mocked Paystack SDK responses, webhook signatures, TanStack example tests, integration tests, type-safety tests, and verification before landing changes.
+type: core
+library: "@alexasomba/better-auth-paystack"
+library_version: "2.4.3" # 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:test/paystack.test.ts"
+  - "alexasomba/better-auth-paystack:test/local_subscription.test.ts"
+  - "alexasomba/better-auth-paystack:test/seat_billing.test.ts"
+  - "alexasomba/better-auth-paystack:test/typesafety.test.ts"
+  - "alexasomba/better-auth-paystack:examples/tanstack/src/__tests__"
+---
+
+## Test Selection
+
+Use `vp test` instead of invoking Vitest directly.
+
+Focused suites:
+
+- core plugin routes, schema, webhooks, products, org billing: `vp test test/paystack.test.ts`
+- local-managed subscriptions and authorization capture: `vp test test/local_subscription.test.ts`
+- seat billing, proration, local renewal UI paths: `vp test test/seat_billing.test.ts`
+- planCode and organization integration regressions: `vp test test/plancode-and-org.integration.test.ts`
+- package type contracts: `vp test test/typesafety.test.ts`
+- TanStack example components/routes: `pnpm --filter ./examples/tanstack test`
+
+Broad gates before landing:
+
+```bash
+vp check
+vp test
+```
+
+Run integration tests only when needed and credentials/environment are available:
+
+```bash
+RUN_INTEGRATION_TESTS=1 vp test
+```
+
+## Fixture Patterns
+
+### Mock Paystack SDK at the adapter boundary
+
+Mocks should resemble `@alexasomba/paystack-node` grouped operations:
+
+```ts
+const paystackClient = {
+  transaction: {
+    initialize: vi.fn().mockResolvedValue({ data: { reference: "REF", authorization_url: "..." } }),
+    verify: vi.fn().mockResolvedValue({ data: { status: "success", reference: "REF" } }),
+    chargeAuthorization: vi.fn(),
+  },
+  subscription: {
+    create: vi.fn(),
+    fetch: vi.fn(),
+    disable: vi.fn(),
+    enable: vi.fn(),
+    manageLink: vi.fn(),
+  },
+};
+```
+
+The package supports SDK `PaystackResponse` objects and legacy/custom nested `{ data }` test shapes.
+Do not overfit tests to only one response wrapper unless the change is specifically about
+`unwrapSdkResult`.
+
+### Sign webhooks like Paystack
+
+Webhook tests should create the exact JSON payload string, sign it with HMAC SHA-512, and send the
+signature in `x-paystack-signature`.
+
+### Use Better Auth client behavior realistically
+
+For browser-style flows, sign up/sign in and pass cookies into the auth client. Use `{ throw: true }`
+when the test should fail immediately on Better Auth errors.
+
+## Common Mistakes
+
+### Only testing the root package after example changes
+
+The TanStack example has its own component and route tests. Run its test/build command when touching
+`examples/tanstack`.
+
+### Skipping type tests for client API changes
+
+Any change to `src/client.ts`, route return shapes, or public exports should run
+`test/typesafety.test.ts`.
+
+### Assuming live Paystack is available
+
+Most tests should use mocked SDK operations. Keep live/integration tests opt-in.

package/skills/webhooks-and-event-processing/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: webhooks-and-event-processing
+description: >
+  Implement, debug, or test @alexasomba/better-auth-paystack webhook handling. Use for Paystack webhook signatures, trusted IP checks, webhook.secret/paystackWebhookSecret behavior, charge.success, subscription.create, subscription.disable, subscription.enable, product quantity updates, subscription status changes, metadata parsing, and event hooks.
+type: core
+library: "@alexasomba/better-auth-paystack"
+library_version: "2.4.3" # 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/routes.ts"
+  - "alexasomba/better-auth-paystack:src/types.ts"
+  - "alexasomba/better-auth-paystack:src/utils.ts"
+  - "alexasomba/better-auth-paystack:test/paystack.test.ts"
+  - "alexasomba/better-auth-paystack:test/seat_billing.test.ts"
+---
+
+## Webhook Contract
+
+The Better Auth endpoint is registered as `auth.api.paystackWebhook` and mounted under
+`/api/auth/paystack/webhook` by the plugin. Always send the raw JSON body that Paystack signed.
+
+Signature verification uses HMAC SHA-512 over the raw request body. Secret precedence is:
+
+1. `webhook.secret`
+2. `paystackWebhookSecret`
+3. `secretKey`
+
+Prefer `webhook.secret` in new code. Keep `paystackWebhookSecret` only for compatibility.
+
+## Core Patterns
+
+### Verify before processing
+
+Webhook code must reject invalid signatures before parsing business effects:
+
+```ts
+const signature = createHmac("sha512", webhookSecret).update(payload).digest("hex");
+```
+
+If `webhook.verifyIP` is true, the request must come from `webhook.trustedIPs` or the built-in
+Paystack IP allowlist. Preserve support for common forwarded IP headers when changing this path.
+
+### Treat `charge.success` as reconciliation
+
+`charge.success` can update multiple local records:
+
+- mark a pending transaction as `success`
+- finalize local subscription checkout when metadata identifies a plan
+- apply checkout-based proration metadata with `type: "proration"`
+- capture `authorization.authorization_code` for local renewals
+- decrement one-time product quantity when product metadata is present
+
+Do not grant paid access from a redirect alone. The callback should verify the transaction and
+webhooks should reconcile persisted state.
+
+### Handle subscription events idempotently
+
+Paystack subscription events should update matching subscriptions without assuming one delivery:
+
+- `subscription.create`: activate or update the subscription and call creation hooks
+- `subscription.disable`: mark cancellation/non-renewal and call cancel hooks
+- `subscription.enable`: restore active state when Paystack re-enables a subscription
+
+Match by known Paystack identifiers first, then metadata such as `referenceId` and plan when needed.
+Avoid creating duplicate subscriptions on repeated webhook delivery.
+
+## Common Mistakes
+
+### Parsing body before signature verification
+
+Do not route Paystack webhooks through a generic JSON handler that loses the exact signed payload.
+The signature must be checked against the same raw string Paystack sent.
+
+### Assuming all metadata is an object
+
+Paystack metadata may arrive as an object or a JSON string. Existing route code handles both forms.
+Keep that tolerance when changing metadata handling.
+
+### Forgetting product side effects
+
+Webhook work is not subscription-only. Successful product purchases must update transaction state and
+respect product quantity/unlimited settings.
+
+## Verification
+
+Run focused tests after webhook changes:
+
+```bash
+vp test test/paystack.test.ts
+vp test test/seat_billing.test.ts
+```
+
+Also run `vp check` before landing broad route or type changes.

package/dist/version-GQ15aLQo.mjs

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

package/dist/version-GQ15aLQo.mjs.map

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