@dotbots-boutique/auth-sdk 1.0.8 → 1.0.10

package/README.md

@@ -115,7 +115,7 @@ App (frontend) → Local proxy (per server) → api.dotbots.ai
 
 During `initialize()`, the SDK fetches the proxy config from `GET {apiUrl}/api/proxy/config`. After that, all `auth.fetch()` calls are routed through the proxy automatically. If the proxy config cannot be fetched, the SDK falls back to direct communication with `apiUrl`.
 
-Auth endpoints (`/auth/*`) and the proxy config endpoint always go directly to `apiUrl` — never through the proxy.
+Only `GET /api/proxy/config` always goes directly to `apiUrl`. All other calls — auth token exchange, refresh, revoke, user info, payments, and `auth.fetch()` — go to `proxyUrl` when available, falling back to `apiUrl` when proxy is unavailable.
 
 ---
 
@@ -150,7 +150,43 @@ const response = await auth.fetch('/api/customers', {
 });
 ```
 
-This is the **only** method that routes via `proxyUrl`. All auth calls and the proxy config call always go directly to `apiUrl`.
+All SDK calls route via `proxyUrl` when available. Only `GET /api/proxy/config` always goes to `apiUrl`.
+
+---
+
+## Payments
+
+Use `auth.charge()` to charge a feature usage to the organisation or app budget. The app never handles token amounts, balances or budgets directly — the platform manages all of that.
+
+```typescript
+const { transactionId } = await auth.charge('ai.generate', 'org');
+```
+
+With a custom quantity:
+
+```typescript
+const { transactionId } = await auth.charge('ai.generate', 'org', 5);
+```
+
+### Error handling
+
+```typescript
+import { DotBotsAuthError } from '@dotbots-boutique/auth-sdk';
+
+try {
+  const { transactionId } = await auth.charge('ai.generate', 'org', 1);
+} catch (error) {
+  if (error instanceof DotBotsAuthError && error.code === 'PAYMENT_FAILED') {
+    if (error.message === 'INSUFFICIENT_BALANCE') {
+      // show top-up prompt
+    } else if (error.message === 'BUDGET_EXCEEDED') {
+      // show budget limit message
+    }
+  }
+}
+```
+
+Possible `PAYMENT_FAILED` messages: `INSUFFICIENT_BALANCE`, `BUDGET_EXCEEDED`, `FEATURE_NOT_FOUND`, `PAYMENT_REJECTED`.
 
 ---
 
@@ -174,6 +210,7 @@ auth.on('sessionExpired', () => {
 });
 auth.on('loggedOut', () => { });
 auth.on('userLoaded', () => { });
+auth.on('charged', () => { });
 ```
 
 | Event | Description |
@@ -182,6 +219,7 @@ auth.on('userLoaded', () => { });
 | `loggedOut` | User logged out |
 | `sessionExpired` | Refresh token expired, user must re-authenticate |
 | `userLoaded` | User data was fetched |
+| `charged` | Successful charge — also sent as `DOTBOTS_CHARGE` postMessage to parent |
 
 ---
 
@@ -223,6 +261,7 @@ try {
 | `NETWORK_ERROR` | API unreachable | Yes |
 | `NOT_INITIALIZED` | `initialize()` has not been called yet | Yes |
 | `PROXY_UNAVAILABLE` | Proxy config could not be fetched | No — falls back to direct API |
+| `PAYMENT_FAILED` | Payment was rejected (402) — see `message` for reason | No |
 
 ---
 
@@ -246,19 +285,17 @@ interface DotBotsConfig {
 ```typescript
 interface DotBotsUser {
   id: string;
-  name: string | null;        // null if 'profile' scope not granted
-  email: string | null;       // null if 'email' scope not granted
+  name: string;
+  email: string;
   orgId: string;
-  orgName: string | null;     // null if 'org' scope not granted
+  orgName: string;
   teams: { teamId: string; teamName: string }[];
   roles: string[];
   permissions: string[];
-  avatarUrl: string | null;   // null if 'avatar' scope not granted
+  avatarUrl?: string;
 }
 ```
 
-Fields marked as `null` are not provided by the platform because the user has not granted the corresponding scope.
-
 ---
 
 ## API Reference
@@ -301,6 +338,10 @@ Check if the user has a specific role.
 
 Authenticated fetch wrapper. Routes through the proxy when available, falls back to `apiUrl` when not. Retries once on 401 after refreshing the token.
 
+#### `charge(featureCode: string, paidBy: 'org' | 'app', quantity?: number): Promise<{ transactionId: string }>`
+
+Charges a feature usage. Calls `POST {proxyUrl}/payments/charge`. On success, sends a `DOTBOTS_CHARGE` postMessage to the parent window (iframe only) and emits the `charged` event. Throws `PAYMENT_FAILED` on 402 with a message indicating the reason (`INSUFFICIENT_BALANCE`, `BUDGET_EXCEEDED`, `FEATURE_NOT_FOUND`, `PAYMENT_REJECTED`).
+
 #### `logout(): Promise<void>`
 
 Logs out the user. Revokes tokens on `apiUrl`, clears state, and redirects (standalone) or notifies the parent (iframe).
@@ -325,6 +366,7 @@ const {
   canAny,     // (permissions: string[]) => boolean
   hasRole,    // (role: string) => boolean
   fetch,      // auth.fetch proxied
+  charge,     // auth.charge proxied
   logout,     // auth.logout proxied
 } = useDotBotsAuth();
 ```

package/dist/cjs/index.js

@@ -193,6 +193,14 @@ class PostMessageHandler {
             window.parent.postMessage({ type: 'DOTBOTS_LOGOUT' }, this.marketplaceOrigin);
         }
     }
+    /**
+     * Notify the parent of a successful charge (for real-time payment indicator).
+     */
+    sendCharge(appId, featureCode, amount, transactionId) {
+        if (this.isInIframe()) {
+            window.parent.postMessage({ type: 'DOTBOTS_CHARGE', appId, featureCode, amount, transactionId }, this.marketplaceOrigin);
+        }
+    }
 }
 
 class ProxyConfigManager {
@@ -325,6 +333,26 @@ class DotBotsAuth {
         }
         return response;
     }
+    async charge(featureCode, paidBy, quantity) {
+        this.assertInitialized();
+        const baseUrl = this.proxyConfigManager.getBaseUrl();
+        const response = await this.buildRequest(`${baseUrl}/payments/charge`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ featureCode, paidBy, quantity: quantity ?? 1 }),
+        });
+        if (response.status === 402) {
+            const body = await response.json();
+            throw new DotBotsAuthError('PAYMENT_FAILED', body.error, body.reason);
+        }
+        if (!response.ok) {
+            throw new DotBotsAuthError('NETWORK_ERROR', 'Payment request failed');
+        }
+        const result = await response.json();
+        this.postMessageHandler.sendCharge(this.config.appId, featureCode, result.amount, result.transactionId);
+        this.emit('charged');
+        return result;
+    }
     async logout() {
         this.assertInitialized();
         await this.tokenManager.revoke();
@@ -335,7 +363,7 @@ class DotBotsAuth {
         }
         else {
             const redirectUri = encodeURIComponent(window.location.origin);
-            window.location.href = `${this.config.apiUrl}/auth/logout?redirectUri=${redirectUri}`;
+            window.location.href = `${this.config.apiUrl}/api/auth/logout?redirectUri=${redirectUri}`;
         }
     }
     on(event, handler) {
@@ -383,7 +411,7 @@ class DotBotsAuth {
         else if (!this.tokenManager.isAuthenticated()) {
             // Redirect to auth
             const redirectUri = encodeURIComponent(window.location.href);
-            window.location.href = `${this.config.apiUrl}/auth/authorize?appId=${this.config.appId}&redirectUri=${redirectUri}`;
+            window.location.href = `${this.config.apiUrl}/api/auth/authorize?appId=${this.config.appId}&redirectUri=${redirectUri}`;
         }
     }
     async buildRequest(url, options) {
@@ -415,7 +443,7 @@ class DotBotsAuth {
         }
     }
 }
-DotBotsAuth.SDK_VERSION = '1.0.8';
+DotBotsAuth.SDK_VERSION = '1.0.10';
 
 exports.DotBotsAuth = DotBotsAuth;
 exports.DotBotsAuthError = DotBotsAuthError;

package/dist/cjs/react/index.js

@@ -49,6 +49,7 @@ function DotBotsAuthProvider({ auth, children, loadingComponent, errorComponent,
         canAny: (permissions) => auth.canAny(permissions),
         hasRole: (role) => auth.hasRole(role),
         fetch: (url, options) => auth.fetch(url, options),
+        charge: (featureCode, paidBy, quantity) => auth.charge(featureCode, paidBy, quantity),
         logout: () => auth.logout(),
     };
     return (jsxRuntime.jsx(DotBotsAuthContext.Provider, { value: value, children: children }));

package/dist/esm/index.js

@@ -191,6 +191,14 @@ class PostMessageHandler {
             window.parent.postMessage({ type: 'DOTBOTS_LOGOUT' }, this.marketplaceOrigin);
         }
     }
+    /**
+     * Notify the parent of a successful charge (for real-time payment indicator).
+     */
+    sendCharge(appId, featureCode, amount, transactionId) {
+        if (this.isInIframe()) {
+            window.parent.postMessage({ type: 'DOTBOTS_CHARGE', appId, featureCode, amount, transactionId }, this.marketplaceOrigin);
+        }
+    }
 }
 
 class ProxyConfigManager {
@@ -323,6 +331,26 @@ class DotBotsAuth {
         }
         return response;
     }
+    async charge(featureCode, paidBy, quantity) {
+        this.assertInitialized();
+        const baseUrl = this.proxyConfigManager.getBaseUrl();
+        const response = await this.buildRequest(`${baseUrl}/payments/charge`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ featureCode, paidBy, quantity: quantity ?? 1 }),
+        });
+        if (response.status === 402) {
+            const body = await response.json();
+            throw new DotBotsAuthError('PAYMENT_FAILED', body.error, body.reason);
+        }
+        if (!response.ok) {
+            throw new DotBotsAuthError('NETWORK_ERROR', 'Payment request failed');
+        }
+        const result = await response.json();
+        this.postMessageHandler.sendCharge(this.config.appId, featureCode, result.amount, result.transactionId);
+        this.emit('charged');
+        return result;
+    }
     async logout() {
         this.assertInitialized();
         await this.tokenManager.revoke();
@@ -333,7 +361,7 @@ class DotBotsAuth {
         }
         else {
             const redirectUri = encodeURIComponent(window.location.origin);
-            window.location.href = `${this.config.apiUrl}/auth/logout?redirectUri=${redirectUri}`;
+            window.location.href = `${this.config.apiUrl}/api/auth/logout?redirectUri=${redirectUri}`;
         }
     }
     on(event, handler) {
@@ -381,7 +409,7 @@ class DotBotsAuth {
         else if (!this.tokenManager.isAuthenticated()) {
             // Redirect to auth
             const redirectUri = encodeURIComponent(window.location.href);
-            window.location.href = `${this.config.apiUrl}/auth/authorize?appId=${this.config.appId}&redirectUri=${redirectUri}`;
+            window.location.href = `${this.config.apiUrl}/api/auth/authorize?appId=${this.config.appId}&redirectUri=${redirectUri}`;
         }
     }
     async buildRequest(url, options) {
@@ -413,6 +441,6 @@ class DotBotsAuth {
         }
     }
 }
-DotBotsAuth.SDK_VERSION = '1.0.8';
+DotBotsAuth.SDK_VERSION = '1.0.10';
 
 export { DotBotsAuth, DotBotsAuthError };

package/dist/esm/react/index.js

@@ -47,6 +47,7 @@ function DotBotsAuthProvider({ auth, children, loadingComponent, errorComponent,
         canAny: (permissions) => auth.canAny(permissions),
         hasRole: (role) => auth.hasRole(role),
         fetch: (url, options) => auth.fetch(url, options),
+        charge: (featureCode, paidBy, quantity) => auth.charge(featureCode, paidBy, quantity),
         logout: () => auth.logout(),
     };
     return (jsx(DotBotsAuthContext.Provider, { value: value, children: children }));

package/dist/types/DotBotsAuth.d.ts

@@ -8,7 +8,7 @@ export declare class DotBotsAuth {
     private readonly listeners;
     private cachedUser;
     private initialized;
-    static readonly SDK_VERSION = "1.0.8";
+    static readonly SDK_VERSION = "1.0.10";
     constructor(config: DotBotsConfig);
     initialize(): Promise<void>;
     getUser(): Promise<DotBotsUser>;
@@ -17,6 +17,9 @@ export declare class DotBotsAuth {
     canAny(permissions: string[]): boolean;
     hasRole(role: string): boolean;
     fetch(url: string, options?: RequestInit): Promise<Response>;
+    charge(featureCode: string, paidBy: 'org' | 'app', quantity?: number): Promise<{
+        transactionId: string;
+    }>;
     logout(): Promise<void>;
     on(event: DotBotsAuthEvent, handler: Function): void;
     off(event: DotBotsAuthEvent, handler: Function): void;

package/dist/types/PostMessageHandler.d.ts

@@ -15,4 +15,8 @@ export declare class PostMessageHandler {
      * Notify the parent that the user has logged out.
      */
     sendLogout(): void;
+    /**
+     * Notify the parent of a successful charge (for real-time payment indicator).
+     */
+    sendCharge(appId: string, featureCode: string, amount: number, transactionId: string): void;
 }

package/dist/types/index.js

@@ -191,6 +191,14 @@ class PostMessageHandler {
             window.parent.postMessage({ type: 'DOTBOTS_LOGOUT' }, this.marketplaceOrigin);
         }
     }
+    /**
+     * Notify the parent of a successful charge (for real-time payment indicator).
+     */
+    sendCharge(appId, featureCode, amount, transactionId) {
+        if (this.isInIframe()) {
+            window.parent.postMessage({ type: 'DOTBOTS_CHARGE', appId, featureCode, amount, transactionId }, this.marketplaceOrigin);
+        }
+    }
 }
 
 class ProxyConfigManager {
@@ -323,6 +331,26 @@ class DotBotsAuth {
         }
         return response;
     }
+    async charge(featureCode, paidBy, quantity) {
+        this.assertInitialized();
+        const baseUrl = this.proxyConfigManager.getBaseUrl();
+        const response = await this.buildRequest(`${baseUrl}/payments/charge`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ featureCode, paidBy, quantity: quantity ?? 1 }),
+        });
+        if (response.status === 402) {
+            const body = await response.json();
+            throw new DotBotsAuthError('PAYMENT_FAILED', body.error, body.reason);
+        }
+        if (!response.ok) {
+            throw new DotBotsAuthError('NETWORK_ERROR', 'Payment request failed');
+        }
+        const result = await response.json();
+        this.postMessageHandler.sendCharge(this.config.appId, featureCode, result.amount, result.transactionId);
+        this.emit('charged');
+        return result;
+    }
     async logout() {
         this.assertInitialized();
         await this.tokenManager.revoke();
@@ -333,7 +361,7 @@ class DotBotsAuth {
         }
         else {
             const redirectUri = encodeURIComponent(window.location.origin);
-            window.location.href = `${this.config.apiUrl}/auth/logout?redirectUri=${redirectUri}`;
+            window.location.href = `${this.config.apiUrl}/api/auth/logout?redirectUri=${redirectUri}`;
         }
     }
     on(event, handler) {
@@ -381,7 +409,7 @@ class DotBotsAuth {
         else if (!this.tokenManager.isAuthenticated()) {
             // Redirect to auth
             const redirectUri = encodeURIComponent(window.location.href);
-            window.location.href = `${this.config.apiUrl}/auth/authorize?appId=${this.config.appId}&redirectUri=${redirectUri}`;
+            window.location.href = `${this.config.apiUrl}/api/auth/authorize?appId=${this.config.appId}&redirectUri=${redirectUri}`;
         }
     }
     async buildRequest(url, options) {
@@ -413,6 +441,6 @@ class DotBotsAuth {
         }
     }
 }
-DotBotsAuth.SDK_VERSION = '1.0.8';
+DotBotsAuth.SDK_VERSION = '1.0.10';
 
 export { DotBotsAuth, DotBotsAuthError };

package/dist/types/react/DotBotsAuthProvider.d.ts

@@ -11,6 +11,9 @@ export interface DotBotsAuthContextValue {
     canAny: (permissions: string[]) => boolean;
     hasRole: (role: string) => boolean;
     fetch: (url: string, options?: RequestInit) => Promise<Response>;
+    charge: (featureCode: string, paidBy: 'org' | 'app', quantity?: number) => Promise<{
+        transactionId: string;
+    }>;
     logout: () => Promise<void>;
 }
 export declare const DotBotsAuthContext: import("react").Context<DotBotsAuthContextValue | null>;

package/dist/types/react/index.js

@@ -47,6 +47,7 @@ function DotBotsAuthProvider({ auth, children, loadingComponent, errorComponent,
         canAny: (permissions) => auth.canAny(permissions),
         hasRole: (role) => auth.hasRole(role),
         fetch: (url, options) => auth.fetch(url, options),
+        charge: (featureCode, paidBy, quantity) => auth.charge(featureCode, paidBy, quantity),
         logout: () => auth.logout(),
     };
     return (jsx(DotBotsAuthContext.Provider, { value: value, children: children }));

package/dist/types/types.d.ts

@@ -19,17 +19,17 @@ export interface DotBotsConfig {
 }
 export interface DotBotsUser {
     id: string;
-    name: string | null;
-    email: string | null;
+    name: string;
+    email: string;
     orgId: string;
-    orgName: string | null;
+    orgName: string;
     teams: {
         teamId: string;
         teamName: string;
     }[];
     roles: string[];
     permissions: string[];
-    avatarUrl: string | null;
+    avatarUrl?: string;
 }
 export interface DotBotsProxyConfig {
     /** URL of the local proxy, e.g. 'https://proxy.test-apps.dotbots.boutique' */
@@ -40,8 +40,8 @@ export interface DotBotsProxyConfig {
     cacheTtl: number;
 }
 export type ProxyFeature = 'cache' | 'localdb' | 'webhooks' | 'ratelimit';
-export type DotBotsAuthEvent = 'tokenRefreshed' | 'loggedOut' | 'sessionExpired' | 'userLoaded';
-export type DotBotsAuthErrorCode = 'IFRAME_TIMEOUT' | 'CODE_EXPIRED' | 'UNAUTHORIZED' | 'REFRESH_FAILED' | 'NETWORK_ERROR' | 'NOT_INITIALIZED' | 'PROXY_UNAVAILABLE';
+export type DotBotsAuthEvent = 'tokenRefreshed' | 'loggedOut' | 'sessionExpired' | 'userLoaded' | 'charged';
+export type DotBotsAuthErrorCode = 'IFRAME_TIMEOUT' | 'CODE_EXPIRED' | 'UNAUTHORIZED' | 'REFRESH_FAILED' | 'NETWORK_ERROR' | 'NOT_INITIALIZED' | 'PROXY_UNAVAILABLE' | 'PAYMENT_FAILED';
 export interface TokenPair {
     accessToken: string;
     refreshToken: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotbots-boutique/auth-sdk",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "Authentication SDK for DotBots marketplace apps",
   "license": "MIT",
   "type": "module",