@proma-dev/sdk

Connect your app to the Proma marketplace. Authenticate users, charge credits, and use AI — all with a few lines of code.

Install

npm install @proma-dev/sdk

Setup

1. Create an app at proma.dev/home/developer
2. Copy your Client ID and register a Redirect URI
3. Initialize the client:

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

const proma = new PromaClient({
  clientId: 'your_client_id',
  redirectUri: 'https://yourapp.com/callback',
  scopes: ['profile', 'credits', 'ai:chat'],
});

Authentication

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

// On your callback page, exchange the code for a session
const session = await proma.handleCallback();

// Get the logged-in user
const user = await proma.getUser();
// => { sub, email, name, picture }

// Check auth status
await proma.isAuthenticated(); // true

// Log out
proma.logout();

Credits

Charge users for features in your app. 1,000,000 micro-credits = $1.00.

// Check balance
const { balance, formatted } = await proma.credits.getBalance();
console.log(`Balance: ${formatted}`); // "Balance: $1.23"

// Spend credits
const result = await proma.credits.spend(500_000, 'Generated a report');
// => { success: true, amount_spent: 500000, new_balance: 730000 }

AI Chat

Stream AI responses through Proma's gateway. Credits are deducted automatically per token.

// Get the full response as text
const answer = await proma.ai.chatText([
  { role: 'user', content: 'Explain quantum entanglement simply.' },
]);

// Or get a streaming Response for real-time UI
const stream = await proma.ai.chat([
  { role: 'user', content: 'Write a haiku about coding.' },
]);

React

npm install @proma-dev/sdk react

Provider

Wrap your app with PromaProvider to enable auth context:

import { PromaProvider } from '@proma-dev/sdk/react';

function App() {
  return (
    <PromaProvider
      clientId="your_client_id"
      redirectUri="https://yourapp.com/callback"
      scopes={['profile', 'credits']}
    >
      <YourApp />
    </PromaProvider>
  );
}

Hook

import { usePromaAuth } from '@proma-dev/sdk/react';

function Dashboard() {
  const { user, isLoading, isAuthenticated, login, logout, client } =
    usePromaAuth();

  if (isLoading) return <p>Loading...</p>;
  if (!isAuthenticated) return <button onClick={() => login()}>Log in</button>;

  return (
    <div>
      <p>Welcome, {user.name ?? user.email}</p>
      <button onClick={logout}>Log out</button>
    </div>
  );
}

Login Button

Drop-in button component:

import { LoginWithProma } from '@proma-dev/sdk/react';

<LoginWithProma
  clientId="your_client_id"
  redirectUri="https://yourapp.com/callback"
  scopes={['profile', 'credits']}
/>;

API Reference

| Method | Description | | --- | --- | | proma.login(scopes?) | Redirect to Proma login | | proma.handleCallback(url?) | Exchange OAuth code for session | | proma.getSession() | Get current session (auto-refreshes) | | proma.isAuthenticated() | Check if user has valid session | | proma.getUser() | Fetch user profile | | proma.logout() | Clear local session | | proma.credits.getBalance() | Get credit balance | | proma.credits.spend(amount, description?) | Deduct credits | | proma.ai.chat(messages) | Streaming AI chat | | proma.ai.chatText(messages) | AI chat (full text) |

License

MIT