@lowdefy/server-dev 6.1.0 → 7.0.0

package/src/routes/docs/runEndpoint.test.mjs

@@ -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 { jest } from '@jest/globals';
+
+const mockRunEndpoint = jest.fn();
+
+jest.unstable_mockModule('../../../lib/docs/runEndpoint.js', () => ({
+  default: mockRunEndpoint,
+}));
+
+const { ConfigError } = await import('@lowdefy/errors');
+const { default: docsRunEndpointHandler } = await import('./runEndpoint.js');
+
+function createContext(body) {
+  const request = new Request('http://localhost:3224/lowdefy-docs/run-endpoint', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  const json = jest.fn((data, status) => ({ data, status: status ?? 200 }));
+  return { req: { raw: request }, json };
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  mockRunEndpoint.mockResolvedValue({ refused: false, status: 'success', response: { ok: true } });
+});
+
+test('docsRunEndpointHandler passes endpointId, payload and a user object through to runEndpoint', async () => {
+  const c = createContext({
+    endpointId: 'create_order',
+    payload: { sku: 'A1' },
+    user: { roles: ['admin'] },
+  });
+
+  const result = await docsRunEndpointHandler(c);
+
+  expect(mockRunEndpoint).toHaveBeenCalledWith({
+    endpointId: 'create_order',
+    payload: { sku: 'A1' },
+    user: { roles: ['admin'] },
+    system: undefined,
+    honoContext: c,
+  });
+  expect(result.status).toBe(200);
+  expect(result.data).toEqual({ refused: false, status: 'success', response: { ok: true } });
+});
+
+test('docsRunEndpointHandler leaves the original request body readable', async () => {
+  const c = createContext({ endpointId: 'create_order' });
+
+  await docsRunEndpointHandler(c);
+
+  expect(c.req.raw.bodyUsed).toBe(false);
+  await expect(c.req.raw.json()).resolves.toEqual({ endpointId: 'create_order' });
+});
+
+test('docsRunEndpointHandler returns 400 when user is malformed', async () => {
+  const c = createContext({ endpointId: 'create_order', user: '{nope' });
+
+  const result = await docsRunEndpointHandler(c);
+
+  expect(result.status).toBe(400);
+  expect(result.data.error).toMatch(/The "user" param must be JSON/);
+  expect(mockRunEndpoint).not.toHaveBeenCalled();
+});
+
+test('docsRunEndpointHandler passes a data set user name and data through', async () => {
+  const c = createContext({ endpointId: 'create_order', user: 'member', data: 'crm' });
+
+  await docsRunEndpointHandler(c);
+
+  expect(mockRunEndpoint).toHaveBeenCalledWith(
+    expect.objectContaining({ user: 'member', data: 'crm' })
+  );
+});
+
+test('docsRunEndpointHandler passes an undefined user when the body omits it', async () => {
+  const c = createContext({ endpointId: 'create_order' });
+
+  await docsRunEndpointHandler(c);
+
+  expect(mockRunEndpoint).toHaveBeenCalledWith({
+    endpointId: 'create_order',
+    payload: undefined,
+    user: undefined,
+    system: undefined,
+    honoContext: c,
+  });
+});
+
+test('docsRunEndpointHandler passes system through to runEndpoint', async () => {
+  const c = createContext({ endpointId: 'purge_stale', system: true });
+
+  await docsRunEndpointHandler(c);
+
+  expect(mockRunEndpoint).toHaveBeenCalledWith({
+    endpointId: 'purge_stale',
+    payload: undefined,
+    user: undefined,
+    system: true,
+    honoContext: c,
+  });
+});
+
+test('docsRunEndpointHandler returns 400 when system is combined with user', async () => {
+  mockRunEndpoint.mockRejectedValue(
+    new ConfigError('run_endpoint "system" cannot be combined with "user".')
+  );
+  const c = createContext({ endpointId: 'purge_stale', system: true, user: { roles: ['admin'] } });
+
+  const result = await docsRunEndpointHandler(c);
+
+  expect(result.status).toBe(400);
+  expect(result.data.error).toMatch(/cannot be combined with "user"/);
+});
+
+test('docsRunEndpointHandler returns 400 when runEndpoint throws a ConfigError', async () => {
+  mockRunEndpoint.mockRejectedValue(
+    new ConfigError('run_endpoint requires an "endpointId" string. Received undefined.')
+  );
+  const c = createContext({ payload: {} });
+
+  const result = await docsRunEndpointHandler(c);
+
+  expect(result.status).toBe(400);
+  expect(result.data.error).toMatch(/requires an "endpointId" string/);
+});
+
+test('docsRunEndpointHandler returns refusals and rejects as 200 data', async () => {
+  mockRunEndpoint.mockResolvedValue({
+    refused: false,
+    success: false,
+    status: 'reject',
+    error: { name: 'Error', message: 'Out of stock.' },
+    response: null,
+  });
+  const c = createContext({ endpointId: 'create_order' });
+
+  const result = await docsRunEndpointHandler(c);
+
+  expect(result.status).toBe(200);
+  expect(result.data.status).toBe('reject');
+});
+
+test('docsRunEndpointHandler rethrows faults that are not ConfigErrors', async () => {
+  mockRunEndpoint.mockRejectedValue(new Error('boom'));
+  const c = createContext({ endpointId: 'create_order' });
+
+  await expect(docsRunEndpointHandler(c)).rejects.toThrow('boom');
+});

package/src/routes/docs/runRequest.js

@@ -14,22 +14,39 @@
   limitations under the License.
 */
 
+import { ConfigError } from '@lowdefy/errors';
+
+import parseUserParam from './parseUserParam.js';
 import runRequest from '../../../lib/docs/runRequest.js';
 
 // Refusals and request errors are returned as 200 data (see runRequest.js) —
-// only malformed input (missing pageId/requestId) is a 400.
+// only malformed input (missing pageId/requestId, thrown as a ConfigError) is a
+// 400. Anything else is a fault and propagates to the error handler.
 async function docsRunRequestHandler(c) {
   // Parse the body from a clone: runRequest builds a Lowdefy context whose
-  // getSession(c) → getAuthUser(c) reconstructs a Request from c.req.raw,
-  // which throws ("body ... disturbed or locked") if the body was already
-  // consumed. The normal /api/request path never hits this because its
-  // session is read in middleware before the handler touches the body.
-  const { pageId, requestId, payload } = await c.req.raw.clone().json();
+  // resolveAuthentication reads c.req.raw (headers) to resolve the caller,
+  // so leave the original request body intact and read our own copy here.
+  const { pageId, requestId, payload, user, data, saveResponse } = await c.req.raw.clone().json();
+  const { user: parsedUser, error: userError } = parseUserParam({ value: user });
+  if (userError) {
+    return c.json({ error: userError }, 400);
+  }
   try {
-    const result = await runRequest({ pageId, requestId, payload, honoContext: c });
+    const result = await runRequest({
+      pageId,
+      requestId,
+      payload,
+      user: parsedUser,
+      data,
+      saveResponse,
+      honoContext: c,
+    });
     return c.json(result);
   } catch (error) {
-    return c.json({ error: error.message }, 400);
+    if (error instanceof ConfigError) {
+      return c.json({ error: error.message }, 400);
+    }
+    throw error;
   }
 }
 

package/src/routes/docs/runRequest.test.mjs

@@ -0,0 +1,92 @@
+/*
+  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';
+
+const mockRunRequest = jest.fn();
+
+jest.unstable_mockModule('../../../lib/docs/runRequest.js', () => ({
+  default: mockRunRequest,
+}));
+
+const { default: docsRunRequestHandler } = await import('./runRequest.js');
+
+function createContext(body) {
+  const request = new Request('http://localhost:3204/lowdefy-docs/run-request', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  const json = jest.fn((data, status) => ({ data, status: status ?? 200 }));
+  return { req: { raw: request }, json };
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  mockRunRequest.mockResolvedValue({ refused: false, response: [] });
+});
+
+test('docsRunRequestHandler passes a user object through to runRequest', async () => {
+  const c = createContext({
+    pageId: 'home',
+    requestId: 'get_rows',
+    user: { roles: ['admin'] },
+  });
+
+  await docsRunRequestHandler(c);
+
+  expect(mockRunRequest).toHaveBeenCalledWith({
+    pageId: 'home',
+    requestId: 'get_rows',
+    payload: undefined,
+    user: { roles: ['admin'] },
+    honoContext: c,
+  });
+});
+
+test('docsRunRequestHandler returns 400 when user is malformed', async () => {
+  const c = createContext({ pageId: 'home', requestId: 'get_rows', user: 42 });
+
+  const result = await docsRunRequestHandler(c);
+
+  expect(result.status).toBe(400);
+  expect(result.data.error).toMatch(/must be a user object/);
+  expect(mockRunRequest).not.toHaveBeenCalled();
+});
+
+test('docsRunRequestHandler passes a data set user name and data through', async () => {
+  const c = createContext({ pageId: 'home', requestId: 'get_rows', user: 'member', data: 'crm' });
+
+  await docsRunRequestHandler(c);
+
+  expect(mockRunRequest).toHaveBeenCalledWith(
+    expect.objectContaining({ user: 'member', data: 'crm' })
+  );
+});
+
+test('docsRunRequestHandler passes an undefined user when the body omits it', async () => {
+  const c = createContext({ pageId: 'home', requestId: 'get_rows' });
+
+  await docsRunRequestHandler(c);
+
+  expect(mockRunRequest).toHaveBeenCalledWith({
+    pageId: 'home',
+    requestId: 'get_rows',
+    payload: undefined,
+    user: undefined,
+    honoContext: c,
+  });
+});

package/src/routes/docs/screenshot.js

@@ -16,8 +16,10 @@
 
 import { type } from '@lowdefy/helpers';
 
+import parsePathParamsParam from './parsePathParamsParam.js';
 import parseUserParam from './parseUserParam.js';
 import screenshotPage from '../../../lib/docs/screenshotPage.js';
+import validateViewport from '../../../lib/docs/validateViewport.js';
 
 // Parses a query param as a number, or undefined if absent/not a valid
 // number — undefined (not NaN/0) so callers can tell "not provided" apart
@@ -56,14 +58,60 @@ async function docsScreenshotHandler(c) {
   const scrollX = queryNumber(c, 'scrollX') ?? 0;
   const scrollY = queryNumber(c, 'scrollY') ?? 0;
 
+  // `width` and `height` name the clip here, so the viewport size takes the
+  // `viewport` prefix; the MCP tool, which nests the clip, calls them width
+  // and height.
+  for (const key of ['viewportWidth', 'viewportHeight']) {
+    const raw = c.req.query(key);
+    if (!type.isNone(raw) && type.isUndefined(queryNumber(c, key))) {
+      return c.json(
+        {
+          error: `"${key}" must be a positive integer (CSS pixels). Received ${JSON.stringify(
+            raw
+          )}.`,
+        },
+        400
+      );
+    }
+  }
+  const width = queryNumber(c, 'viewportWidth');
+  const height = queryNumber(c, 'viewportHeight');
+  const colorScheme = c.req.query('colorScheme');
+  const viewportError = validateViewport({ width, height, colorScheme });
+  if (viewportError) {
+    return c.json({ error: viewportError }, 400);
+  }
+
   const { user, error: userError } = parseUserParam({ value: c.req.query('user') });
   if (userError) {
     return c.json({ error: userError }, 400);
   }
 
-  const result = await screenshotPage({ origin, pageId, fullPage, clip, scrollX, scrollY, user });
+  const { pathParams, error: pathParamsError } = parsePathParamsParam({
+    value: c.req.query('pathParams'),
+  });
+  if (pathParamsError) {
+    return c.json({ error: pathParamsError }, 400);
+  }
+
+  const result = await screenshotPage({
+    origin,
+    pageId,
+    pathParams,
+    fullPage,
+    clip,
+    scrollX,
+    scrollY,
+    user,
+    data: c.req.query('data'),
+    width,
+    height,
+    colorScheme,
+  });
   if (result.error) {
-    return c.json({ error: result.error }, 502);
+    // pathParams the page cannot be opened with are the caller's to fix, not a
+    // failed render.
+    return c.json({ error: result.error }, result.invalidInput ? 400 : 502);
   }
   const buffer = Buffer.from(result.data, 'base64');
   return c.body(buffer, 200, { 'Content-Type': result.mimeType });

package/src/routes/docs/screenshot.test.mjs

@@ -0,0 +1,117 @@
+/*
+  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';
+
+const mockScreenshotPage = jest.fn();
+
+jest.unstable_mockModule('../../../lib/docs/screenshotPage.js', () => ({
+  default: mockScreenshotPage,
+}));
+
+const { default: docsScreenshotHandler } = await import('./screenshot.js');
+
+function createContext(url) {
+  const parsed = new URL(url);
+  const json = jest.fn((data, status) => ({ data, status: status ?? 200 }));
+  const body = jest.fn((data, status, headers) => ({ data, status, headers }));
+  return {
+    req: {
+      url,
+      param: () => parsed.pathname.split('/').pop(),
+      query: (key) => parsed.searchParams.get(key) ?? undefined,
+    },
+    json,
+    body,
+  };
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  mockScreenshotPage.mockResolvedValue({ data: 'cG5n', mimeType: 'image/png' });
+});
+
+test('docsScreenshotHandler passes the viewport size and colour scheme to screenshotPage', async () => {
+  const c = createContext(
+    'http://localhost:3227/lowdefy-docs/screenshot/home?viewportWidth=390&viewportHeight=844&colorScheme=dark'
+  );
+
+  const result = await docsScreenshotHandler(c);
+
+  expect(mockScreenshotPage).toHaveBeenCalledWith(
+    expect.objectContaining({
+      origin: 'http://localhost:3227',
+      pageId: 'home',
+      width: 390,
+      height: 844,
+      colorScheme: 'dark',
+      clip: undefined,
+    })
+  );
+  expect(result.status).toBe(200);
+  expect(result.headers).toEqual({ 'Content-Type': 'image/png' });
+});
+
+test('docsScreenshotHandler keeps width and height as the clip, apart from the viewport', async () => {
+  const c = createContext(
+    'http://localhost:3227/lowdefy-docs/screenshot/home?x=0&y=10&width=200&height=100&viewportWidth=800'
+  );
+
+  await docsScreenshotHandler(c);
+
+  expect(mockScreenshotPage).toHaveBeenCalledWith(
+    expect.objectContaining({
+      clip: { x: 0, y: 10, width: 200, height: 100 },
+      width: 800,
+      height: undefined,
+      colorScheme: undefined,
+    })
+  );
+});
+
+test('docsScreenshotHandler returns 400 for an unknown colour scheme', async () => {
+  const c = createContext('http://localhost:3227/lowdefy-docs/screenshot/home?colorScheme=dim');
+
+  const result = await docsScreenshotHandler(c);
+
+  expect(result.status).toBe(400);
+  expect(result.data.error).toEqual('Color scheme must be "light" or "dark". Received "dim".');
+  expect(mockScreenshotPage).not.toHaveBeenCalled();
+});
+
+test('docsScreenshotHandler returns 400 for a viewport width that is not a positive integer', async () => {
+  const c = createContext('http://localhost:3227/lowdefy-docs/screenshot/home?viewportWidth=0');
+
+  const result = await docsScreenshotHandler(c);
+
+  expect(result.status).toBe(400);
+  expect(result.data.error).toMatch(/Viewport width must be a positive integer/);
+});
+
+test.each(['viewportWidth', 'viewportHeight'])(
+  'docsScreenshotHandler returns 400 naming a non-numeric %s',
+  async (key) => {
+    const c = createContext(`http://localhost:3227/lowdefy-docs/screenshot/home?${key}=wide`);
+
+    const result = await docsScreenshotHandler(c);
+
+    expect(result.status).toBe(400);
+    expect(result.data.error).toEqual(
+      `"${key}" must be a positive integer (CSS pixels). Received "wide".`
+    );
+    expect(mockScreenshotPage).not.toHaveBeenCalled();
+  }
+);

package/src/routes/docs/search.js

@@ -14,14 +14,27 @@
   limitations under the License.
 */
 
+import docSources from '../../../lib/docs/docSources.js';
 import searchDocs from '../../../lib/docs/searchDocs.js';
 
 function docsSearchHandler(c) {
   const query = c.req.query('q');
+  const source = c.req.query('source');
   if (!query || query.trim() === '') {
-    return c.json({ error: 'Missing search query. Use GET /lowdefy-docs/search?q=your+keywords.' }, 400);
+    return c.json(
+      { error: 'Missing search query. Use GET /lowdefy-docs/search?q=your+keywords.' },
+      400
+    );
   }
-  return c.json(searchDocs({ query }));
+  if (source !== undefined && !docSources.includes(source)) {
+    return c.json(
+      {
+        error: `Unknown docs source "${source}". Use one of: ${docSources.join(', ')}.`,
+      },
+      400
+    );
+  }
+  return c.json(searchDocs({ query, source }));
 }
 
 export default docsSearchHandler;

package/src/routes/docs/snapshotState.js

@@ -14,21 +14,35 @@
   limitations under the License.
 */
 
+import { parseRequestBody } from '@lowdefy/api';
+
 import snapshotState from '../../../lib/docs/snapshotState.js';
 
 // Lets an agent (or a developer) snapshot the running app's page state and
 // recorded request/api responses into a checkpoint folder under .lowdefy,
 // for later replay via POST /lowdefy-docs/state/load.
 async function docsSnapshotStateHandler(c) {
-  const { pageId, name, notes, source, overwrite } = await c.req.json();
+  const { pageId, pathParams, name, notes, source, overwrite } = parseRequestBody({
+    text: await c.req.text(),
+  });
   // Derived from the incoming request rather than a config value — this is
   // the origin an agent can actually reach the dev server on (host/port it
   // just connected to), regardless of how the server is bound.
   const origin = new URL(c.req.url).origin;
 
-  const result = await snapshotState({ origin, pageId, name, notes, source, overwrite });
+  const result = await snapshotState({
+    origin,
+    pageId,
+    pathParams,
+    name,
+    notes,
+    source,
+    overwrite,
+  });
   if (result.error) {
-    return c.json({ error: result.error }, 502);
+    // pathParams the page cannot be opened with are the caller's to fix, not a
+    // failed render.
+    return c.json({ error: result.error }, result.invalidInput ? 400 : 502);
   }
   return c.json(result);
 }

package/src/routes/endpoints.js

@@ -14,55 +14,56 @@
   limitations under the License.
 */
 
-import { callEndpoint, getEndpointConfig, runWebhookEndpoint } from '@lowdefy/api';
+import {
+  callEndpoint,
+  getEndpointConfig,
+  parseRequestBody,
+  runWebhookEndpoint,
+} from '@lowdefy/api';
 
 import getPathSegments from '../lib/getPathSegments.js';
 
 async function endpointsHandler(c) {
   if (c.req.method !== 'POST') {
-    throw new Error('Only POST requests are supported.');
+    // A wrong-method request is client-caused: answer 405 rather than raising a
+    // fault that would be logged at error level and answered with a 500.
+    return c.json({ error: 'Method not allowed.' }, 405);
   }
   const context = c.get('lowdefyContext');
   const endpointId = getPathSegments(c, '/api/endpoints/').join('/');
 
-  // Endpoints opting in with `webhook: true` are third-party webhook receivers
-  // (SNS, Event Grid, Stripe, ...): they take the request RAW — body in the
-  // caller's own format (not the { payload } envelope), plus query + headers —
-  // and their return value is sent back verbatim, because webhook handshakes
-  // (e.g. Event Grid's validationResponse) require exact response shapes.
-  // The config lookup is a cached file read; an unknown endpoint falls through
-  // to the standard path so its error shape is unchanged. Everything about
-  // non-webhook endpoints is untouched.
+  // Endpoints opting in with `webhook` (true or a { verify } object) are
+  // third-party webhook receivers (SNS, Event Grid, Stripe, ...): they take the
+  // request RAW — body in the caller's own format (not the { payload }
+  // envelope), plus query + headers — and their return value is sent back
+  // verbatim, because webhook handshakes (e.g. Event Grid's validationResponse)
+  // require exact response shapes. The config lookup is a cached file read; an
+  // unknown endpoint falls through to the standard path so its error shape is
+  // unchanged. Everything about non-webhook endpoints is untouched.
   let endpointConfig = null;
   try {
     endpointConfig = await getEndpointConfig(context, { endpointId });
   } catch {
     /* unknown endpoint — the standard path below reports it exactly as before */
   }
-  if (endpointConfig?.webhook === true) {
-    // SNS posts JSON as text/plain — parse regardless of content-type; an
-    // unparseable body arrives as the raw string.
-    const raw = await c.req.text();
-    let body = raw;
-    try {
-      body = JSON.parse(raw);
-    } catch {
-      /* non-JSON body — raw string passthrough */
-    }
+  if (endpointConfig?.webhook) {
     context.logger.info({ event: 'call_webhook_endpoint', endpointId });
-    const result = await runWebhookEndpoint(context, {
+    const { status, body, contentType } = await runWebhookEndpoint(context, {
       endpointId,
-      body,
+      rawBody: await c.req.text(),
       query: c.req.query(),
       headers: c.req.header(),
     });
-    if (!result.success) {
-      return c.json({ error: 'Webhook failed.' }, 500);
+    if (contentType === 'text/plain') {
+      // A text answer often echoes a value from the request (a handshake token), so the browser
+      // must not sniff it into HTML.
+      c.header('X-Content-Type-Options', 'nosniff');
+      return c.text(body, status);
     }
-    return c.json(result.response ?? { ok: true });
+    return c.json(body, status);
   }
 
-  const { blockId, payload, pageId } = await c.req.json();
+  const { blockId, payload, pageId } = parseRequestBody({ text: await c.req.text() });
   context.logger.info({ event: 'call_api_endpoint', blockId, endpointId, pageId });
   const response = await callEndpoint(context, { blockId, endpointId, pageId, payload });
   return c.json(response);