PromaClient

PromaClient is the main entry point for the SDK. Create one instance per app and reuse it everywhere.

Constructor

new PromaClient({
  clientId: string        // required — from the developer portal
  redirectUri: string     // required — must match a registered URI
  scopes?: OAuthScope[]   // default: ['profile']
  baseUrl?: string        // default: 'https://proma.dev'
  storage?: TokenStorage  // default: localStorage
})

Options

clientId (required)

Your app's Client ID from the Developer Portal. Looks like proma_app_abc123.

redirectUri (required)

The URL Proma will redirect back to after the user approves. Must be registered in the Developer Portal. Can be different per environment (localhost vs production) as long as both URIs are registered.

scopes

Array of OAuth scopes to request. Available scopes:

• profile — read the user's name, email, and avatar
• credits — read balance and spend micro-credits
• ai:chat — stream AI chat completions through the Proma gateway

baseUrl

Override the Proma server URL. Useful when running Proma locally for development.

storage

Custom session storage implementation. Must implement the TokenStorage interface. Defaults to localStorage. Use MemoryStorage for Node.js or SSR contexts where localStorage is unavailable.

Methods

login(scopes?)

Redirects the user to Proma's login and consent page. Does not return — the page navigates away.

await proma.login()
// or override scopes for this specific login:
await proma.login(['profile', 'ai:chat'])

buildAuthorizeUrl(scopes?)

Returns the authorization URL as a string without navigating. Useful when you need to control the redirect yourself (e.g. open in a popup).

const url = await proma.buildAuthorizeUrl()
window.open(url, '_blank')

handleCallback(url?)

Exchanges the authorization code in the URL for access and refresh tokens. Call this on your redirect page. Stores the session automatically.

// On /auth/callback:
const session = await proma.handleCallback()
// session.accessToken, session.refreshToken, session.expiresAt, session.scope

Optionally pass a URL string if you are not running in a browser context:

const session = await proma.handleCallback('https://yourapp.com/auth/callback?code=...')

getSession()

Returns the current Session or null. Automatically refreshes the access token if it expires within the next 30 seconds.

const session = await proma.getSession()
if (!session) {
  // not logged in
}

isAuthenticated()

Returns true if the user has a valid or refreshable session.

if (await proma.isAuthenticated()) {
  // show dashboard
}

getUser()

Fetches the logged-in user's profile from the Proma userinfo endpoint. Requires the profile scope.

const user = await proma.getUser()
// { sub, email, name, picture }

logout()

Clears the stored session. Does not revoke the token server-side.

proma.logout()

Sub-APIs

The client exposes two namespaced APIs as properties:

• proma.credits — see Credits API
• proma.ai — see AI API

TypeScript types

import type {
  OAuthScope,       // 'profile' | 'credits' | 'ai:chat'
  Session,          // { accessToken, refreshToken, expiresAt, scope }
  UserInfo,         // { sub, email?, name?, picture? }
  TokenStorage,     // interface for custom storage backends
  PromaClientConfig,
} from '@proma/sdk'