@pluralize/sdk

JavaScript SDK for Pluralize — a platform that adds auth, billing, and multi-tenancy to single-user apps.

Three entry points ship in the same package:

| Import | Runs on | What it covers | |---|---|---| | @pluralize/sdk | Browser | auth, db, billing, files — the operations your users perform. | | @pluralize/sdk/react | Browser | Drop-in <PluralizeLogin />, <PluralizeSignup />, <PluralPricing />. Pre-styled, themeable. | | @pluralize/sdk/server | Node.js / Fluid Compute | verifyToken(req) for your backend. No React, no DOM, no side effects at import. |

Install

npm install @pluralize/sdk

Quickstart (client)

import { Pluralize } from '@pluralize/sdk';

const app = Pluralize.init({
  appId: process.env.NEXT_PUBLIC_PLURALIZE_APP_ID!,
  apiKey: process.env.NEXT_PUBLIC_PLURALIZE_API_KEY!,
});

await app.auth.login('[email protected]', 'correct horse battery staple');

// If the app's signup mode is `invite_only` (configured in the dashboard),
// pass the invite token alongside the credentials:
// await app.auth.signup(email, password, { inviteToken: 'inv_abc123…' });

// Tenant viral invites (issue #10, requires `max_tenant_invites > 0` on the
// tenant's plan):
const minted = await app.auth.mintInvite({ note: 'juan' });
console.log(`Share: https://your-app.example/login?invite=${minted.token}`);
const { tokens, quota } = await app.auth.listMyInvites();
console.log(`${quota.used} of ${quota.limit} used`);

const sub = await app.billing.getSubscription();
const canExport = await app.billing.hasFeature('export_csv');

Quickstart (server)

Verify a Bearer token from your backend before reading your own database:

import { createPluralizeServer } from '@pluralize/sdk/server';

const pluralize = createPluralizeServer({
  appId: process.env.NEXT_PUBLIC_PLURALIZE_APP_ID!,
  apiKey: process.env.NEXT_PUBLIC_PLURALIZE_API_KEY!,
  cookieName: 'pz_token',  // optional: also accept the token from this cookie
});

export async function GET(req: Request) {
  const session = await pluralize.verifyToken(req, {
    include: ['subscription'],  // optional: get plan slug + entitlements in the same hop
  });
  if (!session) return Response.json({ error: 'unauthorized' }, { status: 401 });

  // session.tenantId — scope your own tables with this
  // session.subscription?.planSlug — tier-aware gating
}

Results cache in-memory for 30 s (configurable via cacheSeconds), keyed by the access token, so hot paths pay for a remote introspect only once per cache window.

Auth route handlers (SSR / Next.js)

Skip writing five proxy endpoints by hand. createAuthRouteHandlers returns signup/login/logout/exchange/me handlers that call Pluralize's auth endpoints, manage the pz_token cookie, and return JSON your client SDK can consume. Drop them into your framework's route files:

// app/api/auth/login/route.ts
import { createAuthRouteHandlers } from '@pluralize/sdk/server';

const { login, signup, logout, exchange, me, mintInvite, listMyInvites } =
  createAuthRouteHandlers({
    appId: process.env.PLURALIZE_APP_ID!,
    apiKey: process.env.PLURALIZE_API_KEY!,
    cookieName: 'pz_token',  // matches createPluralizeServer({ cookieName }) above
  });

export const POST = login;  // for signup/exchange/logout
export const GET  = me;     // for /api/auth/me/route.ts

// For tenant viral invites (issue #10), expose mintInvite + listMyInvites
// at e.g. /api/auth/pluralize/invite-tokens (POST + GET on the same path).
// These read pz_token from the cookie jar and forward to Pluralize with
// the proper Bearer header — necessary for SSR/cookie consumers because
// the browser SDK cannot read httpOnly cookies.

The handlers return Web Standard Response objects, so they work in Next.js, Hono, Bun, Cloudflare Workers, or anything else built on the Fetch API.

Docs

Full documentation at pluralize.app/docs:

• Authentication
• Data
• Files
• Billing
• Server-side integration

License

MIT.