@lowdefy/server-dev 6.1.0 → 7.1.0

package/lib/docs/rails/findExternalBlocks.test.mjs

@@ -0,0 +1,254 @@
+/*
+  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 fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import findExternalBlocks from './findExternalBlocks.js';
+
+let buildDirectory;
+
+const connections = {
+  MongoDBCollection: { meta: { tenant: true, dataSet: 'redirect' } },
+  AxiosHttp: { meta: { dataSet: 'external' } },
+  FolderRuntime: { meta: { dataSet: 'redirect' } },
+  WalledRuntime: {
+    meta: { tenant: false, dataSet: 'walled' },
+    // A request type that declares external is sunk, so the walled connection stays clickable.
+    requests: { Fetch: Object.assign(() => null, { meta: { dataSet: 'external' } }) },
+  },
+  Knex: {},
+  PluginStore: { meta: { dataSet: 'mongo' } },
+};
+
+function write(name, value) {
+  const filePath = path.join(buildDirectory, name);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(value));
+}
+
+function onClick(...actions) {
+  return { onClick: { try: { '~arr': actions }, catch: { '~arr': [] } } };
+}
+
+function block(blockId, events, blocks) {
+  return {
+    id: `block:tickets:${blockId}:0`,
+    blockId,
+    type: 'Button',
+    events,
+    ...(blocks ? { slots: { content: { blocks: { '~arr': blocks } } } } : {}),
+    '~k': blockId,
+  };
+}
+
+beforeEach(() => {
+  buildDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-rails-external-'));
+  write('pages/tickets.json', {
+    id: 'page:tickets',
+    pageId: 'tickets',
+    blockId: 'tickets',
+    events: { onMount: { try: [{ id: 'all', type: 'Request', params: { all: true } }] } },
+    requests: {
+      '~arr': [
+        { requestId: 'get_tickets' },
+        { requestId: 'send_mail' },
+        { requestId: 'post_hook' },
+      ],
+    },
+    slots: {
+      content: {
+        blocks: {
+          '~arr': [
+            block('refresh', onClick({ id: 'r', type: 'Request', params: 'get_tickets' })),
+            block(
+              'invite',
+              onClick({ id: 'r', type: 'Request', params: ['get_tickets', 'send_mail'] })
+            ),
+            block(
+              'hook',
+              onClick({ id: 'r', type: 'Request', params: { requestId: 'post_hook' } })
+            ),
+            block('all', onClick({ id: 'r', type: 'Request', params: { all: true } })),
+            block('card', {}, [
+              block(
+                'assign',
+                onClick({ id: 'c', type: 'CallAPI', params: { endpointId: 'assign' } })
+              ),
+              block('save', onClick({ id: 'c', type: 'CallAPI', params: { endpointId: 'save' } })),
+              block(
+                'ghost',
+                onClick({ id: 'c', type: 'CallAPI', params: { endpointId: 'missing' } })
+              ),
+              block(
+                'dynamic',
+                onClick({ id: 'c', type: 'CallAPI', params: { endpointId: { _state: 'id' } } })
+              ),
+            ]),
+            block('accept', onClick({ id: 'r', type: 'Request', params: 'accept_match' })),
+            block('archive', onClick({ id: 'r', type: 'Request', params: 'move_folder' })),
+            block('report', onClick({ id: 'r', type: 'Request', params: 'run_sql' })),
+            block('stash', onClick({ id: 'r', type: 'Request', params: 'store_row' })),
+            block('orphan', onClick({ id: 'r', type: 'Request', params: 'orphan' })),
+            block('sign_out', onClick({ id: 'l', type: 'Logout' })),
+            block('change_password', {
+              onSubmit: { try: [], catch: [{ id: 'p', type: 'ChangePassword' }] },
+            }),
+          ],
+        },
+      },
+    },
+  });
+  write('pages/tickets/requests/get_tickets.json', {
+    requestId: 'get_tickets',
+    connectionId: 'tickets_db',
+  });
+  write('pages/tickets/requests/send_mail.json', {
+    requestId: 'send_mail',
+    connectionId: 'mailer',
+  });
+  write('pages/tickets/requests/post_hook.json', {
+    requestId: 'post_hook',
+    connectionId: 'webhook',
+  });
+  write('pages/tickets/requests/accept_match.json', {
+    requestId: 'accept_match',
+    connectionId: 'runtime',
+  });
+  write('pages/tickets/requests/move_folder.json', {
+    requestId: 'move_folder',
+    connectionId: 'folders',
+  });
+  write('pages/tickets/requests/run_sql.json', { requestId: 'run_sql', connectionId: 'sql' });
+  write('pages/tickets/requests/store_row.json', { requestId: 'store_row', connectionId: 'store' });
+  write('pages/tickets/requests/orphan.json', { requestId: 'orphan', connectionId: 'gone' });
+  write('api/assign.json', {
+    endpointId: 'assign',
+    routine: {
+      '~arr': [
+        {
+          id: 'request:assign:update',
+          type: 'MongoDBUpdateOne',
+          stepId: 'update',
+          connectionId: 'tickets_db',
+        },
+        {
+          ':if': true,
+          ':then': [
+            {
+              id: 'endpoint:assign:n',
+              type: 'CallApi',
+              stepId: 'n',
+              properties: { endpointId: 'notify' },
+            },
+          ],
+        },
+      ],
+    },
+  });
+  write('api/notify.json', {
+    endpointId: 'notify',
+    routine: [
+      { id: 'request:notify:send', type: 'AxiosHttp', stepId: 'send', connectionId: 'mailer' },
+      {
+        id: 'endpoint:notify:a',
+        type: 'CallApi',
+        stepId: 'a',
+        properties: { endpointId: 'assign' },
+      },
+    ],
+  });
+  write('api/save.json', {
+    endpointId: 'save',
+    routine: [
+      { id: 'request:save:s', type: 'MongoDBInsertOne', stepId: 's', connectionId: 'tickets_db' },
+    ],
+  });
+  write('connections/tickets_db.json', { connectionId: 'tickets_db', type: 'MongoDBCollection' });
+  write('connections/mailer.json', { connectionId: 'mailer', type: 'AxiosHttp' });
+  write('connections/webhook.json', { connectionId: 'webhook', type: 'AxiosHttp' });
+  write('connections/runtime.json', { connectionId: 'runtime', type: 'WalledRuntime' });
+  write('connections/folders.json', { connectionId: 'folders', type: 'FolderRuntime' });
+  write('connections/sql.json', { connectionId: 'sql', type: 'Knex' });
+  write('connections/store.json', { connectionId: 'store', type: 'PluginStore' });
+});
+
+afterEach(() => {
+  fs.rmSync(buildDirectory, { recursive: true, force: true });
+});
+
+const mailer = { connectionId: 'mailer', type: 'AxiosHttp', dataSet: 'external' };
+const webhook = { connectionId: 'webhook', type: 'AxiosHttp', dataSet: 'external' };
+
+test('findExternalBlocks lists blocks whose events reach a connection declaring external, nothing, or with no artifact', () => {
+  expect(findExternalBlocks({ buildDirectory, pageId: 'tickets', connections })).toEqual({
+    blocks: {
+      invite: [mailer],
+      hook: [webhook],
+      all: [mailer, webhook],
+      assign: [mailer],
+      report: [{ connectionId: 'sql', type: 'Knex', dataSet: null }],
+      stash: [{ connectionId: 'store', type: 'PluginStore', dataSet: 'mongo' }],
+      orphan: [{ connectionId: 'gone', type: null, dataSet: null }],
+    },
+  });
+});
+
+test('findExternalBlocks lets a block reach plugin types that declare redirect or walled', () => {
+  const { blocks } = findExternalBlocks({ buildDirectory, pageId: 'tickets', connections });
+  expect(blocks.accept).toBeUndefined();
+  expect(blocks.archive).toBeUndefined();
+  expect(blocks.refresh).toBeUndefined();
+  expect(blocks.save).toBeUndefined();
+});
+
+test('findExternalBlocks refuses MongoDBCollection when the connection map does not declare it', () => {
+  const { MongoDBCollection, ...withoutMongo } = connections;
+  const { blocks } = findExternalBlocks({
+    buildDirectory,
+    pageId: 'tickets',
+    connections: withoutMongo,
+  });
+  const ticketsDb = { connectionId: 'tickets_db', type: 'MongoDBCollection', dataSet: null };
+  expect(blocks.refresh).toEqual([ticketsDb]);
+  expect(blocks.save).toEqual([ticketsDb]);
+  expect(blocks.assign).toEqual([mailer, ticketsDb]);
+});
+
+test('findExternalBlocks throws for a page with no build artifact', () => {
+  expect(() => findExternalBlocks({ buildDirectory, pageId: 'missing', connections })).toThrow(
+    `Page "missing" has no build artifact in ${buildDirectory}.`
+  );
+});
+
+test('findExternalBlocks lets a block reach an external type with request resolvers, which a data session sinks', () => {
+  const sinkable = {
+    ...connections,
+    AxiosHttp: { ...connections.AxiosHttp, requests: { AxiosHttp: () => {} } },
+  };
+  const { blocks } = findExternalBlocks({
+    buildDirectory,
+    pageId: 'tickets',
+    connections: sinkable,
+  });
+  expect(blocks.invite).toBeUndefined();
+  expect(blocks.hook).toBeUndefined();
+  expect(blocks.all).toBeUndefined();
+  expect(blocks.assign).toBeUndefined();
+  // An undeclared type is still refused.
+  expect(blocks.report).toEqual([{ connectionId: 'sql', type: 'Knex', dataSet: null }]);
+});

package/lib/docs/rails/installAuthActionRecorder.js

@@ -0,0 +1,56 @@
+/*
+  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` and its argument.
+//
+// Starts recording the auth-engine actions the page executes. Every
+// lowdefy._internal.auth method in `methods` is wrapped, once per document, to
+// note its name in sessionStorage before it calls through: the engine's action
+// methods look the method up on that object at call time, so a skipped action
+// never reaches it and an executed one always does. sessionStorage, not a
+// window variable, so a call that navigates (a sign-in) is still there to read
+// from the next document. Clears what an earlier step recorded. Returns false
+// when the page has no auth methods to wrap.
+function installAuthActionRecorder({ key, methods }) {
+  const auth = window.lowdefy?._internal?.auth;
+  if (!auth) return false;
+  if (!auth.__lowdefyAuthRecorder) {
+    methods.forEach((name) => {
+      const original = auth[name];
+      if (typeof original !== 'function') return;
+      auth[name] = function recordedAuthMethod(...args) {
+        try {
+          const called = JSON.parse(window.sessionStorage.getItem(key) ?? '[]');
+          called.push(name);
+          window.sessionStorage.setItem(key, JSON.stringify(called));
+        } catch (error) {
+          // A page with no storage cannot be recorded; the call still goes through.
+        }
+        return original.apply(this, args);
+      };
+    });
+    Object.defineProperty(auth, '__lowdefyAuthRecorder', { value: true });
+  }
+  try {
+    window.sessionStorage.removeItem(key);
+  } catch (error) {
+    return false;
+  }
+  return true;
+}
+
+export default installAuthActionRecorder;

package/lib/docs/rails/readAuthActionRecorder.js

@@ -0,0 +1,32 @@
+/*
+  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` and its argument.
+//
+// Reads, and clears, the auth methods installAuthActionRecorder noted since it
+// was installed, in call order.
+function readAuthActionRecorder({ key }) {
+  try {
+    const called = JSON.parse(window.sessionStorage.getItem(key) ?? '[]');
+    window.sessionStorage.removeItem(key);
+    return called;
+  } catch (error) {
+    return [];
+  }
+}
+
+export default readAuthActionRecorder;

package/lib/docs/rails/readBuiltArtifact.js

@@ -0,0 +1,30 @@
+/*
+  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 fs from 'node:fs';
+import path from 'node:path';
+import { serializer } from '@lowdefy/helpers';
+
+// A build artifact, deserialized, or null when the build wrote none.
+function readBuiltArtifact({ buildDirectory, name }) {
+  const filePath = path.join(buildDirectory, name);
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  return serializer.deserialize(JSON.parse(fs.readFileSync(filePath, 'utf8')));
+}
+
+export default readBuiltArtifact;

package/lib/docs/readConnectionPlugins.js

@@ -0,0 +1,26 @@
+/*
+  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.
+*/
+
+// The plugin connection map the data-session gate reads (createLowdefyContext imports the same
+// module). Deferred import: build/plugins/* only exists in a running server directory, so
+// importing it at module load would break every consumer of the journey runner (the MCP server,
+// tests) in environments without a full build.
+async function readConnectionPlugins() {
+  const { default: connections } = await import('../../build/plugins/connections.js');
+  return connections;
+}
+
+export default readConnectionPlugins;

package/lib/docs/readDevAuthMode.js

@@ -0,0 +1,32 @@
+/*
+  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 { type } from '@lowdefy/helpers';
+
+import readBuildArtifact from './readBuildArtifact.js';
+
+// Whether the app configures auth, and whether a dev mock user stands in for every caller
+// (LOWDEFY_DEV_USER, or auth.dev.mockUser - the precedence getMockUser applies). Read fresh from the
+// build, so a journey sees the config as it is now.
+function readDevAuthMode() {
+  const auth = readBuildArtifact({ name: 'auth.json', deserialize: true }) ?? {};
+  return {
+    authConfigured: auth.configured === true,
+    mockUserActive: Boolean(process.env.LOWDEFY_DEV_USER) || !type.isNone(auth.dev?.mockUser),
+  };
+}
+
+export default readDevAuthMode;

package/lib/docs/readDocEntry.js

@@ -0,0 +1,40 @@
+/*
+  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 fs from 'node:fs';
+import { type } from '@lowdefy/helpers';
+
+import makeModuleManifestDoc from './makeModuleManifestDoc.js';
+
+const coreContent = new Map();
+
+// Core docs ship with the installed docs package and never change while the
+// server runs, so they are read once. Plugin and module docs are read on
+// every call; a module's manifest page is generated from its build entry.
+function readDocEntry({ entry }) {
+  if (!type.isUndefined(entry.moduleEntry)) {
+    return makeModuleManifestDoc({ moduleEntry: entry.moduleEntry });
+  }
+  if (entry.source !== 'core') {
+    return fs.readFileSync(entry.filePath, 'utf8');
+  }
+  if (!coreContent.has(entry.filePath)) {
+    coreContent.set(entry.filePath, fs.readFileSync(entry.filePath, 'utf8'));
+  }
+  return coreContent.get(entry.filePath);
+}
+
+export default readDocEntry;

package/lib/docs/readDocTitle.js

@@ -0,0 +1,26 @@
+/*
+  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 fs from 'node:fs';
+
+// A markdown file's first level-one heading, else the fallback.
+function readDocTitle({ filePath, fallback }) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const heading = content.match(/^# +(.+?)\s*$/m);
+  return heading ? heading[1] : fallback;
+}
+
+export default readDocTitle;

package/lib/docs/readJourneyEmailMatch.js

@@ -0,0 +1,57 @@
+/*
+  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 { type } from '@lowdefy/helpers';
+
+import JourneyStepError from './JourneyStepError.js';
+import waitForJourneyEmail from './waitForJourneyEmail.js';
+
+// The words a person reads: the plain-text part, or the HTML without its tags
+// for a message that has none. Tags and attributes are dropped so a pattern
+// can not match inside a link's URL the reader never sees as text.
+function readableText(message) {
+  if (type.isString(message.text)) {
+    return message.text;
+  }
+  return (message.html ?? '').replace(/<[^>]*>/g, ' ');
+}
+
+// Reads text from the newest email to `to` (subject containing `subject`),
+// waiting for one like the email step, without leaving the actor's page: the
+// person has the email open on another screen and types what it says - a
+// one-time sign-in code - into the tab they started from. Returns the first
+// match of `match`, or its first capture group when it has one.
+async function readJourneyEmailMatch({ page, params, since, configDirectory, timeout }) {
+  const { to, subject, match } = params;
+  const message = await waitForJourneyEmail({
+    page,
+    params: { to, subject },
+    since,
+    configDirectory,
+    timeout,
+  });
+  const text = readableText(message);
+  const found = new RegExp(match).exec(text);
+  if (found === null) {
+    throw new JourneyStepError(
+      `The email "${message.subject}" to "${to}" has no text matching ${JSON.stringify(match)}.`,
+      { expected: `text matching ${JSON.stringify(match)}`, actual: text }
+    );
+  }
+  return found[1] ?? found[0];
+}
+
+export default readJourneyEmailMatch;

package/lib/docs/readJourneyEmailMatch.test.mjs

@@ -0,0 +1,110 @@
+/*
+  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 fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { jest } from '@jest/globals';
+
+import JourneyStepError from './JourneyStepError.js';
+import readJourneyEmailMatch from './readJourneyEmailMatch.js';
+
+const STARTED_AT = Date.parse('2026-09-27T10:00:00.000Z');
+const LINK = 'http://localhost:3290/api/auth/magic-link/verify?token=ab123456cd';
+
+let configDirectory;
+
+beforeEach(() => {
+  configDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-journey-email-match-'));
+  fs.mkdirSync(path.join(configDirectory, '.lowdefy', 'mail'), { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(configDirectory, { recursive: true, force: true });
+});
+
+function writeMessage({ id, subject, html = null, text = null }) {
+  const message = {
+    id,
+    receivedAt: new Date(STARTED_AT + 1000).toISOString(),
+    from: 'app@localhost',
+    to: ['ada@example.test'],
+    subject,
+    html,
+    text,
+  };
+  fs.writeFileSync(
+    path.join(configDirectory, '.lowdefy', 'mail', `${id}.json`),
+    JSON.stringify(message)
+  );
+}
+
+const page = { waitForTimeout: jest.fn(async () => {}) };
+
+function read(params) {
+  return readJourneyEmailMatch({
+    page,
+    params: { to: 'ada@example.test', ...params },
+    since: STARTED_AT,
+    configDirectory,
+    timeout: 0,
+  });
+}
+
+test.each([
+  [
+    'the first match in the plain-text part',
+    { text: `Sign in: ${LINK}\n\nOr enter this code:\n\n482913\n` },
+    '\\b\\d{6}\\b',
+    '482913',
+  ],
+  [
+    'the first capture group when the pattern has one',
+    { text: 'Reference ORD-7731 is ready.' },
+    'ORD-(\\d+)',
+    '7731',
+  ],
+  [
+    'the text of an HTML-only message, not its link attributes',
+    { html: `<a href="${LINK}">Sign in</a><p style="letter-spacing:8px">482913</p>` },
+    '\\b\\d{6}\\b',
+    '482913',
+  ],
+])('readJourneyEmailMatch returns %s', async (_, body, match, expected) => {
+  writeMessage({ id: '000001', subject: 'Your sign-in link', ...body });
+  await expect(read({ match })).resolves.toEqual(expected);
+});
+
+test('readJourneyEmailMatch reads the newest message the subject narrows to', async () => {
+  writeMessage({ id: '000001', subject: 'Your sign-in link', text: 'Code 111111' });
+  writeMessage({ id: '000002', subject: 'Verify your email', text: 'Code 222222' });
+  await expect(read({ subject: 'sign-in', match: '\\d{6}' })).resolves.toEqual('111111');
+  await expect(read({ match: '\\d{6}' })).resolves.toEqual('222222');
+});
+
+test('readJourneyEmailMatch fails with the email text when nothing matches', async () => {
+  writeMessage({ id: '000001', subject: 'Your sign-in link', text: 'Click the link.' });
+
+  const error = await read({ match: '\\b\\d{6}\\b' }).catch((caught) => caught);
+
+  expect(error).toBeInstanceOf(JourneyStepError);
+  expect(error.message).toEqual(
+    'The email "Your sign-in link" to "ada@example.test" has no text matching "\\\\b\\\\d{6}\\\\b".'
+  );
+  expect(error.expected).toEqual('text matching "\\\\b\\\\d{6}\\\\b"');
+  expect(error.actual).toEqual('Click the link.');
+});