Skip to content

A local-first personal finance app

[AI] api: add browser build (#8166)

Matiss Janis Aboltins8f27e177dc72
diff --git a/.github/workflows/api-browser-test.yml b/.github/workflows/api-browser-test.yml
new file mode 100644
index 0000000000..2f050bb43e
--- /dev/null
+++ b/.github/workflows/api-browser-test.yml
@@ -0,0 +1,47 @@
+name: API Browser Test
+
+on:
+ pull_request:
+ paths:
+ - 'packages/api/**'
+ - 'packages/loot-core/**'
+ - 'packages/crdt/**'
+ - 'package.json'
+ - 'yarn.lock'
+ - '.github/workflows/api-browser-test.yml'
+ merge_group:
+
+permissions:
+ contents: read
+
+concurrency:
+ group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ api-browser:
+ name: API browser e2e
+ runs-on: depot-ubuntu-latest-4
+ container:
+ image: mcr.microsoft.com/playwright:v1.59.1-jammy
+ steps:
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+ with:
+ persist-credentials: false
+ - name: Set up environment
+ uses: ./.github/actions/setup
+ with:
+ download-translations: 'false'
+ - name: Trust the repository directory
+ run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
+ - name: Build API
+ run: yarn build:api
+ - name: Run browser e2e tests
+ run: yarn workspace @actual-app/api e2e
+ - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+ if: failure()
+ with:
+ name: api-browser-test-results
+ path: packages/api/test-results/
+ retention-days: 30
+ overwrite: true
diff --git a/.gitignore b/.gitignore
index 83fc734300..91fa68e737 100644
--- a/.gitignore
+++ b/.gitignore
@@ -19,6 +19,8 @@ packages/api/app/bundle.api.js
packages/api/app/stats.json
packages/api/dist
packages/api/@types
+packages/api/test-results
+packages/api/playwright-report
packages/crdt/dist
packages/desktop-client/build-stats
packages/desktop-client/dev-dist
diff --git a/packages/api/browser-worker.ts b/packages/api/browser-worker.ts
new file mode 100644
index 0000000000..b47a7f5d12
--- /dev/null
+++ b/packages/api/browser-worker.ts
@@ -0,0 +1,21 @@
+// Web Worker entry for the browser build; owns the real loot-core backend.
+
+import * as connection from '@actual-app/core/platform/server/connection';
+import { handlers, init } from '@actual-app/core/server/main';
+import type { InitConfig } from '@actual-app/core/server/main';
+
+// Worker-local handler, not part of the shared Handlers type.
+(handlers as Record<string, (args?: unknown) => Promise<unknown>>)[
+ 'api-browser/init'
+] = async function (args?: unknown) {
+ const { config, assetsBaseUrl } = (args ?? {}) as {
+ config?: InitConfig;
+ assetsBaseUrl?: string;
+ };
+ if (assetsBaseUrl) {
+ process.env.PUBLIC_URL = assetsBaseUrl;
+ }
+ await init(config ?? {});
+};
+
+connection.init(self, handlers);
diff --git a/packages/api/e2e/browser.test.ts b/packages/api/e2e/browser.test.ts
new file mode 100644
index 0000000000..7370c9abae
--- /dev/null
+++ b/packages/api/e2e/browser.test.ts
@@ -0,0 +1,94 @@
+import { expect, test } from '@playwright/test';
+
+// Structural view of the module harness.html loads from dist/browser.js
+// (`typeof import` would pull the whole loot-core type graph in here).
+type Api = {
+ init(config: { dataDir: string }): Promise<unknown>;
+ shutdown(): Promise<void>;
+ getBudgets(): Promise<unknown[]>;
+ getAccounts(): Promise<Array<{ id: string; name: string }>>;
+ runImport(budgetName: string, func: () => Promise<void>): Promise<void>;
+ createAccount(account: { name: string }, balance?: number): Promise<string>;
+ addTransactions(
+ accountId: string,
+ transactions: Array<{ date: string; amount: number; notes?: string }>,
+ ): Promise<unknown>;
+ getTransactions(
+ accountId: string,
+ startDate: string,
+ endDate: string,
+ ): Promise<Array<{ amount: number }>>;
+};
+
+declare global {
+ // oxlint-disable-next-line typescript/consistent-type-definitions -- global Window augmentation requires interface
+ interface Window {
+ apiReady: Promise<Api>;
+ }
+}
+
+test('boots, imports a budget, reads it back, and persists', async ({
+ page,
+}) => {
+ await page.goto('/e2e/harness.html');
+
+ await page.evaluate(async () => {
+ const api = await window.apiReady;
+ await api.init({ dataDir: '/documents' });
+ });
+
+ // Backend errors must reject as `{ type: 'APIError', message }` envelopes.
+ const error = await page.evaluate(async () => {
+ const api = await window.apiReady;
+ return api.getAccounts().then(
+ () => null,
+ (err: { type?: string; message?: string }) => ({
+ type: err?.type,
+ message: err?.message,
+ }),
+ );
+ });
+ expect(error).toEqual({
+ type: 'APIError',
+ message: 'No budget file is open',
+ });
+
+ const result = await page.evaluate(async () => {
+ const api = await window.apiReady;
+ await api.runImport('e2e-test-budget', async () => {
+ const accountId = await api.createAccount({ name: 'Checking' }, 0);
+ await api.addTransactions(accountId, [
+ { date: '2024-01-15', amount: -1250, notes: 'coffee' },
+ { date: '2024-01-16', amount: 50000, notes: 'paycheck' },
+ ]);
+ });
+
+ const accounts = await api.getAccounts();
+ const transactions = await api.getTransactions(
+ accounts[0].id,
+ '2024-01-01',
+ '2024-01-31',
+ );
+ return {
+ accountNames: accounts.map(a => a.name),
+ amounts: transactions.map(t => t.amount).sort((a, b) => a - b),
+ };
+ });
+ expect(result.accountNames).toEqual(['Checking']);
+ expect(result.amounts).toEqual([-1250, 50000]);
+
+ // Reload the page: the budget must survive in IndexedDB.
+ await page.evaluate(async () => {
+ const api = await window.apiReady;
+ await api.shutdown();
+ });
+ await page.reload();
+ const budgetCount = await page.evaluate(async () => {
+ const api = await window.apiReady;
+ await api.init({ dataDir: '/documents' });
+ const budgets = await api.getBudgets();
+ await api.shutdown();
+ return budgets.length;
+ });
+ expect(budgetCount).toBe(1);
+});
diff --git a/packages/api/e2e/harness.html b/packages/api/e2e/harness.html
new file mode 100644
index 0000000000..7f971a140c
--- /dev/null
+++ b/packages/api/e2e/harness.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html>
+ <head>
+ <meta charset="utf-8" />
+ <title>@actual-app/api browser harness</title>
+ </head>
+ <body>
+ <script type="module">
+ window.apiReady = import('../dist/browser.js');
+ </script>
+ </body>
+</html>
diff --git a/packages/api/e2e/serve-dist.mjs b/packages/api/e2e/serve-dist.mjs
new file mode 100644
index 0000000000..95af157783
--- /dev/null
+++ b/packages/api/e2e/serve-dist.mjs
@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+// Static server for the package root with the COOP/COEP headers required for
+// SharedArrayBuffer (absurd-sql). Used by playwright.config.ts.
+
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const PORT = Number(process.env.PORT) || 4180;
+
+const MIME = {
+ '.html': 'text/html; charset=utf-8',
+ '.js': 'text/javascript; charset=utf-8',
+ '.map': 'application/json; charset=utf-8',
+ '.txt': 'text/plain; charset=utf-8',
+ '.sql': 'text/plain; charset=utf-8',
+ '.wasm': 'application/wasm',
+};
+
+http
+ .createServer((req, res) => {
+ res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
+ res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp');
+
+ const urlPath = decodeURIComponent(req.url.split('?')[0]);
+ const file = path.resolve(ROOT, urlPath.replace(/^\/+/, ''));
+ if (
+ path.relative(ROOT, file).startsWith('..') ||
+ !fs.statSync(file, { throwIfNoEntry: false })?.isFile()
+ ) {
+ res.writeHead(404);
+ res.end('Not found');
+ return;
+ }
+
+ res.setHeader(
+ 'Content-Type',
+ MIME[path.extname(file)] ?? 'application/octet-stream',
+ );
+ fs.createReadStream(file).pipe(res);
+ })
+ .listen(PORT, () => {
+ console.log(`Serving ${ROOT} at http://localhost:${PORT}`);
+ });
diff --git a/packages/api/e2e/tsconfig.json b/packages/api/e2e/tsconfig.json
new file mode 100644
index 0000000000..1a05922153
--- /dev/null
+++ b/packages/api/e2e/tsconfig.json
@@ -0,0 +1,9 @@
+{
+ "extends": "../../../tsconfig.json",
+ "compilerOptions": {
+ "composite": false,
+ "noEmit": true,
+ "types": ["@playwright/test", "node"]
+ },
+ "include": ["./**/*.ts"]
+}
diff --git a/packages/api/index.browser.ts b/packages/api/index.browser.ts
new file mode 100644
index 0000000000..737385a862
--- /dev/null
+++ b/packages/api/index.browser.ts
@@ -0,0 +1,45 @@
+import { startBackendWorker } from '@actual-app/core/platform/client/backend-worker';
+import { send } from '@actual-app/core/platform/client/connection';
+import type { InitConfig } from '@actual-app/core/server/main';
+
+export * from './methods';
+export * as utils from './utils';
+
+let worker: Worker | null = null;
+
+export async function init(
+ config: InitConfig = {},
+): Promise<{ send: typeof send }> {
+ // Non-literal so bundlers don't pre-bundle ./worker.js, which only exists
+ // next to the built file.
+ const rel = './worker.js';
+ worker = new Worker(new URL(rel, import.meta.url), { type: 'module' });
+
+ // Not `new URL('.', import.meta.url)` — consumer asset analyzers rewrite it.
+ const assetsBaseUrl = import.meta.url.replace(/[^/]+$/, '');
+ try {
+ await startBackendWorker(worker, config, assetsBaseUrl);
+ } catch (error) {
+ worker.terminate();
+ worker = null;
+ throw error;
+ }
+
+ return { send };
+}
+
+export async function shutdown() {
+ if (worker) {
+ try {
+ await send('sync');
+ } catch {
+ // most likely that no budget is loaded, so the sync failed
+ }
+ try {
+ await send('close-budget');
+ } finally {
+ worker.terminate();
+ worker = null;
+ }
+ }
+}
diff --git a/packages/api/methods.ts b/packages/api/methods.ts
index fc1fc149d8..888d99709b 100644
--- a/packages/api/methods.ts
+++ b/packages/api/methods.ts
@@ -1,3 +1,4 @@
+import { send } from '@actual-app/core/platform/client/connection';
import type {
APIAccountEntity,
APICategoryEntity,
@@ -7,10 +8,8 @@ import type {
APIScheduleEntity,
APITagEntity,
} from '@actual-app/core/server/api-models';
-import { lib } from '@actual-app/core/server/main';
import type { Query } from '@actual-app/core/shared/query';
import type { ImportTransactionsOpts } from '@actual-app/core/types/api-handlers';
-import type { Handlers } from '@actual-app/core/types/handlers';
import type {
ImportTransactionEntity,
NoteEntity,
@@ -20,13 +19,6 @@ import type {
export { q } from './app/query';
-function send<K extends keyof Handlers, T extends Handlers[K]>(
- name: K,
- args?: Parameters<T>[0],
-): Promise<Awaited<ReturnType<T>>> {
- return lib.send(name, args);
-}
-
export async function runImport(
budgetName: APIFileEntity['name'],
func: () => Promise<void>,
diff --git a/packages/api/package.json b/packages/api/package.json
index 10f665c3c0..0862c5a074 100644
--- a/packages/api/package.json
+++ b/packages/api/package.json
@@ -20,6 +20,10 @@
".": {
"types": "./@types/index.d.ts",
"development": "./index.ts",
+ "browser": {
+ "types": "./@types/index.browser.d.ts",
+ "default": "./dist/browser.js"
+ },
"default": "./dist/index.js"
},
"./models": {
@@ -32,6 +36,10 @@
"exports": {
".": {
"types": "./@types/index.d.ts",
+ "browser": {
+ "types": "./@types/index.browser.d.ts",
+ "default": "./dist/browser.js"
+ },
"default": "./dist/index.js"
},
"./models": {
@@ -41,8 +49,9 @@
}
},
"scripts": {
- "build": "vite build && tsgo --emitDeclarationOnly",
+ "build": "vite build && tsgo --emitDeclarationOnly && vite build --config vite.browser-worker.config.mts && vite build --config vite.browser.config.mts",
"test": "vitest --run",
+ "e2e": "playwright test",
"typecheck": "tsgo -b && tsc-strict"
},
"dependencies": {
@@ -53,10 +62,12 @@
"uuid": "^14.0.0"
},
"devDependencies": {
+ "@playwright/test": "1.59.1",
"@typescript/native-preview": "beta",
"rollup-plugin-visualizer": "^7.0.1",
"typescript-strict-plugin": "^2.4.4",
"vite": "^8.0.16",
+ "vite-plugin-node-polyfills": "^0.28.0",
"vite-plugin-peggy-loader": "^2.0.1",
"vitest": "^4.1.8"
},
diff --git a/packages/api/playwright.config.ts b/packages/api/playwright.config.ts
new file mode 100644
index 0000000000..246ad7361b
--- /dev/null
+++ b/packages/api/playwright.config.ts
@@ -0,0 +1,18 @@
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+ timeout: 60_000,
+ retries: process.env.CI ? 1 : 0,
+ testDir: 'e2e/',
+ reporter: [['list']],
+ use: {
+ browserName: 'chromium',
+ baseURL: 'http://localhost:4180',
+ trace: 'on-first-retry',
+ },
+ webServer: {
+ command: 'node e2e/serve-dist.mjs',
+ url: 'http://localhost:4180/e2e/harness.html',
+ reuseExistingServer: !process.env.CI,
+ },
+});
diff --git a/packages/api/tsconfig.json b/packages/api/tsconfig.json
index 15caf1b278..69fa7e8c64 100644
--- a/packages/api/tsconfig.json
+++ b/packages/api/tsconfig.json
@@ -35,6 +35,7 @@
"**/node_modules/*",
"dist",
"@types",
+ "e2e",
"*.config.ts",
"*.config.mts"
]
diff --git a/packages/api/utils.ts b/packages/api/utils.ts
index b83c3ab072..0d6c587bd9 100644
--- a/packages/api/utils.ts
+++ b/packages/api/utils.ts
@@ -1,4 +1 @@
-import { lib } from '@actual-app/core/server/main';
-
-export const amountToInteger = lib.amountToInteger;
-export const integerToAmount = lib.integerToAmount;
+export { amountToInteger, integerToAmount } from '@actual-app/core/shared/util';
diff --git a/packages/api/vite.browser-worker.config.mts b/packages/api/vite.browser-worker.config.mts
new file mode 100644
index 0000000000..0f179bb48f
--- /dev/null
+++ b/packages/api/vite.browser-worker.config.mts
@@ -0,0 +1,54 @@
+import path from 'path';
+
+import { defineConfig } from 'vite';
+import { nodePolyfills } from 'vite-plugin-node-polyfills';
+import peggyLoader from 'vite-plugin-peggy-loader';
+
+const distDir = path.resolve(__dirname, 'dist');
+
+// Worker bundle: full loot-core + sql.js + absurd-sql.
+export default defineConfig({
+ define: {
+ // Other env vars (PUBLIC_URL etc.) are set at runtime via the process shim.
+ 'process.env.NODE_ENV': JSON.stringify('production'),
+ },
+ build: {
+ target: 'esnext',
+ outDir: distDir,
+ emptyOutDir: false,
+ sourcemap: true,
+ lib: {
+ entry: path.resolve(__dirname, 'browser-worker.ts'),
+ formats: ['es'],
+ fileName: () => 'worker.js',
+ },
+ rollupOptions: {
+ output: {
+ codeSplitting: false,
+ },
+ },
+ },
+ plugins: [
+ peggyLoader(),
+ nodePolyfills({
+ include: [
+ 'process',
+ 'buffer',
+ 'stream',
+ 'path',
+ 'crypto',
+ 'timers',
+ 'util',
+ 'zlib',
+ 'fs',
+ 'assert',
+ ],
+ globals: {
+ process: true,
+ Buffer: true,
+ global: true,
+ },
+ }),
+ ],
+ // No resolve.conditions: ['api'] — loot-core uses its default (browser) files.
+});
diff --git a/packages/api/vite.browser.config.mts b/packages/api/vite.browser.config.mts
new file mode 100644
index 0000000000..3c6f083abe
--- /dev/null
+++ b/packages/api/vite.browser.config.mts
@@ -0,0 +1,25 @@
+import path from 'path';
+
+import { defineConfig } from 'vite';
+
+const distDir = path.resolve(__dirname, 'dist');
+
+// Main-thread facade bundle — the backend never enters it.
+export default defineConfig({
+ build: {
+ target: 'esnext',
+ outDir: distDir,
+ emptyOutDir: false,
+ sourcemap: true,
+ lib: {
+ entry: path.resolve(__dirname, 'index.browser.ts'),
+ formats: ['es'],
+ fileName: () => 'browser.js',
+ },
+ rollupOptions: {
+ output: {
+ codeSplitting: false,
+ },
+ },
+ },
+});
diff --git a/packages/api/vite.config.mts b/packages/api/vite.config.mts
index 595d8acb8f..96ca244024 100644
--- a/packages/api/vite.config.mts
+++ b/packages/api/vite.config.mts
@@ -4,6 +4,7 @@ import path from 'path';
import { visualizer } from 'rollup-plugin-visualizer';
import { defineConfig } from 'vite';
import peggyLoader from 'vite-plugin-peggy-loader';
+import { configDefaults } from 'vitest/config';
const lootCoreRoot = path.resolve(__dirname, '../loot-core');
const distDir = path.resolve(__dirname, 'dist');
@@ -49,6 +50,33 @@ function copyMigrationsAndDefaultDb() {
throw new Error(`default-db.sqlite not found at ${defaultDbPath}`);
}
fs.copyFileSync(defaultDbPath, path.join(distDir, 'default-db.sqlite'));
+
+ // Ship sql.js' WASM next to the bundle so consumers serve it same-origin.
+ const sqlJsWasm = require.resolve('@jlongster/sql.js/dist/sql-wasm.wasm');
+ fs.copyFileSync(sqlJsWasm, path.join(distDir, 'sql-wasm.wasm'));
+
+ // Runtime data files for the browser worker. JS migrations get a `.data`
+ // suffix so consumer bundlers don't import-analyze them.
+ const dataDir = path.join(distDir, 'data');
+ const dataMigrationsDir = path.join(dataDir, 'migrations');
+ fs.mkdirSync(dataMigrationsDir, { recursive: true });
+
+ fs.copyFileSync(defaultDbPath, path.join(dataDir, 'default-db.sqlite'));
+ const migrationNames: string[] = [];
+ for (const name of fs.readdirSync(migrationsDest)) {
+ const wireName = name.endsWith('.js') ? `${name}.data` : name;
+ fs.copyFileSync(
+ path.join(migrationsDest, name),
+ path.join(dataMigrationsDir, wireName),
+ );
+ migrationNames.push(`migrations/${wireName}`);
+ }
+ migrationNames.sort();
+
+ fs.writeFileSync(
+ path.join(distDir, 'data-file-index.txt'),
+ ['default-db.sqlite', ...migrationNames].join('\n') + '\n',
+ );
},
};
}
@@ -85,6 +113,8 @@ export default defineConfig({
},
test: {
globals: true,
+ // e2e/ holds Playwright tests (yarn e2e), not vitest ones.
+ exclude: [...configDefaults.exclude, 'e2e/**'],
// Each test loads a budget file and runs all DB migrations, which can be
// slow on busy CI runners; the default 5s timeout is too tight and causes
// flaky timeouts (and a cascade of unhandled rejections from in-flight work
diff --git a/packages/docs/docs/api/index.md b/packages/docs/docs/api/index.md
index 0d5a4b1b70..a8961ac3c7 100644
--- a/packages/docs/docs/api/index.md
+++ b/packages/docs/docs/api/index.md
@@ -84,6 +84,30 @@ The API communicates with the server using Node's built-in `fetch`. There are a
- Option 2: Set environment variable [NODE_TLS_REJECT_UNAUTHORIZED](https://nodejs.org/api/cli.html#node_tls_reject_unauthorizedvalue) to `0`. Not recommended if your program reaches out to any other endpoints other than the Actual server.
- Options 3: Use OpenSSL CA certificates configuration for Node and add your certificate to the OpenSSL SSL_CERT_DIR. What this requires depends on your build of Node.js, and the configuration details are beyond the scope of this documentation. See the [Node.js OpenSSL Strategy](https://github.com/nodejs/TSC/blob/main/OpenSSL-Strategy.md) page for a starting point.
+## Using the API in a Browser
+
+<ExperimentalFeatureWarning />
+
+The package also ships a browser build. When you bundle your web app with a modern bundler (for example Vite), the package's `browser` entry is picked up automatically and you use the same methods as in Node.js:
+
+```js
+import * as api from '@actual-app/api';
+
+await api.init({
+ // In the browser, budget data is stored in IndexedDB. This is a path
+ // inside that virtual file system.
+ dataDir: '/documents',
+ serverURL: 'https://your-server.example.com',
+ password: 'hunter2',
+});
+
+await api.downloadBudget('1cfdbb80-6274-49bf-b0c2-737235a4c81f');
+console.log(await api.getAccounts());
+await api.shutdown();
+```
+
+Behind the scenes, `init` starts a Web Worker running the same budget engine the Actual web app uses, backed by SQLite compiled to WebAssembly. Your budget data is stored in the browser's IndexedDB and stays on the device.
+
## Writing Data Importers
If you are using another app, like YNAB or Mint, you might want to migrate your data into Actual. Right now, Actual officially supports [importing YNAB4 data](../migration/ynab4.md) and [importing nYNAB data](../migration/nynab.mdx) (and it works very well). But if you want to import all of your data into Actual, you can write a custom importer.
diff --git a/packages/loot-core/package.json b/packages/loot-core/package.json
index e3f959caa6..8b76e8996e 100644
--- a/packages/loot-core/package.json
+++ b/packages/loot-core/package.json
@@ -119,10 +119,12 @@
"./client/transfer": "./src/client/transfer.ts",
"./client/undo": "./src/client/undo.ts",
"./mocks": "./src/mocks/index.ts",
+ "./platform/client/backend-worker": "./src/platform/client/backend-worker.ts",
"./platform/client/browser-preload": "./src/platform/client/browser-preload/index.ts",
"./platform/client/browser-server/coordinator": "./src/platform/client/browser-server/coordinator.ts",
"./platform/client/connection": {
"electron-renderer": "./src/platform/client/connection/index.electron.ts",
+ "api": "./src/platform/client/connection/index.api.ts",
"default": "./src/platform/client/connection/index.ts"
},
"./platform/client/undo": "./src/platform/client/undo/index.ts",
diff --git a/packages/loot-core/src/platform/client/backend-worker.ts b/packages/loot-core/src/platform/client/backend-worker.ts
new file mode 100644
index 0000000000..47bd40b32d
--- /dev/null
+++ b/packages/loot-core/src/platform/client/backend-worker.ts
@@ -0,0 +1,20 @@
+import { initBackend } from 'absurd-sql/dist/indexeddb-main-thread';
+
+import * as connection from '#platform/client/connection';
+import type { InitConfig } from '#server/main';
+
+// initBackend installs absurd-sql's main-thread bridge — without it the
+// worker's first sqlite write hangs.
+export async function startBackendWorker(
+ worker: Worker,
+ config: InitConfig,
+ assetsBaseUrl: string,
+): Promise<void> {
+ initBackend(worker);
+ await connection.init(worker);
+ // Worker-local handler, not part of the shared Handlers union.
+ await (connection.send as (name: string, args?: unknown) => Promise<unknown>)(
+ 'api-browser/init',
+ { config, assetsBaseUrl },
+ );
+}
diff --git a/packages/loot-core/src/platform/client/connection/index-types.ts b/packages/loot-core/src/platform/client/connection/index-types.ts
index c260cebc04..80160f9263 100644
--- a/packages/loot-core/src/platform/client/connection/index-types.ts
+++ b/packages/loot-core/src/platform/client/connection/index-types.ts
@@ -1,7 +1,11 @@
import type { Handlers } from '#types/handlers';
import type { ServerEvents } from '#types/server-events';
-export declare function init(): Promise<unknown>;
+/**
+ * Connect to the backend. Reads the socket from
+ * `global.Actual.getServerSocket()` unless one is passed directly.
+ */
+export declare function init(socket?: Worker | MessagePort): Promise<unknown>;
export type Init = typeof init;
/**
diff --git a/packages/loot-core/src/platform/client/connection/index.api.ts b/packages/loot-core/src/platform/client/connection/index.api.ts
index 1498cc1767..9621e55c83 100644
--- a/packages/loot-core/src/platform/client/connection/index.api.ts
+++ b/packages/loot-core/src/platform/client/connection/index.api.ts
@@ -1,2 +1,20 @@
-// oxlint-disable-next-line no-restricted-imports
-export * from './index.electron';
+import { lib } from '#server/main';
+import type { Handlers } from '#types/handlers';
+
+import type * as T from './index-types';
+
+// In-process client for the api/node platform.
+export const send = (async <K extends keyof Handlers>(
+ name: K,
+ args?: Parameters<Handlers[K]>[0],
+ options?: { catchErrors?: boolean },
+) => {
+ if (options?.catchErrors) {
+ try {
+ return { data: await lib.send(name, args), error: undefined };
+ } catch (error) {
+ return { data: undefined, error };
+ }
+ }
+ return lib.send(name, args);
+}) as T.Send;
diff --git a/packages/loot-core/src/platform/client/connection/index.electron.ts b/packages/loot-core/src/platform/client/connection/index.electron.ts
index d4e1c20f76..ce4c0cbd4d 100644
--- a/packages/loot-core/src/platform/client/connection/index.electron.ts
+++ b/packages/loot-core/src/platform/client/connection/index.electron.ts
@@ -27,7 +27,7 @@ function connectSocket(onOpen) {
}
} else if (msg.type === 'reply') {
let { result } = msg;
- const { id, mutated, undoTag } = msg;
+ const { id, mutated, undoTag, error } = msg;
// Check if the result is a serialized buffer, and if so
// convert it to a Uint8Array. This is only needed when working
@@ -45,7 +45,12 @@ function connectSocket(onOpen) {
undo.gc(undoTag);
}
- handler.resolve(result);
+ // api/* failures arrive as a reply carrying `error`.
+ if (error) {
+ handler.reject(error);
+ } else {
+ handler.resolve(result);
+ }
}
} else if (msg.type === 'push') {
const { name, args } = msg;
diff --git a/packages/loot-core/src/platform/client/connection/index.ts b/packages/loot-core/src/platform/client/connection/index.ts
index 334438705c..c1093f750b 100644
--- a/packages/loot-core/src/platform/client/connection/index.ts
+++ b/packages/loot-core/src/platform/client/connection/index.ts
@@ -50,7 +50,7 @@ function handleMessage(msg) {
handler.reject(error);
}
} else if (msg.type === 'reply') {
- const { id, result, mutated, undoTag } = msg;
+ const { id, result, mutated, undoTag, error } = msg;
const handler = replyHandlers.get(id);
if (handler) {
@@ -60,7 +60,12 @@ function handleMessage(msg) {
undo.gc(undoTag);
}
- handler.resolve(result);
+ // api/* failures arrive as a reply carrying `error`.
+ if (error) {
+ handler.reject(error);
+ } else {
+ handler.resolve(result);
+ }
}
} else if (msg.type === 'push') {
const { name, args } = msg;
@@ -96,11 +101,9 @@ function connectWorker(worker, onOpen, onError) {
// available, but we don't know when the backend is actually
// ready to handle messages.
if (msg.type === 'connect') {
- // Send any messages that were queued while closed
- if (messageQueue?.length > 0) {
- messageQueue.forEach(msg => worker.postMessage(msg));
- messageQueue = null;
- }
+ // Null the queue so later sends post directly instead of queueing.
+ messageQueue?.forEach(msg => worker.postMessage(msg));
+ messageQueue = null;
// signal to the backend that we're connected to it
globalWorker.postMessage({
@@ -146,8 +149,8 @@ function connectWorker(worker, onOpen, onError) {
}
}
-export const init: T.Init = async function () {
- const worker = await global.Actual.getServerSocket();
+export const init: T.Init = async function (socket) {
+ const worker = socket ?? (await global.Actual.getServerSocket());
return new Promise((resolve, reject) =>
connectWorker(worker, resolve, reject),
);
diff --git a/packages/loot-core/src/platform/server/fs/index.ts b/packages/loot-core/src/platform/server/fs/index.ts
index dcddfbfd93..160f0c2a6c 100644
--- a/packages/loot-core/src/platform/server/fs/index.ts
+++ b/packages/loot-core/src/platform/server/fs/index.ts
@@ -255,7 +255,8 @@ async function populateDefaultFilesystem() {
await Promise.all(
files.map(async file => {
const contents = await fetchFile(process.env.PUBLIC_URL + 'data/' + file);
- await _writeFile('/' + file, contents);
+ // `.data` lets shipped JS files escape bundler import-analysis.
+ await _writeFile('/' + file.replace(/\.data$/, ''), contents);
}),
);
}
diff --git a/packages/loot-core/src/server/mutators.ts b/packages/loot-core/src/server/mutators.ts
index 716379c8c4..ff0400ea63 100644
--- a/packages/loot-core/src/server/mutators.ts
+++ b/packages/loot-core/src/server/mutators.ts
@@ -25,8 +25,8 @@ async function flushRunningMethods() {
await wait(200);
while (runningMethods.size > 0) {
- // Wait for all of them
- await Promise.all([...runningMethods.values()]);
+ // Wait for all of them; rejections already went to their callers.
+ await Promise.allSettled([...runningMethods.values()]);
// We give clients more time to make other requests. This lets them continue
// to do an async workflow
@@ -66,9 +66,9 @@ export async function runHandler<T extends Handlers[keyof Handlers]>(
const promise = handler(args);
runningMethods.add(promise);
- void promise.then(() => {
- runningMethods.delete(promise);
- });
+ // Remove on rejection too — a stale promise poisons every later flush.
+ const remove = () => runningMethods.delete(promise);
+ void promise.then(remove, remove);
return promise as Promise<ReturnType<T>>;
}
diff --git a/upcoming-release-notes/8166.md b/upcoming-release-notes/8166.md
new file mode 100644
index 0000000000..c67939455a
--- /dev/null
+++ b/upcoming-release-notes/8166.md
@@ -0,0 +1,6 @@
+---
+category: Features
+authors: [MatissJanis]
+---
+
+api: add a browser build so `@actual-app/api` can run in the browser (loot-core in a Web Worker).
diff --git a/yarn.lock b/yarn.lock
index 0e98800eb0..9f269db493 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -18,6 +18,7 @@ __metadata:
dependencies:
"@actual-app/core": "workspace:*"
"@actual-app/crdt": "workspace:*"
+ "@playwright/test": "npm:1.59.1"
"@typescript/native-preview": "npm:beta"
better-sqlite3: "npm:^12.10.0"
compare-versions: "npm:^6.1.1"
@@ -25,6 +26,7 @@ __metadata:
typescript-strict-plugin: "npm:^2.4.4"
uuid: "npm:^14.0.0"
vite: "npm:^8.0.16"
+ vite-plugin-node-polyfills: "npm:^0.28.0"
vite-plugin-peggy-loader: "npm:^2.0.1"
vitest: "npm:^4.1.8"
languageName: unknown