@alexasomba/better-auth-paystack 2.4.0 → 2.4.1

package/README.md

@@ -15,6 +15,17 @@ A TypeScript-first plugin that integrates Paystack into [Better Auth](https://ww
 
 [**Live Demo (Tanstack Start)**](https://better-auth-paystack.gittech.workers.dev) | [**Source Code**](https://github.com/alexasomba/better-auth-paystack/tree/main/examples/tanstack)
 
+## 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.
+
+```bash
+npx @tanstack/intent@latest list
+npx @tanstack/intent@latest load @alexasomba/better-auth-paystack#setup
+```
+
+If you use an AI agent, run `npx @tanstack/intent@latest install` in your project so the agent knows how to discover package skills.
+
 ## Features
 
 - [x] **Billing Patterns**: Support for Paystack-native plans, local-managed subscriptions, and one-time payments (products/amounts).

package/dist/client.mjs

@@ -1,4 +1,4 @@
-import { t as PACKAGE_VERSION } from "./version-C_50YiuM.mjs";
+import { t as PACKAGE_VERSION } from "./version-DpVME9MV.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.3.0";
+declare const PACKAGE_VERSION = "2.4.1";
 //#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-C_50YiuM.mjs";
+import { t as PACKAGE_VERSION } from "./version-DpVME9MV.mjs";
 import { HIDE_METADATA, defineErrorCodes, logger } from "better-auth";
 import { defu } from "defu";
 import { APIError, createAuthEndpoint, createAuthMiddleware, getSessionFromCtx, originCheck, sessionMiddleware } from "better-auth/api";

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.4.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,
@@ -77,6 +79,7 @@
     "@commitlint/config-conventional": "^21.0.0",
     "@eslint/compat": "^2.1.0",
     "@eslint/js": "^10.0.1",
+    "@tanstack/intent": "^0.0.40",
     "@types/node": "^24.12.3",
     "@typescript-eslint/eslint-plugin": "^8.59.2",
     "@typescript-eslint/parser": "^8.59.2",

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.

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

@@ -0,0 +1,145 @@
+---
+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.1" # x-release-please-version
+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,161 @@
+---
+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.1" # x-release-please-version
+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/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"}