npm package: @proma-dev/sdk
Description: Connect your app to the Proma marketplace — auth, credits, and AI in a few lines of code
Latest version: 0.1.4

# @proma-dev/sdk

Connect your app to the [Proma](https://proma.dev) marketplace. Authenticate users, charge credits, and use AI — all with a few lines of code.

## Install

```bash
npm install @proma-dev/sdk
```

## Setup

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

```ts
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

```ts
// 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.

```ts
// 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.

```ts
// 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

```bash
npm install @proma-dev/sdk react
```

### Provider

Wrap your app with `PromaProvider` to enable auth context:

```tsx
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

```tsx
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:

```tsx
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