PromaDocumentation

Quick Start

Build your first Proma-powered app in 5 minutes.

This guide walks you through creating a minimal app that authenticates users with Proma and spends credits.

Prerequisites

  • A Proma account at proma.dev
  • Node.js 18+
  • A web app (React, Next.js, or plain JavaScript)

Step 1: Register Your App

  1. Go to your Developer Dashboard
  2. Click Create App
  3. Fill in your app name and redirect URI (e.g. http://localhost:3000/callback)
  4. Copy your Client ID

Step 2: Install the SDK

npm install @proma/sdk

Step 3: Add Login with Proma

import { PromaClient } from '@proma/sdk';

const proma = new PromaClient({
  clientId: 'your-client-id',
  redirectUri: 'http://localhost:3000/callback',
});

// Redirect user to Proma login
proma.loginWithRedirect();

Step 4: Handle the Callback

On your redirect URI page, exchange the authorization code for tokens:

// On your /callback page
await proma.handleCallback();

// User is now authenticated
const user = await proma.getUserInfo();
console.log(`Hello, ${user.name}!`);

Step 5: Spend Credits

// Check the user's balance
const balance = await proma.credits.getBalance();
console.log(`User has ${balance.balance} credits`);

// Spend credits for an action in your app
await proma.credits.spend({
  amount: 10,
  description: 'Generated an AI summary',
});

Step 6: Use the AI Gateway (Optional)

Route AI requests through Proma so usage is billed directly to the user:

const stream = proma.ai.chat({
  messages: [{ role: 'user', content: 'Explain quantum computing' }],
});

for await (const chunk of stream) {
  process.stdout.write(chunk);
}

Using React?

The SDK includes React bindings for an even faster setup:

import { PromaProvider, LoginWithProma, usePromaAuth } from '@proma/sdk/react';

function App() {
  return (
    <PromaProvider clientId="your-client-id" redirectUri="/callback">
      <MyApp />
    </PromaProvider>
  );
}

function MyApp() {
  const { isAuthenticated, user } = usePromaAuth();

  if (!isAuthenticated) {
    return <LoginWithProma />;
  }

  return <p>Welcome, {user.name}!</p>;
}

Next Steps