@frappe/cloud-sdk

Use Cloud Settings in a Frappe app. The SDK provides typed API calls and a ready-to-use settings dialog. It works in Desk, React, Vue, and plain browser pages.

Use the shared dialog for a consistent Cloud Settings experience across apps. If your app needs its own UI, use the API calls without the dialog.

Requirements

• A Pilot-managed Frappe site with the Cloud Settings server APIs.
• A signed-in user with the System Manager role.
• The site's session cookie. Write calls also need frappe.csrf_token or window.csrf_token.

The server checks access on every call. The browser does not receive Pilot or Central credentials.

Install

npm install @frappe/cloud-sdk

The package holds the API calls and a small loader. It does not hold the UI. When you first open the dialog, the loader imports the UI from the site's Pilot server, at the esm/ path next to the script URL in bundle.js of get_context. Each panel then loads when it is first shown. So a Pilot update changes the UI in every app, and your app does not need a new release. You do not need to add Vue, Frappe UI, or a stylesheet to your app.

The browser must reach the Pilot server, and the page's Content Security Policy must allow scripts from it. If the UI does not load, openCloudSettings() rejects with a message that says so.

The dialog uses the Inter font. If the page does not load Inter, the dialog adds it to the page the first time it opens.

Open Cloud Settings

Show your button only when isCloudSettingsAvailable() returns true. Call openCloudSettings() when the user clicks it.

import { isCloudSettingsAvailable, openCloudSettings, closeCloudSettings } from '@frappe/cloud-sdk'

const available = await isCloudSettingsAvailable()

async function openSettings() {
  try {
    await openCloudSettings({ panels: ['billing', 'domains', 'advanced'] })
  } catch (error) {
    // Show this message in your app's alert or error component.
    console.error(error instanceof Error ? error.message : 'Could not open Cloud Settings.')
  }
}

// Call this when the host page or component is removed.
closeCloudSettings()

In React, use onClick={openSettings}. In Vue, use @click="openSettings". In a plain page, use button.addEventListener('click', openSettings). Disable the button while the dialog opens.

Availability is asynchronous. It returns false for an unavailable site or a permission denial. A connection error rejects the call. Handle that error in your app too. Importing the package is safe during server rendering. Opening the dialog requires a browser.

Select panels and appearance

await openCloudSettings({
  panels: ['billing', 'domains'],
  tab: 'domains',
  theme: 'auto',
  onClose: () => console.log('Cloud Settings closed'),
})

Panel names: billing, marketplace, analytics, domains, backups, usage, site-config, maintenance, and advanced.

The dialog uses Espresso components. On a phone, it fills the viewport and has a panel selector. It keeps clear of the notch and the home indicator when the page sets viewport-fit=cover in its viewport meta tag. On a desktop, it has a sidebar. Its styles, menus, dialogs, alerts, and toasts stay inside a shadow root. Closing removes the UI and returns focus to the button. Opening again replaces the current dialog. Closing also cancels a pending open.

Mount inline

An app with its own settings page can show the panels inside it. Pass the element to fill as target. The panels fill its height, so give the element one. With one panel, the UI has no sidebar and no panel selector, so the app's own navigation stays the only one. With several panels, the sidebar shows inside the element.

await openCloudSettings({ target: document.querySelector('#cloud-settings'), panels: ['billing'] })

// Call this when the host page or component is removed.
closeCloudSettings()

Opening again, inline or as a dialog, replaces the mounted UI. Menus, dialogs, and toasts stay inside the element's shadow root.

The inline UI is in the tab order, so Tab moves from the host page into the panels. A host can show the inline UI inside its own modal. Then Esc, or a click outside the open Cloud menu or dialog, closes it and also the host modal. To prevent this, ignore the modal's close while fc-cloud-settings[overlay-open] exists. The element has this attribute while a Cloud menu or dialog is open.

const isCloudOverlayOpen = () => !!document.querySelector('fc-cloud-settings[overlay-open]')

<Dialog :open="show" @update:open="(open) => (open || !isCloudOverlayOpen()) && (show = open)">

Use API calls without the dialog

You can build your own pages, panels, or controls with the API calls. The /api import does not load the shared UI. Your app controls the layout and handles loading, empty states, errors, and success feedback.

import { getBilling, getDomains } from '@frappe/cloud-sdk/api'

const billing = await getBilling()
const domains = await getDomains()

The root import and /api export the same API calls and TypeScript models. Use /api when you only need data.

Build your own UI on the read calls, for example a plan badge or a banner. For changes, open the dialog on the right panel, such as openCloudSettings({ tab: 'billing' }). The action calls follow the dialog's flows, and their steps can change between versions. Payment setup is an example.

Requests use the current origin and session. They time out after 30 seconds. The SDK does not retry write calls.

getBilling returns next_bill: this site's server's share of the team's next bill, with amount, subtotal, tax, tax_type, charge_on, days_left, the lines behind it, and blockers, the reasons the team's charge would fail. Show a warning only for a blocker. getInvoices returns this server's share of each team invoice, newest first. has_pdf and can_pay are true only when the invoice covers this server alone, because the invoice PDF and its payment cover the whole team. getInvoicePdf(invoice) returns { filename, content }, with the PDF as base64.

changePlan(plan) returns { queued, resized, progress_url }. A new size stops the site for a few minutes. When progress_url is set, open it: the page lives on Central and brings the user back when the site is ready. During a free trial, the call resizes nothing: Central keeps the plan, and the site moves to it when a payment method converts the trial. getPlanOptions then lists the paid plans the trial may move to, with selected set to the plan it moves to. getBilling returns plan_change.progress_url while a plan change runs, such as that move.

Handle feedback and errors

Direct API calls and errors before the dialog opens belong to your app. Catch CloudSettingsError and show its message. It also has status, serverMessages, and excType. Status 0 means a network failure. Messages are plain text.

Use the Desk bundle

Pilot serves two builds of the same UI under /embed/cloud-settings/:

Both entry files revalidate on every load, so a Pilot update takes effect at once. Chunk names contain a content hash, so the browser caches them for a year. The ES files are sent with Access-Control-Allow-Origin: *, because a site imports them from the Pilot origin.

What needs a release

Release

Raise version in package.json and package-lock.json in a pull request. When it merges into develop, the Publish Cloud SDK workflow tests, builds and publishes that version to npm. It skips a version that npm already has. Run the workflow by hand to publish the current version again after a failed run.

npm trusts the workflow through trusted publishing, so the repository holds no npm token. A package maintainer sets this once on npmjs.com: in the @frappe/cloud-sdk settings, add a GitHub Actions trusted publisher for the repository frappe/pilot and the workflow cloud-sdk-publish.yml.

Build and test

Run npm test and npm run build in this package. Run npm run build in admin/frontend/in-app-embed to build both Pilot outputs into admin/backend/static/in-app-embed/cloud-settings/. That build also checks that the ES runtime exports its methods, contains its styles, and loads panels on demand.

To run browser regression tests, install the dependencies in admin/frontend/dashboard and admin/frontend/in-app-embed, then build this package and the in-app embed. Run npx playwright install chromium and npx playwright test --config cloud-settings.config.ts from admin/frontend/dashboard. The tests check that the SDK loads the UI from Pilot and loads a panel only when it is shown, dialog cleanup, custom feedback translations, task cancellation and resume, and the phone layout. cloud-settings-billing.spec.ts checks the billing tab: the trial notice and its states, the billing details and payment steps during a trial, the country and Indian state lists, a card that fails verification, the plan list, the move to the progress page, and the refusal, spending limit and retry states. cloud-settings-marketplace.spec.ts checks that a trial keeps the app it is for, the backup offer before an uninstall, the move to Desk after the host app is removed, the logo and position of a task card, and that app details wait for the pointer to move. CI runs these tests in the MariaDB browser job.

To test all panels with sample data, build this package and the in-app embed. Run python3 -m http.server 8123 from the repository root. Open http://localhost:8123/admin/frontend/cloud-sdk/tests/embed.html. No real payment or site action runs in this fixture.

To test billing without host metadata, run this from the Pilot repository:

.venv/bin/python -m scripts.cloud_settings_simulator --bench-root /path/to/local/bench

Use a local development site that has the server APIs and a button to open the dialog. Set that site's pilot_endpoint to http://127.0.0.1:8003, then clear its cache. Keep its existing site token. Sign in as a System Manager and open Billing. The simulation controls are at http://127.0.0.1:8124. Save the sample profile, complete the local checkout, then click Check status. To test the trial flow, choose Start a free trial on the controls page: Billing then shows an open trial with no invoices, and a completed checkout converts it. End the free trial shows a trial that ended without converting. When the trial converts to a bigger plan, Billing shows the move, then sends the browser to a simulated progress page, which returns to the site when the move ends. Start the simulator with --trial-app <app> to name the app the trial is for, as Central does. The Marketplace panel then keeps that app installed until the trial converts. The simulation answers as Central does: the country and GST state lists come from the bench's Frappe and Central apps, an address in India bills in INR through Razorpay and every other country in USD through Stripe, and a trial offers only the paid plans. Razorpay Checkout needs real Razorpay keys, so the simulation stops at that step. You can reset the data or simulate an API failure. State stays in memory. Billing makes no real charges. Other Pilot operations still use the real local bench. Stop the simulator and restore the original endpoint when finished.