@alexasomba/better-auth-paystack 2.4.3 → 2.5.0

package/skills/paystack-tanstack-start/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Better Auth Paystack TanStack Start"
+  short_description: "TanStack Start integration patterns"
+  default_prompt: "Use $paystack-tanstack-start to integrate Better Auth Paystack in a TanStack Start application."
+policy:
+  allow_implicit_invocation: true

package/skills/paystack-testing-fixtures/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: paystack-testing-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.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: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/paystack-testing-fixtures/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Better Auth Paystack Tests"
+  short_description: "Focused tests, mocks, and verification"
+  default_prompt: "Use $paystack-testing-fixtures to choose tests, fixtures, and verification commands for Better Auth Paystack changes."
+policy:
+  allow_implicit_invocation: true

package/skills/paystack-webhooks-events/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: paystack-webhooks-events
+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, reconcilePaystackTransaction, 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.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/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.
+
+For trusted server paths that need to re-verify and apply the plugin's local side effects outside a browser session, call `reconcilePaystackTransaction`:
+
+```ts
+import { reconcilePaystackTransaction } from "@alexasomba/better-auth-paystack";
+
+await reconcilePaystackTransaction(ctx, paystackOptions, {
+  reference,
+  source: "webhook",
+  referenceId,
+});
+```
+
+The helper is suitable for webhook handlers, queue retries, cron jobs, and admin repair actions.
+
+### 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/skills/paystack-webhooks-events/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Better Auth Paystack Webhooks"
+  short_description: "Webhook signatures, events, and reconciliation"
+  default_prompt: "Use $paystack-webhooks-events to implement, debug, or test Paystack webhook event processing."
+policy:
+  allow_implicit_invocation: true

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

@@ -1 +0,0 @@
-{"version":3,"file":"types-DHZSS1K6.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","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":";;;;KAIK,iBAAA,uDAAwE,MAAA,CAC3E,SAAA;EAEE,MAAA,EAAQ,MAAA,CAAO,SAAA,EAAW,gBAAA;EAC1B,gBAAA;EACA,SAAA;AAAA;AAAA,KAIC,kBAAA,GAAqB,iBAAA;AAAA,KAgBrB,mBAAA,GAAsB,iBAAA;AAAA,KAoBtB,UAAA,GAAa,iBAAA;AAAA,KAEb,kBAAA,GAAqB,iBAAA;AAAA,KAErB,cAAA,GAAiB,iBAAA;AAAA,KAejB,WAAA,GAAc,iBAAA;AAAA,KAcP,oBAAA,GAAuB,mBAAA,GACjC,kBAAA,GACA,UAAA,GACA,kBAAA,GACA,cAAA,GACA,WAAA;AAAA,cAqSW,SAAA,GAAa,OAAA,EAAS,eAAA,KAAkB,wBAAA;;;KCpXzCwB,uBAAAA;;;;;UAWKC,mBAAAA;EACbE,EAAAA;EACAC,SAAAA;EACAC,UAAAA;EACAC,WAAAA;EACAC,MAAAA;EACAC,MAAAA;EACAC,QAAAA;EACAC,MAAAA;EACAC,IAAAA;EACAC,OAAAA;EACAC,QAAAA;EACAC,SAAAA,EAAWZ,IAAAA;EACXa,SAAAA,EAAWb,IAAAA;AAAAA;AAAAA,UAEEc,eAAAA;EACbb,EAAAA;EACAc,IAAAA;EACAC,WAAAA;EACAC,KAAAA;EACAV,QAAAA;EACAW,QAAAA;EACAC,SAAAA;EACAhB,UAAAA;EACAiB,IAAAA;EACAT,QAAAA;EACAC,SAAAA,GAAYZ,IAAAA;EACZa,SAAAA,GAAYb,IAAAA;AAAAA;AAAAA,UAiBCyB,YAAAA;EACbxB,EAAAA;EACAc,IAAAA;EACAC,WAAAA;EACAV,MAAAA;EACAC,QAAAA;EACAsB,QAAAA;EACAC,QAAAA;EACA3B,UAAAA;EACA4B,UAAAA;EDcF;;;;ECTEC,WAAAA;EACAC,YAAAA;EACAC,YAAAA;EACAC,SAAAA;IACIC,IAAAA;IACAC,YAAAA,IAAgBC,YAAAA,EAAcZ,YAAAA,KAAiBC,OAAAA;EAAAA;EAEnDY,MAAAA,GAASX,MAAAA;EACTY,QAAAA;EACA7B,QAAAA;EACAC,SAAAA,GAAYZ,IAAAA;EACZa,SAAAA,GAAYb,IAAAA;AAAAA;;;;KAKJyC,sBAAAA,GAAyB3D,oBAAAA;AA1ErC;;;AAAA,KA8EY4D,2BAAAA,GAA8BpD,6BAAAA;AAAAA,KAC9BqD,mCAAAA,GAAsCtD,0CAAAA;AAAAA,UAKjC2D,mBAAAA;EA7EbzC;;;EAiFA0C,OAAAA;EA7EAtC;;;EAiFAuC,KAAAA,EAAOzB,YAAAA,YAAwBE,OAAAA,CAAQF,YAAAA;EA/E5BzB;;;EAmFXmD,gBAAAA;EAjF4B;;;;EAsF5BC,cAAAA;EAnFApC;;;EAuFAqC,sBAAAA,IAA0BE,IAAAA;IACtBD,KAAAA,EAAOb,sBAAAA;IACPH,YAAAA,EAAcZ,YAAAA;IACdjB,IAAAA,EAAMgB,YAAAA;EAAAA,GACP+B,GAAAA,EAAKlF,sBAAAA,KAA2BqD,OAAAA;EACnC8B,qBAAAA,IAAyBF,IAAAA;IACrBD,KAAAA,EAAOb,sBAAAA;IACPH,YAAAA,EAAcZ,YAAAA;IACdjB,IAAAA,EAAMgB,YAAAA;EAAAA,GACP+B,GAAAA,EAAKlF,sBAAAA,KAA2BqD,OAAAA;EACnC+B,oBAAAA,IAAwBH,IAAAA;IACpBD,KAAAA,EAAOb,sBAAAA;IACPH,YAAAA,EAAcZ,YAAAA;EAAAA,GACf8B,GAAAA,EAAKlF,sBAAAA,KAA2BqD,OAAAA;EAvDDD;;;EA2DlCiC,kBAAAA,IAAsBJ,IAAAA;IAClBK,IAAAA,EAAMnF,IAAAA;IACNoF,OAAAA,EAASrF,OAAAA;IACT4B,WAAAA;IACA0D,MAAAA;EAAAA,GACDN,GAAAA,EAAKlF,sBAAAA,KAA2BqD,OAAAA;EAhFnCX;;;EAoFA+C,wBAAAA;EAhFAjC;;;;EAqFAkC,sBAAAA,GAAyBlE,uBAAAA;AAAAA;AAAAA,UAEZmE,eAAAA,yBAAwCE,kBAAAA,GAAqBA,kBAAAA;EA5EtE/B;;;EAgFJgC,SAAAA;EA/EmDzC;;;;EAoFnD0C,qBAAAA;EA/EAzD;;;;EAoFA0D,cAAAA,GAAiBJ,eAAAA;EAnFD;AAKpB;;EAkFIK,OAAAA;IAlFqD;;AAIzD;IAkFQC,MAAAA;IAlFkClF;;;AAC1C;IAsFQmF,QAAAA;IAtF0CpF;;;AAKlD;IAsFQqF,UAAAA;EAAAA;EA9EGjD;;;EAmFPa,YAAAA,GAAeU,mBAAAA;EApEGtB;;;;EAyElBiD,cAAAA;EApEkBjD;;;EAwElBkD,OAAAA,IAAWtB,KAAAA,EAAOxE,oBAAAA,KAAyB6C,OAAAA;EApEhCc;;;EAwEXoC,YAAAA;IACI5B,OAAAA;IACA6B,uBAAAA,IAA2BE,GAAAA;MACvB/E,EAAAA;MACAc,IAAAA;MACAgE,KAAAA;IAAAA,GACDvB,GAAAA,EAAKlF,sBAAAA,KAA2BqD,OAAAA,CAAQC,MAAAA;IAC3CqD,gBAAAA,IAAoB1B,IAAAA;MAChB2B,gBAAAA,EAAkBtD,MAAAA;MAClBiD,YAAAA;IAAAA,GACDrB,GAAAA,EAAKlF,sBAAAA,KAA2BqD,OAAAA;EAAAA;EA1GAF;;;EA+GvC0D,QAAAA;IACIA,QAAAA,GAAWrE,eAAAA,YAA2Ba,OAAAA,CAAQb,eAAAA;EAAAA;EAElDsE,sBAAAA;EACAH,gBAAAA,IAAoB1B,IAAAA;IAChB2B,gBAAAA,EAAkBtD,MAAAA;IAClBgC,IAAAA;EAAAA,GACDJ,GAAAA,EAAKlF,sBAAAA,KAA2BqD,OAAAA;EArG3BrD;;;EAyGR+G,MAAAA,GAAS9G,iBAAAA,CAAkBqB,oBAAAA;AAAAA;AAAAA,UAEd8B,YAAAA;EACbzB,EAAAA;EACAI,MAAAA;EACAiF,cAAAA;EACA7E,IAAAA;EACA8E,WAAAA;EACAC,wBAAAA;EACAjE,oBAAAA;EACAkE,gBAAAA;EACAC,yBAAAA;EACAC,4BAAAA;EACAC,kBAAAA;EACApF,MAAAA;EACAqF,KAAAA;EACAzF,WAAAA;EACA0F,WAAAA,GAAc9F,IAAAA;EACd+F,SAAAA,GAAY/F,IAAAA;EACZgG,iBAAAA;EACAC,UAAAA,GAAajG,IAAAA;EACbkG,QAAAA,GAAWlG,IAAAA;EACXmG,OAAAA;EACAvF,SAAAA,EAAWZ,IAAAA;EACXa,SAAAA,EAAWb,IAAAA;AAAAA;AAAAA,UAEEoG,gCAAAA;EACbC,cAAAA;EACA/F,MAAAA;AAAAA;AAAAA,UAEagG,iCAAAA;EACb9F,MAAAA;EACA+C,IAAAA,EAAMZ,mCAAAA;AAAAA;AAAAA,UAEO4D,kBAAAA;EACb/F,MAAAA;EACAgG,KAAAA;AAAAA;AAAAA,KAEQC,kBAAAA,GAAqBxC,eAAAA,CAAgBE,kBAAAA;;;;;UAKhCA,kBAAAA;EACbwC,WAAAA,EAAaD,IAAAA,CAAKtH,yBAAAA;EAClBwH,QAAAA,EAAUF,IAAAA,CAAK1H,sBAAAA;EACfsD,YAAAA,EAAcoE,IAAAA,CAAKvH,0BAAAA;EACnBuB,OAAAA,EAASgG,IAAAA,CAAKxH,qBAAAA;EACduB,IAAAA,EAAMiG,IAAAA,CAAKzH,kBAAAA;AAAAA"}

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"}