@base44-preview/sdk 0.8.55-pr.346.138d91a → 0.8.56-pr.347.bba12e2

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

@@ -14,7 +14,8 @@ export type { AppLogsModule } from "./modules/app-logs.types.js";
 export type { AppModule, AppPublicSettings, AppPublicSettingsResponse, } from "./modules/app.types.js";
 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 { PaymentsModule, ServiceRolePaymentsModule, PaymentsErrorCode, PaymentsRecurringFrequency, CheckoutBuyer, CheckoutFreeTrial, CheckoutItem, CheckoutItemRecurring, CheckoutPresentation, CheckoutShipping, CheckoutElement, CheckoutMount, MountableCheckout, CreateCheckoutParams, CreateCheckoutResult, CompleteCheckoutResult, EmbeddedCheckout, PayPalEmbeddedCheckout, StripeEmbeddedCheckout, MountCheckoutOptions, ListPurchasesParams, ServiceRoleListPurchasesParams, ListPurchasesResult, Purchase, PurchaseItem, PurchaseStatus, RefundParams, ShippingAddress, 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/payments.types.d.ts

@@ -58,6 +58,36 @@ export interface CheckoutBuyer {
     /** Buyer's phone number. */
     phone?: string;
 }
+/**
+ * A shipping address. Returned on a purchase whether your app or the provider collected it.
+ */
+export interface ShippingAddress {
+    /** Recipient's full name, 1 to 300 characters. */
+    name: string;
+    /** Street address, 1 to 300 characters. */
+    line1: string;
+    /** Apartment, suite or building, up to 300 characters. */
+    line2?: string | null;
+    /** City, up to 120 characters. Some countries address by region and postal code alone. */
+    city?: string | null;
+    /** State, province or region, up to 300 characters. */
+    region?: string | null;
+    /** Postal or ZIP code, up to 60 characters. */
+    postal_code?: string | null;
+    /** Two-letter ISO 3166-1 country code, such as `'US'`. */
+    country: string;
+}
+/**
+ * Shipping for a checkout with at least one `shippable` item. Supported for PayPal one-time checkouts only.
+ *
+ * Compute the fee on your server, never in the browser. When the fee depends on the address, such as by distance or zone, collect the address in your app and pass it in `address`: PayPal shows it to the buyer locked, so the order ships where the fee was computed for. When the fee doesn't depend on the address, pass only `amount` and PayPal asks the buyer for the address.
+ */
+export interface CheckoutShipping {
+    /** Address your app collected. Omit it to let the provider ask the buyer. */
+    address?: ShippingAddress;
+    /** Shipping fee in minor units, shown to the buyer as its own shipping line. Omit it for free shipping. */
+    amount?: number;
+}
 /**
  * How the buyer pays.
  *
@@ -85,6 +115,8 @@ export interface CreateCheckoutParams {
     idempotency_key?: string;
     /** How the buyer pays. Defaults to `'redirect'`. PayPal apps must pass `'embedded'`, and Wix Payments supports only `'redirect'`. */
     presentation?: CheckoutPresentation;
+    /** Shipping address and fee. Allowed only when at least one item is `shippable`. Supported for PayPal one-time checkouts only; other providers and subscriptions reject it with `invalid_request`. */
+    shipping?: CheckoutShipping;
 }
 /**
  * Data that Stripe Embedded Checkout needs to render.
@@ -184,6 +216,10 @@ export interface Purchase {
     metadata?: Record<string, string> | null;
     /** ID of the subscription, for recurring purchases. */
     subscription_id?: string | null;
+    /** Where the order ships, whether your app or the provider collected the address. Always `null` unless you call with the service role. Save it on your order record. */
+    shipping_address?: ShippingAddress | null;
+    /** Shipping fee in minor units, when the checkout charged one. */
+    shipping_amount?: number | null;
     /** ID of the payment to pass to [`refund()`](/developers/references/sdk/docs/interfaces/service-role-payments#refund). For a PayPal subscription it's the latest charge, returned only with the service role: read it when you start a refund and reuse it on retries. It's `null` where the provider doesn't name a payment, such as a PayPal subscription whose latest charge is already refunded. */
     payment_id?: string | null;
 }

package/package.json

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