@base44/sdk 0.3.0 → 0.5.0

package/README.md

@@ -20,10 +20,10 @@ import { createClient } from '@base44/sdk';
 // Create a client instance
 const base44 = createClient({
   serverUrl: 'https://base44.app', // Optional, defaults to 'https://base44.app'
-  appId: 'your-app-id',  // Required
-  env: 'prod',           // Optional, defaults to 'prod'
-  token: 'your-token',   // Optional
-  autoInitAuth: true,    // Optional, defaults to true - auto-detects tokens from URL or localStorage
+  appId: 'your-app-id',            // Required
+  token: 'your-user-token',        // Optional, for user authentication
+  serviceToken: 'your-service-token', // Optional, for service role authentication
+  autoInitAuth: true,              // Optional, defaults to true - auto-detects tokens from URL or localStorage
 });
 ```
 
@@ -63,6 +63,77 @@ const newProducts = await base44.entities.Product.bulkCreate([
 ]);
 ```
 
+### Service Role Authentication
+
+Service role authentication allows server-side applications to perform operations with elevated privileges. This is useful for administrative tasks, background jobs, and server-to-server communication.
+
+```javascript
+import { createClient } from '@base44/sdk';
+
+// Create a client with service role token
+const base44 = createClient({
+  appId: 'your-app-id',
+  token: 'user-token',              // For user operations
+  serviceToken: 'service-token'     // For service role operations
+});
+
+// User operations (uses user token)
+const userEntities = await base44.entities.User.list();
+
+// Service role operations (uses service token)
+const allEntities = await base44.asServiceRole.entities.User.list();
+
+// Service role has access to:
+// - base44.asServiceRole.entities
+// - base44.asServiceRole.integrations
+// - base44.asServiceRole.functions
+// Note: Service role does NOT have access to auth module for security
+
+// If no service token is provided, accessing asServiceRole throws an error
+const clientWithoutService = createClient({ appId: 'your-app-id' });
+try {
+  await clientWithoutService.asServiceRole.entities.User.list();
+} catch (error) {
+  // Error: Service token is required to use asServiceRole
+}
+```
+
+### Server-Side Usage
+
+For server-side applications, you can create a client from incoming HTTP requests:
+
+```javascript
+import { createClientFromRequest } from '@base44/sdk';
+
+// In your server handler (Express, Next.js, etc.)
+app.get('/api/data', async (req, res) => {
+  try {
+    // Extract client configuration from request headers
+    const base44 = createClientFromRequest(req);
+    
+    // Headers used:
+    // - Authorization: Bearer <user-token>
+    // - Base44-Service-Authorization: Bearer <service-token>
+    // - Base44-App-Id: <app-id>
+    // - Base44-Api-Url: <custom-api-url> (optional)
+    
+    // Use appropriate authentication based on available tokens
+    let data;
+    if (base44.asServiceRole) {
+      // Service token available - use elevated privileges
+      data = await base44.asServiceRole.entities.SensitiveData.list();
+    } else {
+      // Only user token available - use user permissions
+      data = await base44.entities.PublicData.list();
+    }
+    
+    res.json(data);
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+});
+```
+
 ### Working with Integrations
 
 ```javascript
@@ -103,7 +174,7 @@ import { getAccessToken } from '@base44/sdk/utils/auth-utils';
 // Create a client with authentication
 const base44 = createClient({
   appId: 'your-app-id',
-  accessToken: getAccessToken() // Automatically retrieves token from localStorage or URL
+  token: getAccessToken() // Automatically retrieves token from localStorage or URL
 });
 
 // Check authentication status
@@ -167,7 +238,7 @@ function AuthProvider({ children }) {
   const [client] = useState(() => 
     createClient({ 
       appId: 'your-app-id', 
-      accessToken: getAccessToken()
+      token: getAccessToken()
     })
   );
 
@@ -347,6 +418,24 @@ async function fetchProducts() {
   }
 }
 
+// Service role operations with TypeScript
+async function adminOperations() {
+  const base44 = createClient({
+    appId: 'your-app-id',
+    serviceToken: 'service-token'
+  });
+
+  // TypeScript knows asServiceRole requires a service token
+  try {
+    const allUsers: Entity[] = await base44.asServiceRole.entities.User.list();
+    console.log(`Total users: ${allUsers.length}`);
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(error.message); // Service token is required to use asServiceRole
+    }
+  }
+}
+
 // Authentication with TypeScript
 async function handleAuth(auth: AuthModule) {
   // Check authentication
@@ -456,6 +545,25 @@ try {
 }
 ```
 
+## Functions
+
+The SDK supports invoking custom functions:
+
+```javascript
+// Invoke a function without parameters
+const result = await base44.functions.myFunction();
+
+// Invoke a function with parameters
+const result = await base44.functions.calculateTotal({
+  items: ['item1', 'item2'],
+  discount: 0.1
+});
+
+// Functions are automatically authenticated with the user token
+// Service role can also invoke functions
+const serviceResult = await base44.asServiceRole.functions.adminFunction();
+```
+
 ## Testing
 
 The SDK includes comprehensive tests to ensure reliability.

package/dist/client.d.ts

@@ -3,18 +3,39 @@
  * @param {Object} config - Client configuration
  * @param {string} [config.serverUrl='https://base44.app'] - API server URL
  * @param {string|number} config.appId - Application ID
- * @param {string} [config.env='prod'] - Environment ('prod' or 'dev')
  * @param {string} [config.token] - Authentication token
+ * @param {string} [config.serviceToken] - Service role authentication token
  * @param {boolean} [config.requiresAuth=false] - Whether the app requires authentication
  * @returns {Object} Base44 client instance
  */
 export declare function createClient(config: {
     serverUrl?: string;
     appId: string;
-    env?: string;
     token?: string;
+    serviceToken?: string;
     requiresAuth?: boolean;
 }): {
+    /**
+     * Set authentication token for all requests
+     * @param {string} newToken - New auth token
+     */
+    setToken(newToken: string): void;
+    /**
+     * Get current configuration
+     * @returns {Object} Current configuration
+     */
+    getConfig(): {
+        serverUrl: string;
+        appId: string;
+        requiresAuth: boolean;
+    };
+    asServiceRole: {
+        entities: {};
+        integrations: {};
+        functions: {
+            invoke(functionName: string, data: Record<string, any>): Promise<import("axios").AxiosResponse<any, any>>;
+        };
+    };
     entities: {};
     integrations: {};
     auth: {
@@ -24,7 +45,7 @@ export declare function createClient(config: {
         redirectToLogin(nextUrl: string): void;
         logout(redirectUrl?: string): void;
         setToken(token: string, saveToStorage?: boolean): void;
-        loginViaUsernamePassword(email: string, password: string, turnstileToken?: string): Promise<{
+        loginViaEmailPassword(email: string, password: string, turnstileToken?: string): Promise<{
             access_token: string;
             user: any;
         }>;
@@ -33,6 +54,8 @@ export declare function createClient(config: {
     functions: {
         invoke(functionName: string, data: Record<string, any>): Promise<import("axios").AxiosResponse<any, any>>;
     };
+};
+export declare function createClientFromRequest(request: Request): {
     /**
      * Set authentication token for all requests
      * @param {string} newToken - New auth token
@@ -45,7 +68,31 @@ export declare function createClient(config: {
     getConfig(): {
         serverUrl: string;
         appId: string;
-        env: string;
         requiresAuth: boolean;
     };
+    asServiceRole: {
+        entities: {};
+        integrations: {};
+        functions: {
+            invoke(functionName: string, data: Record<string, any>): Promise<import("axios").AxiosResponse<any, any>>;
+        };
+    };
+    entities: {};
+    integrations: {};
+    auth: {
+        me(): Promise<import("axios").AxiosResponse<any, any>>;
+        getSsoAccessToken(): Promise<import("axios").AxiosResponse<any, any>>;
+        updateMe(data: Record<string, any>): Promise<import("axios").AxiosResponse<any, any>>;
+        redirectToLogin(nextUrl: string): void;
+        logout(redirectUrl?: string): void;
+        setToken(token: string, saveToStorage?: boolean): void;
+        loginViaEmailPassword(email: string, password: string, turnstileToken?: string): Promise<{
+            access_token: string;
+            user: any;
+        }>;
+        isAuthenticated(): Promise<boolean>;
+    };
+    functions: {
+        invoke(functionName: string, data: Record<string, any>): Promise<import("axios").AxiosResponse<any, any>>;
+    };
 };

package/dist/client.js

@@ -9,30 +9,27 @@ import { createFunctionsModule } from "./modules/functions.js";
  * @param {Object} config - Client configuration
  * @param {string} [config.serverUrl='https://base44.app'] - API server URL
  * @param {string|number} config.appId - Application ID
- * @param {string} [config.env='prod'] - Environment ('prod' or 'dev')
  * @param {string} [config.token] - Authentication token
+ * @param {string} [config.serviceToken] - Service role authentication token
  * @param {boolean} [config.requiresAuth=false] - Whether the app requires authentication
  * @returns {Object} Base44 client instance
  */
 export function createClient(config) {
-    const { serverUrl = "https://base44.app", appId, env = "prod", token, requiresAuth = false, } = config;
-    // Create the base axios client
+    const { serverUrl = "https://base44.app", appId, token, serviceToken, requiresAuth = false, } = config;
     const axiosClient = createAxiosClient({
         baseURL: `${serverUrl}/api`,
         headers: {
             "X-App-Id": String(appId),
-            "X-Environment": env,
         },
         token,
-        requiresAuth, // Pass requiresAuth to axios client
-        appId, // Pass appId for login redirect
-        serverUrl, // Pass serverUrl for login redirect
+        requiresAuth,
+        appId,
+        serverUrl,
     });
     const functionsAxiosClient = createAxiosClient({
         baseURL: `${serverUrl}/api`,
         headers: {
             "X-App-Id": String(appId),
-            "X-Environment": env,
         },
         token,
         requiresAuth,
@@ -40,17 +37,42 @@ export function createClient(config) {
         serverUrl,
         interceptResponses: false,
     });
-    // Create modules
-    const entities = createEntitiesModule(axiosClient, appId);
-    const integrations = createIntegrationsModule(axiosClient, appId);
-    const auth = createAuthModule(axiosClient, appId, serverUrl);
-    const functions = createFunctionsModule(functionsAxiosClient, appId);
+    const serviceRoleAxiosClient = createAxiosClient({
+        baseURL: `${serverUrl}/api`,
+        headers: {
+            "X-App-Id": String(appId),
+        },
+        token: serviceToken,
+        serverUrl,
+        appId,
+    });
+    const serviceRoleFunctionsAxiosClient = createAxiosClient({
+        baseURL: `${serverUrl}/api`,
+        headers: {
+            "X-App-Id": String(appId),
+        },
+        token: serviceToken,
+        serverUrl,
+        appId,
+        interceptResponses: false,
+    });
+    const userModules = {
+        entities: createEntitiesModule(axiosClient, appId),
+        integrations: createIntegrationsModule(axiosClient, appId),
+        auth: createAuthModule(axiosClient, functionsAxiosClient, appId),
+        functions: createFunctionsModule(functionsAxiosClient, appId),
+    };
+    const serviceRoleModules = {
+        entities: createEntitiesModule(serviceRoleAxiosClient, appId),
+        integrations: createIntegrationsModule(serviceRoleAxiosClient, appId),
+        functions: createFunctionsModule(serviceRoleFunctionsAxiosClient, appId),
+    };
     // Always try to get token from localStorage or URL parameters
     if (typeof window !== "undefined") {
         // Get token from URL or localStorage
         const accessToken = token || getAccessToken();
         if (accessToken) {
-            auth.setToken(accessToken);
+            userModules.auth.setToken(accessToken);
         }
     }
     // If authentication is required, verify token and redirect to login if needed
@@ -58,29 +80,26 @@ export function createClient(config) {
         // We perform this check asynchronously to not block client creation
         setTimeout(async () => {
             try {
-                const isAuthenticated = await auth.isAuthenticated();
+                const isAuthenticated = await userModules.auth.isAuthenticated();
                 if (!isAuthenticated) {
-                    auth.redirectToLogin(window.location.href);
+                    userModules.auth.redirectToLogin(window.location.href);
                 }
             }
             catch (error) {
                 console.error("Authentication check failed:", error);
-                auth.redirectToLogin(window.location.href);
+                userModules.auth.redirectToLogin(window.location.href);
             }
         }, 0);
     }
     // Assemble and return the client
-    return {
-        entities,
-        integrations,
-        auth,
-        functions,
+    const client = {
+        ...userModules,
         /**
          * Set authentication token for all requests
          * @param {string} newToken - New auth token
          */
         setToken(newToken) {
-            auth.setToken(newToken);
+            userModules.auth.setToken(newToken);
         },
         /**
          * Get current configuration
@@ -90,9 +109,49 @@ export function createClient(config) {
             return {
                 serverUrl,
                 appId,
-                env,
                 requiresAuth,
             };
         },
+        /**
+         * Access service role modules - throws error if no service token was provided
+         * @throws {Error} When accessed without a service token
+         */
+        get asServiceRole() {
+            if (!serviceToken) {
+                throw new Error('Service token is required to use asServiceRole. Please provide a serviceToken when creating the client.');
+            }
+            return serviceRoleModules;
+        }
     };
+    return client;
+}
+export function createClientFromRequest(request) {
+    const authHeader = request.headers.get("Authorization");
+    const serviceRoleAuthHeader = request.headers.get("Base44-Service-Authorization");
+    const appId = request.headers.get("Base44-App-Id");
+    const serverUrlHeader = request.headers.get("Base44-Api-Url");
+    if (!appId) {
+        throw new Error("Base44-App-Id header is required, but is was not found on the request");
+    }
+    // Validate authorization header formats
+    let serviceRoleToken;
+    let userToken;
+    if (serviceRoleAuthHeader !== null) {
+        if (serviceRoleAuthHeader === '' || !serviceRoleAuthHeader.startsWith('Bearer ') || serviceRoleAuthHeader.split(' ').length !== 2) {
+            throw new Error('Invalid authorization header format. Expected "Bearer <token>"');
+        }
+        serviceRoleToken = serviceRoleAuthHeader.split(' ')[1];
+    }
+    if (authHeader !== null) {
+        if (authHeader === '' || !authHeader.startsWith('Bearer ') || authHeader.split(' ').length !== 2) {
+            throw new Error('Invalid authorization header format. Expected "Bearer <token>"');
+        }
+        userToken = authHeader.split(' ')[1];
+    }
+    return createClient({
+        serverUrl: serverUrlHeader || "https://base44.app",
+        appId,
+        token: userToken,
+        serviceToken: serviceRoleToken,
+    });
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { createClient } from "./client.js";
+import { createClient, createClientFromRequest } from "./client.js";
 import { Base44Error } from "./utils/axios-client.js";
 import { getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl } from "./utils/auth-utils.js";
-export { createClient, Base44Error, getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, };
+export { createClient, createClientFromRequest, Base44Error, getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, };

package/dist/index.js

@@ -1,6 +1,4 @@
-import { createClient } from "./client.js";
+import { createClient, createClientFromRequest } from "./client.js";
 import { Base44Error } from "./utils/axios-client.js";
 import { getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, } from "./utils/auth-utils.js";
-export { createClient, Base44Error, 
-// Export auth utilities for easier access
-getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, };
+export { createClient, createClientFromRequest, Base44Error, getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, };

package/dist/modules/auth.d.ts

@@ -6,7 +6,7 @@ import { AxiosInstance } from "axios";
  * @param {string} serverUrl - Server URL
  * @returns {Object} Auth module with authentication methods
  */
-export declare function createAuthModule(axios: AxiosInstance, appId: string, serverUrl: string): {
+export declare function createAuthModule(axios: AxiosInstance, functionsAxiosClient: AxiosInstance, appId: string): {
     /**
      * Get current user information
      * @returns {Promise<Object>} Current user data
@@ -49,7 +49,7 @@ export declare function createAuthModule(axios: AxiosInstance, appId: string, se
      * @param turnstileToken - Optional Turnstile captcha token
      * @returns Login response with access_token and user
      */
-    loginViaUsernamePassword(email: string, password: string, turnstileToken?: string): Promise<{
+    loginViaEmailPassword(email: string, password: string, turnstileToken?: string): Promise<{
         access_token: string;
         user: any;
     }>;

package/dist/modules/auth.js

@@ -5,7 +5,7 @@
  * @param {string} serverUrl - Server URL
  * @returns {Object} Auth module with authentication methods
  */
-export function createAuthModule(axios, appId, serverUrl) {
+export function createAuthModule(axios, functionsAxiosClient, appId) {
     return {
         /**
          * Get current user information
@@ -83,6 +83,7 @@ export function createAuthModule(axios, appId, serverUrl) {
             if (!token)
                 return;
             axios.defaults.headers.common["Authorization"] = `Bearer ${token}`;
+            functionsAxiosClient.defaults.headers.common["Authorization"] = `Bearer ${token}`;
             // Save token to localStorage if requested
             if (saveToStorage &&
                 typeof window !== "undefined" &&
@@ -102,7 +103,7 @@ export function createAuthModule(axios, appId, serverUrl) {
          * @param turnstileToken - Optional Turnstile captcha token
          * @returns Login response with access_token and user
          */
-        async loginViaUsernamePassword(email, password, turnstileToken) {
+        async loginViaEmailPassword(email, password, turnstileToken) {
             var _a;
             try {
                 const response = await axios.post(`/apps/${appId}/auth/login`, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/sdk",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",