@proma-dev/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,186 @@
+type OAuthScope = 'profile' | 'credits' | 'ai:chat';
+interface PromaClientConfig {
+    /** Your app's client ID from the Proma developer portal. */
+    clientId: string;
+    /** The URL Proma will redirect to after login. Must be registered in your app settings. */
+    redirectUri: string;
+    /** Scopes to request. Defaults to ['profile']. */
+    scopes?: OAuthScope[];
+    /** Override the Proma base URL. Defaults to https://proma.dev */
+    baseUrl?: string;
+    /** Custom storage for tokens. Defaults to localStorage. */
+    storage?: TokenStorage;
+}
+interface TokenStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+interface Session {
+    accessToken: string;
+    refreshToken: string;
+    /** Unix timestamp (ms) when the access token expires. */
+    expiresAt: number;
+    scope: string;
+}
+/** Raw token response from the Proma token endpoint. */
+interface TokenResponse {
+    access_token: string;
+    token_type: 'Bearer';
+    expires_in: number;
+    refresh_token: string;
+    scope: string;
+}
+interface UserInfo {
+    sub: string;
+    email?: string;
+    name?: string;
+    picture?: string | null;
+}
+interface BalanceResponse {
+    balance: number;
+    /** Human-readable balance, e.g. "$1.23" */
+    formatted: string;
+}
+interface SpendCreditsResponse {
+    success: true;
+    amount_spent: number;
+    new_balance: number;
+}
+interface ChatMessage {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+}
+interface ChatOptions {
+    messages: ChatMessage[];
+    /** Gemini model to use. Defaults to gemini-2.0-flash. */
+    model?: string;
+}
+
+declare class PromaClient {
+    private readonly config;
+    readonly baseUrl: string;
+    private readonly store;
+    private readonly defaultScopes;
+    /** Credits API — requires the `credits` scope. */
+    readonly credits: CreditsApi;
+    /** AI gateway API — requires the `ai:chat` scope. */
+    readonly ai: AiApi;
+    constructor(config: PromaClientConfig);
+    /**
+     * Redirects the user to Proma's login page.
+     * Call this on a button click — it will navigate away from the current page.
+     *
+     * @example
+     * button.onclick = () => proma.login()
+     */
+    login(scopes?: OAuthScope[]): Promise<void>;
+    /**
+     * Builds the authorization URL without navigating.
+     * Useful if you want to control the redirect yourself.
+     */
+    buildAuthorizeUrl(scopes?: OAuthScope[]): Promise<string>;
+    /**
+     * Handles the OAuth callback. Call this on your redirect page.
+     * Reads the `code` from the URL, exchanges it for tokens, and stores the session.
+     *
+     * @param url - Defaults to `window.location.href`
+     * @returns The new session
+     *
+     * @example
+     * // pages/callback.tsx
+     * useEffect(() => {
+     *   proma.handleCallback().then(session => {
+     *     router.push('/dashboard')
+     *   })
+     * }, [])
+     */
+    handleCallback(url?: string): Promise<Session>;
+    /**
+     * Returns the current session (access token, refresh token, expiry).
+     * Automatically refreshes the access token if it is expired.
+     * Returns `null` if the user is not logged in.
+     */
+    getSession(): Promise<Session | null>;
+    /**
+     * Returns `true` if the user has a valid (or refreshable) session.
+     */
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * Fetches the logged-in user's profile.
+     * Requires the `profile` scope.
+     */
+    getUser(): Promise<UserInfo>;
+    /**
+     * Clears the stored session and logs the user out.
+     * Does not revoke the token server-side.
+     */
+    logout(): void;
+    requireAccessToken(): Promise<string>;
+    private refresh;
+    private fetchTokens;
+    private tokensToSession;
+}
+declare class CreditsApi {
+    private readonly client;
+    constructor(client: PromaClient);
+    /**
+     * Returns the user's current credit balance.
+     * Requires scope: `credits`
+     *
+     * @example
+     * const { balance, formatted } = await proma.credits.getBalance()
+     * console.log(`You have ${formatted}`) // "You have $1.23"
+     */
+    getBalance(): Promise<BalanceResponse>;
+    /**
+     * Deducts credits from the user's account.
+     * Requires scope: `credits`
+     *
+     * @param amount - Micro-credits to spend. 1,000,000 = $1.00
+     * @param description - Optional description for the transaction ledger.
+     *
+     * @example
+     * await proma.credits.spend(500_000, 'Generated a report')
+     */
+    spend(amount: number, description?: string): Promise<SpendCreditsResponse>;
+}
+declare class AiApi {
+    private readonly client;
+    constructor(client: PromaClient);
+    /**
+     * Sends a chat request through the Proma AI gateway (Gemini).
+     * Credits are deducted automatically per token used.
+     * Requires scope: `ai:chat`
+     *
+     * Returns a streaming `Response` — iterate SSE chunks or use a helper library.
+     *
+     * @example
+     * const stream = await proma.ai.chat({
+     *   messages: [{ role: 'user', content: 'Explain quantum entanglement simply.' }]
+     * })
+     * const reader = stream.body.getReader()
+     */
+    chat(options: ChatOptions | ChatMessage[]): Promise<Response>;
+    /**
+     * Convenience wrapper around `chat` that collects the full streamed text.
+     * Use this when you don't need streaming and just want the final string.
+     *
+     * @example
+     * const text = await proma.ai.chatText({
+     *   messages: [{ role: 'user', content: 'Hello!' }]
+     * })
+     * console.log(text)
+     */
+    chatText(options: ChatOptions | ChatMessage[]): Promise<string>;
+}
+
+/** Default in-memory storage for environments without localStorage (SSR, Node). */
+declare class MemoryStorage implements TokenStorage {
+    private map;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+
+export { type BalanceResponse, type ChatMessage, type ChatOptions, MemoryStorage, type OAuthScope, PromaClient, type PromaClientConfig, type Session, type SpendCreditsResponse, type TokenResponse, type TokenStorage, type UserInfo };

package/dist/index.d.ts

@@ -0,0 +1,186 @@
+type OAuthScope = 'profile' | 'credits' | 'ai:chat';
+interface PromaClientConfig {
+    /** Your app's client ID from the Proma developer portal. */
+    clientId: string;
+    /** The URL Proma will redirect to after login. Must be registered in your app settings. */
+    redirectUri: string;
+    /** Scopes to request. Defaults to ['profile']. */
+    scopes?: OAuthScope[];
+    /** Override the Proma base URL. Defaults to https://proma.dev */
+    baseUrl?: string;
+    /** Custom storage for tokens. Defaults to localStorage. */
+    storage?: TokenStorage;
+}
+interface TokenStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+interface Session {
+    accessToken: string;
+    refreshToken: string;
+    /** Unix timestamp (ms) when the access token expires. */
+    expiresAt: number;
+    scope: string;
+}
+/** Raw token response from the Proma token endpoint. */
+interface TokenResponse {
+    access_token: string;
+    token_type: 'Bearer';
+    expires_in: number;
+    refresh_token: string;
+    scope: string;
+}
+interface UserInfo {
+    sub: string;
+    email?: string;
+    name?: string;
+    picture?: string | null;
+}
+interface BalanceResponse {
+    balance: number;
+    /** Human-readable balance, e.g. "$1.23" */
+    formatted: string;
+}
+interface SpendCreditsResponse {
+    success: true;
+    amount_spent: number;
+    new_balance: number;
+}
+interface ChatMessage {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+}
+interface ChatOptions {
+    messages: ChatMessage[];
+    /** Gemini model to use. Defaults to gemini-2.0-flash. */
+    model?: string;
+}
+
+declare class PromaClient {
+    private readonly config;
+    readonly baseUrl: string;
+    private readonly store;
+    private readonly defaultScopes;
+    /** Credits API — requires the `credits` scope. */
+    readonly credits: CreditsApi;
+    /** AI gateway API — requires the `ai:chat` scope. */
+    readonly ai: AiApi;
+    constructor(config: PromaClientConfig);
+    /**
+     * Redirects the user to Proma's login page.
+     * Call this on a button click — it will navigate away from the current page.
+     *
+     * @example
+     * button.onclick = () => proma.login()
+     */
+    login(scopes?: OAuthScope[]): Promise<void>;
+    /**
+     * Builds the authorization URL without navigating.
+     * Useful if you want to control the redirect yourself.
+     */
+    buildAuthorizeUrl(scopes?: OAuthScope[]): Promise<string>;
+    /**
+     * Handles the OAuth callback. Call this on your redirect page.
+     * Reads the `code` from the URL, exchanges it for tokens, and stores the session.
+     *
+     * @param url - Defaults to `window.location.href`
+     * @returns The new session
+     *
+     * @example
+     * // pages/callback.tsx
+     * useEffect(() => {
+     *   proma.handleCallback().then(session => {
+     *     router.push('/dashboard')
+     *   })
+     * }, [])
+     */
+    handleCallback(url?: string): Promise<Session>;
+    /**
+     * Returns the current session (access token, refresh token, expiry).
+     * Automatically refreshes the access token if it is expired.
+     * Returns `null` if the user is not logged in.
+     */
+    getSession(): Promise<Session | null>;
+    /**
+     * Returns `true` if the user has a valid (or refreshable) session.
+     */
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * Fetches the logged-in user's profile.
+     * Requires the `profile` scope.
+     */
+    getUser(): Promise<UserInfo>;
+    /**
+     * Clears the stored session and logs the user out.
+     * Does not revoke the token server-side.
+     */
+    logout(): void;
+    requireAccessToken(): Promise<string>;
+    private refresh;
+    private fetchTokens;
+    private tokensToSession;
+}
+declare class CreditsApi {
+    private readonly client;
+    constructor(client: PromaClient);
+    /**
+     * Returns the user's current credit balance.
+     * Requires scope: `credits`
+     *
+     * @example
+     * const { balance, formatted } = await proma.credits.getBalance()
+     * console.log(`You have ${formatted}`) // "You have $1.23"
+     */
+    getBalance(): Promise<BalanceResponse>;
+    /**
+     * Deducts credits from the user's account.
+     * Requires scope: `credits`
+     *
+     * @param amount - Micro-credits to spend. 1,000,000 = $1.00
+     * @param description - Optional description for the transaction ledger.
+     *
+     * @example
+     * await proma.credits.spend(500_000, 'Generated a report')
+     */
+    spend(amount: number, description?: string): Promise<SpendCreditsResponse>;
+}
+declare class AiApi {
+    private readonly client;
+    constructor(client: PromaClient);
+    /**
+     * Sends a chat request through the Proma AI gateway (Gemini).
+     * Credits are deducted automatically per token used.
+     * Requires scope: `ai:chat`
+     *
+     * Returns a streaming `Response` — iterate SSE chunks or use a helper library.
+     *
+     * @example
+     * const stream = await proma.ai.chat({
+     *   messages: [{ role: 'user', content: 'Explain quantum entanglement simply.' }]
+     * })
+     * const reader = stream.body.getReader()
+     */
+    chat(options: ChatOptions | ChatMessage[]): Promise<Response>;
+    /**
+     * Convenience wrapper around `chat` that collects the full streamed text.
+     * Use this when you don't need streaming and just want the final string.
+     *
+     * @example
+     * const text = await proma.ai.chatText({
+     *   messages: [{ role: 'user', content: 'Hello!' }]
+     * })
+     * console.log(text)
+     */
+    chatText(options: ChatOptions | ChatMessage[]): Promise<string>;
+}
+
+/** Default in-memory storage for environments without localStorage (SSR, Node). */
+declare class MemoryStorage implements TokenStorage {
+    private map;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+
+export { type BalanceResponse, type ChatMessage, type ChatOptions, MemoryStorage, type OAuthScope, PromaClient, type PromaClientConfig, type Session, type SpendCreditsResponse, type TokenResponse, type TokenStorage, type UserInfo };