@lowdefy/shell 3.23.2 → 7.2.0

package/src/plugins/types.js

@@ -0,0 +1,64 @@
+/*
+  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 actions from '@lowdefy/actions-core/actions';
+import * as blocks from '@lowdefy/blocks-native/blocks';
+import * as deviceActions from '@lowdefy/blocks-native/actions';
+import * as changeCaseOperators from '@lowdefy/operators-change-case/operators/client';
+import * as cronOperators from '@lowdefy/operators-cron/operators/client';
+import * as dayjsOperators from '@lowdefy/operators-dayjs/operators/client';
+import * as diffOperators from '@lowdefy/operators-diff/operators/client';
+import * as jsOperators from '@lowdefy/operators-js/operators/client';
+import * as jsonataOperators from '@lowdefy/operators-jsonata/operators/client';
+import * as mqlOperators from '@lowdefy/operators-mql/operators/client';
+import * as nunjucksOperators from '@lowdefy/operators-nunjucks/operators/client';
+import * as uuidOperators from '@lowdefy/operators-uuid/operators/client';
+import * as yamlOperators from '@lowdefy/operators-yaml/operators/client';
+import { Screen } from '@lowdefy/client-native';
+
+import nativeActions from '../actions/nativeActions.js';
+import appTypes from './appTypes.js';
+
+// The plugin maps the shell renders pages with. They hold the packages in shellPlugins.json and the
+// native types of the app's shell plugins (appTypes.js, from shell.json `plugins`), from which
+// scripts/createTypeManifest.mjs writes the type manifest pages are checked against
+// (typeManifest.js); a test keeps the two the same. The blocks are the whole native block set,
+// with the Screen page type from the native renderer (blocks-native carries only its meta). The
+// actions-core actions that reach the DOM on the web run native bodies under the same names, and
+// blocks-native's native-only actions (Haptic, Share, PickFile, ...) reach the phone through the
+// device the shell installs (src/device). The client operators are those of every default operator package,
+// as the build's mobile type map allows. icons is the icon data the native Icon renderer draws
+// from (client-native installs it as components.Icon over this map): each page carries the data
+// of its own icons (_icons) and PageScreen adds them here before the page renders.
+const types = {
+  actions: { ...actions, ...deviceActions, ...nativeActions, ...appTypes.actions },
+  blocks: { ...blocks, Screen, ...appTypes.blocks },
+  icons: {},
+  operators: {
+    ...jsOperators,
+    ...changeCaseOperators,
+    ...cronOperators,
+    ...dayjsOperators,
+    ...diffOperators,
+    ...jsonataOperators,
+    ...mqlOperators,
+    ...nunjucksOperators,
+    ...uuidOperators,
+    ...yamlOperators,
+  },
+};
+
+export default types;

package/src/plugins/types.test.js

@@ -0,0 +1,173 @@
+/*
+  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 { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import * as nativeBlocks from '@lowdefy/blocks-native/blocks';
+import { Screen } from '@lowdefy/client-native';
+
+import nativeActions from '../actions/nativeActions.js';
+import prefixTypes from './prefixTypes.js';
+import typeManifest from './typeManifest.js';
+import types from './types.js';
+
+const shellRoot = path.join(__dirname, '../..');
+
+function createTypeManifest(env = process.env) {
+  return JSON.parse(
+    execFileSync(process.execPath, [path.join(shellRoot, 'scripts/createTypeManifest.mjs')], {
+      encoding: 'utf8',
+      env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+  );
+}
+
+// The test shell plugin (fixtures/printer-plugin) installed as `lowdefy mobile config` installs it,
+// listed in a shell.json, and the types the shell registers with appTypes.js written for it.
+function withPrinterPlugin(plugin, callback) {
+  const directory = fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), 'lowdefy-shell-types-'));
+  try {
+    const nodeModules = path.join(directory, 'node_modules');
+    fs.mkdirSync(path.join(nodeModules, '@example'), { recursive: true });
+    fs.symlinkSync(
+      path.join(shellRoot, 'fixtures/printer-plugin'),
+      path.join(nodeModules, '@example/lowdefy-printer'),
+      'dir'
+    );
+    const devShell = JSON.parse(fs.readFileSync(path.join(shellRoot, 'shell.dev.json'), 'utf8'));
+    const configPath = path.join(directory, 'shell.json');
+    fs.writeFileSync(configPath, JSON.stringify({ ...devShell, plugins: [plugin] }));
+    let pluginTypes;
+    jest.isolateModules(() => {
+      jest.doMock('./appTypes.js', () => {
+        const native = jest.requireActual('../../fixtures/printer-plugin/native.js');
+        return {
+          __esModule: true,
+          default: {
+            actions: prefixTypes({ types: native.actions, typePrefix: plugin.typePrefix }),
+            blocks: prefixTypes({ types: native.blocks, typePrefix: plugin.typePrefix }),
+          },
+        };
+      });
+      pluginTypes = require('./types.js').default;
+    });
+    return callback({
+      env: { ...process.env, LOWDEFY_SHELL_CONFIG: configPath, NODE_PATH: nodeModules },
+      pluginTypes,
+    });
+  } finally {
+    fs.rmSync(directory, { recursive: true, force: true });
+  }
+}
+
+// The committed manifest the bundle carries must be the one shellPlugins.json and the plugin
+// packages make: run `pnpm --filter=@lowdefy/shell type-manifest` after changing either.
+test('src/plugins/typeManifest.js matches the manifest made from shellPlugins.json', () => {
+  expect(typeManifest).toEqual(createTypeManifest());
+});
+
+// The manifest pages are checked against must name exactly the types the shell registers.
+test('the type manifest lists every type the shell registers, and no other', () => {
+  ['actions', 'blocks', 'operators'].forEach((category) => {
+    expect(Object.keys(typeManifest[category]).sort()).toEqual(Object.keys(types[category]).sort());
+  });
+  expect(typeManifest.blocks.Box).toEqual({ package: '@lowdefy/blocks-native', version: 7 });
+  expect(typeManifest.blocks.Screen).toEqual({ package: '@lowdefy/blocks-native', version: 7 });
+  expect(typeManifest.blocks.TextInput).toEqual({ package: '@lowdefy/blocks-native', version: 7 });
+  expect(typeManifest.blocks.Markdown).toEqual({ package: '@lowdefy/blocks-native', version: 7 });
+  expect(typeManifest.actions.SetState.package).toBe('@lowdefy/actions-core');
+  expect(typeManifest.operators._state.package).toBe('@lowdefy/operators-js');
+});
+
+// The build's mobile type map allows the client operators of every default operator package.
+test('the shell registers the client operators of every default operator package', () => {
+  [
+    ['_change_case', 'change-case'],
+    ['_cron', 'cron'],
+    ['_dayjs', 'dayjs'],
+    ['_diff', 'diff'],
+    ['_jsonata', 'jsonata'],
+    ['_mql', 'mql'],
+    ['_nunjucks', 'nunjucks'],
+    ['_uuid', 'uuid'],
+    ['_yaml', 'yaml'],
+  ].forEach(([operator, name]) => {
+    expect(typeof types.operators[operator]).toBe('function');
+    expect(typeManifest.operators[operator].package).toBe(`@lowdefy/operators-${name}`);
+  });
+});
+
+test("the shell renders the whole native block set, with the native renderer's Screen", () => {
+  expect(Object.keys(types.blocks).sort()).toEqual([...Object.keys(nativeBlocks), 'Screen'].sort());
+  expect(types.blocks.Screen).toBe(Screen);
+  expect(types.blocks.Box).toBe(nativeBlocks.Box);
+});
+
+test('the DOM-bound actions-core actions run their native bodies under the same names', () => {
+  expect(types.actions.SetFocus).toBe(nativeActions.SetFocus);
+  expect(types.actions.ScrollTo).toBe(nativeActions.ScrollTo);
+  expect(types.actions.CopyToClipboard).toBe(nativeActions.CopyToClipboard);
+  expect(types.actions.GetLocalStorage).toBe(nativeActions.GetLocalStorage);
+  expect(types.actions.SetLocalStorage).toBe(nativeActions.SetLocalStorage);
+  expect(types.actions.RemoveLocalStorage).toBe(nativeActions.RemoveLocalStorage);
+  expect(types.actions.SetState).not.toBeUndefined();
+});
+
+test("a shell plugin's native types register and join the manifest, named with its typePrefix", () => {
+  withPrinterPlugin(
+    { name: '@example/lowdefy-printer', version: '2.1.0', typePrefix: 'Printer' },
+    ({ env, pluginTypes }) => {
+      const manifest = createTypeManifest(env);
+      ['actions', 'blocks', 'operators'].forEach((category) => {
+        expect(Object.keys(manifest[category]).sort()).toEqual(
+          Object.keys(pluginTypes[category]).sort()
+        );
+      });
+      const printer = { package: '@example/lowdefy-printer', version: 2 };
+      expect(manifest.blocks.PrinterLabel).toEqual(printer);
+      expect(manifest.blocks.PrinterTag).toEqual(printer);
+      expect(manifest.actions.PrinterPrint).toEqual(printer);
+      expect(manifest.blocks.Label).toBeUndefined();
+      expect(manifest.blocks.Tag).toEqual({ package: '@lowdefy/blocks-native', version: 7 });
+      // The registry jest.isolateModules loads them in is its own, so they are compared by what
+      // they do: the plugin's Label under its prefixed name, the built-in Tag kept.
+      expect(
+        pluginTypes.blocks.PrinterLabel({ blockId: 'label', properties: { text: 'A1' } })
+      ).toEqual({ type: 'PrinterLabel', blockId: 'label', text: 'A1' });
+      expect(pluginTypes.actions.PrinterPrint({ params: { text: 'A1' } })).toEqual({
+        printed: 'A1',
+      });
+      expect(pluginTypes.blocks.Tag.meta).toEqual(nativeBlocks.Tag.meta);
+    }
+  );
+});
+
+test('a shell plugin type named like a built-in one fails the manifest: use typePrefix', () => {
+  withPrinterPlugin({ name: '@example/lowdefy-printer', version: '2.1.0' }, ({ env }) => {
+    expect(() => createTypeManifest(env)).toThrow(
+      'Shell plugin "@example/lowdefy-printer" gives the block type "Tag", which "@lowdefy/blocks-native" already gives. Set a typePrefix on the plugin in mobile.shells[].plugins.'
+    );
+  });
+});
+
+test('appTypes.js ships empty, so a shell without plugins registers only the built-in types', () => {
+  const appTypes = jest.requireActual('./appTypes.js').default;
+  expect(appTypes).toEqual({ actions: {}, blocks: {} });
+});

package/src/polyfills/installGetRandomValues.js

@@ -0,0 +1,28 @@
+/*
+  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 { getRandomValues } from 'expo-crypto';
+
+// The _uuid operator's uuid package draws random ids from crypto.getRandomValues, which Hermes
+// does not have. expo-crypto fills it from the platform's secure random source.
+function installGetRandomValues() {
+  if (typeof globalThis.crypto?.getRandomValues === 'function') {
+    return;
+  }
+  globalThis.crypto = { ...globalThis.crypto, getRandomValues };
+}
+
+export default installGetRandomValues;

package/src/queue/createRequestQueue.js

@@ -0,0 +1,198 @@
+/*
+  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 { getAuthorizationHeaders } from '@lowdefy/client-core';
+
+import isNetworkError from '../host/isNetworkError.js';
+import readServerError from '../host/readServerError.js';
+import reportShellError from '../host/reportShellError.js';
+import summarizeQueue from './summarizeQueue.js';
+
+const QUEUED_MESSAGE = 'Queued until the phone is back online.';
+
+/**
+ * The offline request queue: the host's `requestQueue`, which `offline: queue` requests go through
+ * (@lowdefy/client-core createCallRequest).
+ *
+ * - A request is kept when the shell is offline, when the send fails for the network, or when
+ *   earlier requests still wait (order is kept). Its action resolves with { queued: true, id } as
+ *   the response. The body, with the payload evaluated when the action ran, is sent unchanged on
+ *   every try, so a `_uuid` in the payload is a stable idempotency key.
+ * - The queue sends in order, one at a time, when the shell comes back online, at launch and on
+ *   RetryRequestQueue. A 2xx removes the item. A network failure stops the replay and keeps it
+ *   pending. A 401 stops too: the session ended, and sign-out clears the queue. Any other answer
+ *   (a validation error, a 409 conflict, a 403) marks it failed with the server's message, kept
+ *   until RetryRequestQueue or DiscardQueuedRequest; the replay moves on. A request refused for
+ *   another build goes through the shell's fetch, which syncs and retries it when its page did not
+ *   change (createShellFetch).
+ * - Every change fires the app's onRequestQueue event with { pending, failed, sent, items }.
+ *
+ * @param {Object} params
+ * @param {string} params.appId
+ * @param {Function} params.fetch The shell's fetch (createShellFetch).
+ * @param {{ isOnline, subscribe }} params.networkStatus
+ * @param {() => string} params.newId Makes a queue item id.
+ * @param {Object} params.queueStore createSqliteQueueStore.
+ * @param {{ get }} params.tokenStore
+ * @param {Function} params.triggerAppEvent
+ */
+function createRequestQueue({
+  appId,
+  fetch,
+  networkStatus,
+  newId,
+  queueStore,
+  tokenStore,
+  triggerAppEvent,
+}) {
+  let replaying = null;
+
+  async function get() {
+    return summarizeQueue(await queueStore.list({ appId }));
+  }
+
+  async function announce({ sent = 0 } = {}) {
+    const summary = await get();
+    triggerAppEvent({ name: 'onRequestQueue', event: { ...summary, sent } });
+    return summary;
+  }
+
+  async function enqueue({ body, buildId, pageId, requestId, url }) {
+    const id = newId();
+    await queueStore.add({
+      appId,
+      item: { body, buildId, id, pageId, queuedAt: new Date().toISOString(), requestId, url },
+    });
+    await announce();
+    return { response: { queued: true, id, message: QUEUED_MESSAGE } };
+  }
+
+  // Sends one item. 'sent', 'failed', or 'stop' (no network, or the session ended).
+  async function sendItem(item) {
+    const headers = {
+      'Content-Type': 'application/json',
+      ...getAuthorizationHeaders({ host: { authTransport: 'bearer', tokenStore } }),
+    };
+    if (item.buildId !== null) {
+      headers['x-lowdefy-build'] = item.buildId;
+    }
+    let res;
+    try {
+      // keepBuild: the item's build is checked, not replaced by the build the shell holds now.
+      res = await fetch(item.url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(item.body),
+        keepBuild: true,
+      });
+    } catch (error) {
+      if (isNetworkError(error)) return 'stop';
+      throw error;
+    }
+    if (res.ok) {
+      await queueStore.remove({ id: item.id });
+      return 'sent';
+    }
+    if (res.status === 401) {
+      return 'stop';
+    }
+    await queueStore.update({
+      id: item.id,
+      status: 'failed',
+      error: (await readServerError({ res, message: `The server answered ${res.status}.` }))
+        .message,
+      attempts: item.attempts + 1,
+    });
+    return 'failed';
+  }
+
+  async function runReplay() {
+    let sent = 0;
+    let changed = false;
+    const items = await queueStore.list({ appId });
+    for (const item of items.filter((entry) => entry.status === 'pending')) {
+      if (!networkStatus.isOnline()) break;
+      const result = await sendItem(item);
+      if (result === 'stop') break;
+      changed = true;
+      if (result === 'sent') sent += 1;
+    }
+    if (changed) {
+      await announce({ sent });
+    }
+  }
+
+  // One replay at a time; a replay asked for while one runs waits for it.
+  function replay() {
+    if (replaying === null) {
+      replaying = runReplay().finally(() => {
+        replaying = null;
+      });
+    }
+    return replaying;
+  }
+
+  async function send({ body, buildId, pageId, requestId, send: sendNow, url }) {
+    const waiting = (await get()).pending > 0;
+    if (!networkStatus.isOnline() || waiting) {
+      const queued = await enqueue({ body, buildId, pageId, requestId, url });
+      if (networkStatus.isOnline()) replay();
+      return queued;
+    }
+    try {
+      return await sendNow();
+    } catch (error) {
+      if (!isNetworkError(error)) throw error;
+      return enqueue({ body, buildId, pageId, requestId, url });
+    }
+  }
+
+  async function retry({ id } = {}) {
+    const items = await queueStore.list({ appId });
+    for (const item of items) {
+      if (item.status === 'failed' && (id === undefined || item.id === id)) {
+        await queueStore.update({ id: item.id, status: 'pending', attempts: item.attempts });
+      }
+    }
+    await replay();
+    return announce();
+  }
+
+  async function discard({ failed, id } = {}) {
+    if (failed === true) {
+      await queueStore.removeFailed({ appId });
+    } else if (typeof id === 'string') {
+      await queueStore.remove({ id });
+    } else {
+      throw new Error('DiscardQueuedRequest requires "id", or "failed: true".');
+    }
+    return announce();
+  }
+
+  // Replays at launch and whenever the shell comes back online. Returns the function that stops it.
+  function start() {
+    // No action waits on these replays: a fault (a store that cannot be read) is reported.
+    const report = (error) => reportShellError({ error });
+    replay().catch(report);
+    return networkStatus.subscribe((online) => {
+      if (online) replay().catch(report);
+    });
+  }
+
+  return { discard, get, replay, retry, send, start };
+}
+
+export default createRequestQueue;

package/src/queue/createRequestQueue.test.js

@@ -0,0 +1,215 @@
+/*
+  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 createNetworkError from '../test/createNetworkError.js';
+import createRequestQueue from './createRequestQueue.js';
+
+function createMemoryQueueStore() {
+  let rows = [];
+  return {
+    async add({ appId, item }) {
+      rows.push({ ...item, appId, status: 'pending', error: null, attempts: 0 });
+    },
+    async list({ appId }) {
+      return rows.filter((row) => row.appId === appId).map((row) => ({ ...row }));
+    },
+    async update({ attempts, error = null, id, status }) {
+      rows = rows.map((row) => (row.id === id ? { ...row, attempts, error, status } : row));
+    },
+    async remove({ id }) {
+      rows = rows.filter((row) => row.id !== id);
+    },
+    async removeFailed({ appId }) {
+      rows = rows.filter((row) => !(row.appId === appId && row.status === 'failed'));
+    },
+    async removeApp({ appId }) {
+      rows = rows.filter((row) => row.appId !== appId);
+    },
+  };
+}
+
+function createNetwork(online) {
+  const listeners = new Set();
+  return {
+    isOnline: () => online,
+    set(next) {
+      online = next;
+      listeners.forEach((listener) => listener(online));
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}
+
+function response(status, body = {}) {
+  return { ok: status >= 200 && status < 300, status, json: async () => body };
+}
+
+function setup({ online = true, fetch = jest.fn(async () => response(200)) } = {}) {
+  let next = 0;
+  const networkStatus = createNetwork(online);
+  const triggerAppEvent = jest.fn();
+  const queue = createRequestQueue({
+    appId: 'acme',
+    fetch,
+    networkStatus,
+    newId: () => `q${(next += 1)}`,
+    queueStore: createMemoryQueueStore(),
+    tokenStore: { get: () => 'token' },
+    triggerAppEvent,
+  });
+  return { fetch, networkStatus, queue, triggerAppEvent };
+}
+
+const call = (requestId) => ({
+  body: { payload: { id: requestId } },
+  buildId: 'b1',
+  pageId: 'jobs',
+  requestId,
+  url: `https://acme.example.com/api/request/jobs/${requestId}`,
+});
+
+test('an offline request is kept and answers { queued: true, id }', async () => {
+  const { queue, triggerAppEvent } = setup({ online: false });
+  const send = jest.fn();
+  await expect(queue.send({ ...call('save'), send })).resolves.toEqual({
+    response: { queued: true, id: 'q1', message: 'Queued until the phone is back online.' },
+  });
+  expect(send).not.toHaveBeenCalled();
+  expect(triggerAppEvent).toHaveBeenCalledWith({
+    name: 'onRequestQueue',
+    event: expect.objectContaining({ pending: 1, failed: 0, sent: 0 }),
+  });
+});
+
+test('an online request sends at once, and is kept when the send fails for the network', async () => {
+  const { queue } = setup();
+  await expect(queue.send({ ...call('a'), send: async () => ({ response: 1 }) })).resolves.toEqual({
+    response: 1,
+  });
+  await expect(
+    queue.send({
+      ...call('b'),
+      send: async () => {
+        throw createNetworkError();
+      },
+    })
+  ).resolves.toEqual(
+    expect.objectContaining({ response: expect.objectContaining({ queued: true }) })
+  );
+  expect((await queue.get()).pending).toBe(1);
+});
+
+test('a fault in the send path is thrown, not queued as waiting for the network', async () => {
+  const { queue } = setup();
+  const fault = new TypeError("Cannot read properties of undefined (reading 'json')");
+  await expect(
+    queue.send({
+      ...call('b'),
+      send: async () => {
+        throw fault;
+      },
+    })
+  ).rejects.toBe(fault);
+  expect((await queue.get()).pending).toBe(0);
+});
+
+test('the queue replays in order when the phone comes back online, with the stored body and build', async () => {
+  const { fetch, networkStatus, queue, triggerAppEvent } = setup({ online: false });
+  await queue.send({ ...call('first'), send: jest.fn() });
+  await queue.send({ ...call('second'), send: jest.fn() });
+  queue.start();
+  networkStatus.set(true);
+  await queue.replay();
+  expect(fetch.mock.calls.map(([url]) => url)).toEqual([
+    'https://acme.example.com/api/request/jobs/first',
+    'https://acme.example.com/api/request/jobs/second',
+  ]);
+  expect(fetch.mock.calls[0][1].headers).toEqual(
+    expect.objectContaining({ Authorization: 'Bearer token', 'x-lowdefy-build': 'b1' })
+  );
+  // The shell's fetch keeps the queued build instead of stamping the current one.
+  expect(fetch.mock.calls[0][1].keepBuild).toBe(true);
+  expect(JSON.parse(fetch.mock.calls[0][1].body)).toEqual({ payload: { id: 'first' } });
+  expect(await queue.get()).toEqual({ pending: 0, failed: 0, items: [] });
+  expect(triggerAppEvent).toHaveBeenLastCalledWith({
+    name: 'onRequestQueue',
+    event: expect.objectContaining({ pending: 0, sent: 2 }),
+  });
+});
+
+test('a refused request is marked failed with the server message, and the replay moves on', async () => {
+  const fetch = jest
+    .fn()
+    .mockResolvedValueOnce(response(409, { message: 'The job was closed.' }))
+    .mockResolvedValueOnce(response(200));
+  const { networkStatus, queue } = setup({ online: false, fetch });
+  await queue.send({ ...call('close'), send: jest.fn() });
+  await queue.send({ ...call('note'), send: jest.fn() });
+  networkStatus.set(true);
+  await queue.replay();
+  const summary = await queue.get();
+  expect(summary.pending).toBe(0);
+  expect(summary.failed).toBe(1);
+  expect(summary.items[0]).toEqual(
+    expect.objectContaining({ requestId: 'close', status: 'failed', error: 'The job was closed.' })
+  );
+});
+
+test('a refused request keeps the message of the server error it carries', async () => {
+  const fetch = jest.fn().mockResolvedValueOnce(
+    response(400, {
+      '~e': { name: 'RequestError', message: 'The job is closed.', isLowdefyError: true },
+    })
+  );
+  const { networkStatus, queue } = setup({ online: false, fetch });
+  await queue.send({ ...call('close'), send: jest.fn() });
+  networkStatus.set(true);
+  await queue.replay();
+  expect((await queue.get()).items[0]).toEqual(
+    expect.objectContaining({ status: 'failed', error: 'The job is closed.' })
+  );
+});
+
+test('a network failure during the replay stops it and keeps the request pending', async () => {
+  const fetch = jest.fn(async () => {
+    throw createNetworkError();
+  });
+  const { networkStatus, queue } = setup({ online: false, fetch });
+  await queue.send({ ...call('save'), send: jest.fn() });
+  networkStatus.set(true);
+  await queue.replay();
+  expect((await queue.get()).pending).toBe(1);
+});
+
+test('retry sends failed requests again, and discard removes them', async () => {
+  const fetch = jest.fn().mockResolvedValue(response(400, { message: 'Bad' }));
+  const { networkStatus, queue } = setup({ online: false, fetch });
+  await queue.send({ ...call('save'), send: jest.fn() });
+  networkStatus.set(true);
+  await queue.replay();
+  expect((await queue.get()).failed).toBe(1);
+  fetch.mockResolvedValue(response(200));
+  await expect(queue.retry({ id: 'q1' })).resolves.toEqual({ pending: 0, failed: 0, items: [] });
+  await queue.send({ ...call('again'), send: async () => response(200) });
+  await expect(queue.discard({})).rejects.toThrow(
+    'DiscardQueuedRequest requires "id", or "failed: true".'
+  );
+});