@alexasomba/better-auth-paystack 2.2.0 → 2.4.1

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/types-B5ZnlFrq.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types-B5ZnlFrq.d.mts","names":["GenericEndpointContext","Session","User","Organization","Member","PaystackPaths","PaystackResponse","PaystackWebhookEvent","PaystackClient","PaystackCustomerClient","PaystackPlanClient","PaystackProductClient","PaystackSubscriptionClient","PaystackTransactionClient","components","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","modelName","fields","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/types.d.ts"],"mappings":"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"}