@lowdefy/server-dev 5.6.0 → 6.1.0

package/src/routes/docs/pageConfig.js

@@ -0,0 +1,36 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import getPageConfig from '../../../lib/docs/getPageConfig.js';
+
+// 404 when the pageId isn't registered at all. 200 with { buildError, errors }
+// when the pageId is registered but its JIT build failed — agents need the
+// errors in the body, not just a failing status code.
+async function docsPageConfigHandler(c) {
+  const pageId = c.req.param('pageId');
+  const result = await getPageConfig({ pageId });
+  if (result === null) {
+    return c.json(
+      {
+        error: `No page found for pageId "${pageId}". Check the pageId in your lowdefy.yaml pages config.`,
+      },
+      404
+    );
+  }
+  return c.json(result);
+}
+
+export default docsPageConfigHandler;

package/src/routes/docs/parseUserParam.js

@@ -0,0 +1,52 @@
+/*
+  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';
+
+// The docs routes take the headless caller as a JSON string on the GET routes
+// (query params are always strings) and as an object in the POST bodies, so both
+// arrive here and every route answers a bad `user` with the same message.
+// Returns { user } or { error }.
+function parseUserParam({ value }) {
+  if (type.isNone(value)) {
+    return {};
+  }
+
+  let user = value;
+  if (type.isString(value)) {
+    try {
+      user = JSON.parse(value);
+    } catch {
+      return {
+        error: `The "user" param must be JSON, e.g. {"roles":["admin"]}. Received ${JSON.stringify(
+          value
+        )}.`,
+      };
+    }
+  }
+
+  if (!type.isObject(user)) {
+    return {
+      error: `The "user" param must be an object, e.g. {"roles":["admin"]}. Received ${JSON.stringify(
+        user
+      )}.`,
+    };
+  }
+
+  return { user };
+}
+
+export default parseUserParam;

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

@@ -0,0 +1,45 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import parseUserParam from './parseUserParam.js';
+
+test('parseUserParam returns nothing when the param is absent', () => {
+  expect(parseUserParam({ value: undefined })).toEqual({});
+});
+
+test('parseUserParam parses a JSON string from a query param', () => {
+  expect(parseUserParam({ value: '{"roles":["admin"]}' })).toEqual({
+    user: { roles: ['admin'] },
+  });
+});
+
+test('parseUserParam passes an object from a JSON body through', () => {
+  expect(parseUserParam({ value: { roles: ['admin'] } })).toEqual({
+    user: { roles: ['admin'] },
+  });
+});
+
+test('parseUserParam returns an error when the query param is not JSON', () => {
+  expect(parseUserParam({ value: 'admin' }).error).toMatch(/must be JSON/);
+});
+
+test('parseUserParam returns an error when the param parses to a non-object', () => {
+  expect(parseUserParam({ value: '["admin"]' }).error).toMatch(/must be an object/);
+});
+
+test('parseUserParam returns an error when a body value is not an object', () => {
+  expect(parseUserParam({ value: 42 }).error).toMatch(/must be an object/);
+});

package/src/routes/docs/pluginDoc.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.
+*/
+
+import getPluginDoc from '../../../lib/docs/getPluginDoc.js';
+
+function docsPluginDocHandler(c) {
+  const packageName = c.req.param('package');
+  const doc = getPluginDoc({ packageName });
+  if (doc === null) {
+    return c.json(
+      {
+        error: `Package "${packageName}" ships no markdown docs. See GET /lowdefy-docs/plugins for its types.`,
+      },
+      404
+    );
+  }
+  return c.text(doc.markdown, 200, { 'Content-Type': 'text/markdown; charset=utf-8' });
+}
+
+export default docsPluginDocHandler;

package/src/routes/docs/plugins.js

@@ -0,0 +1,23 @@
+/*
+  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 listPlugins from '../../../lib/docs/listPlugins.js';
+
+function docsPluginsHandler(c) {
+  return c.json(listPlugins());
+}
+
+export default docsPluginsHandler;

package/src/routes/docs/runRequest.js

@@ -0,0 +1,36 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import 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.
+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();
+  try {
+    const result = await runRequest({ pageId, requestId, payload, honoContext: c });
+    return c.json(result);
+  } catch (error) {
+    return c.json({ error: error.message }, 400);
+  }
+}
+
+export default docsRunRequestHandler;

package/{lib/server/auth/getServerSession.js → src/routes/docs/schema.js}

@@ -14,22 +14,24 @@
   limitations under the License.
 */
 
-import { getServerSession as getNextAuthServerSession } from 'next-auth/next';
-
-import authJson from '../../build/auth.js';
-import getMockSession from './getMockSession.js';
-
-async function getServerSession({ authOptions, req, res }) {
-  // Check for mock user first (dev server only)
-  const mockSession = await getMockSession();
-  if (mockSession) {
-    return mockSession;
+import getSchema from '../../../lib/docs/getSchema.js';
+
+function docsSchemaHandler(c) {
+  const kind = c.req.param('kind');
+  const type = c.req.param('type');
+  let schema;
+  try {
+    schema = getSchema({ kind, type });
+  } catch (error) {
+    return c.json({ error: error.message }, 400);
   }
-
-  if (authJson.configured === true) {
-    return getNextAuthServerSession(req, res, authOptions);
+  if (schema === null) {
+    return c.json(
+      { error: `No schema found for ${kind} type "${type}". See GET /lowdefy-docs/${kind} for available types.` },
+      404
+    );
   }
-  return undefined;
+  return c.json(schema);
 }
 
-export default getServerSession;
+export default docsSchemaHandler;

package/src/routes/docs/screenshot.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.
+*/
+
+import { type } from '@lowdefy/helpers';
+
+import parseUserParam from './parseUserParam.js';
+import screenshotPage from '../../../lib/docs/screenshotPage.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
+// from an explicit 0.
+function queryNumber(c, key) {
+  const raw = c.req.query(key);
+  if (type.isNone(raw)) {
+    return undefined;
+  }
+  const value = Number(raw);
+  return Number.isFinite(value) ? value : undefined;
+}
+
+async function docsScreenshotHandler(c) {
+  const pageId = c.req.param('pageId');
+  const fullPage = c.req.query('fullPage') === 'true';
+  // 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 clipX = queryNumber(c, 'x');
+  const clipY = queryNumber(c, 'y');
+  const clipWidth = queryNumber(c, 'width');
+  const clipHeight = queryNumber(c, 'height');
+  // Only build a clip when all four dimensions are present — a partial
+  // clip is ambiguous, so screenshotPage falls back to a normal viewport
+  // screenshot in that case (same as an invalid clip).
+  const clip =
+    !type.isNone(clipX) &&
+    !type.isNone(clipY) &&
+    !type.isNone(clipWidth) &&
+    !type.isNone(clipHeight)
+      ? { x: clipX, y: clipY, width: clipWidth, height: clipHeight }
+      : undefined;
+  const scrollX = queryNumber(c, 'scrollX') ?? 0;
+  const scrollY = queryNumber(c, 'scrollY') ?? 0;
+
+  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 });
+  if (result.error) {
+    return c.json({ error: result.error }, 502);
+  }
+  const buffer = Buffer.from(result.data, 'base64');
+  return c.body(buffer, 200, { 'Content-Type': result.mimeType });
+}
+
+export default docsScreenshotHandler;

package/src/routes/docs/search.js

@@ -0,0 +1,27 @@
+/*
+  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 searchDocs from '../../../lib/docs/searchDocs.js';
+
+function docsSearchHandler(c) {
+  const query = c.req.query('q');
+  if (!query || query.trim() === '') {
+    return c.json({ error: 'Missing search query. Use GET /lowdefy-docs/search?q=your+keywords.' }, 400);
+  }
+  return c.json(searchDocs({ query }));
+}
+
+export default docsSearchHandler;

package/src/routes/docs/snapshotState.js

@@ -0,0 +1,36 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import 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();
+  // 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 });
+  if (result.error) {
+    return c.json({ error: result.error }, 502);
+  }
+  return c.json(result);
+}
+
+export default docsSnapshotStateHandler;

package/src/routes/docs/stateCheckpointsList.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 { listStateCheckpoints } from '../../../lib/docs/checkpointStore.js';
+
+// Lists state checkpoints (page state + recorded request/api
+// responses) — distinct from GET /lowdefy-docs/checkpoints, which lists
+// config-directory-snapshot checkpoints (see checkpointStore.js).
+function docsStateCheckpointsListHandler(c) {
+  return c.json(listStateCheckpoints());
+}
+
+export default docsStateCheckpointsListHandler;

package/src/routes/docs/types.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.
+*/
+
+import listTypes from '../../../lib/docs/listTypes.js';
+import normalizeTypeKind from '../../../lib/docs/normalizeTypeKind.js';
+
+function docsTypesHandler(c) {
+  const kind = c.req.param('kind');
+  if (normalizeTypeKind({ kind }) === null) {
+    return c.json(
+      {
+        error: `Unknown docs kind "${kind}". Use one of: blocks, operators, actions, connections, requests, agents, notifications, websockets. See GET /lowdefy-docs for all routes.`,
+      },
+      404
+    );
+  }
+  return c.json(listTypes({ kind }));
+}
+
+export default docsTypesHandler;

package/src/routes/endpoints.js

@@ -0,0 +1,71 @@
+/*
+  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 { callEndpoint, getEndpointConfig, 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.');
+  }
+  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.
+  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 */
+    }
+    context.logger.info({ event: 'call_webhook_endpoint', endpointId });
+    const result = await runWebhookEndpoint(context, {
+      endpointId,
+      body,
+      query: c.req.query(),
+      headers: c.req.header(),
+    });
+    if (!result.success) {
+      return c.json({ error: 'Webhook failed.' }, 500);
+    }
+    return c.json(result.response ?? { ok: true });
+  }
+
+  const { blockId, payload, pageId } = await c.req.json();
+  context.logger.info({ event: 'call_api_endpoint', blockId, endpointId, pageId });
+  const response = await callEndpoint(context, { blockId, endpointId, pageId, payload });
+  return c.json(response);
+}
+
+export default endpointsHandler;

package/src/routes/feedback.js

@@ -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 enrichFeedback from '../../lib/docs/enrichFeedback.js';
+import formatFeedback from '../../lib/docs/formatFeedback.js';
+import createLogger from '../../lib/server/log/createLogger.js';
+
+const logger = createLogger({ server: 'lowdefy-dev-feedback' });
+
+// Receives annotation batches from the dev browser overlay (a developer
+// draws on a live page and comments), enriches each annotation with its
+// yaml file:line via findConfig, and returns the formatted agent-readable
+// text. The overlay copies that text to the clipboard — the developer
+// pastes it into whichever agent session they choose, which is also what
+// makes delivery unambiguous when several sessions share one dev server.
+// Same-origin check cloned from routes/clientError.js: only a page served
+// by this dev server (not an arbitrary site) should be able to use it.
+async function feedbackHandler(c) {
+  const origin = c.req.header('origin');
+  if (!origin) {
+    return c.json({ error: 'Forbidden' }, 403);
+  }
+  try {
+    if (new URL(origin).host !== c.req.header('host')) {
+      return c.json({ error: 'Forbidden' }, 403);
+    }
+  } catch {
+    return c.json({ error: 'Forbidden' }, 403);
+  }
+
+  const batch = await c.req.json();
+  if (!Array.isArray(batch?.annotations)) {
+    return c.json(
+      {
+        error:
+          'Feedback batch requires an "annotations" array. See GET /lowdefy-docs for the ' +
+          'feedback batch shape.',
+      },
+      400
+    );
+  }
+
+  // The tab screenshot rides in as a multi-MB data URL — lift it off the
+  // batch before enrichment so it never reaches the formatted text or the
+  // headless capture path.
+  const tabScreenshot = batch.screenshot;
+  delete batch.screenshot;
+  let enriched = await enrichFeedback({ batch });
+  delete enriched.screenshot;
+
+  // Default on — the overlay sends includeScreenshot: false when the
+  // developer unticks it.
+  if (batch.includeScreenshot !== false) {
+    const fileName = `${batch.pageId}-${new Date().toISOString().replace(/[:.]/g, '-')}.png`;
+    if (typeof tabScreenshot === 'string') {
+      // Preferred path: the overlay captured the developer's actual tab —
+      // theme, loaded data, exact pixels — with annotations already drawn.
+      const { default: saveAnnotatedScreenshot } = await import(
+        '../../lib/docs/saveAnnotatedScreenshot.js'
+      );
+      const result = saveAnnotatedScreenshot({ dataUrl: tabScreenshot, fileName });
+      if (result.path) {
+        enriched = { ...enriched, screenshotPath: result.path };
+      } else {
+        logger.warn(result.error);
+      }
+    } else {
+      // Fallback: re-render the page headless (batches from agents or older
+      // clients, or when the in-tab capture failed). The response must NOT
+      // wait for this capture: the overlay writes the clipboard when this
+      // returns, and Chrome's transient user-activation (required for
+      // clipboard writes) expires within ~5s — a headless browser launch can
+      // take longer. So the path is pre-assigned, the formatted text returns
+      // immediately, and the PNG lands on disk a moment later — well before
+      // a human pastes it anywhere.
+      // Deferred import: the capture module pulls in the browser singleton,
+      // which reads build artifacts at import time — only load it when a
+      // screenshot is actually wanted.
+      const { default: captureAnnotatedScreenshot } = await import(
+        '../../lib/docs/captureAnnotatedScreenshot.js'
+      );
+      const serverOrigin = new URL(c.req.url).origin;
+      enriched = { ...enriched, screenshotPath: `.lowdefy/annotations/${fileName}` };
+      captureAnnotatedScreenshot({ origin: serverOrigin, batch: enriched, fileName }).then(
+        (result) => {
+          if (result.error) {
+            logger.warn(result.error);
+          }
+        }
+      );
+    }
+  }
+
+  return c.json({ ok: true, formatted: formatFeedback({ items: [enriched] }) });
+}
+
+export default feedbackHandler;