Overview

@kerne/server is the only place that should ever hold your secret key. It’s what lets a request act on behalf of any customer, not just the caller - that’s the whole reason it stays server-side.

Install & configure

npm install @kerne/server

import { Kerne } from '@kerne/server';

const kerne = new Kerne({
  appId: process.env.KERNE_APP_ID!,
  secretKey: process.env.KERNE_SECRET_KEY!, // sk_live_... or sk_test_...
  // baseUrl defaults to https://api.kerne.io
});

The surface, by tier

The methods are grouped by who is meant to call them - not by resource - because that’s what actually changes as you build:

Tier 1 - entitlements, flat on the client

The reason this SDK exists. No .billing. prefix - these are the calls you’ll write the most.

kerne.allows(featureKey, { customer })       // boolean, never throws
kerne.enforce(featureKey, { customer })      // throws EntitlementDeniedError if denied
kerne.check(featureKey, { customer })        // full detail: limit/used/remaining/...
kerne.consume(featureKey, { customer, delta })
kerne.reportUsage(featureKey, { customer, delta })   // customer is required here
kerne.reportUsageBatch(events)              // each event carries its own customer
kerne.entitlements({ customer })
kerne.usage({ customer, featureKey? })

customer is required on reportUsage() / reportUsageBatch(). On allows() / enforce() / check() / consume() it is optional in the types, but with a secret key there is no implicit “current user” - pass the customer you mean. See Entitlements & usage.

Tier 2 - billing the end user touches

kerne.billing.subscription()
kerne.billing.plans(productIdOrSlug)   // public pricing data, read-only
kerne.billing.priceIdFor(planSlug, priceLabel?)
kerne.billing.checkout(planPriceId, options)   // redirect flow
kerne.billing.portal(options)                  // redirect flow
kerne.billing.cancel(options)
kerne.billing.subscriptions.list/get/cancel/changePlanPrice(...)
kerne.billing.isSubscribedTo(customer, planSlug)
// Stripe-only, embedded card instead of the redirect (see Checkout > Headless):
kerne.billing.createSetupIntent(options)
kerne.billing.createSubscriptionHeadless({ customer, planPriceId, stripePaymentMethodId })

See Billing.

Tier 3 - identity & growth

kerne.auth.*         // signup, login, password reset, email verification
kerne.users.me/get/update(...)
kerne.waitlist.*
kerne.invitations.*

See Authentication, Users, Waitlist, Invitations.

Tier 4 - admin corrections, never from an end-user request

kerne.customers.upsert / get / list / update(...)
kerne.admin.setUsage / adjustUsage / resetUsage(...)
kerne.admin.grant / listGrants / revokeGrant(...)

Same idea as supabase.auth.admin.* - one client, a namespace that signals “this call needs elevated trust.” See Customers below, and Admin.

Customers

The billable identity every call above names as customer. A signed-up Kerne user already has one - external_id is set to their User.id at signup, so you never call this yourself just to use the SDK. Reach for kerne.customers when you run your own auth (Clerk, Supabase, your own backend) and want to keep email/name in sync with your system of record ahead of the customer’s first billing action, or when you bill an organization rather than a person and want to look it up later by the id you gave it:

// Pre-register a BYO customer - optional. checkout() also creates one on first
// use if you pass `email` there instead; consume() never creates one, so an
// unknown id 404s until it exists.
const customer = await kerne.customers.upsert({
  externalId: 'org_492',
  email: '[email protected]',
  name: 'Acme Inc.',
});

await kerne.customers.get('org_492');
await kerne.customers.list({ limit: 50 });

// Renaming to an externalId already used by another customer 409s rather than merging
await kerne.customers.update('org_492', { name: 'Acme Corporation' });

get, list and update return the customer’s metadata exactly as you last wrote it, plus provider_accounts - the provider customer this one maps to on each connected payment account ([{ provider, provider_customer_id }]). That list stays empty until their first checkout, which is what creates the provider customer. Admin-only (secret key) - not exposed in @kerne/react, since a signed-in end user’s own customer is always resolved from their session, never named explicitly.

Next.js (App Router)

There is no Next-specific adapter - @kerne/server is the same client in a Route Handler or a Server Action. Take the customer id from your own session/user record and pass it explicitly:

// app/api/export/route.ts
import { NextResponse } from 'next/server';
import { Kerne } from '@kerne/server';
import { getUserIdFromSession } from '@/lib/session'; // your own auth

const kerne = new Kerne({
  appId: process.env.KERNE_APP_ID!,
  secretKey: process.env.KERNE_SECRET_KEY!,
});

export async function POST() {
  const userId = await getUserIdFromSession();
  if (!userId) return NextResponse.json({ error: 'unauthenticated' }, { status: 401 });

  if (!(await kerne.allows('export_pdf', { customer: userId }))) {
    return NextResponse.json({ error: 'upgrade_required' }, { status: 403 });
  }

  return NextResponse.json(await renderPdf());
}

Importing from @kerne/server/next instead of @kerne/server gives you the identical surface plus an import 'server-only' guard, so a bundler pulling the module into a Client Component fails at build time rather than shipping the secret key to the browser.

Escape hatch

If a route you need isn’t wrapped yet, kerne.request() calls it directly with the same authentication as everything else - see Direct requests.

What this SDK does not do

Catalog management (products, plans, prices, packs) isn’t in this SDK - that’s control-plane configuration for your own dashboard, not something your app’s backend does at runtime. Use the Kerne dashboard or @kerne/contracts for that.

Server SDK

Frontend SDKs

Install & configure

The surface, by tier

Customers

Next.js (App Router)

Escape hatch

What this SDK does not do

​Install & configure

​The surface, by tier

​Customers

​Next.js (App Router)

​Escape hatch

​What this SDK does not do

Install & configure

The surface, by tier

Customers

Next.js (App Router)

Escape hatch

What this SDK does not do