@dotbots-boutique/auth-sdk 1.0.8 → 1.0.9

package/README.md

@@ -154,6 +154,42 @@ This is the **only** method that routes via `proxyUrl`. All auth calls and the p
 
 ---
 
+## 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`.
+
+---
+
 ## Checking permissions
 
 ```typescript
@@ -223,6 +259,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 |
 
 ---
 
@@ -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`. 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

@@ -325,6 +325,23 @@ 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');
+        }
+        return response.json();
+    }
     async logout() {
         this.assertInitialized();
         await this.tokenManager.revoke();
@@ -415,7 +432,7 @@ class DotBotsAuth {
         }
     }
 }
-DotBotsAuth.SDK_VERSION = '1.0.8';
+DotBotsAuth.SDK_VERSION = '1.0.9';
 
 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

@@ -323,6 +323,23 @@ 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');
+        }
+        return response.json();
+    }
     async logout() {
         this.assertInitialized();
         await this.tokenManager.revoke();
@@ -413,6 +430,6 @@ class DotBotsAuth {
         }
     }
 }
-DotBotsAuth.SDK_VERSION = '1.0.8';
+DotBotsAuth.SDK_VERSION = '1.0.9';
 
 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.9";
     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/index.js

@@ -323,6 +323,23 @@ 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');
+        }
+        return response.json();
+    }
     async logout() {
         this.assertInitialized();
         await this.tokenManager.revoke();
@@ -413,6 +430,6 @@ class DotBotsAuth {
         }
     }
 }
-DotBotsAuth.SDK_VERSION = '1.0.8';
+DotBotsAuth.SDK_VERSION = '1.0.9';
 
 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

@@ -41,7 +41,7 @@ export interface DotBotsProxyConfig {
 }
 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 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.9",
   "description": "Authentication SDK for DotBots marketplace apps",
   "license": "MIT",
   "type": "module",