Next.js Full-Stack Integration

What You’ll Build

This tutorial walks you through building a Next.js 14+ (App Router) full-stack application using a dual-client architecture:

Profy client — initialized with your platform API key (sk-pro-...). Used to call AI experts and chat completions. The cost is charged to your platform account.
ProfyApp client — initialized with your OAuth App credentials. Used to bill end users for usage via reportEvent, using each user’s OAuth token.

This separation keeps AI invocation simple (one API key, no per-user tokens) while still enabling per-user billing through OAuth.

The Profy client (API key) and ProfyApp client (OAuth) serve different purposes. You use the API key to call AI — the platform charges your account. You use OAuth tokens to bill your end users for the actions they take in your app.

Prerequisites

Profy Developer Account

Register a Profy account, then create an App in the developer dashboard to get your Client ID, Client Secret, and API Key (sk-pro-...)

Development Environment

Node.js 18+, npm/pnpm/bun, basic Next.js and React experience

Step 1: Create a Next.js Project and Install Dependencies

npx create-next-app@latest profy-demo --typescript --app --tailwind
cd profy-demo
npm install @profy-ai/sdk

pnpm create next-app profy-demo --typescript --app --tailwind
cd profy-demo
pnpm add @profy-ai/sdk

bun create next-app profy-demo --typescript --app --tailwind
cd profy-demo
bun add @profy-ai/sdk

Step 2: Configure Environment Variables

.env.local

# Profy API key — used by the Profy client to call AI experts and chat
PROFY_API_KEY=sk-pro-your_api_key_here

# OAuth App credentials — used by ProfyApp for user billing
PROFY_APP_ID=your_app_client_id
PROFY_APP_SECRET=your_app_client_secret
PROFY_CALLBACK_URL=http://localhost:3000/api/callback

# Your application database (for storing OAuth tokens)
DATABASE_URL=postgres://user:pass@localhost:5432/profy_demo

Never commit .env.local to version control. Make sure .gitignore includes this file. The PROFY_API_KEY and PROFY_APP_SECRET are sensitive credentials.

Step 3: Initialize Both SDK Clients

Create a shared module that exports both the Profy client (for AI calls) and the ProfyApp client (for OAuth and billing):

lib/profy.ts

import { Profy, ProfyApp } from "@profy-ai/sdk";

// Client for calling AI experts and chat completions.
// Authenticated with your platform API key — costs are charged to your account.
export const profy = new Profy({
  apiKey: process.env.PROFY_API_KEY!,
});

// Client for OAuth login and billing event reporting.
// Authenticated with your App credentials — used to bill end users.
export const profyApp = new ProfyApp({
  clientId: process.env.PROFY_APP_ID!,
  clientSecret: process.env.PROFY_APP_SECRET!,
});

Both clients should be used as singletons on the server side. Never expose apiKey or clientSecret to the browser.

Use profyApp.authorizationUrl() to generate the OAuth URL. The events:write scope is required for billing event reporting.

app/page.tsx

import { profyApp } from "@/lib/profy";

export default function Home() {
  const authUrl = profyApp.authorizationUrl({
    redirectUri: process.env.PROFY_CALLBACK_URL!,
    scope: "events:write",
  });

  return (
    <main className="flex min-h-screen items-center justify-center">
      <a
        href={authUrl}
        className="rounded-lg bg-indigo-600 px-6 py-3 text-white font-medium hover:bg-indigo-700 transition-colors"
      >
        Login with Profy
      </a>
    </main>
  );
}

Step 5: Handle the OAuth Callback

When the user authorizes your app, Profy redirects back with a code parameter. Exchange it for an OAuthToken and persist it.

app/api/callback/route.ts

import { NextRequest, NextResponse } from "next/server";
import { profyApp } from "@/lib/profy";
import { saveToken } from "@/lib/token-store";
import { cookies } from "next/headers";

export async function GET(request: NextRequest) {
  const code = request.nextUrl.searchParams.get("code");

  if (!code) {
    return NextResponse.json({ error: "Missing authorization code" }, { status: 400 });
  }

  const redirectUri = process.env.PROFY_CALLBACK_URL!;
  const token = await profyApp.exchangeCode(code, redirectUri);

  // Generate a user ID for your app (in production, derive from your user system)
  const userId = crypto.randomUUID();

  // Persist the OAuth token — see Step 6
  await saveToken(userId, token);

  // Set a cookie so subsequent requests can identify this user
  const cookieStore = await cookies();
  cookieStore.set("profy_user_id", userId, {
    httpOnly: true,
    secure: process.env.NODE_ENV === "production",
    sameSite: "lax",
    maxAge: 60 * 60 * 24 * 90, // 90 days
  });

  return NextResponse.redirect(new URL("/dashboard", request.url));
}

The OAuthToken returned by exchangeCode contains accessToken, refreshToken, expiresAt, tokenType, and scope. Always persist the full token object so you can refresh it later.

Step 6: Token Persistence

You need to store OAuth tokens securely and refresh them when they expire. Here we show a manual DB store pattern using the SDK’s isTokenExpired() and app.refresh() helpers.

The example below uses an in-memory Map for simplicity. In production, replace it with your real database (PostgreSQL, MySQL, Redis, etc.). In-memory storage will lose all tokens when the server restarts.

lib/token-store.ts

import { isTokenExpired, type OAuthToken } from "@profy-ai/sdk";
import { profyApp } from "./profy";

// ============================================================
// Token Store
//
// CONSTRAINTS:
// - In production, replace this Map with your real database
// - Token refresh rotates the old refresh token (it becomes invalid)
// - Always persist the new token immediately after refresh
// ============================================================

// Demo: in-memory store. Replace with your DB in production.
const tokenStore = new Map<string, OAuthToken>();

export async function saveToken(userId: string, token: OAuthToken): Promise<void> {
  tokenStore.set(userId, token);
}

export async function getToken(userId: string): Promise<OAuthToken | null> {
  return tokenStore.get(userId) ?? null;
}

export async function deleteToken(userId: string): Promise<void> {
  tokenStore.delete(userId);
}

/**
 * TokenManager: retrieves a valid token for a user, refreshing if expired.
 *
 * Uses isTokenExpired() to check expiration with a 60-second leeway,
 * then calls profyApp.refresh() to get a new token pair.
 * The old refresh token is rotated (invalidated) after refresh.
 */
export async function getValidToken(userId: string): Promise<OAuthToken> {
  const token = await getToken(userId);

  if (!token) {
    throw new Error("User not authenticated. Please log in again.");
  }

  // Check if the access token is expired (with 60s leeway for clock skew)
  if (!isTokenExpired(token, 60_000)) {
    return token;
  }

  // Refresh the token — this rotates the refresh token
  const refreshed = await profyApp.refresh(token.refreshToken);

  // Persist the new token immediately (old refresh token is now invalid)
  await saveToken(userId, refreshed);

  return refreshed;
}

isTokenExpired(token, leewayMs?) checks whether the token’s expiresAt timestamp has passed (with an optional leeway in milliseconds). A 60-second leeway prevents edge cases where the token expires between the check and the API call.

Here’s an example of what a production database store might look like using raw SQL:

lib/token-store-production-example.ts

import { type OAuthToken } from "@profy-ai/sdk";
import { db } from "@/db";

export async function saveToken(userId: string, token: OAuthToken): Promise<void> {
  await db.query(
    `INSERT INTO profy_tokens (user_id, access_token, refresh_token, token_type, expires_at, scope, updated_at)
     VALUES ($1, $2, $3, $4, $5, $6, NOW())
     ON CONFLICT (user_id) DO UPDATE SET
       access_token = EXCLUDED.access_token,
       refresh_token = EXCLUDED.refresh_token,
       token_type = EXCLUDED.token_type,
       expires_at = EXCLUDED.expires_at,
       scope = EXCLUDED.scope,
       updated_at = NOW()`,
    [userId, token.accessToken, token.refreshToken, token.tokenType, token.expiresAt, token.scope]
  );
}

export async function getToken(userId: string): Promise<OAuthToken | null> {
  const result = await db.query(
    `SELECT access_token, refresh_token, token_type, expires_at, scope
     FROM profy_tokens WHERE user_id = $1`,
    [userId]
  );

  if (result.rows.length === 0) return null;

  const row = result.rows[0];
  return {
    accessToken: row.access_token,
    refreshToken: row.refresh_token,
    tokenType: row.token_type,
    expiresAt: row.expires_at,
    scope: row.scope,
  };
}

export async function deleteToken(userId: string): Promise<void> {
  await db.query(`DELETE FROM profy_tokens WHERE user_id = $1`, [userId]);
}

Step 7: Report Billing Events

Use profyApp.reportEvent() with the user’s OAuth token to bill them. The onRefresh callback handles automatic token rotation during the API call.

app/api/report-event/route.ts

import { NextRequest, NextResponse } from "next/server";
import { profyApp } from "@/lib/profy";
import { getValidToken, saveToken } from "@/lib/token-store";
import { cookies } from "next/headers";

export async function POST(request: NextRequest) {
  const cookieStore = await cookies();
  const userId = cookieStore.get("profy_user_id")?.value;

  if (!userId) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { eventName, idempotencyKey, metadata } = await request.json();
  const token = await getValidToken(userId);

  const result = await profyApp.reportEvent(eventName, {
    token,
    idempotencyKey,
    metadata,
    // If the token is refreshed during this call, persist the new token
    onRefresh: async (rotatedToken) => {
      await saveToken(userId, rotatedToken);
    },
  });

  return NextResponse.json(result);
}

The onRefresh callback on reportEvent is called if the SDK internally refreshes the token during the API call. This ensures your stored token stays up to date without a separate refresh step.

Client-side usage example:

app/dashboard/page.tsx

"use client";

import { useState } from "react";

export default function Dashboard() {
  const [balance, setBalance] = useState<number | null>(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  async function handleBilledAction() {
    setLoading(true);
    setError(null);

    try {
      const res = await fetch("/api/report-event", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          eventName: "ai_generation",
          idempotencyKey: crypto.randomUUID(),
          metadata: { type: "text", model: "gpt-4" },
        }),
      });

      if (!res.ok) {
        const err = await res.json();
        setError(err.error);
        return;
      }

      const data = await res.json();
      setBalance(data.balanceRemaining);
    } finally {
      setLoading(false);
    }
  }

  return (
    <main className="flex min-h-screen flex-col items-center justify-center gap-4">
      <h1 className="text-2xl font-bold">Dashboard</h1>

      <button
        onClick={handleBilledAction}
        disabled={loading}
        className="rounded-lg bg-green-600 px-6 py-3 text-white font-medium hover:bg-green-700 transition-colors disabled:opacity-50"
      >
        {loading ? "Processing..." : "Trigger AI Generation (Billed)"}
      </button>

      {error && (
        <p className="text-sm text-red-500">{error}</p>
      )}

      {balance !== null && (
        <p className="text-sm text-gray-500">Remaining balance: {balance}</p>
      )}
    </main>
  );
}

Step 8: Call AI (Expert or Chat)

Use the Profy client (API key) for all AI calls. This is completely separate from the OAuth billing flow — the AI cost is charged to your platform account.

Call an Expert

app/api/ai/expert/route.ts

import { NextRequest, NextResponse } from "next/server";
import { profy } from "@/lib/profy";
import { cookies } from "next/headers";

export async function POST(request: NextRequest) {
  const cookieStore = await cookies();
  const userId = cookieStore.get("profy_user_id")?.value;

  if (!userId) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { expert, message, sessionId } = await request.json();

  const result = await profy.agents.run(expert, message, {
    sessionId,
  });

  return NextResponse.json(result);
}

Call an Expert (Streaming)

app/api/ai/expert-stream/route.ts

import { NextRequest } from "next/server";
import { profy } from "@/lib/profy";
import { cookies } from "next/headers";

export async function POST(request: NextRequest) {
  const cookieStore = await cookies();
  const userId = cookieStore.get("profy_user_id")?.value;

  if (!userId) {
    return new Response("Unauthorized", { status: 401 });
  }

  const { expert, message, sessionId } = await request.json();

  const stream = profy.agents.runStream(expert, message, {
    sessionId,
  });

  const encoder = new TextEncoder();
  const readable = new ReadableStream({
    async start(controller) {
      try {
        for await (const chunk of stream) {
          controller.enqueue(
            encoder.encode(`data: ${JSON.stringify(chunk)}\n\n`)
          );
        }
        controller.enqueue(encoder.encode("data: [DONE]\n\n"));
        controller.close();
      } catch (err) {
        controller.error(err);
      }
    },
  });

  return new Response(readable, {
    headers: {
      "Content-Type": "text/event-stream",
      "Cache-Control": "no-cache",
      Connection: "keep-alive",
    },
  });
}

Chat Completions

app/api/ai/chat/route.ts

import { NextRequest, NextResponse } from "next/server";
import { profy } from "@/lib/profy";
import { cookies } from "next/headers";

export async function POST(request: NextRequest) {
  const cookieStore = await cookies();
  const userId = cookieStore.get("profy_user_id")?.value;

  if (!userId) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { model, messages, temperature, maxTokens } = await request.json();

  const result = await profy.chat.completions.create({
    model,
    messages,
    temperature,
    maxTokens,
  });

  return NextResponse.json(result);
}

Combining AI Calls with Billing

In a real application, you typically call the AI and report a billing event together. Here’s how:

lib/ai-with-billing.ts

import { profy, profyApp } from "./profy";
import { getValidToken, saveToken } from "./token-store";

export async function callExpertAndBill(
  userId: string,
  expert: string,
  message: string,
  options?: { sessionId?: string }
) {
  // 1. Call the AI expert using the API key client
  const aiResult = await profy.agents.run(expert, message, {
    sessionId: options?.sessionId,
  });

  // 2. Get the user's OAuth token for billing
  const token = await getValidToken(userId);

  // 3. Report the billing event using the OAuth client
  const billingResult = await profyApp.reportEvent("ai_generation", {
    token,
    idempotencyKey: crypto.randomUUID(),
    metadata: {
      expert,
      sessionId: options?.sessionId,
    },
    onRefresh: async (rotatedToken) => {
      await saveToken(userId, rotatedToken);
    },
  });

  return {
    ai: aiResult,
    billing: billingResult,
  };
}

You can decouple AI calls from billing. For example, you might call the AI first and only report the billing event after confirming the response was successful. Use the idempotencyKey to prevent duplicate charges if you need to retry.

Step 9: Error Handling

The SDK throws typed errors that you can catch precisely. All error classes extend ProfyApiError.

lib/error-handler.ts

import {
  AuthenticationError,
  InsufficientBalanceError,
  InvalidRequestError,
  PermissionDeniedError,
  RateLimitError,
  ProfyApiError,
} from "@profy-ai/sdk";
import { profyApp } from "./profy";
import { getValidToken, saveToken, deleteToken } from "./token-store";

export async function reportEventSafely(
  userId: string,
  eventName: string,
  options?: { idempotencyKey?: string; metadata?: Record<string, unknown> }
) {
  const token = await getValidToken(userId);

  try {
    return await profyApp.reportEvent(eventName, {
      token,
      idempotencyKey: options?.idempotencyKey,
      metadata: options?.metadata,
      onRefresh: async (rotatedToken) => {
        await saveToken(userId, rotatedToken);
      },
    });
  } catch (error) {
    if (error instanceof AuthenticationError) {
      // 401: Token is invalid or revoked — clear it and ask user to re-login
      await deleteToken(userId);
      throw new Error("SESSION_EXPIRED");
    }

    if (error instanceof InsufficientBalanceError) {
      // 402: User doesn't have enough balance
      throw new Error("INSUFFICIENT_BALANCE");
    }

    if (error instanceof InvalidRequestError) {
      // 400: Bad request (e.g., invalid event name)
      throw new Error("INVALID_REQUEST");
    }

    if (error instanceof PermissionDeniedError) {
      // 403: Missing required scope or permission
      throw new Error("PERMISSION_DENIED");
    }

    if (error instanceof RateLimitError) {
      // 429: Too many requests
      throw new Error("RATE_LIMITED");
    }

    if (error instanceof ProfyApiError) {
      // Other API errors
      throw new Error(`PROFY_ERROR: ${error.message}`);
    }

    throw error;
  }
}

Unified handling in the API route:

app/api/report-event/route.ts

import { NextRequest, NextResponse } from "next/server";
import { reportEventSafely } from "@/lib/error-handler";
import { cookies } from "next/headers";

export async function POST(request: NextRequest) {
  const cookieStore = await cookies();
  const userId = cookieStore.get("profy_user_id")?.value;

  if (!userId) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { eventName, idempotencyKey, metadata } = await request.json();

  try {
    const result = await reportEventSafely(userId, eventName, {
      idempotencyKey,
      metadata,
    });
    return NextResponse.json(result);
  } catch (error) {
    const message = error instanceof Error ? error.message : "Unknown error";

    switch (message) {
      case "SESSION_EXPIRED":
        return NextResponse.json(
          { error: "Session expired. Please log in again." },
          { status: 401 }
        );

      case "INSUFFICIENT_BALANCE":
        return NextResponse.json(
          { error: "Insufficient balance. Please top up and try again." },
          { status: 402 }
        );

      case "INVALID_REQUEST":
        return NextResponse.json(
          { error: "Invalid event name. Check your Meter configuration." },
          { status: 400 }
        );

      case "PERMISSION_DENIED":
        return NextResponse.json(
          { error: "Permission denied. Ensure the user granted the required scope." },
          { status: 403 }
        );

      case "RATE_LIMITED":
        return NextResponse.json(
          { error: "Too many requests. Please try again later." },
          { status: 429 }
        );

      default:
        return NextResponse.json(
          { error: "Internal server error" },
          { status: 500 }
        );
    }
  }
}

Complete Project Structure

profy-demo/
├── app/
│   ├── api/
│   │   ├── ai/
│   │   │   ├── chat/
│   │   │   │   └── route.ts          # Chat completions (Profy client)
│   │   │   ├── expert/
│   │   │   │   └── route.ts          # Expert invoke (Profy client)
│   │   │   └── expert-stream/
│   │   │       └── route.ts          # Expert streaming (Profy client)
│   │   ├── callback/
│   │   │   └── route.ts              # OAuth callback (ProfyApp client)
│   │   └── report-event/
│   │       └── route.ts              # Billing event reporting (ProfyApp client)
│   ├── dashboard/
│   │   └── page.tsx                  # Post-login dashboard
│   ├── layout.tsx
│   └── page.tsx                      # Login page with OAuth
├── lib/
│   ├── profy.ts                      # Dual SDK clients (Profy + ProfyApp)
│   ├── token-store.ts                # Token persistence + refresh manager
│   ├── ai-with-billing.ts            # Combined AI call + billing helper
│   └── error-handler.ts              # Typed error handling
├── .env.local
├── next.config.ts
├── package.json
└── tsconfig.json

Get Started

Authentication & Keys

API Guides

SDK

Integrations

Cookbook

Reference

Next.js Full-Stack Integration

What You’ll Build

Prerequisites

Profy Developer Account

Development Environment

Step 1: Create a Next.js Project and Install Dependencies

Step 2: Configure Environment Variables

Step 3: Initialize Both SDK Clients

Step 5: Handle the OAuth Callback

Step 6: Token Persistence

Step 7: Report Billing Events

Step 8: Call AI (Expert or Chat)

Call an Expert

Call an Expert (Streaming)

Chat Completions

Combining AI Calls with Billing

Step 9: Error Handling

Complete Project Structure

FAQ

Next Steps

Per-Use Billing SaaS

AI Metered Billing

Webhook Event Handling

Token Management Best Practices

​What You’ll Build

​Prerequisites

Profy Developer Account

Development Environment

​Step 1: Create a Next.js Project and Install Dependencies

​Step 2: Configure Environment Variables

​Step 3: Initialize Both SDK Clients

​Step 4: Create the OAuth Login Page

​Step 5: Handle the OAuth Callback

​Step 6: Token Persistence

​Step 7: Report Billing Events

​Step 8: Call AI (Expert or Chat)

​Call an Expert

​Call an Expert (Streaming)

​Chat Completions

​Combining AI Calls with Billing

​Step 9: Error Handling

​Complete Project Structure

​FAQ

​Next Steps

Per-Use Billing SaaS

AI Metered Billing

Webhook Event Handling

Token Management Best Practices

What You’ll Build

Prerequisites

Step 1: Create a Next.js Project and Install Dependencies

Step 2: Configure Environment Variables

Step 3: Initialize Both SDK Clients

Step 4: Create the OAuth Login Page

Step 5: Handle the OAuth Callback

Step 6: Token Persistence

Step 7: Report Billing Events

Step 8: Call AI (Expert or Chat)

Call an Expert

Call an Expert (Streaming)

Chat Completions

Combining AI Calls with Billing

Step 9: Error Handling

Complete Project Structure

FAQ

Next Steps