Next.js Full-Stack Integration

What You’ll Build

This tutorial walks you through building a Next.js 14+ (App Router) full-stack application from scratch, implementing Profy OAuth login, secure Token storage, and per-use billing event reporting. After users click “Login with Profy” and complete authorization, the application automatically manages the Token lifecycle and reports billing events to Profy when users trigger paid actions.

Prerequisites

Profy Developer Account

Registered a Profy account and created an App in the developer dashboard to obtain your Client ID and Client Secret

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

If you need Drizzle for Token persistence, also install:

npm install drizzle-orm postgres
npm install -D drizzle-kit

Step 2: Configure Environment Variables

.env.local

PROFY_APP_ID=your_app_client_id
PROFY_APP_SECRET=your_app_client_secret
PROFY_CALLBACK_URL=http://localhost:3000/api/callback

# Drizzle Token Store (optional)
DATABASE_URL=postgres://user:pass@localhost:5432/profy_demo

Never commit .env.local to version control. Make sure .gitignore includes this file.

Step 3: Initialize the SDK

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

export const profy = new ProfyApp({
  clientId: process.env.PROFY_APP_ID!,
  clientSecret: process.env.PROFY_APP_SECRET!,
});

import os
from profy_sdk import ProfyApp

profy = ProfyApp(
    client_id=os.environ["PROFY_APP_ID"],
    client_secret=os.environ["PROFY_APP_SECRET"],
)

The ProfyApp instance should be used as a singleton on the server side. Never expose clientSecret to the client.

app/page.tsx

const PROFY_AUTHORIZE_URL = "https://app.profy.cn/oauth/authorize";

export default function Home() {
  const clientId = process.env.PROFY_APP_ID!;
  const redirectUri = process.env.PROFY_CALLBACK_URL!;

  const authUrl = `${PROFY_AUTHORIZE_URL}?${new URLSearchParams({
    client_id: clientId,
    redirect_uri: redirectUri,
    scope: "events:write",
    response_type: "code",
  })}`;

  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

import { NextRequest, NextResponse } from "next/server";
import { profy } from "@/lib/profy";
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 code" }, { status: 400 });
  }

  const redirectUri = process.env.PROFY_CALLBACK_URL!;
  const tokenResult = await profy.exchangeCode(code, redirectUri);

  const cookieStore = await cookies();
  cookieStore.set("profy_user_id", tokenResult.userId, {
    httpOnly: true,
    secure: process.env.NODE_ENV === "production",
    sameSite: "lax",
    maxAge: 60 * 60 * 24 * 90,
  });

  // Token persistence — see Step 6
  await saveToken(tokenResult);

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

from fastapi import FastAPI, Request
from fastapi.responses import RedirectResponse
from config import profy

app = FastAPI()

@app.get("/api/callback")
async def oauth_callback(request: Request, code: str | None = None):
    if not code:
        return {"error": "Missing code"}, 400

    redirect_uri = os.environ["PROFY_CALLBACK_URL"]
    token_result = await profy.exchange_code(code, redirect_uri)

    # Token persistence — see Step 6
    await save_token(token_result)

    response = RedirectResponse(url="/dashboard")
    response.set_cookie(
        "profy_user_id",
        token_result["user_id"],
        httponly=True,
        secure=os.environ.get("ENV") == "production",
        samesite="lax",
        max_age=60 * 60 * 24 * 90,
    )
    return response

The expiresAt returned by exchangeCode is the access token’s expiration timestamp, used to determine when to refresh.

Step 6: Token Persistence

Option A: Using DrizzleTokenStore (Recommended)

The SDK provides out-of-the-box Drizzle integration:

import { DrizzleTokenStore, profyOAuthToken } from "@profy-ai/sdk/contrib/drizzle";
import { drizzle } from "drizzle-orm/postgres-js";
import postgres from "postgres";

const client = postgres(process.env.DATABASE_URL!);
const db = drizzle(client);

export const tokenStore = new DrizzleTokenStore(db);

from profy_sdk.contrib.sqlalchemy import SQLAlchemyTokenStore
from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker

engine = create_async_engine(os.environ["DATABASE_URL"])
async_session = async_sessionmaker(engine)

token_store = SQLAlchemyTokenStore(async_session)

Export the Token table in your schema:

db/schema.ts

export { profyOAuthToken } from "@profy-ai/sdk/contrib/drizzle";

After running migrations to create the table, implement saveToken in the callback:

import { isTokenExpired } from "@profy-ai/sdk";
import { profy } from "./profy";

export async function saveToken(tokenResult: {
  accessToken: string;
  refreshToken: string;
  userId: string;
  expiresAt: number;
}) {
  await tokenStore.save(tokenResult.userId, {
    accessToken: tokenResult.accessToken,
    refreshToken: tokenResult.refreshToken,
    expiresAt: tokenResult.expiresAt,
  });
}

export async function getValidToken(userId: string) {
  const stored = await tokenStore.get(userId);
  if (!stored) throw new Error("User not authenticated");

  if (isTokenExpired(stored)) {
    const refreshed = await profy.refreshToken(stored.refreshToken);
    await tokenStore.save(userId, refreshed);
    return refreshed.accessToken;
  }

  return stored.accessToken;
}

from profy_sdk import is_token_expired
from config import profy

async def save_token(token_result: dict):
    await token_store.save(
        token_result["user_id"],
        {
            "access_token": token_result["access_token"],
            "refresh_token": token_result["refresh_token"],
            "expires_at": token_result["expires_at"],
        },
    )

async def get_valid_token(user_id: str) -> str:
    stored = await token_store.get(user_id)
    if not stored:
        raise Exception("User not authenticated")

    if is_token_expired(stored):
        refreshed = await profy.refresh_token(stored["refresh_token"])
        await token_store.save(user_id, refreshed)
        return refreshed["access_token"]

    return stored["access_token"]

For simple scenarios that don’t require a database, you can encrypt Tokens and store them in HTTP-only cookies:

lib/token-cookie.ts

import { SignJWT, jwtVerify } from "jose";

const secret = new TextEncoder().encode(process.env.PROFY_APP_SECRET!);

export async function encryptToken(payload: Record<string, unknown>) {
  return new SignJWT(payload)
    .setProtectedHeader({ alg: "HS256" })
    .setExpirationTime("90d")
    .sign(secret);
}

export async function decryptToken(token: string) {
  const { payload } = await jwtVerify(token, secret);
  return payload;
}

The cookie approach requires updating the cookie on every Token refresh and doesn’t support server-side revocation. Option A is recommended for production environments.

Step 7: Report Billing Events

import { NextRequest, NextResponse } from "next/server";
import { profy } from "@/lib/profy";
import { getValidToken } 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 profy.reportEvent(eventName, {
    token,
    idempotencyKey,
    metadata,
  });

  return NextResponse.json(result);
}

from fastapi import FastAPI, Request, HTTPException
from config import profy
from token_store import get_valid_token

@app.post("/api/report-event")
async def report_event(request: Request):
    user_id = request.cookies.get("profy_user_id")
    if not user_id:
        raise HTTPException(status_code=401, detail="Unauthorized")

    body = await request.json()
    token = await get_valid_token(user_id)

    result = await profy.report_event(
        body["eventName"],
        token=token,
        idempotency_key=body.get("idempotencyKey"),
        metadata=body.get("metadata"),
    )

    return result

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);

  async function handleAction() {
    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" },
      }),
    });

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

    const { balance_remaining } = await res.json();
    setBalance(balance_remaining);
  }

  return (
    <main className="flex min-h-screen flex-col items-center justify-center gap-4">
      <button
        onClick={handleAction}
        className="rounded-lg bg-green-600 px-6 py-3 text-white font-medium hover:bg-green-700 transition-colors"
      >
        Trigger AI Generation (Billed)
      </button>
      {balance !== null && (
        <p className="text-sm text-gray-500">Remaining balance: {balance}</p>
      )}
    </main>
  );
}

Step 8: Error Handling

All errors thrown by the SDK are typed exceptions that can be caught precisely:

import { AuthExpired, InsufficientBalance, InvalidEvent, ProfyApiError } from "@profy-ai/sdk";
import { profy } from "./profy";
import { getValidToken, tokenStore } 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 profy.reportEvent(eventName, { token, ...options });
  } catch (error) {
    if (error instanceof AuthExpired) {
      await tokenStore.delete(userId);
      throw new Error("SESSION_EXPIRED");
    }
    if (error instanceof InsufficientBalance) {
      throw new Error("INSUFFICIENT_BALANCE");
    }
    if (error instanceof InvalidEvent) {
      throw new Error("INVALID_EVENT");
    }
    if (error instanceof ProfyApiError) {
      throw new Error(`PROFY_ERROR: ${error.message}`);
    }
    throw error;
  }
}

from profy_sdk import AuthExpired, InsufficientBalance, InvalidEvent, ProfyApiError
from config import profy
from token_store import get_valid_token, token_store

async def report_event_safely(
    user_id: str,
    event_name: str,
    idempotency_key: str | None = None,
    metadata: dict | None = None,
):
    token = await get_valid_token(user_id)

    try:
        return await profy.report_event(
            event_name,
            token=token,
            idempotency_key=idempotency_key,
            metadata=metadata,
        )
    except AuthExpired:
        await token_store.delete(user_id)
        raise Exception("SESSION_EXPIRED")
    except InsufficientBalance:
        raise Exception("INSUFFICIENT_BALANCE")
    except InvalidEvent:
        raise Exception("INVALID_EVENT")
    except ProfyApiError as e:
        raise Exception(f"PROFY_ERROR: {e}")

Unified handling in the API Route:

app/api/report-event/route.ts

import { NextRequest, NextResponse } from "next/server";
import { reportEventSafely } from "@/lib/report-with-error-handling";
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";

    if (message === "SESSION_EXPIRED") {
      return NextResponse.json(
        { error: "Session expired. Please re-authorize." },
        { status: 401 }
      );
    }
    if (message === "INSUFFICIENT_BALANCE") {
      return NextResponse.json(
        { error: "Insufficient balance. Please top up and try again." },
        { status: 402 }
      );
    }
    if (message === "INVALID_EVENT") {
      return NextResponse.json(
        { error: "Invalid event name. Please check your Meter configuration." },
        { status: 400 }
      );
    }

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

Complete Project Structure

profy-demo/
├── app/
│   ├── api/
│   │   ├── callback/
│   │   │   └── route.ts          # OAuth callback
│   │   └── report-event/
│   │       └── route.ts          # Billing event reporting
│   ├── dashboard/
│   │   └── page.tsx              # Post-login page
│   ├── layout.tsx
│   └── page.tsx                  # Login page
├── db/
│   └── schema.ts                 # Drizzle schema
├── lib/
│   ├── profy.ts                  # SDK singleton
│   ├── token-store.ts            # Token storage & refresh
│   └── report-with-error-handling.ts
├── .env.local
├── drizzle.config.ts
├── 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 the SDK

Step 5: Handle the OAuth Callback

Step 6: Token Persistence

Option A: Using DrizzleTokenStore (Recommended)

Step 7: Report Billing Events

Step 8: 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 the SDK

​Step 4: Create the OAuth Login Page

​Step 5: Handle the OAuth Callback

​Step 6: Token Persistence

​Option A: Using DrizzleTokenStore (Recommended)

​Option B: Encrypted Cookie (Lightweight Scenarios)

​Step 7: Report Billing Events

​Step 8: 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 the SDK

Step 4: Create the OAuth Login Page

Step 5: Handle the OAuth Callback

Step 6: Token Persistence

Option A: Using DrizzleTokenStore (Recommended)

Option B: Encrypted Cookie (Lightweight Scenarios)

Step 7: Report Billing Events

Step 8: Error Handling

Complete Project Structure

FAQ

Next Steps