@base44-preview/sdk 0.8.53-pr.331.bf2d5aa → 0.8.54-pr.316.81dc6f9

package/README.md

@@ -29,6 +29,7 @@ The SDK provides access to Base44's functionality through the following modules:
 - **[`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)**: Access pre-built and third-party integrations.
+- **[`payments`](https://docs.base44.com/developers/references/sdk/docs/interfaces/payments)**: Embed checkouts, look up purchases, and handle refunds and subscriptions with the service role.
 
 ## Quickstarts
 

package/dist/client.js

@@ -14,6 +14,7 @@ import { createAppModule } from "./modules/app.js";
 import { createUsersModule } from "./modules/users.js";
 import { RoomsSocket } from "./utils/socket-utils.js";
 import { createAnalyticsModule } from "./modules/analytics.js";
+import { createPaymentsModule, createServiceRolePaymentsModule, } from "./modules/payments.js";
 import { createActorsModule, resolveActorsHost, } from "./modules/actors.js";
 /**
  * Creates a Base44 client.
@@ -202,6 +203,7 @@ export function createClient(config) {
         appLogs: createAppLogsModule(axiosClient, appId),
         app: createAppModule(axiosClient, appId),
         users: createUsersModule(axiosClient, appId),
+        payments: createPaymentsModule(axiosClient, appId),
         analytics: createAnalyticsModule({
             axiosClient,
             serverUrl,
@@ -252,6 +254,7 @@ export function createClient(config) {
             headers: aiGatewayHeaders,
         }),
         appLogs: createAppLogsModule(serviceRoleAxiosClient, appId),
+        payments: createServiceRolePaymentsModule(serviceRoleAxiosClient, appId),
         cleanup: () => {
             if (socket) {
                 socket.disconnect();

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 { PaymentsModule, ServiceRolePaymentsModule } from "./modules/payments.types.js";
 import type { ConnectorsModule, UserConnectorsModule } from "./modules/connectors.types.js";
 import type { FunctionsModule } from "./modules/functions.types.js";
 import type { AgentsModule } from "./modules/agents.types.js";
@@ -138,6 +139,8 @@ export interface Base44Client {
     functions: FunctionsModule;
     /** {@link IntegrationsModule | Integrations module} for calling pre-built integration endpoints. */
     integrations: IntegrationsModule;
+    /** {@link PaymentsModule | Payments module} for checkouts and purchases. */
+    payments: PaymentsModule;
     /** Cleanup function to disconnect WebSocket connections. Call when you're done with the client. */
     cleanup: () => void;
     /**
@@ -233,6 +236,8 @@ export interface Base44Client {
         functions: FunctionsModule;
         /** {@link IntegrationsModule | Integrations module} with elevated permissions. */
         integrations: IntegrationsModule;
+        /** {@link ServiceRolePaymentsModule | Payments module} for creating checkouts, refunds, and subscription changes. */
+        payments: ServiceRolePaymentsModule;
         /** {@link SsoModule | SSO module} for generating SSO tokens. */
         sso: SsoModule;
         /** Cleanup function to disconnect WebSocket connections. */

package/dist/index.d.ts

@@ -14,6 +14,7 @@ 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 { 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/app.types.d.ts

@@ -1,49 +1,66 @@
 /**
- * The app's access policy: whether the app is reachable without an account, and
- * who may sign in.
+ * The app's [visibility](/Setting-up-your-app/Managing-access#setting-your-app-visibility).
+ *
+ * You can set and manage the app's visibility in the app's dashboard or with the Base44 CLI [`visibility`](/developers/references/cli/commands/visibility) command.
+ *
+ * The following table shows the supported values and the visibility each one represents:
+ *
+ * | Value | Visibility |
+ * | --- | --- |
+ * | `private_with_login` | **Private**: Only [invited users](/Setting-up-your-app/Managing-access#inviting-users-to-your-app) |
+ * | `workspace_with_login` | **Workspace**: Users in your Base44 [workspace](/documentation/account-and-billing/about-workspaces) |
+ * | `public_with_login` | **Public (login required)**: Visitors must log in |
+ * | `public_without_login` | **Public (no login)**: Anyone |
+ *
+ * <Note>
+ * If your workspace [enforces SSO for apps](/Enterprise/Enterprise-SSO-and-app-visibility), apps set to `public_without_login` also require sign-in.
+ * </Note>
  */
 export type AppPublicSettings = "private_with_login" | "public_with_login" | "public_without_login" | "workspace_with_login" | string;
 /**
- * The app's public configuration, as returned by {@link AppModule.getPublicSettings}.
+ * The app's public settings.
  */
 export interface AppPublicSettingsResponse {
     /** The app's ID. */
     id: string;
-    /** The app's access policy. */
+    /**
+     * The app's visibility.
+     * For supported values, see [`AppPublicSettings`](#apppublicsettings).
+     */
     public_settings: AppPublicSettings;
 }
 /**
- * App module for reading the app's own public configuration.
+ * App module for reading an app's public settings.
+ *
+ * Use it to read the app's visibility and determine whether the current visitor can access the app.
+ * If the app requires login, use `redirectToLogin()` from the {@link AuthModule | auth module} to send the visitor to the login page.
  *
- * Use it to discover how the app is gated before rendering it, so a private app
- * can send the visitor to login instead of rendering an empty shell.
+ * Learn more about [app visibility](/Setting-up-your-app/Managing-access#setting-your-app-visibility).
  *
- * ## Authentication Modes
+ * ## Authentication modes
  *
- * This module is available to use with a client in all authentication modes. The
- * client's token, when it has one, is sent with the request — a signed-in visitor
- * who has no access to the app is reported differently from an anonymous one.
+ * You can use this module with a client in any authentication mode. The client sends its token, if it has one, with the request.
  */
 export interface AppModule {
     /**
-     * Get the app's public configuration.
+     * Retrieves the app's public settings.
      *
-     * Rejects with a {@linkcode Base44Error} when the visitor may not open the app:
-     * `status` is `403` and `data.extra_data.reason` says why — `"auth_required"`
-     * when the visitor must sign in, `"user_not_registered"` when the signed-in
-     * visitor has no access to this app.
+     * Rejects with a {@linkcode Base44Error} that has a `status` of `403` when the visitor can't access the app.
+     * Check `data.extra_data.reason` to find the cause:
+     * - `auth_required`: The visitor must sign in.
+     * - `user_not_registered`: The visitor is signed in but doesn't have access.
      *
-     * @returns Promise resolving to the app's ID and access policy.
+     * @returns Promise resolving to the app's ID and visibility.
      *
      * @example
      * ```typescript
-     * // Decide what to render before the app boots
+     * // Redirect a visitor who isn't signed in
      * try {
      *   const { public_settings } = await base44.app.getPublicSettings();
-     *   console.log('App access policy:', public_settings);
+     *   console.log('App visibility:', public_settings);
      * } catch (error) {
-     *   if (error.status === 403) {
-     *     console.log('Blocked because:', error.data?.extra_data?.reason);
+     *   if (error.status === 403 && error.data?.extra_data?.reason === 'auth_required') {
+     *     base44.auth.redirectToLogin('<URL to return to after login>');
      *   }
      * }
      * ```

package/dist/modules/payments-checkout.d.ts

@@ -0,0 +1,31 @@
+import type { CheckoutElement, CheckoutMount, CompleteCheckoutResult, MountableCheckout, MountCheckoutOptions } from "./payments.types.js";
+/** @internal */
+export type LoadScript = (src: string) => Promise<void>;
+/**
+ * The response of `GET /payments/config`.
+ * @internal
+ */
+export interface PaymentsCheckoutConfig {
+    paypal?: {
+        script_url?: string;
+    };
+    stripe?: {
+        script_url?: string;
+    };
+}
+/** @internal */
+export interface MountCheckoutDeps {
+    completeCheckout: (checkoutId: string) => Promise<CompleteCheckoutResult>;
+    getConfig: () => Promise<PaymentsCheckoutConfig>;
+    loadScript: LoadScript;
+}
+/**
+ * Appends a script tag once per URL and resolves when it loads.
+ * @internal
+ */
+export declare const loadScript: LoadScript;
+/**
+ * Mounts the embedded checkout that createCheckout() returned.
+ * @internal
+ */
+export declare function mountCheckout(element: CheckoutElement, checkout: MountableCheckout, options: MountCheckoutOptions, deps: MountCheckoutDeps): Promise<CheckoutMount>;

package/dist/modules/payments-checkout.js

@@ -0,0 +1,235 @@
+// The backend picks each script URL, but the script runs on the buyer's page, so only these hosts may load.
+const ALLOWED_SCRIPT_HOSTS = {
+    paypal: ["www.paypal.com", "www.sandbox.paypal.com"],
+    stripe: ["js.stripe.com"],
+};
+async function scriptUrlFor(provider, deps) {
+    var _a, _b;
+    const value = (_b = (_a = (await deps.getConfig())) === null || _a === void 0 ? void 0 : _a[provider]) === null || _b === void 0 ? void 0 : _b.script_url;
+    let url;
+    try {
+        url = value ? new URL(value) : undefined;
+    }
+    catch (_c) {
+        url = undefined;
+    }
+    if (!url ||
+        url.protocol !== "https:" ||
+        url.port !== "" ||
+        url.username !== "" ||
+        url.password !== "" ||
+        !ALLOWED_SCRIPT_HOSTS[provider].includes(url.hostname)) {
+        const name = provider === "paypal" ? "PayPal" : "Stripe";
+        throw new Error(`The payments config has no valid ${name} script URL`);
+    }
+    return url.href;
+}
+function browserGlobals() {
+    return window;
+}
+const scriptLoads = new Map();
+/**
+ * Appends a script tag once per URL and resolves when it loads.
+ * @internal
+ */
+export const loadScript = (src) => {
+    let load = scriptLoads.get(src);
+    if (!load) {
+        load = new Promise((resolve, reject) => {
+            const script = document.createElement("script");
+            script.src = src;
+            script.async = true;
+            script.onload = () => resolve();
+            script.onerror = () => {
+                // Forget the failure so a later mount can retry.
+                scriptLoads.delete(src);
+                script.remove();
+                reject(new Error(`Failed to load ${src}`));
+            };
+            document.head.appendChild(script);
+        });
+        scriptLoads.set(src, load);
+    }
+    return load;
+};
+async function loadGlobal(src, read, load) {
+    if (!read()) {
+        await load(src);
+    }
+    const value = read();
+    if (!value) {
+        throw new Error(`${src} loaded but didn't define its global`);
+    }
+    return value;
+}
+// Stripe asks for a single Stripe instance per key.
+const stripeInstances = new Map();
+// Stripe allows one Embedded Checkout at a time, so mounts run in order and replace the last.
+let stripeQueue = Promise.resolve();
+let activeStripeCheckout = null;
+function mountStripe(element, scriptUrl, embedded, deps) {
+    const mount = stripeQueue.then(async () => {
+        var _a;
+        const Stripe = await loadGlobal(scriptUrl, () => browserGlobals().Stripe, deps.loadScript);
+        let stripe = stripeInstances.get(embedded.publishable_key);
+        if (!stripe) {
+            stripe = Stripe(embedded.publishable_key);
+            stripeInstances.set(embedded.publishable_key, stripe);
+        }
+        // Try the pre-dahlia name first, since dahlia and later reject the ui_mode Base44 sessions use.
+        // A newer Stripe.js that the app loaded itself is still tried rather than refused.
+        const create = (_a = stripe.initEmbeddedCheckout) !== null && _a !== void 0 ? _a : stripe.createEmbeddedCheckoutPage;
+        if (typeof create !== "function") {
+            throw new Error("Stripe.js doesn't support Embedded Checkout");
+        }
+        activeStripeCheckout === null || activeStripeCheckout === void 0 ? void 0 : activeStripeCheckout.destroy();
+        const checkout = await create.call(stripe, {
+            fetchClientSecret: () => Promise.resolve(embedded.client_secret),
+        });
+        try {
+            checkout.mount(element);
+        }
+        catch (error) {
+            checkout.destroy();
+            throw error;
+        }
+        let destroyed = false;
+        const handle = {
+            destroy() {
+                if (destroyed)
+                    return;
+                destroyed = true;
+                if (activeStripeCheckout === handle)
+                    activeStripeCheckout = null;
+                checkout.destroy();
+            },
+        };
+        activeStripeCheckout = handle;
+        return handle;
+    });
+    stripeQueue = mount.catch(() => undefined);
+    return mount;
+}
+async function mountPayPal(element, scriptUrl, checkoutId, currency, embedded, options, deps) {
+    var _a;
+    const paypal = await loadGlobal(scriptUrl, () => browserGlobals().paypal, deps.loadScript);
+    if (typeof paypal.createInstance !== "function") {
+        throw new Error("Another PayPal JS SDK version is already loaded on this page. Remove it to use mountCheckout().");
+    }
+    const subscription = embedded.intent === "subscription";
+    const sdk = await paypal.createInstance({
+        clientId: embedded.client_id,
+        merchantId: embedded.merchant_id,
+        // Sent only when set, since the backend returns null when no attribution ID is configured.
+        ...(embedded.partner_attribution_id
+            ? { partnerAttributionId: embedded.partner_attribution_id }
+            : {}),
+        components: [subscription ? "paypal-subscriptions" : "paypal-payments"],
+        pageType: "checkout",
+    });
+    const methods = await sdk.findEligibleMethods({
+        currencyCode: currency.toUpperCase(),
+        ...(subscription ? { paymentFlow: "RECURRING_PAYMENT" } : {}),
+    });
+    if (!methods.isEligible("paypal")) {
+        throw new Error("PayPal isn't available for this checkout");
+    }
+    const createSession = subscription
+        ? (_a = sdk.createPayPalSubscriptionPaymentSession) !== null && _a !== void 0 ? _a : sdk.createPayPalSubscriptionSession
+        : sdk.createPayPalOneTimePaymentSession;
+    if (typeof createSession !== "function") {
+        throw new Error("The loaded PayPal JS SDK can't create this checkout");
+    }
+    let destroyed = false;
+    let completing = false;
+    // App callbacks run only while mounted, and their own errors never reach PayPal or onError.
+    const notify = (callback) => {
+        if (destroyed)
+            return;
+        try {
+            callback();
+        }
+        catch (error) {
+            console.error("[Base44 SDK] A mountCheckout() callback threw", error);
+        }
+    };
+    const button = document.createElement("paypal-button");
+    const session = createSession.call(sdk, {
+        // Errors are reported here, not rethrown, so PayPal doesn't report them a second time.
+        async onApprove() {
+            completing = true;
+            button.disabled = true;
+            let result;
+            try {
+                // Runs even after destroy(), so an approved payment is still captured.
+                result = await deps.completeCheckout(checkoutId);
+            }
+            catch (error) {
+                // Re-enabled only on failure, since a paid order can't be approved again.
+                completing = false;
+                button.disabled = false;
+                notify(() => { var _a; return (_a = options.onError) === null || _a === void 0 ? void 0 : _a.call(options, error); });
+                return;
+            }
+            completing = false;
+            notify(() => { var _a; return (_a = options.onComplete) === null || _a === void 0 ? void 0 : _a.call(options, result); });
+        },
+        onCancel() {
+            notify(() => { var _a; return (_a = options.onCancel) === null || _a === void 0 ? void 0 : _a.call(options); });
+        },
+        onError(error) {
+            notify(() => { var _a; return (_a = options.onError) === null || _a === void 0 ? void 0 : _a.call(options, error); });
+        },
+    });
+    button.setAttribute("type", subscription ? "subscribe" : "pay");
+    const onClick = () => {
+        if (completing)
+            return;
+        // Not awaited before start(), which must run inside the click to open PayPal's popup.
+        const id = Promise.resolve(subscription ? { subscriptionId: checkoutId } : { orderId: checkoutId });
+        const report = (error) => notify(() => { var _a; return (_a = options.onError) === null || _a === void 0 ? void 0 : _a.call(options, error); });
+        try {
+            Promise.resolve(session.start({ presentationMode: "auto" }, id)).catch(report);
+        }
+        catch (error) {
+            report(error);
+        }
+    };
+    button.addEventListener("click", onClick);
+    element.appendChild(button);
+    return {
+        destroy() {
+            var _a;
+            if (destroyed)
+                return;
+            destroyed = true;
+            button.removeEventListener("click", onClick);
+            button.remove();
+            (_a = session.destroy) === null || _a === void 0 ? void 0 : _a.call(session);
+        },
+    };
+}
+/**
+ * Mounts the embedded checkout that createCheckout() returned.
+ * @internal
+ */
+export async function mountCheckout(element, checkout, options, deps) {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+        throw new Error("mountCheckout() requires a browser environment");
+    }
+    if (!element) {
+        throw new Error("mountCheckout() requires an element to render in");
+    }
+    const embedded = checkout === null || checkout === void 0 ? void 0 : checkout.embedded;
+    if (!embedded) {
+        throw new Error("This checkout isn't embedded. Create it with presentation: 'embedded', or send the buyer to its redirect_url.");
+    }
+    switch (embedded.provider) {
+        case "stripe":
+            return mountStripe(element, await scriptUrlFor("stripe", deps), embedded, deps);
+        case "paypal":
+            return mountPayPal(element, await scriptUrlFor("paypal", deps), checkout.checkout_id, checkout.currency, embedded, options, deps);
+        default:
+            throw new Error(`Embedded checkout isn't supported for provider ${embedded.provider}`);
+    }
+}

package/dist/modules/payments.d.ts

@@ -0,0 +1,20 @@
+import { AxiosInstance } from "axios";
+import { PaymentsModule, ServiceRolePaymentsModule } from "./payments.types.js";
+/**
+ * Creates the payments module for anonymous and user authentication.
+ *
+ * @param axios - Axios instance
+ * @param appId - Application ID
+ * @returns Payments module for the browser
+ * @internal
+ */
+export declare function createPaymentsModule(axios: AxiosInstance, appId: string): PaymentsModule;
+/**
+ * Creates the payments module for service role authentication.
+ *
+ * @param axios - Axios instance (should be service role client)
+ * @param appId - Application ID
+ * @returns Payments module for backend functions
+ * @internal
+ */
+export declare function createServiceRolePaymentsModule(axios: AxiosInstance, appId: string): ServiceRolePaymentsModule;

package/dist/modules/payments.js

@@ -0,0 +1,79 @@
+import { loadScript, mountCheckout, } from "./payments-checkout.js";
+function requireId(value, name) {
+    if (!value || typeof value !== "string") {
+        throw new Error(`${name} is required and must be a string`);
+    }
+    return encodeURIComponent(value);
+}
+function createPaymentsRequests(axios, appId) {
+    const base = `/apps/${appId}/payments`;
+    return {
+        async completeCheckout(checkoutId) {
+            const id = requireId(checkoutId, "Checkout ID");
+            return axios.post(`${base}/checkout-sessions/${id}/complete`);
+        },
+        async listPurchases(params = {}) {
+            return axios.get(`${base}/purchases`, { params });
+        },
+        async createCheckout(params) {
+            return axios.post(`${base}/checkout-sessions`, params);
+        },
+        async refund(params) {
+            return axios.post(`${base}/refunds`, params);
+        },
+        async cancelSubscription(subscriptionId, options = {}) {
+            const id = requireId(subscriptionId, "Subscription ID");
+            return axios.post(`${base}/subscriptions/${id}/cancel`, options);
+        },
+        async pauseSubscription(subscriptionId) {
+            const id = requireId(subscriptionId, "Subscription ID");
+            return axios.post(`${base}/subscriptions/${id}/pause`);
+        },
+        async resumeSubscription(subscriptionId) {
+            const id = requireId(subscriptionId, "Subscription ID");
+            return axios.post(`${base}/subscriptions/${id}/resume`);
+        },
+    };
+}
+/**
+ * Creates the payments module for anonymous and user authentication.
+ *
+ * @param axios - Axios instance
+ * @param appId - Application ID
+ * @returns Payments module for the browser
+ * @internal
+ */
+export function createPaymentsModule(axios, appId) {
+    const requests = createPaymentsRequests(axios, appId);
+    // One fetch per client, retried on the next mount if it fails.
+    let config;
+    const getConfig = () => {
+        config !== null && config !== void 0 ? config : (config = axios.get(`/apps/${appId}/payments/config`).catch((error) => {
+            config = undefined;
+            throw error;
+        }));
+        return config;
+    };
+    return {
+        completeCheckout: requests.completeCheckout,
+        listPurchases: requests.listPurchases,
+        mountCheckout(element, checkout, options = {}) {
+            return mountCheckout(element, checkout, options, {
+                completeCheckout: requests.completeCheckout,
+                getConfig,
+                loadScript,
+            });
+        },
+    };
+}
+/**
+ * Creates the payments module for service role authentication.
+ *
+ * @param axios - Axios instance (should be service role client)
+ * @param appId - Application ID
+ * @returns Payments module for backend functions
+ * @internal
+ */
+export function createServiceRolePaymentsModule(axios, appId) {
+    return createPaymentsRequests(axios, appId);
+}

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

@@ -0,0 +1,626 @@
+/**
+ * How often a recurring item bills.
+ */
+export type PaymentsRecurringFrequency = "day" | "week" | "month" | "year";
+/**
+ * Free trial before the first charge of a recurring item.
+ */
+export interface CheckoutFreeTrial {
+    /** Unit of the trial length. Stripe supports only `'day'` and `'week'`. */
+    frequency: PaymentsRecurringFrequency;
+    /** Number of `frequency` units the trial lasts, from 1 to 999. */
+    interval: number;
+}
+/**
+ * Billing terms that turn a checkout item into a subscription.
+ */
+export interface CheckoutItemRecurring {
+    /** Unit of the billing period. */
+    frequency: PaymentsRecurringFrequency;
+    /** Number of `frequency` units between charges, from 1 to 3650. Defaults to `1`. */
+    interval?: number;
+    /** Whether the subscription renews automatically at the end of its billing cycles. Stripe doesn't support `false`. */
+    auto_renewal?: boolean;
+    /** Number of billing cycles before the subscription ends, at least 1. Omit for no limit. Not supported for Stripe. */
+    billing_cycles?: number;
+    /** Free trial before the first charge. Stripe applies one trial to the whole checkout, so every recurring item must request the same trial. */
+    free_trial?: CheckoutFreeTrial;
+    /** Subscription title shown to the buyer, up to 150 characters. */
+    title?: string;
+    /** Subscription description shown to the buyer, up to 500 characters. */
+    description?: string;
+}
+/**
+ * A line item in a checkout.
+ */
+export interface CheckoutItem {
+    /** Item name shown to the buyer, 1 to 255 characters. */
+    name: string;
+    /** Unit price in the currency's minor units, such as cents. Must be greater than `0`. Providers may also reject a total below their minimum charge. */
+    amount: number;
+    /** Number of units, from 1 to 1,000,000. Defaults to `1`. */
+    quantity?: number;
+    /** Whether the item ships, so the provider collects a shipping address. */
+    shippable?: boolean;
+    /** Billing terms. Set this to sell the item as a subscription. PayPal and Wix Payments allow one recurring item per checkout, and PayPal allows no other items with it. */
+    recurring?: CheckoutItemRecurring;
+}
+/**
+ * Details about the buyer, used to prefill the checkout. Every field is optional.
+ */
+export interface CheckoutBuyer {
+    /** Buyer's email address. */
+    email?: string;
+    /** Buyer's first name. */
+    first_name?: string;
+    /** Buyer's last name. */
+    last_name?: string;
+    /** Buyer's phone number. */
+    phone?: string;
+}
+/**
+ * How the buyer pays.
+ *
+ * - `'redirect'`: The buyer leaves the app for the provider's hosted checkout page at `redirect_url`.
+ * - `'embedded'`: The checkout renders inside the app with [`mountCheckout()`](/developers/references/sdk/docs/interfaces/payments#mountcheckout).
+ */
+export type CheckoutPresentation = "redirect" | "embedded";
+/**
+ * Parameters for [`createCheckout()`](/developers/references/sdk/docs/interfaces/service-role-payments#createcheckout).
+ */
+export interface CreateCheckoutParams {
+    /** Items to sell, 1 to 100 entries. */
+    items: CheckoutItem[];
+    /** Three-letter ISO currency code, such as `'usd'`. Defaults to the payment account's currency. Required for PayPal. */
+    currency?: string;
+    /** App-relative path the buyer returns to after paying, such as `'/thank-you'`. Must start with `/`. */
+    success_path: string;
+    /** App-relative path the buyer returns to after cancelling. Must start with `/`. Not supported for Stripe embedded checkout. */
+    cancel_path?: string;
+    /** Details about the buyer, used to prefill the checkout. */
+    buyer?: CheckoutBuyer;
+    /** Your own key-value pairs, up to 50 keys. Returned in each purchase's `metadata` to service role callers only. Not supported for PayPal. */
+    metadata?: Record<string, string>;
+    /** Key that makes retries return the same checkout instead of creating another, 1 to 200 characters. Not supported for Wix Payments or PayPal subscriptions. */
+    idempotency_key?: string;
+    /** How the buyer pays. Defaults to `'redirect'`. PayPal apps must pass `'embedded'`, and Wix Payments supports only `'redirect'`. */
+    presentation?: CheckoutPresentation;
+}
+/**
+ * Data that Stripe Embedded Checkout needs to render.
+ */
+export interface StripeEmbeddedCheckout {
+    /** Payment provider. */
+    provider: "stripe";
+    /** Stripe publishable key of the app's payment account. */
+    publishable_key: string;
+    /** Client secret of the Stripe Checkout Session. */
+    client_secret: string;
+}
+/**
+ * Data that the PayPal button needs to render.
+ */
+export interface PayPalEmbeddedCheckout {
+    /** Payment provider. */
+    provider: "paypal";
+    /** PayPal client ID. */
+    client_id: string;
+    /** PayPal merchant ID of the app's seller account. */
+    merchant_id: string;
+    /** PayPal partner attribution ID, when set. */
+    partner_attribution_id?: string | null;
+    /** Whether the checkout is a one-time payment or a subscription. */
+    intent: "capture" | "subscription";
+}
+/**
+ * Data that an embedded checkout needs to render, by provider.
+ */
+export type EmbeddedCheckout = StripeEmbeddedCheckout | PayPalEmbeddedCheckout;
+/**
+ * Result of [`createCheckout()`](/developers/references/sdk/docs/interfaces/service-role-payments#createcheckout).
+ *
+ * Exactly one of `redirect_url` and `embedded` is set, depending on the checkout's `presentation`.
+ */
+export interface CreateCheckoutResult {
+    /** ID of the checkout. For Stripe it's the Checkout Session ID, and for PayPal it's the PayPal order or subscription ID. */
+    checkout_id: string;
+    /** Three-letter ISO currency code of the checkout, in lowercase. */
+    currency: string;
+    /** Amount the buyer pays now, in minor units. It's `0` for a subscription that starts with a free trial. */
+    amount_total: number;
+    /** Absolute URL of the provider's hosted checkout page, for redirect checkouts. */
+    redirect_url: string | null;
+    /** Data for [`mountCheckout()`](/developers/references/sdk/docs/interfaces/payments#mountcheckout), for embedded checkouts. */
+    embedded: EmbeddedCheckout | null;
+}
+/**
+ * Result of [`completeCheckout()`](/developers/references/sdk/docs/interfaces/payments#completecheckout).
+ */
+export interface CompleteCheckoutResult {
+    /** ID of the checkout. */
+    checkout_id: string;
+    /** Whether the payment went through or the provider is still processing it. */
+    status: "paid" | "pending";
+}
+/**
+ * Status of a purchase.
+ *
+ * - `'pending'`: The buyer hasn't finished paying, or the provider is still processing the payment.
+ * - `'paid'`: The payment went through.
+ * - `'refunded'`: The payment was refunded.
+ * - `'canceled'`: The checkout or subscription was canceled.
+ * - `'failed'`: The payment failed.
+ * - `'unknown'`: The provider reported a state that doesn't map to the others.
+ */
+export type PurchaseStatus = "pending" | "paid" | "refunded" | "canceled" | "failed" | "unknown";
+/**
+ * A line item of a purchase.
+ */
+export interface PurchaseItem {
+    /** Item name. */
+    name: string;
+    /** Unit price in minor units, when the provider reports it. */
+    amount?: number | null;
+    /** Number of units, when the provider reports it. */
+    quantity?: number | null;
+}
+/**
+ * A completed or in-progress checkout.
+ */
+export interface Purchase {
+    /** ID of the checkout the purchase came from. */
+    checkout_id: string;
+    /** Status of the purchase. */
+    status: PurchaseStatus;
+    /** Line items of the purchase. */
+    items: PurchaseItem[];
+    /** Total amount in minor units. */
+    amount_total?: number | null;
+    /** Three-letter ISO currency code, in lowercase. */
+    currency?: string | null;
+    /** Buyer's email address. */
+    buyer_email?: string | null;
+    /** The metadata passed to [`createCheckout()`](/developers/references/sdk/docs/interfaces/service-role-payments#createcheckout). Always `null` unless you call with the service role. */
+    metadata?: Record<string, string> | null;
+    /** ID of the subscription, for recurring purchases. */
+    subscription_id?: string | null;
+    /** ID of the payment to pass to [`refund()`](/developers/references/sdk/docs/interfaces/service-role-payments#refund). It's `null` where the provider doesn't name a single payment, such as PayPal subscriptions. */
+    payment_id?: string | null;
+}
+/**
+ * Parameters for [`listPurchases()`](/developers/references/sdk/docs/interfaces/payments#listpurchases).
+ */
+export interface ListPurchasesParams {
+    /** Only return the purchase from this checkout. */
+    checkout_id?: string;
+    /** Only return purchases of this subscription. */
+    subscription_id?: string;
+    /** Maximum number of purchases to return, from 1 to 100. Defaults to `20`. */
+    limit?: number;
+    /** The `next_cursor` from the previous page. Send the same filters and `limit` as that call. */
+    cursor?: string;
+}
+/**
+ * Parameters for [`listPurchases()`](/developers/references/sdk/docs/interfaces/service-role-payments#listpurchases) with the service role.
+ */
+export interface ServiceRoleListPurchasesParams extends ListPurchasesParams {
+    /** Only return purchases made with this email address. */
+    buyer_email?: string;
+}
+/**
+ * A page of purchases.
+ */
+export interface ListPurchasesResult {
+    /** Purchases on this page. */
+    items: Purchase[];
+    /** Cursor for the next page, or `null` on the last page. */
+    next_cursor: string | null;
+}
+/**
+ * Parameters for [`refund()`](/developers/references/sdk/docs/interfaces/service-role-payments#refund).
+ */
+export interface RefundParams {
+    /** The `payment_id` of the purchase to refund. */
+    payment_id: string;
+    /** Amount to refund in minor units. Must be greater than `0`. */
+    amount: number;
+    /** Key that makes retries return the original refund instead of refunding twice, 1 to 100 characters. */
+    idempotency_key: string;
+}
+/**
+ * Result of [`refund()`](/developers/references/sdk/docs/interfaces/service-role-payments#refund).
+ */
+export interface RefundResult {
+    /** Provider's ID of the refund. */
+    refund_id: string;
+    /** ID of the refunded payment. */
+    payment_id: string;
+    /** Refunded amount in minor units. */
+    amount: number;
+    /** Three-letter ISO currency code, in lowercase. */
+    currency: string;
+    /** Whether the refund went through or the provider is still processing it. */
+    status: "succeeded" | "pending";
+}
+/**
+ * Options for [`cancelSubscription()`](/developers/references/sdk/docs/interfaces/service-role-payments#cancelsubscription).
+ */
+export interface CancelSubscriptionOptions {
+    /** Cancel at the end of the current billing period instead of now. Defaults to `false`. Not supported for PayPal. */
+    at_period_end?: boolean;
+}
+/**
+ * State of a subscription after a change.
+ */
+export interface SubscriptionResult {
+    /** ID of the subscription. */
+    subscription_id: string;
+    /** Current status of the subscription. */
+    status: "active" | "past_due" | "paused" | "canceled";
+    /** Whether the subscription is set to cancel at the end of the current billing period. */
+    cancel_at_period_end: boolean;
+}
+/**
+ * Error codes that payments methods reject with, in the `code` of a `Base44Error`.
+ *
+ * Some notable ones:
+ *
+ * - `payment_declined`: The buyer's payment method was declined when completing the checkout. The buyer can try again with another method.
+ * - `refund_failed`: The refund's outcome is unknown. Retry with the same `idempotency_key` and `amount`, which returns the original refund if one was made.
+ * - `refund_in_progress`: A refund with the same `idempotency_key` is still running.
+ * - `refund_amount_mismatch`: The `idempotency_key` was already used for a different amount.
+ * - `rate_limited`: Too many requests. Wait for the number of seconds in the `Retry-After` response header, available at `error.originalError.response.headers['retry-after']`.
+ * - `refund_not_supported`, `subscription_action_not_supported`, `complete_not_supported`, `presentation_not_supported`: The app's payment provider doesn't support the operation.
+ */
+export type PaymentsErrorCode = "forbidden" | "unauthenticated" | "not_found" | "conflict" | "rate_limited" | "payments_not_connected" | "invalid_request" | "invalid_items" | "amount_below_minimum" | "currency_mismatch" | "currency_required" | "invalid_metadata" | "idempotency_not_supported" | "idempotency_key_reused" | "multiple_subscription_items" | "recurring_option_not_supported" | "invalid_cursor" | "presentation_not_supported" | "embedded_checkout_unavailable" | "checkout_not_found" | "checkout_not_approved" | "checkout_closed" | "payment_declined" | "complete_not_supported" | "provider_unavailable" | "payment_not_found" | "refund_rejected" | "refund_in_progress" | "refund_amount_mismatch" | "refund_temporarily_unavailable" | "refund_failed" | "refund_not_supported" | "subscription_not_found" | "subscription_not_active" | "subscription_action_not_supported";
+/**
+ * Callbacks for [`mountCheckout()`](/developers/references/sdk/docs/interfaces/payments#mountcheckout).
+ */
+export interface MountCheckoutOptions {
+    /**
+     * Called after the buyer approves a PayPal payment and the SDK completes the checkout.
+     *
+     * Use it to update the page, not to grant access. Browser callbacks can be faked, so unlock paid content only after your backend confirms the purchase, for example with [`listPurchases()`](/developers/references/sdk/docs/interfaces/service-role-payments#listpurchases) in a backend function.
+     *
+     * Stripe doesn't call this. After a Stripe payment, the buyer returns to the checkout's `success_path` with a `session_id` query parameter. That parameter is the `checkout_id`. Show the result there with [`listPurchases()`](/developers/references/sdk/docs/interfaces/payments#listpurchases), and grant access only after your backend confirms it.
+     */
+    onComplete?: (result: CompleteCheckoutResult) => void;
+    /** Called when the buyer closes the PayPal window without paying. The button stays mounted so the buyer can try again. */
+    onCancel?: () => void;
+    /**
+     * Called when a PayPal checkout fails after it's mounted, including a declined payment with the `payment_declined` code. The button stays mounted so the buyer can try again. If it keeps failing with `payment_declined`, create a new checkout and mount it. Stripe shows its own errors inside the checkout.
+     *
+     * The error is a `Base44Error` when completing the checkout fails, or PayPal's own error object when the PayPal window fails.
+     */
+    onError?: (error: unknown) => void;
+}
+/**
+ * An element on the page to render the checkout in, such as the result of `document.getElementById()`.
+ *
+ * Typed structurally so that the SDK's types don't require the DOM library in backend code.
+ */
+export interface CheckoutElement {
+    /** Present on every DOM element. */
+    appendChild(node: never): unknown;
+}
+/**
+ * The fields of a {@linkcode CreateCheckoutResult} that [`mountCheckout()`](/developers/references/sdk/docs/interfaces/payments#mountcheckout) reads.
+ */
+export interface MountableCheckout {
+    /** ID of the checkout. */
+    checkout_id: string;
+    /** Three-letter ISO currency code of the checkout. */
+    currency: string;
+    /** Data for the embedded checkout. Mounting rejects when it's `null`. */
+    embedded: EmbeddedCheckout | null;
+}
+/**
+ * A mounted embedded checkout.
+ */
+export interface CheckoutMount {
+    /** Removes the checkout from the page. Call it when the component that holds it unmounts. For Stripe, mounting another checkout destroys this one for you. */
+    destroy: () => void;
+}
+/**
+ * Payments module for selling from the app through its connected payment provider.
+ *
+ * This module provides:
+ * - An embedded checkout that renders in any framework, with a PayPal button or Stripe Embedded Checkout
+ * - Completing PayPal checkouts
+ * - Lookup of the signed-in user's purchases
+ *
+ * Creating checkouts, refunds, and subscription changes are in {@linkcode ServiceRolePaymentsModule}.
+ *
+ * Each app connects one provider, which is Stripe, PayPal, or Wix Payments. Amounts are always integers in the currency's minor units, such as cents.
+ *
+ * | | Stripe | PayPal | Wix Payments |
+ * | :- | :- | :- | :- |
+ * | Redirect checkout | Yes | No | Yes |
+ * | Embedded checkout | Yes | Yes, the only mode | No |
+ * | Refunds | Yes | Yes | No |
+ * | Cancel a subscription | Yes, now or at period end | Yes, now only | No |
+ * | Pause and resume a subscription | Yes | Yes | No |
+ *
+ * ## Authentication modes
+ *
+ * - **Anonymous or user authentication** (`base44.payments`): Completes checkouts, mounts embedded checkouts, and lists the signed-in user's own purchases.
+ * - **Service role authentication** (`base44.asServiceRole.payments`): Creates checkouts, lists any purchase, refunds payments, and changes subscriptions. Use it in backend functions.
+ *
+ * Failed requests reject with a `Base44Error` whose `code` is one of the {@linkcode PaymentsErrorCode} values. Invalid arguments and [`mountCheckout()`](#mountcheckout) failures reject with a plain `Error`.
+ */
+export interface PaymentsModule {
+    /**
+     * Completes a PayPal checkout after the buyer approves it.
+     *
+     * When you use {@linkcode mountCheckout | mountCheckout()}, it calls this for you. Call it yourself only if you render the PayPal button yourself. Calling it again for the same checkout returns the same result.
+     *
+     * Only PayPal checkouts need completing. Other providers reject with `complete_not_supported`.
+     *
+     * @param checkoutId - The `checkout_id` from [`createCheckout()`](/developers/references/sdk/docs/interfaces/service-role-payments#createcheckout).
+     * @returns Promise resolving to the checkout's payment status.
+     *
+     * @example
+     * ```typescript
+     * // Complete a PayPal checkout in your own onApprove handler
+     * const { status } = await base44.payments.completeCheckout(checkoutId);
+     * if (status === 'paid') {
+     *   showThankYou();
+     * }
+     * ```
+     */
+    completeCheckout(checkoutId: string): Promise<CompleteCheckoutResult>;
+    /**
+     * Lists the signed-in user's purchases.
+     *
+     * Only purchases made with the user's own email address are returned. Rejects with `forbidden` when no user is signed in. PayPal apps must pass `checkout_id` or `subscription_id`, and get at most one purchase.
+     *
+     * @param params - Optional filters and pagination.
+     * @returns Promise resolving to a page of purchases.
+     *
+     * @example
+     * ```typescript
+     * // Check a purchase on the success page
+     * const { items } = await base44.payments.listPurchases({ checkout_id: checkoutId });
+     * const paid = items[0]?.status === 'paid';
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Page through the user's purchases
+     * let cursor: string | undefined;
+     * do {
+     *   const page = await base44.payments.listPurchases({ limit: 50, cursor });
+     *   page.items.forEach((purchase) => console.log(purchase.checkout_id, purchase.status));
+     *   cursor = page.next_cursor ?? undefined;
+     * } while (cursor);
+     * ```
+     */
+    listPurchases(params?: ListPurchasesParams): Promise<ListPurchasesResult>;
+    /**
+     * Renders an embedded checkout inside an element on the page.
+     *
+     * Pass the result of a [`createCheckout()`](/developers/references/sdk/docs/interfaces/service-role-payments#createcheckout) call made with `presentation: 'embedded'`. Because only the service role can create checkouts, create it in a backend function and return the result to the page.
+     *
+     * The SDK loads the provider's script and renders the checkout for you:
+     * - PayPal: Renders a PayPal button. When the buyer approves the payment, the SDK calls {@linkcode completeCheckout | completeCheckout()} and then `onComplete`.
+     * - Stripe: Mounts Stripe Embedded Checkout. After paying, the buyer returns to the checkout's `success_path`. Stripe allows one embedded checkout per page, so mounting another Stripe checkout destroys the previous one.
+     *
+     * Requires a browser environment and can't be used in the backend. Rejects when the checkout isn't embedded, when the payments config can't be fetched or has no valid script URL for the provider, when the provider's script fails to load, or when PayPal isn't available for the checkout's currency.
+     *
+     * The checkout's callbacks run in the buyer's browser, where they can be faked. Grant access to what the buyer paid for only after your backend confirms the purchase, for example with [`listPurchases()`](/developers/references/sdk/docs/interfaces/service-role-payments#listpurchases) in a backend function.
+     *
+     * @param element - Element to render the checkout in. It should be empty.
+     * @param checkout - The result of [`createCheckout()`](/developers/references/sdk/docs/interfaces/service-role-payments#createcheckout).
+     * @param options - Callbacks for the checkout's outcome.
+     * @returns Promise resolving to the mounted checkout once it renders.
+     *
+     * @example
+     * ```typescript
+     * // Create the checkout in a backend function, then mount it
+     * const { data: checkout } = await base44.functions.invoke('createCheckout', { planId });
+     *
+     * const mount = await base44.payments.mountCheckout(
+     *   document.getElementById('checkout')!,
+     *   checkout,
+     *   {
+     *     onComplete: ({ status }) => navigate(status === 'paid' ? '/thank-you' : '/processing'),
+     *     onError: () => setError('The payment failed. Please try again.'),
+     *   }
+     * );
+     *
+     * // Later, when the page unmounts
+     * mount.destroy();
+     * ```
+     *
+     * @example
+     * ```tsx
+     * // React component
+     * function Checkout({ checkout }: { checkout: CreateCheckoutResult }) {
+     *   const ref = useRef<HTMLDivElement>(null);
+     *
+     *   useEffect(() => {
+     *     let mount: CheckoutMount | undefined;
+     *     let cancelled = false;
+     *     base44.payments
+     *       .mountCheckout(ref.current!, checkout, { onComplete: () => navigate('/thank-you') })
+     *       .then((m) => (cancelled ? m.destroy() : (mount = m)))
+     *       .catch(() => setError('The checkout could not load.'));
+     *     return () => {
+     *       cancelled = true;
+     *       mount?.destroy();
+     *     };
+     *   }, [checkout]);
+     *
+     *   return <div ref={ref} />;
+     * }
+     * ```
+     */
+    mountCheckout(element: CheckoutElement, checkout: MountableCheckout, options?: MountCheckoutOptions): Promise<CheckoutMount>;
+}
+/**
+ * Payments module with service role authentication, for backend functions.
+ *
+ * Creates checkouts, lists any purchase, refunds payments, and changes subscriptions. See {@linkcode PaymentsModule} for which providers support which operations.
+ *
+ * Refunds take a required `idempotency_key` and checkouts take an optional one, so retrying them doesn't charge or refund twice. Repeating a subscription change returns the subscription's current state.
+ */
+export interface ServiceRolePaymentsModule {
+    /**
+     * Creates a checkout.
+     *
+     * For a redirect checkout, send the buyer to the returned `redirect_url`. For an embedded checkout, return the result to the page and pass it to [`mountCheckout()`](/developers/references/sdk/docs/interfaces/payments#mountcheckout).
+     *
+     * A checkout with a `recurring` item creates a subscription.
+     *
+     * @param params - Items, return paths, and options for the checkout.
+     * @returns Promise resolving to the checkout.
+     *
+     * @example
+     * ```typescript
+     * // Create a redirect checkout in a backend function
+     * import { createClientFromRequest } from 'npm:@base44/sdk';
+     *
+     * Deno.serve(async (req) => {
+     *   const base44 = createClientFromRequest(req);
+     *   const checkout = await base44.asServiceRole.payments.createCheckout({
+     *     items: [{ name: 'T-shirt', amount: 2500, quantity: 2, shippable: true }],
+     *     currency: 'usd',
+     *     success_path: '/thank-you',
+     *     cancel_path: '/cart',
+     *   });
+     *
+     *   return Response.json({ url: checkout.redirect_url });
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Create an embedded subscription checkout for the signed-in user
+     * import { createClientFromRequest } from 'npm:@base44/sdk';
+     *
+     * Deno.serve(async (req) => {
+     *   const base44 = createClientFromRequest(req);
+     *   const user = await base44.auth.me();
+     *   const checkout = await base44.asServiceRole.payments.createCheckout({
+     *     items: [{
+     *       name: 'Pro plan',
+     *       amount: 1500,
+     *       recurring: { frequency: 'month', free_trial: { frequency: 'day', interval: 14 } },
+     *     }],
+     *     currency: 'usd',
+     *     success_path: '/welcome',
+     *     buyer: { email: user.email },
+     *     presentation: 'embedded',
+     *   });
+     *
+     *   // Pass this to base44.payments.mountCheckout() on the page
+     *   return Response.json(checkout);
+     * });
+     * ```
+     */
+    createCheckout(params: CreateCheckoutParams): Promise<CreateCheckoutResult>;
+    /**
+     * Completes a PayPal checkout after the buyer approves it.
+     *
+     * See [`base44.payments.completeCheckout()`](/developers/references/sdk/docs/interfaces/payments#completecheckout).
+     *
+     * @param checkoutId - The `checkout_id` from {@linkcode createCheckout | createCheckout()}.
+     * @returns Promise resolving to the checkout's payment status.
+     *
+     * @example
+     * ```typescript
+     * // Complete a PayPal checkout from a backend function
+     * const { status } = await base44.asServiceRole.payments.completeCheckout(checkoutId);
+     * ```
+     */
+    completeCheckout(checkoutId: string): Promise<CompleteCheckoutResult>;
+    /**
+     * Lists the app's purchases.
+     *
+     * Unlike [`base44.payments.listPurchases()`](/developers/references/sdk/docs/interfaces/payments#listpurchases), it returns any buyer's purchases and includes their `metadata`. PayPal apps must pass `checkout_id` or `subscription_id`, and get at most one purchase.
+     *
+     * @param params - Optional filters and pagination.
+     * @returns Promise resolving to a page of purchases.
+     *
+     * @example
+     * ```typescript
+     * // Find a buyer's purchases
+     * const { items } = await base44.asServiceRole.payments.listPurchases({
+     *   buyer_email: 'buyer@example.com',
+     * });
+     * ```
+     */
+    listPurchases(params?: ServiceRoleListPurchasesParams): Promise<ListPurchasesResult>;
+    /**
+     * Refunds all or part of a payment.
+     *
+     * Retrying with the same `idempotency_key` and `amount` returns the original refund instead of refunding twice. When the call rejects with `refund_failed`, the outcome is unknown, so retry it with the same values.
+     *
+     * Not supported for Wix Payments.
+     *
+     * @param params - The payment, amount, and idempotency key.
+     * @returns Promise resolving to the refund.
+     *
+     * @example
+     * ```typescript
+     * // Refund a purchase in full
+     * const { items } = await base44.asServiceRole.payments.listPurchases({ checkout_id: checkoutId });
+     * const purchase = items[0];
+     *
+     * const refund = await base44.asServiceRole.payments.refund({
+     *   payment_id: purchase.payment_id!,
+     *   amount: purchase.amount_total!,
+     *   idempotency_key: `refund-${checkoutId}`,
+     * });
+     * ```
+     */
+    refund(params: RefundParams): Promise<RefundResult>;
+    /**
+     * Cancels a subscription, now or at the end of the current billing period.
+     *
+     * Not supported for Wix Payments. PayPal supports cancelling now only.
+     *
+     * @param subscriptionId - The `subscription_id` of the purchase.
+     * @param options - When to cancel.
+     * @returns Promise resolving to the subscription's state.
+     *
+     * @example
+     * ```typescript
+     * // Cancel at the end of the billing period
+     * await base44.asServiceRole.payments.cancelSubscription(subscriptionId, {
+     *   at_period_end: true,
+     * });
+     * ```
+     */
+    cancelSubscription(subscriptionId: string, options?: CancelSubscriptionOptions): Promise<SubscriptionResult>;
+    /**
+     * Pauses a subscription's billing.
+     *
+     * Not supported for Wix Payments.
+     *
+     * @param subscriptionId - The `subscription_id` of the purchase.
+     * @returns Promise resolving to the subscription's state.
+     *
+     * @example
+     * ```typescript
+     * // Pause a subscription
+     * await base44.asServiceRole.payments.pauseSubscription(subscriptionId);
+     * ```
+     */
+    pauseSubscription(subscriptionId: string): Promise<SubscriptionResult>;
+    /**
+     * Resumes a paused subscription's billing.
+     *
+     * Not supported for Wix Payments.
+     *
+     * @param subscriptionId - The `subscription_id` of the purchase.
+     * @returns Promise resolving to the subscription's state.
+     *
+     * @example
+     * ```typescript
+     * // Resume a paused subscription
+     * await base44.asServiceRole.payments.resumeSubscription(subscriptionId);
+     * ```
+     */
+    resumeSubscription(subscriptionId: string): Promise<SubscriptionResult>;
+}

package/dist/modules/payments.types.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.53-pr.331.bf2d5aa",
+  "version": "0.8.54-pr.316.81dc6f9",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",