@alexasomba/better-auth-paystack 2.4.0 → 2.4.3

package/skills/subscriptions-and-transactions/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: subscriptions-and-transactions
+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
+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:README.md"
+  - "alexasomba/better-auth-paystack:src/routes.ts"
+  - "alexasomba/better-auth-paystack:src/operations.ts"
+  - "alexasomba/better-auth-paystack:src/client.ts"
+---
+
+## Setup
+
+Enable subscriptions with concrete Paystack plan metadata:
+
+```ts
+import { paystack } from "@alexasomba/better-auth-paystack";
+
+paystack({
+  secretKey: process.env.PAYSTACK_SECRET_KEY!,
+  webhook: {
+    secret: process.env.PAYSTACK_WEBHOOK_SECRET!,
+  },
+  subscription: {
+    enabled: true,
+    plans: [
+      {
+        name: "starter",
+        amount: 250_000,
+        currency: "NGN",
+        interval: "monthly",
+        planCode: "PLN_starter",
+        paystackId: "1001",
+      },
+      {
+        name: "team",
+        amount: 1_000_000,
+        currency: "NGN",
+        interval: "monthly",
+        planCode: "PLN_team",
+        paystackId: "1002",
+        limits: {
+          seats: 10,
+          teams: 3,
+        },
+      },
+    ],
+  },
+});
+```
+
+## Core Patterns
+
+### Initialize and verify a transaction
+
+Use the client plugin for browser-triggered checkout:
+
+```ts
+const initialized = await authClient.transaction.initialize({
+  amount: 250_000,
+  email: "customer@example.com",
+  currency: "NGN",
+  metadata: {
+    product: "starter-pack",
+  },
+});
+
+const verified = await authClient.transaction.verify({
+  reference: initialized.data.reference,
+});
+```
+
+Do not trust a redirect callback alone. Always verify the Paystack reference before granting access or updating billing state.
+
+### Manage subscription lifecycle
+
+Use canonical methods in new code:
+
+```ts
+await authClient.subscription.create({
+  plan: "starter",
+});
+
+await authClient.subscription.upgrade({
+  plan: "team",
+});
+
+await authClient.subscription.cancel({
+  subscriptionId: "subscription_id",
+});
+
+await authClient.subscription.restore({
+  subscriptionId: "subscription_id",
+});
+
+const subscriptions = await authClient.subscription.list();
+```
+
+Deprecated aliases:
+
+- `subscription.disable` maps to `subscription.cancel`
+- `subscription.enable` maps to `subscription.restore`
+
+Keep aliases only for compatibility tests or migration examples.
+
+### Keep renewal and catalog sync server-side
+
+These helpers are exported by the server package and are intentionally not client actions:
+
+```ts
+import {
+  chargeSubscriptionRenewal,
+  syncPaystackPlans,
+  syncPaystackProducts,
+} from "@alexasomba/better-auth-paystack";
+
+export async function runBillingJob(ctx: unknown, options: unknown) {
+  await syncPaystackProducts(ctx, options);
+  await syncPaystackPlans(ctx, options);
+  await chargeSubscriptionRenewal(ctx, options, {
+    subscriptionId: "subscription_id",
+  });
+}
+```
+
+Use cron, background jobs, or trusted server functions. Do not call these from a browser component.
+
+## Common Mistakes
+
+### Mutating Paystack-managed subscriptions like local subscriptions
+
+Seat-based or prorated subscription changes require locally managed subscription state. Paystack-managed subscriptions do not support every local mutation path.
+
+Before implementing seat changes, check whether the target plan is local/seat-aware and whether the operation is supported by the helper being used.
+
+### Skipping webhook verification
+
+Configure `webhook.secret` and let the plugin verify incoming webhook payloads. Do not process Paystack webhook bodies through an unrelated JSON route that bypasses the plugin endpoint.
+
+### Mixing plan name and Paystack plan code
+
+Use `plan.name` for app-facing plan selection and `plan.planCode`/`paystackId` for Paystack identity. Do not send a Paystack plan code where the plugin expects the configured plan name.

package/skills/tanstack-start/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: 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
+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:examples/tanstack/README.md"
+  - "alexasomba/better-auth-paystack:examples/tanstack/src/lib/auth.ts"
+  - "alexasomba/better-auth-paystack:examples/tanstack/src/lib/auth-client.ts"
+  - "alexasomba/better-auth-paystack:examples/tanstack/src/routes/api/auth/$.ts"
+---
+
+## Setup
+
+Create the Better Auth server config with Paystack and `tanstackStartCookies()` last:
+
+```ts
+import { betterAuth } from "better-auth";
+import { tanstackStartCookies } from "better-auth/tanstack-start";
+import { paystack } from "@alexasomba/better-auth-paystack";
+
+export const auth = betterAuth({
+  baseURL: process.env.BETTER_AUTH_URL,
+  plugins: [
+    paystack({
+      secretKey: process.env.PAYSTACK_SECRET_KEY!,
+      webhook: {
+        secret: process.env.PAYSTACK_WEBHOOK_SECRET!,
+      },
+      subscription: {
+        enabled: true,
+        plans: [],
+      },
+    }),
+    tanstackStartCookies(),
+  ],
+});
+```
+
+Wire the catch-all auth route:
+
+```ts
+import { createFileRoute } from "@tanstack/react-router";
+import { auth } from "../../../lib/auth";
+
+export const Route = createFileRoute("/api/auth/$")({
+  server: {
+    handlers: {
+      GET: ({ request }) => auth.handler(request),
+      POST: ({ request }) => auth.handler(request),
+    },
+  },
+});
+```
+
+Create the client plugin:
+
+```ts
+import { createAuthClient } from "better-auth/client";
+import { paystackClient } from "@alexasomba/better-auth-paystack/client";
+
+export const authClient = createAuthClient({
+  plugins: [paystackClient()],
+});
+```
+
+## Core Patterns
+
+### Use Paystack client actions in client components
+
+```tsx
+import { authClient } from "../lib/auth-client";
+
+export function SubscribeButton() {
+  return (
+    <button
+      type="button"
+      onClick={async () => {
+        await authClient.subscription.create({
+          plan: "starter",
+        });
+      }}
+    >
+      Subscribe
+    </button>
+  );
+}
+```
+
+Use client actions for checkout and user-triggered subscription lifecycle calls. Do not import server helpers into React components.
+
+### Use server functions for trusted billing operations
+
+```ts
+import { createServerFn } from "@tanstack/react-start";
+import { getRequestHeaders } from "@tanstack/react-start/server";
+import { auth } from "./auth";
+import { syncPaystackPlans } from "@alexasomba/better-auth-paystack";
+
+export const syncPlans = createServerFn({ method: "POST" }).handler(async () => {
+  const session = await auth.api.getSession({
+    headers: await getRequestHeaders(),
+  });
+
+  if (!session?.user) {
+    throw new Response("Unauthorized", { status: 401 });
+  }
+
+  await syncPaystackPlans(await auth.$context, {
+    secretKey: process.env.PAYSTACK_SECRET_KEY!,
+  });
+
+  return { ok: true };
+});
+```
+
+Pass request headers when Better Auth needs session context.
+
+### Keep Cloudflare Worker dependencies compatible
+
+The TanStack example deploys to Cloudflare Workers. Keep Better Auth companion packages on compatible versions. If `@better-auth/infra` pulls in `@better-auth/sso`, avoid mixing a beta SSO package with stable `better-auth`.
+
+The known safe pin for this package version is:
+
+```yaml
+overrides:
+  "@better-auth/sso": 1.6.9
+```
+
+## Common Mistakes
+
+### Putting `tanstackStartCookies()` before Paystack
+
+`tanstackStartCookies()` should be last in the Better Auth plugin array so cookie handling wraps the final auth behavior.
+
+### Omitting auth headers in server functions
+
+Wrong:
+
+```ts
+const session = await auth.api.getSession();
+```
+
+Correct:
+
+```ts
+const session = await auth.api.getSession({
+  headers: await getRequestHeaders(),
+});
+```
+
+### Debugging only root package builds
+
+The root package can pass `vp pack` while the example Worker build fails. Reproduce Worker issues with:
+
+```bash
+pnpm --filter ./examples/tanstack build
+pnpm --filter ./examples/tanstack exec wrangler deploy --dry-run
+```

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

@@ -1 +0,0 @@
-{"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-C_50YiuM.mjs

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

package/dist/version-C_50YiuM.mjs.map

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