@base44-preview/sdk 0.8.18-pr.91.a4c0940 → 0.8.18-pr.91.cfad1b0

package/README.md

@@ -9,31 +9,32 @@ You can use it in two ways:
 
 ## Installation
 
-Install the SDK via npm:
+**Inside Base44 apps**: The SDK is already available. No installation needed.
+
+**External apps**: Install the SDK via npm:
 
 ```bash
 npm install @base44/sdk
 ```
 
-> **Note**: In Base44-generated apps, the SDK is already installed for you.
-
 ## Modules
 
 The SDK provides access to Base44's functionality through the following modules:
 
 - **[`agents`](https://docs.base44.com/developers/references/sdk/docs/interfaces/agents)**: Interact with AI agents and manage conversations.
+- **[`analytics`](https://docs.base44.com/developers/references/sdk/docs/interfaces/analytics)**: Track custom events in your app.
 - **[`app-logs`](https://docs.base44.com/developers/references/sdk/docs/interfaces/app-logs)**: Access and query app logs.
 - **[`auth`](https://docs.base44.com/developers/references/sdk/docs/interfaces/auth)**: Manage user authentication, registration, and session handling.
 - **[`connectors`](https://docs.base44.com/developers/references/sdk/docs/interfaces/connectors)**: Manage OAuth connections and access tokens for third-party services.
 - **[`entities`](https://docs.base44.com/developers/references/sdk/docs/interfaces/entities)**: Work with your app's data entities using CRUD operations.
 - **[`functions`](https://docs.base44.com/developers/references/sdk/docs/interfaces/functions)**: Execute backend functions.
-- **[`integrations`](https://docs.base44.com/developers/references/sdk/docs/type-aliases/integrations)**: Pre-built integrations for external services.
+- **[`integrations`](https://docs.base44.com/developers/references/sdk/docs/type-aliases/integrations)**: Access pre-built and third-party integrations.
 
-## Quick starts
+## Quickstarts
 
-How you get started depends on your context:
+How you get started depends on whether you're working inside a Base44-generated app or building your own.
 
-### Inside a Base44 app
+### Inside Base44 apps
 
 In Base44-generated apps, the client is pre-configured. Just import and use it:
 
@@ -58,32 +59,32 @@ const tasks = await base44.entities.Task.list();
 
 ### External apps
 
-When using Base44 as a backend for your own app, create and configure the client yourself:
+When using Base44 as a backend for your own app, install the SDK and create the client yourself:
 
 ```typescript
-import { createClient } from '@base44/sdk';
+import { createClient } from "@base44/sdk";
 
 // Create a client for your Base44 app
 const base44 = createClient({
-  appId: 'your-app-id'  // Find this in the Base44 editor URL
+  appId: "your-app-id", // Find this in the Base44 editor URL
 });
 
-// Read public data (anonymous access)
+// Read public data
 const products = await base44.entities.Products.list();
 
 // Authenticate a user (token is automatically set)
-await base44.auth.loginViaEmailPassword('user@example.com', 'password');
+await base44.auth.loginViaEmailPassword("user@example.com", "password");
 
-// Now operations use the authenticated user's permissions
+// Access user's data
 const userOrders = await base44.entities.Orders.list();
 ```
 
 ### Service role
 
-For backend code that needs admin-level access, use the service role. Service role is only available in Base44-hosted backend functions:
+By default, the client operates with user-level permissions, limiting access to what the current user can see and do. The service role provides elevated permissions for backend operations and is only available in Base44-hosted backend functions. External backends can't use service role permissions.
 
 ```typescript
-import { createClientFromRequest } from 'npm:@base44/sdk';
+import { createClientFromRequest } from "npm:@base44/sdk";
 
 Deno.serve(async (req) => {
   const base44 = createClientFromRequest(req);
@@ -97,7 +98,15 @@ Deno.serve(async (req) => {
 
 ## Learn more
 
-For complete documentation, guides, and API reference, visit the **[Base44 SDK Documentation](https://docs.base44.com/developers/landing)**.
+The best way to get started with the JavaScript SDK is to have Base44 build an app for you. Once you have an app, you can explore the generated code and experiment with the SDK to see how it works in practice. You can also ask Base44 to demonstrate specific features of the SDK.
+
+For a deeper understanding, check out these guides:
+
+1. [Base44 client](https://docs.base44.com/developers/references/sdk/getting-started/client) - Work with the client in frontend, backend, and external app contexts.
+2. [Work with data](https://docs.base44.com/developers/references/sdk/getting-started/work-with-data) - Create, read, update, and delete data.
+3. [Common SDK patterns](https://docs.base44.com/developers/references/sdk/getting-started/work-with-sdk) - Authentication, integrations, functions, and error handling.
+
+For the complete documentation and API reference, visit the **[Base44 Developer Docs](https://docs.base44.com/developers/home)**.
 
 ## Development
 

package/dist/client.js

@@ -50,6 +50,8 @@ import { createAnalyticsModule } from "./modules/analytics.js";
  */
 export function createClient(config) {
     const { serverUrl = "https://base44.app", appId, token, serviceToken, requiresAuth = false, appBaseUrl, options, functionsVersion, headers: optionalHeaders, } = config;
+    // Normalize appBaseUrl to always be a string (empty if not provided or invalid)
+    const normalizedAppBaseUrl = typeof appBaseUrl === "string" ? appBaseUrl : "";
     const socketConfig = {
         serverUrl,
         mountPath: "/ws-user-apps/socket.io/",
@@ -102,7 +104,7 @@ export function createClient(config) {
         interceptResponses: false,
     });
     const userAuthModule = createAuthModule(axiosClient, functionsAxiosClient, appId, {
-        appBaseUrl,
+        appBaseUrl: normalizedAppBaseUrl,
         serverUrl,
     });
     const userModules = {

package/dist/modules/auth.js

@@ -20,7 +20,6 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
         },
         // Redirects the user to the app's login page
         redirectToLogin(nextUrl) {
-            var _a;
             // This function only works in a browser environment
             if (typeof window === "undefined") {
                 throw new Error("Login method can only be used in a browser environment");
@@ -30,7 +29,7 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
                 ? new URL(nextUrl, window.location.origin).toString()
                 : window.location.href;
             // Build the login URL
-            const loginUrl = `${(_a = options.appBaseUrl) !== null && _a !== void 0 ? _a : ""}/login?from_url=${encodeURIComponent(redirectUrl)}`;
+            const loginUrl = `${options.appBaseUrl}/login?from_url=${encodeURIComponent(redirectUrl)}`;
             // Redirect to the login page
             window.location.href = loginUrl;
         },
@@ -64,7 +63,7 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
                 // Determine the from_url parameter
                 const fromUrl = redirectUrl || window.location.href;
                 // Redirect to server-side logout endpoint to clear HTTP-only cookies
-                const logoutUrl = `${options.appBaseUrl}/api/apps/${appId}/auth/logout?from_url=${encodeURIComponent(fromUrl)}`;
+                const logoutUrl = `${options.appBaseUrl}/api/apps/auth/logout?from_url=${encodeURIComponent(fromUrl)}`;
                 window.location.href = logoutUrl;
             }
         },

package/dist/modules/auth.types.d.ts

@@ -90,8 +90,8 @@ export interface ResetPasswordParams {
 export interface AuthModuleOptions {
     /** Server URL for API requests. */
     serverUrl: string;
-    /** Optional base URL for the app (used for login redirects). */
-    appBaseUrl?: string;
+    /** Base URL for the app (used for login redirects). */
+    appBaseUrl: string;
 }
 /**
  * Authentication module for managing user authentication and authorization. The module automatically stores tokens in local storage when available and manages authorization headers for API requests.

package/dist/modules/entities.types.d.ts

@@ -4,12 +4,14 @@
 export type RealtimeEventType = "create" | "update" | "delete";
 /**
  * Payload received when a realtime event occurs.
+ *
+ * @typeParam T - The entity type for the data field. Defaults to `any`.
  */
-export interface RealtimeEvent {
+export interface RealtimeEvent<T = any> {
     /** The type of change that occurred */
     type: RealtimeEventType;
     /** The entity data */
-    data: any;
+    data: T;
     /** The unique identifier of the affected entity */
     id: string;
     /** ISO 8601 timestamp of when the event occurred */
@@ -17,14 +19,65 @@ export interface RealtimeEvent {
 }
 /**
  * Callback function invoked when a realtime event occurs.
+ *
+ * @typeParam T - The entity type for the event data. Defaults to `any`.
+ */
+export type RealtimeCallback<T = any> = (event: RealtimeEvent<T>) => void;
+/**
+ * Result returned when deleting a single entity.
+ */
+export interface DeleteResult {
+    /** Whether the deletion was successful */
+    success: boolean;
+}
+/**
+ * Result returned when deleting multiple entities.
+ */
+export interface DeleteManyResult {
+    /** Whether the deletion was successful */
+    success: boolean;
+    /** Number of entities that were deleted */
+    deleted: number;
+}
+/**
+ * Result returned when importing entities from a file.
+ *
+ * @typeParam T - The entity type for imported records. Defaults to `any`.
  */
-export type RealtimeCallback = (event: RealtimeEvent) => void;
+export interface ImportResult<T = any> {
+    /** Status of the import operation */
+    status: "success" | "error";
+    /** Details message, e.g., "Successfully imported 3 entities with RLS enforcement" */
+    details: string | null;
+    /** Array of created entity objects when successful, or null on error */
+    output: T[] | null;
+}
+/**
+ * Sort field type for entity queries.
+ *
+ * Supports ascending (no prefix or `'+'`) and descending (`'-'`) sorting.
+ *
+ * @typeParam T - The entity type to derive sortable fields from.
+ *
+ * @example
+ * ```typescript
+ * // Ascending sort (default)
+ * 'created_date'
+ * '+created_date'
+ *
+ * // Descending sort
+ * '-created_date'
+ * ```
+ */
+export type SortField<T> = (keyof T & string) | `+${keyof T & string}` | `-${keyof T & string}`;
 /**
  * Entity handler providing CRUD operations for a specific entity type.
  *
  * Each entity in the app gets a handler with these methods for managing data.
+ *
+ * @typeParam T - The entity type. Defaults to `any` for backward compatibility.
  */
-export interface EntityHandler {
+export interface EntityHandler<T = any> {
     /**
      * Lists records with optional pagination and sorting.
      *
@@ -33,11 +86,12 @@ export interface EntityHandler {
      *
      * **Note:** The maximum limit is 5,000 items per request.
      *
+     * @typeParam K - The fields to include in the response. Defaults to all fields.
      * @param sort - Sort parameter, such as `'-created_date'` for descending. Defaults to `'-created_date'`.
      * @param limit - Maximum number of results to return. Defaults to `50`.
      * @param skip - Number of results to skip for pagination. Defaults to `0`.
      * @param fields - Array of field names to include in the response. Defaults to all fields.
-     * @returns Promise resolving to an array of records.
+     * @returns Promise resolving to an array of records with selected fields.
      *
      * @example
      * ```typescript
@@ -64,7 +118,7 @@ export interface EntityHandler {
      * const fields = await base44.entities.MyEntity.list('-created_date', 10, 0, ['name', 'status']);
      * ```
      */
-    list(sort?: string, limit?: number, skip?: number, fields?: string[]): Promise<any>;
+    list<K extends keyof T = keyof T>(sort?: SortField<T>, limit?: number, skip?: number, fields?: K[]): Promise<Pick<T, K>[]>;
     /**
      * Filters records based on a query.
      *
@@ -73,6 +127,7 @@ export interface EntityHandler {
      *
      * **Note:** The maximum limit is 5,000 items per request.
      *
+     * @typeParam K - The fields to include in the response. Defaults to all fields.
      * @param query - Query object with field-value pairs. Each key should be a field name
      * from your entity schema, and each value is the criteria to match. Records matching all
      * specified criteria are returned. Field names are case-sensitive.
@@ -80,7 +135,7 @@ export interface EntityHandler {
      * @param limit - Maximum number of results to return. Defaults to `50`.
      * @param skip - Number of results to skip for pagination. Defaults to `0`.
      * @param fields - Array of field names to include in the response. Defaults to all fields.
-     * @returns Promise resolving to an array of filtered records.
+     * @returns Promise resolving to an array of filtered records with selected fields.
      *
      * @example
      * ```typescript
@@ -122,7 +177,7 @@ export interface EntityHandler {
      * );
      * ```
      */
-    filter(query: Record<string, any>, sort?: string, limit?: number, skip?: number, fields?: string[]): Promise<any>;
+    filter<K extends keyof T = keyof T>(query: Partial<T>, sort?: SortField<T>, limit?: number, skip?: number, fields?: K[]): Promise<Pick<T, K>[]>;
     /**
      * Gets a single record by ID.
      *
@@ -138,7 +193,7 @@ export interface EntityHandler {
      * console.log(record.name);
      * ```
      */
-    get(id: string): Promise<any>;
+    get(id: string): Promise<T>;
     /**
      * Creates a new record.
      *
@@ -158,7 +213,7 @@ export interface EntityHandler {
      * console.log('Created record with ID:', newRecord.id);
      * ```
      */
-    create(data: Record<string, any>): Promise<any>;
+    create(data: Partial<T>): Promise<T>;
     /**
      * Updates an existing record.
      *
@@ -187,7 +242,7 @@ export interface EntityHandler {
      * });
      * ```
      */
-    update(id: string, data: Record<string, any>): Promise<any>;
+    update(id: string, data: Partial<T>): Promise<T>;
     /**
      * Deletes a single record by ID.
      *
@@ -200,10 +255,10 @@ export interface EntityHandler {
      * ```typescript
      * // Delete a record
      * const result = await base44.entities.MyEntity.delete('entity-123');
-     * console.log('Deleted:', result);
+     * console.log('Deleted:', result.success);
      * ```
      */
-    delete(id: string): Promise<any>;
+    delete(id: string): Promise<DeleteResult>;
     /**
      * Deletes multiple records matching a query.
      *
@@ -224,7 +279,7 @@ export interface EntityHandler {
      * console.log('Deleted:', result);
      * ```
      */
-    deleteMany(query: Record<string, any>): Promise<any>;
+    deleteMany(query: Partial<T>): Promise<DeleteManyResult>;
     /**
      * Creates multiple records in a single request.
      *
@@ -244,7 +299,7 @@ export interface EntityHandler {
      * ]);
      * ```
      */
-    bulkCreate(data: Record<string, any>[]): Promise<any>;
+    bulkCreate(data: Partial<T>[]): Promise<T[]>;
     /**
      * Imports records from a file.
      *
@@ -252,7 +307,7 @@ export interface EntityHandler {
      * The file format should match your entity structure. Requires a browser environment and can't be used in the backend.
      *
      * @param file - File object to import.
-     * @returns Promise resolving to the import result.
+     * @returns Promise resolving to the import result containing status, details, and created records.
      *
      * @example
      * ```typescript
@@ -261,12 +316,14 @@ export interface EntityHandler {
      *   const file = event.target.files?.[0];
      *   if (file) {
      *     const result = await base44.entities.MyEntity.importEntities(file);
-     *     console.log(`Imported ${result.count} records`);
+     *     if (result.status === 'success' && result.output) {
+     *       console.log(`Imported ${result.output.length} records`);
+     *     }
      *   }
      * };
      * ```
      */
-    importEntities(file: File): Promise<any>;
+    importEntities(file: File): Promise<ImportResult<T>>;
     /**
      * Subscribes to realtime updates for all records of this entity type.
      *
@@ -292,7 +349,7 @@ export interface EntityHandler {
      * unsubscribe();
      * ```
      */
-    subscribe(callback: RealtimeCallback): () => void;
+    subscribe(callback: RealtimeCallback<T>): () => void;
 }
 /**
  * Entities module for managing app data.
@@ -340,5 +397,5 @@ export interface EntitiesModule {
      * base44.entities.AnotherEntity
      * ```
      */
-    [entityName: string]: EntityHandler;
+    [entityName: string]: EntityHandler<any>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.18-pr.91.a4c0940",
+  "version": "0.8.18-pr.91.cfad1b0",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",