@lowdefy/shell 3.23.3 → 7.2.0

package/src/host/createShellFetch.test.js

@@ -0,0 +1,165 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import createAppSession from '../session/createAppSession.js';
+import createFakeServer, { header } from '../test/createFakeServer.js';
+import createMemoryCacheStore from '../test/createMemoryCacheStore.js';
+import createMemoryStore from './createMemoryStore.js';
+import createShellFetch from './createShellFetch.js';
+import { createPages, createRoot } from '../test/fixtures.js';
+
+const apiBase = 'https://field.example.com';
+
+async function setup() {
+  const server = createFakeServer({
+    root: createRoot(),
+    rootEtag: '"root-1"',
+    pages: createPages([
+      ['today', 'today', '"p-today-1"'],
+      ['jobs', 'jobs', '"p-jobs-1"'],
+      ['jobs/{job_id}', 'job', '"p-job-1"'],
+    ]),
+    requests: () => ({ id: 'get_jobs', success: true, response: [] }),
+  });
+  const session = createAppSession({
+    apiBase,
+    app: { id: 'field' },
+    cacheStore: createMemoryCacheStore(),
+    fetch: server.fetch,
+    kv: createMemoryStore(),
+    tokenStore: { get: () => null },
+  });
+  await session.start();
+  const shellFetch = createShellFetch({ fetch: server.fetch, session });
+  return { server, session, shellFetch };
+}
+
+function deploy({ server, todayHash }) {
+  server.state.buildId = 'build-2';
+  server.state.root = createRoot({
+    buildId: 'build-2',
+    pageIndex: [
+      { path: 'today', pageId: 'today', hash: todayHash, typesKey: 'carried' },
+      { path: 'jobs', pageId: 'jobs', hash: 'h-jobs-1', typesKey: 'carried' },
+    ],
+  });
+  server.state.rootEtag = '"root-2"';
+}
+
+const requestInit = {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json', 'x-lowdefy-build': 'build-1' },
+  body: '{}',
+};
+
+test('a page request carries the build of the root the shell holds', async () => {
+  const { server, shellFetch } = await setup();
+  const res = await shellFetch(`${apiBase}/api/request/jobs/get_jobs`, {
+    ...requestInit,
+    headers: { ...requestInit.headers, 'x-lowdefy-build': 'stale-core-build' },
+  });
+  expect(res.status).toBe(200);
+  expect(header(server.fetch.mock.calls.at(-1)[1], 'x-lowdefy-build')).toBe('build-1');
+});
+
+test('a request sent with keepBuild keeps its build, so an older build gets the 409 and its retry', async () => {
+  const { server, shellFetch } = await setup();
+  deploy({ server, todayHash: 'h-today-1' });
+  server.fetch.mockClear();
+  const res = await shellFetch(`${apiBase}/api/request/jobs/get_jobs`, {
+    ...requestInit,
+    headers: { ...requestInit.headers, 'x-lowdefy-build': 'build-0' },
+    keepBuild: true,
+  });
+  expect(res.status).toBe(200);
+  expect(header(server.fetch.mock.calls[0][1], 'x-lowdefy-build')).toBe('build-0');
+  expect(server.fetch.mock.calls[0][1].keepBuild).toBeUndefined();
+  expect(header(server.fetch.mock.calls.at(-1)[1], 'x-lowdefy-build')).toBe('build-2');
+});
+
+test('a 409 syncs the root and changed pages, then retries the request once on the new build', async () => {
+  const { server, session, shellFetch } = await setup();
+  deploy({ server, todayHash: 'h-today-2' });
+  server.state.pages.today = { pageConfig: { pageId: 'today', v: 2 }, etag: '"p-today-2"' };
+  server.fetch.mockClear();
+  const res = await shellFetch(`${apiBase}/api/request/jobs/get_jobs`, requestInit);
+  expect(res.status).toBe(200);
+  expect(await res.json()).toEqual({ id: 'get_jobs', success: true, response: [] });
+  const urls = server.fetch.mock.calls.map(([url]) => new URL(url).pathname);
+  expect(urls).toEqual([
+    '/api/request/jobs/get_jobs',
+    '/api/mobile/root',
+    '/api/user',
+    '/api/page/today',
+    '/api/request/jobs/get_jobs',
+  ]);
+  expect(header(server.fetch.mock.calls.at(-1)[1], 'x-lowdefy-build')).toBe('build-2');
+  expect(session.getState().buildId).toBe('build-2');
+  expect(session.getState().pages.today.pageConfig.v).toBe(2);
+});
+
+test('a 409 for a page that changed with the build goes to the core, not retried', async () => {
+  const { server, session, shellFetch } = await setup();
+  deploy({ server, todayHash: 'h-today-2' });
+  server.fetch.mockClear();
+  const res = await shellFetch(`${apiBase}/api/request/today/get_jobs`, requestInit);
+  expect(res.status).toBe(409);
+  expect((await res.json()).buildId).toBe('build-2');
+  expect(server.fetch.mock.calls.filter(([url]) => url.includes('/api/request/'))).toHaveLength(1);
+  expect(session.getState().buildId).toBe('build-2');
+});
+
+test('a second 409 after the retry goes to the core', async () => {
+  const { server, shellFetch } = await setup();
+  deploy({ server, todayHash: 'h-today-1' });
+  const serve = server.fetch.getMockImplementation();
+  server.fetch.mockImplementation(async (url, init) => {
+    if (url.includes('/api/request/')) {
+      return {
+        ok: false,
+        status: 409,
+        headers: { get: () => null },
+        json: async () => ({ buildId: 'build-3' }),
+      };
+    }
+    return serve(url, init);
+  });
+  const res = await shellFetch(`${apiBase}/api/request/jobs/get_jobs`, requestInit);
+  expect(res.status).toBe(409);
+  expect(server.fetch.mock.calls.filter(([url]) => url.includes('/api/request/'))).toHaveLength(2);
+});
+
+test('a 409 the shell cannot sync for goes to the core', async () => {
+  const { server, shellFetch } = await setup();
+  deploy({ server, todayHash: 'h-today-1' });
+  const serve = server.fetch.getMockImplementation();
+  server.fetch.mockImplementation(async (url, init) => {
+    if (url.includes('/api/mobile/root')) throw new TypeError('Network request failed');
+    return serve(url, init);
+  });
+  const res = await shellFetch(`${apiBase}/api/request/jobs/get_jobs`, requestInit);
+  expect(res.status).toBe(409);
+});
+
+test('a call without a build stamp (an endpoint call) is never retried', async () => {
+  const { server, shellFetch } = await setup();
+  deploy({ server, todayHash: 'h-today-1' });
+  server.fetch.mockClear();
+  const res = await shellFetch(`${apiBase}/api/endpoints/save`, { method: 'POST', headers: {} });
+  expect(res.status).toBe(404);
+  expect(server.fetch).toHaveBeenCalledTimes(1);
+  expect(header(server.fetch.mock.calls[0][1], 'x-lowdefy-build')).toBeNull();
+});

package/src/host/createShellGlobals.js

@@ -0,0 +1,62 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { createNativeGlobals } from '@lowdefy/client-native';
+
+/**
+ * The host globals of one app in the shell: @lowdefy/client-native's (the shown route, window
+ * size, visibility, network and the pages' elements), and the device services the shell's native
+ * actions reach (src/actions):
+ * - `clipboard`: `{ setString(text) }`, for CopyToClipboard.
+ * - `storage`: the device store the core keeps the app's and its users' keys in
+ *   (`{ get, set, remove, keys }`), for the local storage actions. Sign-out clears the user keys
+ *   from it.
+ * - `shownScreen`: `{ instanceId }`, the route instance of the focused screen, whose page context
+ *   is keyed by it (client-native LowdefyPage); Lowdefy Dev finds the shown page's context by it.
+ *
+ * @param {Object} params
+ * @param {(url: string) => void} params.assign
+ * @param {{ setString: (text: string) => Promise<void> }} params.clipboard
+ * @param {Function} params.fetch
+ * @param {() => (string|null)} params.getInstanceId The focused screen's route instance.
+ * @param {() => string} params.getPath
+ * @param {Object} [params.network]
+ * @param {string} params.origin
+ * @param {Object} params.storage
+ */
+function createShellGlobals({
+  assign,
+  clipboard,
+  fetch,
+  getInstanceId,
+  getPath,
+  network,
+  origin,
+  storage,
+}) {
+  return {
+    ...createNativeGlobals({ assign, fetch, getPath, network, origin }),
+    clipboard,
+    shownScreen: {
+      get instanceId() {
+        return getInstanceId();
+      },
+    },
+    storage,
+  };
+}
+
+export default createShellGlobals;

package/src/host/createShellHost.js

@@ -0,0 +1,83 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { Linking } from 'react-native';
+import * as Clipboard from 'expo-clipboard';
+
+import createDeviceStore from './createDeviceStore.js';
+import createMemoryStore from './createMemoryStore.js';
+import createShellGlobals from './createShellGlobals.js';
+import getOrigin from './getOrigin.js';
+import networkStatus from './networkStatus.js';
+
+// The app's `online` and `offline` events follow the shell's one online state.
+const network = {
+  addListener: networkStatus.subscribe,
+};
+
+/**
+ * The @lowdefy/client-core host for one app in the shell. Calls are signed in with the session
+ * token as a bearer token. The core's build and caller handling lands on the session: a page
+ * request refused for another build is retried by `fetch` (createShellFetch) or rebuilds the
+ * screens (onBuildChanged); another caller resets the app (onCallerChanged).
+ */
+const clipboard = {
+  setString: (text) => Clipboard.setStringAsync(text),
+};
+
+function createShellHost({
+  fetch,
+  requestQueue,
+  router,
+  session,
+  streamFetch,
+  tokenStore,
+  WebSocket,
+}) {
+  const storage = createDeviceStore();
+  return {
+    authTransport: 'bearer',
+    fetch,
+    globals: createShellGlobals({
+      assign: (url) => Linking.openURL(url),
+      clipboard,
+      fetch,
+      getInstanceId: session.getCurrentInstanceId,
+      getPath: session.getCurrentPath,
+      network,
+      origin: getOrigin(session.apiBase),
+      storage,
+    }),
+    onBuildChanged: () => {
+      session.handleBuildChanged();
+    },
+    onCallerChanged: () => {
+      session.handleCallerChanged();
+    },
+    // `offline: queue` requests go through it (src/queue/createRequestQueue.js).
+    requestQueue,
+    router,
+    sessionStorage: createMemoryStore(),
+    storage,
+    // The Fetch API whose response body streams, for blocks (client-native's createStreamFetch).
+    streamFetch,
+    tokenStore,
+    WebSocket,
+    websocketUrl: (apiPath) => apiPath.replace(/^http/, 'ws'),
+  };
+}
+
+export default createShellHost;

package/src/host/createShellHost.test.js

@@ -0,0 +1,36 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { jest } from '@jest/globals';
+
+import createShellHost from './createShellHost.js';
+
+jest.mock('expo-clipboard', () => ({ setStringAsync: jest.fn(async () => true) }));
+jest.mock('./createDeviceStore.js', () => () => ({}));
+jest.mock('./networkStatus.js', () => ({ subscribe: () => () => undefined }));
+
+// Copy link and the other CopyToClipboard actions reach the phone's clipboard through the host.
+test('the host clipboard copies through expo-clipboard', async () => {
+  const Clipboard = jest.requireMock('expo-clipboard');
+  const session = {
+    apiBase: 'https://field.example.com',
+    getCurrentInstanceId: () => null,
+    getCurrentPath: () => '/',
+  };
+  const host = createShellHost({ fetch: jest.fn(), router: {}, session, tokenStore: {} });
+  await host.globals.clipboard.setString('https://field.example.com/tasks/12');
+  expect(Clipboard.setStringAsync.mock.calls).toEqual([['https://field.example.com/tasks/12']]);
+});

package/src/host/getOrigin.js

@@ -0,0 +1,31 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { LowdefyInternalError } from '@lowdefy/errors';
+
+// The origin of the app server's URL: its scheme, host and port. checkShellConfig refuses a
+// shell.json url that is not absolute, so one reaching here is a Lowdefy wiring bug.
+function getOrigin(url) {
+  const match = /^[a-z][a-z0-9+.-]*:\/\/[^/?#]+/i.exec(url);
+  if (match === null) {
+    throw new LowdefyInternalError(
+      `Shell app url is not an absolute URL. Received ${JSON.stringify(url)}.`
+    );
+  }
+  return match[0];
+}
+
+export default getOrigin;

package/src/host/isNetworkError.js

@@ -0,0 +1,24 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+// A call that never reached the server: the platform's fetch rejected (no connection, a DNS or TLS
+// failure, Lowdefy Dev's offline injection), which every shell call marks at the one fetch it goes
+// through (withNetworkErrors). A TypeError thrown after a response arrived is a fault, not this.
+function isNetworkError(error) {
+  return error?.isNetworkError === true;
+}
+
+export default isNetworkError;

package/src/host/isOnline.js

@@ -0,0 +1,22 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+// An expo-network state counts as offline only when it says so: unknown reachability is online.
+function isOnline(networkState) {
+  return networkState.isConnected !== false && networkState.isInternetReachable !== false;
+}
+
+export default isOnline;

package/src/host/networkStatus.js

@@ -0,0 +1,24 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import * as Network from 'expo-network';
+
+import createNetworkStatus from './createNetworkStatus.js';
+
+// The shell's one online state (createNetworkStatus), shared by every app the shell opens.
+const networkStatus = createNetworkStatus({ network: Network });
+
+export default networkStatus;

package/src/host/readServerError.js

@@ -0,0 +1,45 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { decodeErrorBody } from '@lowdefy/client-core';
+import { type } from '@lowdefy/helpers';
+
+/**
+ * The error a non-2xx answer from the app's server carries, decoded as the core's requests decode
+ * it (decodeErrorBody): a fault keeps its class, `requestId`, `handled` mark and dev error, and an
+ * expected outcome (a 400, 401 or 403 the server answered as { name, message }) its class. Any other
+ * answer (a gateway's page, a library's own body) is a plain Error with the body's message, or
+ * `message`. Every error carries the HTTP `status`, so a caller can tell a refusal that will not
+ * change from an outage.
+ *
+ * @param {Object} params
+ * @param {Response} params.res The answer, not yet read.
+ * @param {string} params.message The message for an answer that carries none.
+ */
+async function readServerError({ res, message }) {
+  let body = null;
+  try {
+    body = await res.json();
+  } catch (error) {
+    // Not JSON: a host or gateway answered before the app did.
+  }
+  const error =
+    decodeErrorBody(body) ?? new Error(type.isString(body?.message) ? body.message : message);
+  error.status = res.status;
+  return error;
+}
+
+export default readServerError;

package/src/host/readServerError.test.js

@@ -0,0 +1,85 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { getDevError } from '@lowdefy/engine';
+import { AuthorizationError, RequestError } from '@lowdefy/errors';
+
+import readServerError from './readServerError.js';
+
+function answer({ status, body, json = async () => body }) {
+  return { ok: false, status, json };
+}
+
+test('a fault the server answered keeps its class, request id, handled mark and dev error', async () => {
+  const error = await readServerError({
+    res: answer({
+      status: 500,
+      body: {
+        '~e': {
+          name: 'RequestError',
+          message: 'Something went wrong.',
+          requestId: 'rid-1',
+          handled: true,
+          isLowdefyError: true,
+        },
+        devError: {
+          '~e': { name: 'RequestError', message: 'Mongo refused the query.', isLowdefyError: true },
+        },
+      },
+    }),
+    message: 'The app answered 500.',
+  });
+  expect(error).toBeInstanceOf(RequestError);
+  expect(error.message).toBe('Something went wrong.');
+  expect(error.requestId).toBe('rid-1');
+  expect(error.handled).toBe(true);
+  expect(error.status).toBe(500);
+  expect(getDevError(error).message).toBe('Mongo refused the query.');
+});
+
+test('an expected outcome the server answered as name and message keeps its class', async () => {
+  const error = await readServerError({
+    res: answer({ status: 403, body: { name: 'AuthorizationError', message: 'Not allowed.' } }),
+    message: 'The app answered 403.',
+  });
+  expect(error).toBeInstanceOf(AuthorizationError);
+  expect(error.message).toBe('Not allowed.');
+  expect(error.status).toBe(403);
+});
+
+test('another JSON answer is a plain Error with its message and the status', async () => {
+  const error = await readServerError({
+    res: answer({ status: 400, body: { code: 'INVALID_OTP', message: 'Invalid code.' } }),
+    message: 'The app answered 400.',
+  });
+  expect(error.constructor).toBe(Error);
+  expect(error.message).toBe('Invalid code.');
+  expect(error.status).toBe(400);
+});
+
+test('an answer that is not JSON is a plain Error with the given message and the status', async () => {
+  const error = await readServerError({
+    res: answer({
+      status: 502,
+      json: async () => {
+        throw new SyntaxError('Unexpected token <');
+      },
+    }),
+    message: 'The app answered 502.',
+  });
+  expect(error.message).toBe('The app answered 502.');
+  expect(error.status).toBe(502);
+});

package/src/host/reportShellError.js

@@ -0,0 +1,47 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { isExpectedError } from '@lowdefy/errors';
+
+import isNetworkError from './isNetworkError.js';
+import { peekCurrentApp } from '../native/currentApp.js';
+
+/**
+ * The shell's sink for a fault no screen shows or that a developer must know of: a failed sync, a
+ * push token the server refused, a background task that threw. It goes to the core's handleError
+ * once a page has created one (the device log, Lowdefy Dev's error bar, and for a Lowdefy error the
+ * server log), and to the device console before then. Expected outcomes are not faults: no
+ * network, or a refusal the server answered as one (UserError, AuthenticationError, ...), are
+ * dropped.
+ *
+ * @param {Object} params
+ * @param {Error} params.error
+ * @param {{ getState }} [params.session] The app session whose core reports it; the open app's by
+ *   default (currentApp.js).
+ */
+function reportShellError({ error, session = peekCurrentApp()?.session }) {
+  if (isNetworkError(error) || isExpectedError(error)) {
+    return;
+  }
+  const handleError = session?.getState().lowdefy?._internal?.handleError;
+  if (handleError === undefined) {
+    console.error(error);
+    return;
+  }
+  Promise.resolve(handleError(error)).catch(() => console.error(error));
+}
+
+export default reportShellError;