SDKsPreview · 2 min read

Next.js SDK

Use @perkamo/nextjs when a Next.js app needs trusted Perkamo server calls plus browser-safe Client Component helpers.

The package supports the stable Next.js LTS lines: Next.js 16 Active LTS and Next.js 15 Maintenance LTS. It requires Node.js 20.9 or newer.

Install

bash

npm install @perkamo/nextjs @perkamo/browser @perkamo/sdk

App Router token routes

Create browser tokens from trusted route handlers. The route verifies your app session, calls Perkamo with a server key and returns only a short-lived browser token to Client Components.

// app/api/perkamo/token/route.ts
import { createPerkamoBrowserTokenRoute } from "@perkamo/nextjs/server";
import { auth } from "@/auth";

export const POST = createPerkamoBrowserTokenRoute({
  apiKey: () => process.env.PERKAMO_SECRET_KEY,
  browserKey: () => process.env.PERKAMO_BROWSER_KEY,
  getUserId: async () => {
    const session = await auth();
    return session?.user?.id ?? null;
  },
});

Use a separate stream-token route when customer streams are enabled:

// app/api/perkamo/stream-token/route.ts
import { createPerkamoStreamTokenRoute } from "@perkamo/nextjs/server";
import { auth } from "@/auth";

export const POST = createPerkamoStreamTokenRoute({
  apiKey: () => process.env.PERKAMO_SECRET_KEY,
  browserKey: () => process.env.PERKAMO_BROWSER_KEY,
  getUserId: async () => {
    const session = await auth();
    return session?.user?.id ?? null;
  },
});

Server Components and actions

Use @perkamo/nextjs/server only from trusted server code.

import { createPerkamoNextServerClient } from "@perkamo/nextjs/server";

const perkamo = createPerkamoNextServerClient({
  apiKey: () => process.env.PERKAMO_SECRET_KEY,
});

export async function trackPurchase(userId: string, orderId: string) {
  "use server";

  await perkamo.emit(
    userId,
    "purchase.completed",
    { order_id: orderId },
    { txId: orderId },
  );
}

The server client exposes the same trusted helpers as @perkamo/sdk, including program() and eventCatalog() for backend admin tooling:

const events = await perkamo.eventCatalog();

Client Components

Use @perkamo/nextjs/client only from Client Components.

tsx

"use client";

import { PerkamoProvider, usePerkamoCustomerJson } from "@perkamo/nextjs/client";

export function LoyaltyPanel() {
  return (
    <PerkamoProvider>
      <Points />
    </PerkamoProvider>
  );
}

function Points() {
  const { customer, loading, error, refresh } = usePerkamoCustomerJson();

  if (loading) return <p>Loading...</p>;
  if (error) return <button onClick={refresh}>Retry</button>;

  return <p>{customer?.wallets.points ?? 0} points</p>;
}

PerkamoProvider defaults to:

POST /api/perkamo/token
POST /api/perkamo/stream-token

Override tokenEndpoint and streamTokenEndpoint when your app uses different route names.

Security boundary

Server keys stay in route handlers, Server Components or server actions.
Client Components receive only short-lived browser tokens from your own Next.js

routes.

getUserId() should return your immutable application user id after verifying

the current session.

Token helpers return 401 when no user id is available.
Helpers default to the hosted Perkamo API. Set baseUrl only for a custom,

staging or private endpoint.

Perkamo API failures use PerkamoApiError from @perkamo/sdk, including

request id, retry-after and rate-limit metadata when available.

Browser SDK

PHP SDK