@base44-preview/sdk 0.8.55-pr.345.357a9ca → 0.8.56-pr.346.ce5b5be

package/dist/client.js

@@ -3,6 +3,7 @@ import { createEntitiesModule } from "./modules/entities.js";
 import { createIntegrationsModule } from "./modules/integrations.js";
 import { createAuthModule } from "./modules/auth.js";
 import { createSsoModule } from "./modules/sso.js";
+import { createBrowserModule } from "./modules/browser.js";
 import { createConnectorsModule, createUserConnectorsModule, } from "./modules/connectors.js";
 import { getAccessToken } from "./utils/auth-utils.js";
 import { createFetchWithAuth } from "./utils/fetch-with-auth.js";
@@ -228,6 +229,7 @@ export function createClient(config) {
         }),
         integrations: createIntegrationsModule(serviceRoleAxiosClient, appId),
         sso: createSsoModule(serviceRoleAxiosClient, appId),
+        browser: createBrowserModule(serviceRoleAxiosClient),
         connectors: createConnectorsModule(serviceRoleAxiosClient, appId),
         functions: createFunctionsModule(serviceRoleFunctionsAxiosClient, appId, {
             getAuthHeaders: () => {

package/dist/client.types.d.ts

@@ -2,6 +2,7 @@ import type { EntitiesModule } from "./modules/entities.types.js";
 import type { IntegrationsModule } from "./modules/integrations.types.js";
 import type { AuthModule } from "./modules/auth.types.js";
 import type { SsoModule } from "./modules/sso.types.js";
+import type { BrowserModule } from "./modules/browser.types.js";
 import type { PaymentsModule, ServiceRolePaymentsModule } from "./modules/payments.types.js";
 import type { ConnectorsModule, UserConnectorsModule } from "./modules/connectors.types.js";
 import type { FunctionsModule } from "./modules/functions.types.js";
@@ -228,6 +229,8 @@ export interface Base44Client {
         aiGateway: AiGatewayModule;
         /** {@link AppLogsModule | App logs module} with elevated permissions. */
         appLogs: AppLogsModule;
+        /** {@link BrowserModule | Browser module} for remote browser sessions. */
+        browser: BrowserModule;
         /** {@link ConnectorsModule | Connectors module} for OAuth token retrieval. */
         connectors: ConnectorsModule;
         /** {@link EntitiesModule | Entities module} with elevated permissions. */

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export type { AppModule, AppPublicSettings, AppPublicSettingsResponse, } from ".
 export type { ActorsModule, ActorClient, ActorRef, Connection, ActorSubscription, ActorConnectOptions, ActorNameRegistry, ActorRegistry, } from "./modules/actors.types.js";
 export type { SsoModule, SsoAccessTokenResponse } from "./modules/sso.types.js";
 export type { PaymentsModule, ServiceRolePaymentsModule, PaymentsErrorCode, PaymentsRecurringFrequency, CheckoutBuyer, CheckoutFreeTrial, CheckoutItem, CheckoutItemRecurring, CheckoutPresentation, CheckoutElement, CheckoutMount, MountableCheckout, CreateCheckoutParams, CreateCheckoutResult, CompleteCheckoutResult, EmbeddedCheckout, PayPalEmbeddedCheckout, StripeEmbeddedCheckout, MountCheckoutOptions, ListPurchasesParams, ServiceRoleListPurchasesParams, ListPurchasesResult, Purchase, PurchaseItem, PurchaseStatus, RefundParams, RefundResult, CancelSubscriptionOptions, SubscriptionResult, } from "./modules/payments.types.js";
+export type { BrowserModule, BrowserSession, BrowserSessionOptions, } from "./modules/browser.types.js";
 export { Actor, type Conn } from "./actor.js";
 export type { ConnectorsModule, UserConnectorsModule, ConnectorApiRequest, ConnectorApiResponse, ConnectorApiResponsePhase, } from "./modules/connectors.types.js";
 export type { CustomIntegrationsModule, CustomIntegrationCallParams, CustomIntegrationCallResponse, } from "./modules/custom-integrations.types.js";

package/dist/modules/browser.d.ts

@@ -0,0 +1,10 @@
+import { AxiosInstance } from "axios";
+import { BrowserModule } from "./browser.types.js";
+/**
+ * Creates the Browser module for the Base44 SDK.
+ *
+ * @param axios - Axios instance (should be service role client)
+ * @returns Browser module with methods to create and end remote browser sessions
+ * @internal
+ */
+export declare function createBrowserModule(axios: AxiosInstance): BrowserModule;

package/dist/modules/browser.js

@@ -0,0 +1,42 @@
+/**
+ * Creates the Browser module for the Base44 SDK.
+ *
+ * @param axios - Axios instance (should be service role client)
+ * @returns Browser module with methods to create and end remote browser sessions
+ * @internal
+ */
+export function createBrowserModule(axios) {
+    const endSession = async (sessionId) => {
+        if (!sessionId || typeof sessionId !== "string") {
+            throw new Error("Session ID is required and must be a string");
+        }
+        await axios.delete(`/v1/browser-sessions/${encodeURIComponent(sessionId)}`);
+    };
+    return {
+        async getSession(options = {}) {
+            var _a;
+            // The app is derived from the service token, so the route isn't app-scoped.
+            const response = await axios.post("/v1/browser-sessions", {
+                capture_debug_artifacts: (_a = options.captureDebugArtifacts) !== null && _a !== void 0 ? _a : true,
+                // Omit when unset so the backend applies its configured default.
+                ...(options.sessionTimeoutSeconds !== undefined && {
+                    session_timeout_seconds: options.sessionTimeoutSeconds,
+                }),
+            });
+            const data = response;
+            return {
+                sessionId: data.session_id,
+                connectionUrl: data.connection_url,
+                connectionScope: data.connection_scope,
+                ...(data.connection_expires_at && {
+                    connectionExpiresAt: data.connection_expires_at,
+                }),
+                ...(data.session_expires_at && {
+                    sessionExpiresAt: data.session_expires_at,
+                }),
+                end: () => endSession(data.session_id),
+            };
+        },
+        endSession,
+    };
+}

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

@@ -0,0 +1,130 @@
+/**
+ * Options for {@linkcode BrowserModule.getSession | getSession()}.
+ */
+export interface BrowserSessionOptions {
+    /**
+     * Whether to capture browser recordings and diagnostic logs for the session.
+     *
+     * Captured artifacts stay with the remote browser provider and can't be retrieved through the SDK. Defaults to `true`.
+     */
+    captureDebugArtifacts?: boolean;
+    /**
+     * Maximum lifetime of the session, in whole seconds.
+     *
+     * The session ends when the timeout expires, even if it's still in use. Base44 sets minimum and maximum allowed values and clamps the timeout to that range. When omitted, Base44 applies a default timeout.
+     */
+    sessionTimeoutSeconds?: number;
+}
+/**
+ * A remote browser session returned by {@linkcode BrowserModule.getSession | getSession()}.
+ */
+export interface BrowserSession {
+    /**
+     * Opaque session identifier issued to your app.
+     *
+     * Pass it unchanged to {@linkcode BrowserModule.endSession | endSession()} to end the session from a different request.
+     */
+    sessionId: string;
+    /**
+     * Signed WebSocket URL for connecting to the browser over the Chrome DevTools Protocol (CDP).
+     *
+     * Treat the complete URL as a credential. Don't log it or send it to the frontend.
+     */
+    connectionUrl: string;
+    /**
+     * Scope of the CDP connection.
+     *
+     * - `'browser'`: The socket controls the whole browser.
+     * - `'page'`: The socket controls a single page.
+     */
+    connectionScope: "browser" | "page";
+    /** ISO 8601 timestamp when the connection URL expires. Omitted when the provider doesn't expose it. */
+    connectionExpiresAt?: string;
+    /** ISO 8601 timestamp when the browser session expires. Omitted when the provider doesn't expose it. */
+    sessionExpiresAt?: string;
+    /**
+     * Ends the session. Equivalent to calling {@linkcode BrowserModule.endSession | endSession()} with this session's ID.
+     */
+    end: () => Promise<void>;
+}
+/**
+ * Browser module for running browser automation from your backend.
+ *
+ * This module creates remote browser sessions that you can control with a CDP client library such as Playwright or Puppeteer. Base44 doesn't store browser state, so each session is independent. End each session when you're done with it. Otherwise it keeps running until its timeout expires. To change the timeout, pass the `sessionTimeoutSeconds` option to {@linkcode BrowserModule.getSession | getSession()}.
+ *
+ * This module is only available to use with a client in service role authentication mode, which means it can only be used in backend environments.
+ */
+export interface BrowserModule {
+    /**
+     * Creates a new remote browser session and returns its connection details.
+     *
+     * Each call creates a fresh session. Calls aren't retried automatically, and repeating a failed call doesn't resume a previous session. Session creation is rate limited per app.
+     *
+     * @param options - Optional session settings.
+     * @returns Promise resolving to the new browser session.
+     *
+     * @example
+     * ```typescript
+     * // Open a page in a remote browser with Playwright
+     * import { createClientFromRequest } from 'npm:@base44/sdk';
+     * import { chromium } from 'npm:playwright-core';
+     *
+     * Deno.serve(async (req) => {
+     *   const base44 = createClientFromRequest(req);
+     *   const session = await base44.asServiceRole.browser.getSession();
+     *
+     *   try {
+     *     const browser = await chromium.connectOverCDP(session.connectionUrl);
+     *     const page = browser.contexts()[0]?.pages()[0] ?? (await browser.newPage());
+     *     await page.goto('https://example.com');
+     *     const title = await page.title();
+     *     await browser.close();
+     *
+     *     return Response.json({ title });
+     *   } finally {
+     *     await session.end();
+     *   }
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Turn off recordings and diagnostic logs
+     * const session = await base44.asServiceRole.browser.getSession({
+     *   captureDebugArtifacts: false,
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Request a custom session timeout
+     * const session = await base44.asServiceRole.browser.getSession({
+     *   sessionTimeoutSeconds: 600,
+     * });
+     * ```
+     */
+    getSession(options?: BrowserSessionOptions): Promise<BrowserSession>;
+    /**
+     * Ends a browser session created by your app.
+     *
+     * Use this when the session was created in a different request. Otherwise call `end()` on the session returned by {@linkcode getSession | getSession()}. Ending a session that has already ended succeeds, so it's safe to call more than once. The call fails with the `browser_session_not_found` error code if the ID wasn't issued to your app.
+     *
+     * @param sessionId - The `sessionId` returned by {@linkcode getSession | getSession()}, unchanged.
+     * @returns Promise that resolves when the session has ended.
+     *
+     * @example
+     * ```typescript
+     * // End a session whose ID was saved by an earlier request
+     * import { createClientFromRequest } from 'npm:@base44/sdk';
+     *
+     * Deno.serve(async (req) => {
+     *   const base44 = createClientFromRequest(req);
+     *   const { sessionId } = await req.json();
+     *   await base44.asServiceRole.browser.endSession(sessionId);
+     *
+     *   return new Response(null, { status: 204 });
+     * });
+     * ```
+     */
+    endSession(sessionId: string): Promise<void>;
+}

package/dist/modules/browser.types.js

@@ -0,0 +1 @@
+export {};

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

@@ -81,7 +81,7 @@ export interface ConnectorApiRequest {
 export interface ConnectorApiResponse<T = unknown> {
     /** `true` only when the upstream API returned a 2xx status. Proxy and upstream errors are `false`. */
     success: boolean;
-    /** How far the call progressed. Only `not_sent` proves the provider did not execute it. */
+    /** How far the call progressed. */
     phase: ConnectorApiResponsePhase;
     /** The upstream HTTP status code, or `null` when no response was received. */
     status: number | null;

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

@@ -702,6 +702,10 @@ export interface EntityHandler<T = any> {
      *
      * Permanently removes all records that match the provided query.
      *
+     * This isn't a transaction. Each record is deleted on its own, so if the call
+     * fails partway, the records already deleted stay deleted. Learn more about
+     * [concurrent updates](/developers/backend/resources/entities/entity-schemas#concurrent-updates).
+     *
      * @param query - Query matching {@linkcode EntityFilterQuery}. Every matching record is deleted.
      * @returns Promise resolving to the deletion result.
      *
@@ -722,6 +726,10 @@ export interface EntityHandler<T = any> {
      * Efficiently creates multiple records at once. This is faster
      * than creating them individually.
      *
+     * This isn't a transaction. Each record is written on its own, so if the call
+     * fails partway, the records already written stay written. Learn more about
+     * [concurrent updates](/developers/backend/resources/entities/entity-schemas#concurrent-updates).
+     *
      * @param data - Array of record data objects.
      * @returns Promise resolving to an array of created records.
      *
@@ -749,6 +757,15 @@ export interface EntityHandler<T = any> {
      * so you don't re-process the same entities on each iteration. For
      * example, filter by `status: 'pending'` when setting status to `'processed'`.
      *
+     * Each matching record is updated on its own, and the call isn't a transaction.
+     * To claim one record safely, so that only one of 2 users acting at the same
+     * time succeeds, pass that record's `id` as a plain value plus the conditions
+     * that must still be true, then check `updated` in the response. The conditions
+     * are only checked again at write time when the query names a single `id`. Any
+     * other query, including several IDs in `$in` or `$or`, finds the matching
+     * records first and then updates them. Learn more about
+     * [concurrent updates](/developers/backend/resources/entities/entity-schemas#concurrent-updates).
+     *
      * To update a single record by ID, use {@linkcode update | update()} instead. To update
      * multiple specific records with different data each, use {@linkcode bulkUpdate | bulkUpdate()}.
      *
@@ -808,6 +825,21 @@ export interface EntityHandler<T = any> {
      *   hasMore = result.has_more;
      * }
      * ```
+     *
+     * @example
+     * ```typescript
+     * // Claim a record
+     * // Only one user can claim the task, even if several try at the same time
+     * const result = await base44.entities.Task.updateMany(
+     *   { id: taskId, status: 'open' },
+     *   { $set: { status: 'claimed', claimed_by: user.email } }
+     * );
+     * if (result.updated === 1) {
+     *   // This user claimed the task
+     * } else {
+     *   // Someone else claimed it first, or it was no longer open
+     * }
+     * ```
      */
     updateMany(query: Partial<T>, data: Record<string, Record<string, any>>): Promise<UpdateManyResult>;
     /**
@@ -919,6 +951,11 @@ export interface EntityHandler<T = any> {
      * key, the last one wins. Updates merge the given fields into the existing record, like
      * {@linkcode update | update()}.
      *
+     * This isn't a transaction. Each record is written on its own, so if the call
+     * fails partway, the records already written stay written. Concurrent calls with
+     * the same key can also create duplicate records. Learn more about
+     * [concurrent updates](/developers/backend/resources/entities/entity-schemas#concurrent-updates).
+     *
      * @param records - Array of record data objects. Each must carry a value, not an object or
      * array, for every field named in `options.key`, to find or create by. Other fields are
      * optional, and only the ones you include are merged into a matched record, like `update()`.
@@ -955,6 +992,10 @@ export interface EntityHandler<T = any> {
      *
      * You can update up to 500 records per request.
      *
+     * This isn't a transaction. Each record is written on its own, so if the call
+     * fails partway, the records already written stay written. Learn more about
+     * [concurrent updates](/developers/backend/resources/entities/entity-schemas#concurrent-updates).
+     *
      * To apply the same update to all records matching a query, use
      * {@linkcode updateMany | updateMany()}. To update a single record by ID, use
      * {@linkcode update | update()}.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.55-pr.345.357a9ca",
+  "version": "0.8.56-pr.346.ce5b5be",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",