@dotbots-boutique/auth-sdk 0.1.0 → 1.0.2

package/README.md

@@ -1,51 +1,51 @@
 # @dotbots-boutique/auth-sdk
- 
+
 The official authentication and authorisation SDK for apps running on the [DotBots Boutique](https://dotbots.boutique) platform.
- 
+
 ## What is DotBots Boutique?
- 
+
 [DotBots Boutique](https://dotbots.boutique) is a marketplace platform where vibe coders build and publish apps. The platform handles user management, authentication, authorisation, payments, and infrastructure, and offers a growing set of additional services — so you can focus on building your app.
- 
+
 ---
- 
+
 ## Installation
- 
+
 ```bash
 npm install @dotbots-boutique/auth-sdk
 ```
- 
+
 > **Note:** This package is for **browser use only**. Do not install it in a Deno or Node backend. A separate `@dotbots-boutique/server-sdk` for backend use is coming soon.
- 
+
 ---
- 
+
 ## Quick start
- 
+
 ### React
- 
+
 ```tsx
 // main.tsx
 import { DotBotsAuth } from '@dotbots-boutique/auth-sdk';
 import { DotBotsAuthProvider } from '@dotbots-boutique/auth-sdk/react';
- 
+
 const auth = new DotBotsAuth({
   appId: import.meta.env.VITE_DOTBOTS_APP_ID,
   apiUrl: import.meta.env.VITE_DOTBOTS_API_URL
 });
- 
+
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <DotBotsAuthProvider auth={auth}>
     <App />
   </DotBotsAuthProvider>
 );
 ```
- 
+
 ```tsx
 // In any component
 import { useDotBotsAuth } from '@dotbots-boutique/auth-sdk/react';
- 
+
 const MyComponent = () => {
   const { user, can, hasRole, fetch, logout } = useDotBotsAuth();
- 
+
   return (
     <div>
       <p>Welcome, {user?.name}</p>
@@ -56,94 +56,140 @@ const MyComponent = () => {
   );
 };
 ```
- 
+
+Custom loading and error screens:
+
+```tsx
+<DotBotsAuthProvider
+  auth={auth}
+  loadingComponent={<MySpinner />}
+  errorComponent={(error) => <MyError error={error} />}
+>
+  <App />
+</DotBotsAuthProvider>
+```
+
 ### Without React
- 
+
 ```typescript
 import { DotBotsAuth } from '@dotbots-boutique/auth-sdk';
- 
+
 const auth = new DotBotsAuth({
   appId: import.meta.env.VITE_DOTBOTS_APP_ID,
   apiUrl: import.meta.env.VITE_DOTBOTS_API_URL
 });
- 
+
 await auth.initialize();
- 
+
 const user = await auth.getUser();
 console.log(user.name, user.roles);
 ```
- 
+
 ---
- 
+
 ## How authentication works
- 
+
 Your app can run in two modes — the SDK handles both automatically.
- 
+
 **Inside an iframe** (embedded in the DotBots Boutique marketplace):
 1. The SDK sends a `DOTBOTS_READY` message to the marketplace
 2. The marketplace responds with a short-lived auth code
 3. The SDK exchanges the code for an access token and refresh token
- 
+
 **Standalone** (opened directly on your app's domain):
 1. The SDK checks for a `?code=` parameter in the URL
 2. If absent, it redirects the user to the DotBots login page
 3. After login, the user is redirected back with a code that the SDK exchanges for tokens
- 
+
 All tokens are stored in memory only — never in `localStorage`, `sessionStorage`, or cookies.
- 
+
+---
+
+## Proxy architecture
+
+The SDK does not communicate directly with `api.dotbots.ai` for app-related calls. Each app server runs a shared proxy that handles caching, local database access, and request forwarding:
+
+```
+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 (`/api/auth/*`) and the proxy config endpoint always go directly to `apiUrl` — never through the proxy.
+
+---
+
+## X-Environment header
+
+The SDK automatically detects the environment based on `window.location.hostname`:
+
+- Hostnames containing `test-apps` → `test`
+- All other hostnames → `prod`
+
+The `X-Environment` header is included on **every** request the SDK makes — auth endpoints, proxy config, and all `auth.fetch()` calls. No configuration is needed.
+
 ---
- 
+
 ## Making API calls
- 
+
 Always use `auth.fetch()` instead of the native `fetch()`. The SDK automatically:
 - Adds the `Authorization`, `X-App-Id` and `X-Environment` headers
 - Routes calls through the local proxy when available
 - Refreshes the access token when it is about to expire
 - Retries once on a `401` response
- 
+
 ```typescript
 // GET
 const response = await auth.fetch('/api/customers');
 const customers = await response.json();
- 
+
 // POST
 const response = await auth.fetch('/api/customers', {
   method: 'POST',
   body: JSON.stringify({ name: 'Acme' })
 });
 ```
- 
+
+This is the **only** method that routes via `proxyUrl`. All auth calls and the proxy config call always go directly to `apiUrl`.
+
 ---
- 
+
 ## Checking permissions
- 
+
 ```typescript
 auth.can('customers.read')                           // true/false
 auth.canAll(['customers.read', 'customers.write'])   // true/false — all required
 auth.canAny(['customers.read', 'invoices.read'])     // true/false — at least one
 auth.hasRole('admin')                                // true/false
 ```
- 
+
 ---
- 
+
 ## Events
- 
+
 ```typescript
 auth.on('tokenRefreshed', () => { });
 auth.on('sessionExpired', () => {
   // Show a message to the user
 });
 auth.on('loggedOut', () => { });
-auth.on('userLoaded', (user) => { });
+auth.on('userLoaded', () => { });
 ```
- 
+
+| Event | Description |
+|-------|-------------|
+| `tokenRefreshed` | Access token was refreshed |
+| `loggedOut` | User logged out |
+| `sessionExpired` | Refresh token expired, user must re-authenticate |
+| `userLoaded` | User data was fetched |
+
 ---
- 
+
 ## Error handling
- 
+
 ```typescript
 import { DotBotsAuthError } from '@dotbots-boutique/auth-sdk';
- 
+
 try {
   await auth.initialize();
 } catch (error) {
@@ -165,9 +211,9 @@ try {
   }
 }
 ```
- 
+
 ### Error codes
- 
+
 | Code | Description | Fatal |
 |------|-------------|-------|
 | `IFRAME_TIMEOUT` | Marketplace did not respond within the timeout | Yes |
@@ -177,11 +223,11 @@ 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 |
- 
+
 ---
- 
+
 ## Configuration
- 
+
 ```typescript
 interface DotBotsConfig {
   appId: string;                     // Required — app ID assigned by the platform
@@ -192,11 +238,11 @@ interface DotBotsConfig {
   onTokenRefreshFailed?: () => void; // Called when token refresh fails
 }
 ```
- 
+
 ---
- 
+
 ## DotBotsUser
- 
+
 ```typescript
 interface DotBotsUser {
   id: string;
@@ -204,25 +250,108 @@ interface DotBotsUser {
   email: string | null;       // null if 'email' scope not granted
   orgId: string;
   orgName: string | null;     // null if 'org' scope not granted
+  teams: { teamId: string; teamName: string }[];
   roles: string[];
   permissions: string[];
   avatarUrl: string | null;   // null if 'avatar' scope not granted
 }
 ```
- 
-Fields marked as `null` are not provided by the platform because the user has not granted the corresponding scope. Scopes are declared in your app's `dotbots.boutique.json` file.
- 
+
+Fields marked as `null` are not provided by the platform because the user has not granted the corresponding scope.
+
 ---
- 
+
+## API Reference
+
+### `DotBotsAuth`
+
+#### `constructor(config: DotBotsConfig)`
+
+Creates a new SDK instance.
+
+#### `initialize(): Promise<void>`
+
+Starts the authentication flow. Must be called before any other method.
+
+1. Fetches proxy config from `apiUrl`
+2. Detects the auth scenario (iframe or standalone)
+3. Authenticates the user
+
+#### `getUser(): Promise<DotBotsUser>`
+
+Returns the current user. Cached until the access token expires.
+
+#### `can(permission: string): boolean`
+
+Check if the user has a specific permission. Throws if `getUser()` hasn't been called.
+
+#### `canAll(permissions: string[]): boolean`
+
+Check if the user has **all** specified permissions.
+
+#### `canAny(permissions: string[]): boolean`
+
+Check if the user has **at least one** of the specified permissions.
+
+#### `hasRole(role: string): boolean`
+
+Check if the user has a specific role.
+
+#### `fetch(url: string, options?: RequestInit): Promise<Response>`
+
+Authenticated fetch wrapper. Routes through the proxy when available, falls back to `apiUrl` when not. Retries once on 401 after refreshing the token.
+
+#### `logout(): Promise<void>`
+
+Logs out the user. Revokes tokens on `apiUrl`, clears state, and redirects (standalone) or notifies the parent (iframe).
+
+#### `on(event: DotBotsAuthEvent, handler: Function): void`
+
+Register an event listener.
+
+#### `off(event: DotBotsAuthEvent, handler: Function): void`
+
+Remove an event listener.
+
+### `useDotBotsAuth()` (React)
+
+```typescript
+const {
+  user,       // DotBotsUser | null
+  isLoading,  // boolean
+  error,      // DotBotsAuthError | null
+  can,        // (permission: string) => boolean
+  canAll,     // (permissions: string[]) => boolean
+  canAny,     // (permissions: string[]) => boolean
+  hasRole,    // (role: string) => boolean
+  fetch,      // auth.fetch proxied
+  logout,     // auth.logout proxied
+} = useDotBotsAuth();
+```
+
+---
+
 ## Backend integration
- 
+
 If your app has a backend, forward the three headers from the frontend request to your backend, and from your backend to the proxy.
- 
+
+### Frontend → Proxy (direct)
+
+Use this when your app has no backend or when the data is public within the organisation. The SDK handles everything automatically.
+
+```typescript
+const response = await auth.fetch('/api/customers');
+```
+
+### Frontend → Backend → Proxy
+
+Use this when your backend performs extra logic before sending data to the frontend, such as validation, transformation, or aggregation of multiple proxy calls.
+
 ```typescript
 // Deno backend example
 app.get('/api/customers', async (req) => {
   const proxyUrl = Deno.env.get('DOTBOTS_PROXY_URL');
- 
+
   const response = await fetch(`${proxyUrl}/api/customers`, {
     headers: {
       'Authorization': req.headers.get('authorization') ?? '',
@@ -230,19 +359,21 @@ app.get('/api/customers', async (req) => {
       'X-Environment': req.headers.get('x-environment') ?? '',
     }
   });
- 
+
   return response;
 });
 ```
- 
+
+Forward the headers exactly as received from the frontend. Do not add your own logic to the token.
+
 **Never** store tokens in a database or log file, and never forward them to services outside the DotBots platform. The access token is scoped to your specific app — it cannot be used to access any other app's data.
- 
+
 ---
- 
+
 ## dotbots.boutique.json
- 
+
 Your repository must contain a `dotbots.boutique.json` file. Use the `env` field to declare any environment variables your app needs beyond the platform defaults. The platform will ask the installer to fill these in before deployment.
- 
+
 ```json
 {
   "dotbotsPromptVersion": "2.1.0",
@@ -267,33 +398,34 @@ Your repository must contain a `dotbots.boutique.json` file. Use the `env` field
   ]
 }
 ```
- 
+
 Platform variables (`DATABASE_URL`, `PORT`, `DOTBOTS_APP_ID`, `DOTBOTS_PROXY_URL`, `DOTBOTS_API_URL`) are injected automatically and do not need to be declared here.
- 
+
 ---
- 
+
 ## Security
- 
+
 - Tokens are stored in memory only — never persisted
 - `postMessage` origin is always validated — only messages from `marketplaceOrigin` are accepted
 - Auth codes are single-use and removed from the URL immediately after exchange
+- Tokens are never logged, not even in development mode
 - No runtime dependencies — eliminates supply chain risk entirely
 - Open source — [view the source on GitHub](https://github.com/dotbots-boutique/auth-sdk)
- 
+
 To report a security vulnerability, please email [security@dotbots.ai](mailto:security@dotbots.ai) instead of opening a public issue.
- 
+
 ---
- 
+
 ## Exports
- 
+
 ```typescript
 import { DotBotsAuth, DotBotsAuthError } from '@dotbots-boutique/auth-sdk';
 import type { DotBotsUser, DotBotsConfig, DotBotsAuthEvent, DotBotsProxyConfig } from '@dotbots-boutique/auth-sdk';
 import { DotBotsAuthProvider, useDotBotsAuth } from '@dotbots-boutique/auth-sdk/react';
 ```
- 
+
 ---
- 
+
 ## License
- 
+
 [MIT](./LICENSE) — © DotBots Boutique

package/dist/cjs/index.js

@@ -213,17 +213,17 @@ class ProxyConfigManager {
         }
     }
     getProxyUrl() {
-        return this.config?.proxyUrl ?? null;
+        return this.config !== null ? this.config.proxyUrl : null;
     }
     getConfig() {
         return this.config;
     }
     /**
-     * Returns the base URL to use for API calls.
+     * Returns the base URL to use for auth.fetch() calls.
      * Uses the proxy if available, otherwise falls back to apiUrl.
      */
     getBaseUrl() {
-        return this.config?.proxyUrl ?? this.apiUrl;
+        return this.config !== null ? this.config.proxyUrl : this.apiUrl;
     }
 }
 

package/dist/esm/index.js

@@ -211,17 +211,17 @@ class ProxyConfigManager {
         }
     }
     getProxyUrl() {
-        return this.config?.proxyUrl ?? null;
+        return this.config !== null ? this.config.proxyUrl : null;
     }
     getConfig() {
         return this.config;
     }
     /**
-     * Returns the base URL to use for API calls.
+     * Returns the base URL to use for auth.fetch() calls.
      * Uses the proxy if available, otherwise falls back to apiUrl.
      */
     getBaseUrl() {
-        return this.config?.proxyUrl ?? this.apiUrl;
+        return this.config !== null ? this.config.proxyUrl : this.apiUrl;
     }
 }
 

package/dist/types/ProxyConfigManager.d.ts

@@ -9,7 +9,7 @@ export declare class ProxyConfigManager {
     getProxyUrl(): string | null;
     getConfig(): DotBotsProxyConfig | null;
     /**
-     * Returns the base URL to use for API calls.
+     * Returns the base URL to use for auth.fetch() calls.
      * Uses the proxy if available, otherwise falls back to apiUrl.
      */
     getBaseUrl(): string;

package/dist/types/index.js

@@ -211,17 +211,17 @@ class ProxyConfigManager {
         }
     }
     getProxyUrl() {
-        return this.config?.proxyUrl ?? null;
+        return this.config !== null ? this.config.proxyUrl : null;
     }
     getConfig() {
         return this.config;
     }
     /**
-     * Returns the base URL to use for API calls.
+     * Returns the base URL to use for auth.fetch() calls.
      * Uses the proxy if available, otherwise falls back to apiUrl.
      */
     getBaseUrl() {
-        return this.config?.proxyUrl ?? this.apiUrl;
+        return this.config !== null ? this.config.proxyUrl : this.apiUrl;
     }
 }
 

package/dist/types/types.d.ts

@@ -1,7 +1,7 @@
 /**
- * Shared types for @dotbots/auth-sdk.
+ * Shared types for @dotbots-boutique/auth-sdk.
  * This file contains no browser dependencies so it can be reused
- * in a future @dotbots/server-sdk package.
+ * in a future @dotbots-boutique/server-sdk package.
  */
 export interface DotBotsConfig {
     /** Unique app identifier */
@@ -23,6 +23,10 @@ export interface DotBotsUser {
     email: string | null;
     orgId: string;
     orgName: string | null;
+    teams: {
+        teamId: string;
+        teamName: string;
+    }[];
     roles: string[];
     permissions: string[];
     avatarUrl: string | null;

package/package.json

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