@lowdefy/server-dev 6.1.0 → 7.0.0

package/lib/docs/observe/evaluateInvariants.js

@@ -0,0 +1,183 @@
+/*
+  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 { expectedErrorNames } from '@lowdefy/errors';
+import { type } from '@lowdefy/helpers';
+import { getStepKey } from '@lowdefy/node-utils';
+
+import findingKey from './findingKey.js';
+import hasNoEffect from './hasNoEffect.js';
+import parseAppApiUrl from './parseAppApiUrl.js';
+import relativeSource from './relativeSource.js';
+
+const SEVERITY = {
+  'action-error': 'error',
+  'client-error': 'error',
+  'server-error': 'error',
+  'request-failed': 'error',
+  'dead-click': 'warning',
+  environment: 'info',
+};
+
+function describeTarget(target) {
+  const parts = [target.blockId ?? 'control'];
+  if (!type.isNone(target.text)) parts.push(`"${target.text}"`);
+  if (!type.isNone(target.row)) parts.push(`row ${target.row}`);
+  return parts.join(' ');
+}
+
+function isExplained({ response, serverEntries, basePath }) {
+  const called = parseAppApiUrl({ url: response.url, basePath });
+  return serverEntries.some(
+    (entry) =>
+      (!type.isNone(called?.requestId) &&
+        entry.requestId === called.requestId &&
+        entry.pageId === called.pageId) ||
+      (!type.isNone(called?.endpointId) && entry.endpointId === called.endpointId)
+  );
+}
+
+function isDeadClick({ step, result, window }) {
+  return !type.isUndefined(step.click) && result.status === 'ok' && hasNoEffect({ window });
+}
+
+// The fixed checks that decide whether a journey step broke something, over what
+// the step's window produced for this run only:
+//   action-error    an event failed with an error that is not an expected
+//                   outcome: a failed Validate (a UserError) or an auth gate's
+//                   401 or 403 refusal is the app doing its job
+//   client-error    an uncaught page error, or a client error entry this run
+//                   caused
+//   server-error    a server error entry this run caused
+//   request-failed  a 5xx from the app's request or endpoint routes that no
+//                   server error entry in the window explains
+//   dead-click      a click that succeeded and changed nothing: no event, no
+//                   lasting DOM change, no app request, no URL change
+//   environment     a server error from a request using a $search or
+//                   $vectorSearch stage, which the data set's memory store
+//                   cannot run: not the app's fault
+// window: { emits, mutationCount (null when the document was replaced),
+// urlBefore, urlAfter, pageErrors, requests, responses, errors (run-claimed
+// error entries, each with store 'client' or 'server') }. usesSearchStage
+// (entry) and resolveSource(configKey) read the dev server's build. Sources
+// are made relative to configDirectory. Returns findings { kind, severity,
+// message, pageId, source, configKey, key }, one per key.
+// The browser's TypeError for a fetch that did not complete, in each engine.
+const FETCH_FAILURE =
+  /^(TypeError: )?(Failed to fetch|NetworkError when attempting to fetch|Load failed)/;
+
+// A goto replaces the page, and the browser aborts the requests the page left
+// behind had in flight; the page reports each as a failed fetch. That is the
+// runner's own navigation, not an app error, so a goto step's fetch failures
+// are dropped when the window also saw the browser abort a request. A failed
+// fetch with no aborted request, or in any other step, is still an error.
+function isCausedByGoto({ step, window, message }) {
+  return (
+    getStepKey(step ?? {}) === 'goto' &&
+    (window.abortedRequests ?? []).length > 0 &&
+    FETCH_FAILURE.test(message ?? '')
+  );
+}
+
+async function evaluateInvariants({
+  step,
+  result,
+  window,
+  pageId,
+  basePath = '',
+  configDirectory,
+  usesSearchStage,
+  resolveSource,
+}) {
+  let findings = [];
+  function add({ kind, message, source = null, configKey = null }) {
+    findings.push({
+      kind,
+      severity: SEVERITY[kind],
+      message,
+      pageId,
+      source: relativeSource({ source, configDirectory }),
+      configKey,
+    });
+  }
+
+  for (const emit of window.emits) {
+    if (emit.success !== false || expectedErrorNames.has(emit.failure?.errorName)) continue;
+    const { actionId, actionType, configKey, errorName } = emit.failure ?? {};
+    add({
+      kind: 'action-error',
+      message: `${actionType ?? 'An action'} "${actionId ?? 'unknown'}" failed in ${emit.blockId}.${
+        emit.eventName
+      } with ${errorName ?? 'an error'}.`,
+      configKey: configKey ?? null,
+      source: type.isNone(configKey) ? null : await resolveSource(configKey),
+    });
+  }
+
+  const clientEntries = window.errors
+    .filter((entry) => entry.store === 'client')
+    .filter((entry) => !isCausedByGoto({ step, window, message: entry.message ?? entry.name }));
+  const serverEntries = window.errors.filter((entry) => entry.store === 'server');
+  clientEntries.forEach((entry) => {
+    add({ kind: 'client-error', message: entry.message ?? entry.name, source: entry.source });
+  });
+  window.pageErrors
+    .filter((pageError) => !isCausedByGoto({ step, window, message: pageError.message }))
+    .filter((pageError) => !clientEntries.some((entry) => entry.message === pageError.message))
+    .forEach((pageError) => {
+      add({ kind: 'client-error', message: `${pageError.name}: ${pageError.message}` });
+    });
+  serverEntries.forEach((entry) => {
+    add({
+      kind: usesSearchStage(entry) ? 'environment' : 'server-error',
+      message: entry.message ?? entry.name,
+      source: entry.source,
+    });
+  });
+  window.responses
+    .filter((response) => response.status >= 500)
+    .filter((response) => !isExplained({ response, serverEntries, basePath }))
+    .forEach((response) => {
+      add({
+        kind: 'request-failed',
+        message: `${response.method} ${new URL(response.url).pathname} answered ${
+          response.status
+        }.`,
+      });
+    });
+  if (isDeadClick({ step, result, window })) {
+    add({
+      kind: 'dead-click',
+      message: `Clicking ${describeTarget(
+        step.click
+      )} did nothing: no event ran, the page did not change and no request was sent.`,
+    });
+  }
+
+  if (findings.some((finding) => finding.kind === 'environment')) {
+    findings = findings.filter((finding) => finding.kind === 'environment');
+  }
+  const seen = new Set();
+  return findings
+    .map((finding) => ({ ...finding, key: findingKey(finding) }))
+    .filter((finding) => {
+      if (seen.has(finding.key)) return false;
+      seen.add(finding.key);
+      return true;
+    });
+}
+
+export default evaluateInvariants;

package/lib/docs/observe/evaluateInvariants.test.mjs

@@ -0,0 +1,299 @@
+/*
+  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 evaluateInvariants from './evaluateInvariants.js';
+
+const origin = 'http://localhost:3111';
+
+function quietWindow(overrides = {}) {
+  return {
+    urlBefore: `${origin}/tickets`,
+    urlAfter: `${origin}/tickets`,
+    emits: [],
+    mutationCount: 0,
+    pageErrors: [],
+    requests: [],
+    responses: [],
+    errors: [],
+    ...overrides,
+  };
+}
+
+function evaluate({
+  step = { click: { blockId: 'assign_button' } },
+  result,
+  window,
+  search = false,
+}) {
+  return evaluateInvariants({
+    step,
+    result: result ?? { status: 'ok' },
+    window,
+    pageId: 'tickets',
+    usesSearchStage: () => search,
+    resolveSource: async (configKey) => (configKey === 'k1' ? 'pages/tickets.yaml:88' : null),
+  });
+}
+
+function failedEmit(errorName, extra = {}) {
+  return {
+    blockId: 'assign_button',
+    eventName: 'onClick',
+    success: false,
+    failure: { actionId: 'assign', actionType: 'CallAPI', configKey: 'k1', errorName, ...extra },
+  };
+}
+
+test('a failed event with an error that is not a UserError is an action-error located through its config key', async () => {
+  const findings = await evaluate({
+    window: quietWindow({ emits: [failedEmit('RequestError')], mutationCount: 3 }),
+  });
+  expect(findings).toEqual([
+    {
+      kind: 'action-error',
+      severity: 'error',
+      message: 'CallAPI "assign" failed in assign_button.onClick with RequestError.',
+      pageId: 'tickets',
+      source: 'pages/tickets.yaml:88',
+      configKey: 'k1',
+      key: 'action-error|tickets|pages/tickets.yaml:88',
+    },
+  ]);
+});
+
+test('a failed Validate (a UserError) is not a finding, and its click is not dead', async () => {
+  const findings = await evaluate({
+    window: quietWindow({ emits: [failedEmit('UserError', { actionType: 'Validate' })] }),
+  });
+  expect(findings).toEqual([]);
+});
+
+test.each(['AuthenticationError', 'AuthorizationError', 'TwoFactorEnrolmentRequiredError'])(
+  'a CallAPI an auth gate refused (%s) is not a finding, and its click is not dead',
+  async (errorName) => {
+    const findings = await evaluate({
+      window: quietWindow({
+        emits: [failedEmit(errorName)],
+        requests: [{ method: 'POST', url: `${origin}/api/endpoints/assign` }],
+        responses: [
+          {
+            method: 'POST',
+            url: `${origin}/api/endpoints/assign`,
+            status: errorName === 'AuthenticationError' ? 401 : 403,
+          },
+        ],
+      }),
+    });
+    expect(findings).toEqual([]);
+  }
+);
+
+test('client error entries and uncaught page errors are client-errors; a page error the entry already reports is not repeated', async () => {
+  const findings = await evaluate({
+    window: quietWindow({
+      mutationCount: 1,
+      errors: [
+        {
+          store: 'client',
+          name: 'OperatorError',
+          message: 'Ticket boom',
+          source: 'pages/tickets.yaml:12',
+        },
+      ],
+      pageErrors: [
+        { name: 'Error', message: 'Ticket boom' },
+        { name: 'TypeError', message: 'x is undefined' },
+      ],
+    }),
+  });
+  expect(findings.map(({ kind, message, source }) => [kind, message, source])).toEqual([
+    ['client-error', 'Ticket boom', 'pages/tickets.yaml:12'],
+    ['client-error', 'TypeError: x is undefined', null],
+  ]);
+});
+
+test('a window with an environment finding reports only that, not the failed action or 5xx it caused', async () => {
+  const response = { url: `${origin}/api/request/tickets/search`, method: 'POST', status: 500 };
+  const findings = await evaluate({
+    search: true,
+    window: quietWindow({
+      emits: [failedEmit('ServiceError', { actionType: 'Request' })],
+      requests: [response],
+      responses: [response],
+      errors: [{ store: 'server', message: 'Atlas only', pageId: 'other', requestId: 'x' }],
+    }),
+  });
+  expect(findings.map((finding) => finding.kind)).toEqual(['environment']);
+});
+
+test('an absolute source is made relative to the config directory', async () => {
+  const findings = await evaluateInvariants({
+    step: { click: { blockId: 'a' } },
+    result: { status: 'ok' },
+    window: quietWindow({
+      mutationCount: 1,
+      errors: [{ store: 'server', message: 'Boom', source: '/apps/crm/pages/tickets.yaml:30' }],
+    }),
+    pageId: 'tickets',
+    configDirectory: '/apps/crm',
+    usesSearchStage: () => false,
+    resolveSource: async () => null,
+  });
+  expect(findings[0].source).toBe('pages/tickets.yaml:30');
+  expect(findings[0].key).toBe('server-error|tickets|pages/tickets.yaml:30');
+});
+
+test('a server error entry is a server-error, or environment when its request uses a search stage', async () => {
+  const window = quietWindow({
+    mutationCount: 1,
+    errors: [{ store: 'server', message: 'Unrecognized stage', source: 'pages/tickets.yaml:30' }],
+  });
+  expect((await evaluate({ window })).map((finding) => [finding.kind, finding.severity])).toEqual([
+    ['server-error', 'error'],
+  ]);
+  expect(
+    (await evaluate({ window, search: true })).map((finding) => [finding.kind, finding.severity])
+  ).toEqual([['environment', 'info']]);
+});
+
+test('a 5xx from an app route is request-failed unless a server error entry for that request explains it', async () => {
+  const response = {
+    url: `${origin}/api/endpoints/assign_ticket`,
+    method: 'POST',
+    status: 500,
+  };
+  const unexplained = await evaluate({
+    window: quietWindow({ requests: [response], responses: [response] }),
+  });
+  expect(unexplained).toEqual([
+    expect.objectContaining({
+      kind: 'request-failed',
+      message: 'POST /api/endpoints/assign_ticket answered 500.',
+    }),
+  ]);
+  const explained = await evaluate({
+    window: quietWindow({
+      requests: [response],
+      responses: [response],
+      errors: [{ store: 'server', message: 'Boom', endpointId: 'assign_ticket', source: null }],
+    }),
+  });
+  expect(explained.map((finding) => finding.kind)).toEqual(['server-error']);
+  const request = {
+    url: `${origin}/api/request/tickets/close_ticket`,
+    method: 'POST',
+    status: 502,
+  };
+  const explainedRequest = await evaluate({
+    window: quietWindow({
+      requests: [request],
+      responses: [request],
+      errors: [{ store: 'server', message: 'Down', pageId: 'tickets', requestId: 'close_ticket' }],
+    }),
+  });
+  expect(explainedRequest.map((finding) => finding.kind)).toEqual(['server-error']);
+});
+
+test('a successful click with no event, no lasting mutation, no app request and no URL change is a dead-click warning', async () => {
+  const findings = await evaluate({ window: quietWindow() });
+  expect(findings).toEqual([
+    expect.objectContaining({
+      kind: 'dead-click',
+      severity: 'warning',
+      message:
+        'Clicking assign_button did nothing: no event ran, the page did not change and no request was sent.',
+    }),
+  ]);
+});
+
+test('a click is not dead when an event ran, the DOM changed, a request went out, the URL changed, the document was replaced or the step failed', async () => {
+  const lively = [
+    quietWindow({ emits: [{ blockId: 'a', eventName: 'onClick', success: true }] }),
+    quietWindow({ mutationCount: 1 }),
+    quietWindow({ requests: [{ url: `${origin}/api/request/tickets/x` }] }),
+    quietWindow({ urlAfter: `${origin}/ticket` }),
+    quietWindow({ mutationCount: null }),
+  ];
+  for (const window of lively) {
+    expect(await evaluate({ window })).toEqual([]);
+  }
+  expect(await evaluate({ window: quietWindow(), result: { status: 'failed' } })).toEqual([]);
+  expect(
+    await evaluate({ window: quietWindow(), step: { fill: { blockId: 'title', value: 'x' } } })
+  ).toEqual([]);
+});
+
+test('findings with the same key in one window are reported once', async () => {
+  const findings = await evaluate({
+    window: quietWindow({
+      mutationCount: 1,
+      errors: [
+        { store: 'server', message: 'Boom', source: 'pages/tickets.yaml:30' },
+        { store: 'server', message: 'Boom again', source: 'pages/tickets.yaml:30' },
+      ],
+    }),
+  });
+  expect(findings).toHaveLength(1);
+});
+
+describe('a fetch failure the runner caused by navigating away', () => {
+  const failedFetch = {
+    store: 'client',
+    name: 'TypeError',
+    message: 'Failed to fetch at onboarding-step-2.',
+    source: null,
+  };
+  const aborted = [{ time: 1, url: `${origin}/api/request/step/get_header` }];
+
+  test('a goto step that aborted requests in flight does not fail on the page reporting them', async () => {
+    const findings = await evaluate({
+      step: { goto: 'onboarding-step-connect' },
+      window: quietWindow({
+        errors: [failedFetch],
+        pageErrors: [{ name: 'TypeError', message: 'Failed to fetch' }],
+        abortedRequests: aborted,
+      }),
+    });
+    expect(findings).toEqual([]);
+  });
+
+  test('a failed fetch outside a goto is still a client-error, aborted requests or not', async () => {
+    const findings = await evaluate({
+      step: { click: { blockId: 'next_button' } },
+      window: quietWindow({ mutationCount: 1, errors: [failedFetch], abortedRequests: aborted }),
+    });
+    expect(findings.map(({ kind }) => kind)).toEqual(['client-error']);
+  });
+
+  test('a failed fetch in a goto that aborted nothing is still a client-error', async () => {
+    const findings = await evaluate({
+      step: { goto: 'onboarding-step-connect' },
+      window: quietWindow({ errors: [failedFetch] }),
+    });
+    expect(findings.map(({ kind }) => kind)).toEqual(['client-error']);
+  });
+
+  test('another error in a goto that aborted requests still fails the step', async () => {
+    const findings = await evaluate({
+      step: { goto: 'onboarding-step-connect' },
+      window: quietWindow({
+        errors: [failedFetch, { store: 'client', name: 'OperatorError', message: 'Ticket boom' }],
+        abortedRequests: aborted,
+      }),
+    });
+    expect(findings.map(({ message }) => message)).toEqual(['Ticket boom']);
+  });
+});

package/lib/docs/observe/findingKey.js

@@ -0,0 +1,29 @@
+/*
+  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 crypto from 'node:crypto';
+
+// One finding per (kind, page, source location), or per message when there
+// is no location: a journey's app errors are reported, and compared across
+// runs, by it.
+function findingKey({ kind, pageId, source, message }) {
+  const where =
+    source ??
+    `message:${crypto.createHash('sha1').update(String(message)).digest('hex').slice(0, 8)}`;
+  return [kind, pageId ?? '', where].join('|');
+}
+
+export default findingKey;

package/lib/docs/observe/hasNoEffect.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.
+*/
+
+// Whether a step's window shows the step did nothing: no event ran, no lasting
+// DOM change (a mutationCount of null means the document was replaced), no
+// request to the app's request or endpoint routes (the window holds only
+// those) and the URL is unchanged. The dead-click invariant and the journey
+// runner's expect.effect both read it, so the two cannot drift.
+function hasNoEffect({ window }) {
+  return (
+    window.emits.length === 0 &&
+    window.mutationCount === 0 &&
+    window.requests.length === 0 &&
+    window.urlBefore === window.urlAfter
+  );
+}
+
+export default hasNoEffect;

package/lib/docs/observe/hasNoEffect.test.mjs

@@ -0,0 +1,37 @@
+/*
+  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 hasNoEffect from './hasNoEffect.js';
+
+const url = 'http://localhost:3227/orders';
+
+function windowWith(overrides) {
+  return { emits: [], mutationCount: 0, requests: [], urlBefore: url, urlAfter: url, ...overrides };
+}
+
+test('hasNoEffect is true when the window holds no event, DOM change, app request or URL change', () => {
+  expect(hasNoEffect({ window: windowWith({}) })).toBe(true);
+});
+
+test.each([
+  ['an event', { emits: [{ blockId: 'save', eventName: 'onClick', success: true }] }],
+  ['a DOM change', { mutationCount: 2 }],
+  ['a replaced document', { mutationCount: null }],
+  ['an app request', { requests: [{ url: 'http://localhost:3227/api/request/orders/load' }] }],
+  ['a URL change', { urlAfter: 'http://localhost:3227/second' }],
+])('hasNoEffect is false when the window holds %s', (_, overrides) => {
+  expect(hasNoEffect({ window: windowWith(overrides) })).toBe(false);
+});

package/lib/docs/observe/installStepObserver.js

@@ -0,0 +1,72 @@
+/*
+  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.
+*/
+
+// Serialized into the journey's page by page.evaluate, so this function must be
+// pure: it may reference nothing but `window`, `document` and its argument.
+//
+// Opens a step's window in the page. Installed once per document (a
+// full page load replaces it, so each step installs it again if needed): it
+// subscribes to the engine's trace registry and keeps each completed event's
+// value-free summary, and records the nodes DOM mutations added or changed
+// under document.body. Only what happens while a window is open is kept.
+// Throws when the page has no trace registry: a step's window never guesses.
+function installStepObserver() {
+  const lowdefy = window.lowdefy;
+  if (!lowdefy || !lowdefy._trace || typeof lowdefy._trace.subscribe !== 'function') {
+    throw new Error(
+      'The page has no Lowdefy trace registry (window.lowdefy._trace), so its events cannot be observed. Restart the dev server so pages load the current client.'
+    );
+  }
+  let observer = window.__lowdefyStepObserver;
+  if (!observer) {
+    observer = { open: false, emits: [], nodes: [] };
+    lowdefy._trace.subscribe((payload) => {
+      if (!observer.open) return;
+      observer.emits.push({
+        scope: payload.scope ?? null,
+        pageId: payload.pageId ?? null,
+        blockId: payload.blockId ?? null,
+        blockType: payload.blockType ?? null,
+        eventName: payload.eventName ?? null,
+        success: payload.success,
+        failure: payload.failure ?? null,
+      });
+    });
+    const mutations = new MutationObserver((records) => {
+      if (!observer.open) return;
+      records.forEach((record) => {
+        if (record.type === 'childList') {
+          record.addedNodes.forEach((node) => observer.nodes.push(node));
+          return;
+        }
+        observer.nodes.push(record.target);
+      });
+    });
+    mutations.observe(document.body, {
+      childList: true,
+      attributes: true,
+      characterData: true,
+      subtree: true,
+    });
+    window.__lowdefyStepObserver = observer;
+  }
+  observer.emits = [];
+  observer.nodes = [];
+  observer.open = true;
+  return true;
+}
+
+export default installStepObserver;

package/lib/docs/observe/isAppApiUrl.js

@@ -0,0 +1,33 @@
+/*
+  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.
+*/
+
+const APP_API_PREFIXES = ['/api/request/', '/api/endpoints/'];
+
+// Whether a URL is one of the app's request or endpoint API routes on this
+// dev server: what a journey step counts as the app doing work, and where a 5xx
+// is a failed request.
+function isAppApiUrl({ url, origin, basePath = '' }) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return false;
+  }
+  if (parsed.origin !== origin) return false;
+  return APP_API_PREFIXES.some((prefix) => parsed.pathname.startsWith(`${basePath}${prefix}`));
+}
+
+export default isAppApiUrl;