paystack-client-api

name	paystack-client-api
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 methods, BetterFetch throw option return types, and legacy disable/enable aliases.
type	core
library	@alexasomba/better-auth-paystack
library_version	3.0.0
license	MIT
compatibility	Node.js >=22.0.0; better-auth ^1.6.9; @alexasomba/paystack-node 1.10.x; @alexasomba/better-auth-paystack >=3.0.0 <4.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:

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:

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 legacy aliases

subscription.disable maps to subscription.cancel. subscription.enable maps to subscription.restore.

Keep these aliases for migration 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:

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:

vp test test/typesafety.test.ts
vp test test/paystack.test.ts

Run TanStack example tests when examples or client usage are changed:

pnpm --filter ./examples/tanstack test