@lowdefy/api 5.6.0 → 6.0.0

package/dist/routes/auth/strategies/createAuthStrategies.js

@@ -0,0 +1,77 @@
+/*
+  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 { ServerParser } from '@lowdefy/operators';
+import { _app, _secret } from '@lowdefy/operators-js/operators/server';
+import { type } from '@lowdefy/helpers';
+import { ConfigError } from '@lowdefy/errors';
+// Builds the API auth strategy verifiers from the auth.json build artifact.
+// Build has validated the config and written all defaults, so this resolves
+// the _secret operators and constructs each strategy type's verifier.
+// Verifier factories warn on short static keys at construction, so key
+// strength surfaces at startup, never as a build failure.
+function createAuthStrategies({ appMeta, authJson, logger, plugins, secrets }) {
+    if (!type.isArray(authJson.strategies) || authJson.strategies.length === 0) {
+        return [];
+    }
+    const operatorsParser = new ServerParser({
+        lowdefyApp: appMeta,
+        operators: {
+            _app,
+            _secret
+        },
+        secrets,
+        user: {}
+    });
+    const { output: strategiesConfig, errors: operatorErrors } = operatorsParser.parse({
+        input: authJson.strategies,
+        location: 'auth.strategies',
+        payload: {}
+    });
+    if (operatorErrors.length > 0) {
+        // Startup fails on the first error; log the rest so they can all be
+        // fixed in one pass instead of one boot per error.
+        operatorErrors.slice(1).forEach((error)=>logger.error(error));
+        throw operatorErrors[0];
+    }
+    return strategiesConfig.map((strategy)=>{
+        const strategyPlugin = plugins.strategies[strategy.type];
+        if (type.isNone(strategyPlugin)) {
+            throw new ConfigError(`Auth strategy type "${strategy.type}" not found at strategy "${strategy.id}".`, {
+                configKey: strategy['~k']
+            });
+        }
+        let verify;
+        try {
+            verify = strategyPlugin({
+                logger,
+                properties: strategy.properties,
+                strategyId: strategy.id
+            });
+        } catch (error) {
+            throw new ConfigError(error.message, {
+                cause: error,
+                configKey: strategy['~k']
+            });
+        }
+        return {
+            attributes: strategy.attributes,
+            id: strategy.id,
+            roles: strategy.roles,
+            type: strategy.type,
+            verify
+        };
+    });
+}
+export default createAuthStrategies;

package/dist/routes/auth/strategies/getAuthStrategies.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.
+*/ import createAuthStrategies from './createAuthStrategies.js';
+let strategies;
+// The strategy verifiers are constructed once per process at first use -
+// the server middleware tries them in config order on every request that
+// resolves no session.
+function getAuthStrategies({ appMeta, authJson, logger, plugins, secrets }) {
+    if (strategies) return strategies;
+    strategies = createAuthStrategies({
+        appMeta,
+        authJson,
+        logger,
+        plugins,
+        secrets
+    });
+    return strategies;
+}
+export default getAuthStrategies;

package/dist/routes/endpoints/authorizeApiEndpoint.js

@@ -12,14 +12,20 @@
   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 { ConfigError } from '@lowdefy/errors';
-function authorizeApiEndpoint({ authorize, logger }, { endpointConfig }) {
+*/ import { AuthenticationError, ConfigError } from '@lowdefy/errors';
+import { type } from '@lowdefy/helpers';
+function authorizeApiEndpoint({ authorize, logger, user }, { endpointConfig }) {
     if (!authorize(endpointConfig)) {
         logger.debug({
             event: 'debug_api_authorize',
             authorized: false,
             auth_config: endpointConfig.auth
         });
+        // Unauthenticated on a protected endpoint - 401 tells the caller to fix
+        // its credentials. Wrong roles stay opaque below.
+        if (type.isNone(user)) {
+            throw new AuthenticationError(`Authentication required for API endpoint "${endpointConfig.endpointId}".`);
+        }
         throw new ConfigError(`API Endpoint "${endpointConfig.endpointId}" does not exist.`);
     }
     logger.debug({

package/dist/routes/endpoints/callEndpoint.js

@@ -13,12 +13,14 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */ import { serializer } from '@lowdefy/helpers';
-import { ConfigError } from '@lowdefy/errors';
+import { AuthenticationError, ConfigError } from '@lowdefy/errors';
 import authorizeApiEndpoint from './authorizeApiEndpoint.js';
 import buildEndpointResult from '../../response/buildEndpointResult.js';
 import createEvaluateOperators from '../../context/createEvaluateOperators.js';
 import getEndpointConfig from './getEndpointConfig.js';
+import isUnauthenticatedHuman from './isUnauthenticatedHuman.js';
 import runRoutine from './runRoutine.js';
+import scheduleBackground from './scheduleBackground.js';
 async function callEndpoint(context, { blockId, endpointId, pageId, payload }) {
     const { logger } = context;
     context.blockId = blockId;
@@ -35,9 +37,11 @@ async function callEndpoint(context, { blockId, endpointId, pageId, payload }) {
     const endpointConfig = await getEndpointConfig(context, {
         endpointId
     });
-    // Block HTTP access to InternalApi endpoints — same error as missing endpoint
+    // Block HTTP access to InternalApi endpoints - same error as a missing
+    // endpoint, including the unauthenticated fork, so an internal endpoint is
+    // indistinguishable from one that does not exist on both paths.
     if (endpointConfig.type === 'InternalApi') {
-        const err = new ConfigError(`API Endpoint "${endpointId}" does not exist.`);
+        const err = await isUnauthenticatedHuman(context) ? new AuthenticationError(`Authentication required for API endpoint "${endpointId}".`) : new ConfigError(`API Endpoint "${endpointId}" does not exist.`);
         logger.debug({
             params: {
                 endpointId
@@ -57,6 +61,25 @@ async function callEndpoint(context, { blockId, endpointId, pageId, payload }) {
         state: {},
         endpointDepth: 0
     };
+    // async: true — acknowledge now, run the routine in the background.
+    // Auth was already checked above; the outcome lands in logs (scheduleBackground)
+    // and in whatever the routine itself records.
+    if (endpointConfig.async === true) {
+        scheduleBackground(context, {
+            event: 'background_endpoint',
+            endpointId
+        }, ()=>runRoutine(context, routineContext, {
+                routine: endpointConfig.routine
+            }));
+        return {
+            error: null,
+            response: serializer.serialize({
+                accepted: true
+            }),
+            status: 'accepted',
+            success: true
+        };
+    }
     const { error, response, status } = await runRoutine(context, routineContext, {
         routine: endpointConfig.routine
     });

package/dist/routes/endpoints/control/controlReject.js

@@ -37,9 +37,11 @@ async function controlReject(context, routineContext, { control }) {
         cause,
         isReject: true
     });
+    // Log under `err` — see controlThrow: only the `err` key runs the pino error
+    // serializer, so `error` would drop the message from the log line.
     context.logger.warn({
         event: 'warn_control_reject',
-        error
+        err: error
     });
     return {
         status: 'reject',

package/dist/routes/endpoints/control/controlThrow.js

@@ -36,9 +36,12 @@ async function controlThrow(context, routineContext, { control }) {
     const error = new UserError(message, {
         cause
     });
+    // Log under `err` — the pino error serializer (createNodeLogger) is registered
+    // for the `err` key only; an Error passed as `error` is JSON-dumped without its
+    // non-enumerable `message`/`stack`, producing a log line with no message.
     context.logger.error({
         event: 'error_control_throw',
-        error
+        err: error
     });
     return {
         status: 'error',

package/dist/routes/endpoints/findSchedule.js

@@ -0,0 +1,35 @@
+/*
+  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 { ConfigError } from '@lowdefy/errors';
+// Vercel sends the firing expression in x-vercel-cron-schedule; cron expressions are unique per
+// endpoint and environment (enforced at build) so this is unambiguous. Without a cron (e.g. local
+// testing) fall back to the single schedule, otherwise require it to disambiguate the payload.
+function findSchedule({ schedules, cron, endpointId, environment }) {
+    const where = environment === undefined ? '' : ` for environment "${environment}"`;
+    if (!Array.isArray(schedules) || schedules.length === 0) {
+        throw new ConfigError(`API Endpoint "${endpointId}" is not scheduled${where}.`);
+    }
+    let schedule;
+    if (cron) {
+        schedule = schedules.find((s)=>s.cron === cron);
+    } else if (schedules.length === 1) {
+        schedule = schedules[0];
+    }
+    if (!schedule) {
+        throw new ConfigError(`No schedule matching cron "${cron}" for API Endpoint "${endpointId}"${where}.`);
+    }
+    return schedule;
+}
+export default findSchedule;

package/dist/routes/endpoints/forwardScheduledEndpoint.js

@@ -0,0 +1,106 @@
+/*
+  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 { serializer, type } from '@lowdefy/helpers';
+import { ConfigError } from '@lowdefy/errors';
+import findSchedule from './findSchedule.js';
+import getEndpointConfig from './getEndpointConfig.js';
+import getEnvironmentSchedules from './getEnvironmentSchedules.js';
+import scheduleBackground from './scheduleBackground.js';
+// Vercel fires cron jobs only on the production deployment, so the schedules of every other
+// environment are registered there as /api/cron-forward/<environment>/<endpointId> jobs. When one
+// fires, this pings the environment's own /api/cron/<endpointId> with that environment's
+// CRON_SECRET (a Lowdefy secret named in config.cron.environments) so the environment runs its own
+// code, and answers Vercel immediately: the ping is fire-and-forget, kept alive by scheduleBackground
+// and bounded by the function duration, and its outcome exists only in the logs.
+async function forwardScheduledEndpoint(context, { environment, endpointId, cron }) {
+    const { config, logger, secrets } = context;
+    const target = config?.cron?.environments?.[environment];
+    if (!type.isObject(target)) {
+        throw new ConfigError(`Cron environment "${environment}" is not declared in lowdefy.config.cron.environments.`);
+    }
+    if (type.isUndefined(target.url)) {
+        throw new ConfigError(`Cron environment "${environment}" has no url to forward to: it is the environment that runs the crons.`);
+    }
+    if (target.enabled === false) {
+        throw new ConfigError(`Cron environment "${environment}" is disabled.`);
+    }
+    const secret = secrets?.[target.secret];
+    if (!type.isString(secret) || secret === '') {
+        throw new ConfigError(`Secret "${target.secret}" holding the CRON_SECRET of cron environment "${environment}" is not set. Set the LOWDEFY_SECRET_${target.secret} environment variable on this deployment.`);
+    }
+    // The same build is deployed to every environment, so the local artifact says whether the target
+    // declares the firing schedule: fail here with a config error instead of having the target 500.
+    const endpointConfig = await getEndpointConfig(context, {
+        endpointId
+    });
+    const schedules = getEnvironmentSchedules({
+        endpointConfig,
+        environment
+    });
+    findSchedule({
+        schedules,
+        cron,
+        endpointId,
+        environment
+    });
+    // Trim trailing slashes with a loop rather than a regex: CodeQL flags `/\/+$/` on config input.
+    let origin = target.url;
+    while(origin.endsWith('/')){
+        origin = origin.slice(0, -1);
+    }
+    const url = `${origin}/api/cron/${endpointId}`;
+    const timeoutMs = (config?.vercel?.maxDuration ?? 60) * 1000;
+    const headers = {
+        authorization: `Bearer ${secret}`
+    };
+    if (cron) headers['x-vercel-cron-schedule'] = cron;
+    headers['x-lowdefy-cron-environment'] = environment;
+    logger.info({
+        event: 'forward_scheduled_endpoint',
+        endpointId,
+        environment,
+        cron,
+        url
+    });
+    scheduleBackground(context, {
+        event: 'forward_scheduled_endpoint',
+        endpointId
+    }, async ()=>{
+        const response = await fetch(url, {
+            method: 'GET',
+            headers,
+            signal: AbortSignal.timeout(timeoutMs)
+        });
+        // Drain the body so the connection is released; the target logs its own outcome.
+        await response.arrayBuffer();
+        if (!response.ok) {
+            throw new Error(`Forwarded cron for environment "${environment}" at ${url} responded ${response.status}.`);
+        }
+        return {
+            status: response.status
+        };
+    });
+    return {
+        error: null,
+        response: serializer.serialize({
+            accepted: true,
+            environment,
+            endpointId
+        }),
+        status: 'accepted',
+        success: true
+    };
+}
+export default forwardScheduledEndpoint;

package/dist/routes/endpoints/getEndpointConfig.js

@@ -12,11 +12,17 @@
   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 { ConfigError } from '@lowdefy/errors';
-async function getEndpointConfig({ logger, readConfigFile }, { endpointId }) {
+*/ import { AuthenticationError, ConfigError } from '@lowdefy/errors';
+import isUnauthenticatedHuman from './isUnauthenticatedHuman.js';
+// A missing endpoint answers the same as a protected one for an anonymous
+// caller on an auth'd app - the message is byte-identical to the one
+// authorizeApiEndpoint throws, so present and absent are indistinguishable
+// before authenticating. Every other caller keeps the opaque does-not-exist.
+async function getEndpointConfig(context, { endpointId }) {
+    const { logger, readConfigFile } = context;
     const endpoint = await readConfigFile(`api/${endpointId}.json`);
     if (!endpoint) {
-        const err = new ConfigError(`API Endpoint "${endpointId}" does not exist.`);
+        const err = await isUnauthenticatedHuman(context) ? new AuthenticationError(`Authentication required for API endpoint "${endpointId}".`) : new ConfigError(`API Endpoint "${endpointId}" does not exist.`);
         logger.debug({
             params: {
                 endpointId

package/dist/routes/endpoints/getEnvironmentSchedules.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 { type } from '@lowdefy/helpers';
+// With config.cron.environments declared the build resolves `schedules` onto every environment
+// (schedules.<name>, defaults inherited), so an environment run reads its own list; without
+// environments the endpoint carries a plain array.
+function getEnvironmentSchedules({ endpointConfig, environment }) {
+    const schedules = endpointConfig.schedules;
+    if (type.isArray(schedules)) {
+        return schedules;
+    }
+    if (environment === undefined) {
+        return [];
+    }
+    return schedules?.[environment] ?? [];
+}
+export default getEnvironmentSchedules;

package/dist/routes/endpoints/handleAgentCall.js

@@ -0,0 +1,83 @@
+/*
+  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 { ConfigError } from '@lowdefy/errors';
+import { type } from '@lowdefy/helpers';
+import addStepResult from './addStepResult.js';
+import prepareAgent from '../agent/prepareAgent.js';
+async function handleAgentCall(context, routineContext, { step }) {
+    const { logger, evaluateOperators } = context;
+    logger.debug({
+        event: 'debug_start_agent_call',
+        step
+    });
+    // Evaluate operators in step.properties (resolves agentId, prompt)
+    const evaluatedProperties = evaluateOperators({
+        input: step.properties,
+        items: routineContext.items,
+        location: step.stepId,
+        payload: routineContext.payload,
+        state: routineContext.state,
+        steps: routineContext.steps
+    });
+    const { agentId, prompt } = evaluatedProperties;
+    if (!type.isString(agentId)) {
+        throw new ConfigError(`CallAgent step "${step.stepId}" properties.agentId must evaluate to a string. Received ${JSON.stringify(agentId)}.`, {
+            configKey: step['~k']
+        });
+    }
+    if (!type.isString(prompt)) {
+        throw new ConfigError(`CallAgent step "${step.stepId}" properties.prompt must evaluate to a string. Received ${JSON.stringify(prompt)}.`, {
+            configKey: step['~k']
+        });
+    }
+    // Headless agent context — no page, no conversation, no sharedState (which
+    // also excludes the client-only update-page-state tool). userId is null
+    // under scheduled (system) context.
+    const agentContext = {
+        conversationId: null,
+        pageId: null,
+        sharedState: undefined,
+        urlQuery: {},
+        userId: context.user?.sub ?? context.user?.id ?? null
+    };
+    const { agentConfig, connectionInstance, agentType, resolverContext } = await prepareAgent(context, {
+        agentId,
+        agentContext,
+        endpointDepth: routineContext.endpointDepth,
+        mode: 'generate'
+    });
+    const { result } = await agentType.resolver({
+        connection: connectionInstance,
+        properties: {
+            agent: agentConfig,
+            prompt
+        },
+        context: resolverContext
+    });
+    addStepResult(context, routineContext, {
+        result,
+        stepId: step.stepId
+    });
+    logger.debug({
+        event: 'debug_end_agent_call',
+        stepId: step.stepId,
+        targetAgentId: agentId,
+        finishReason: result?.finishReason
+    });
+    return {
+        status: 'continue'
+    };
+}
+export default handleAgentCall;

package/dist/routes/endpoints/handleEndpointCall.js

@@ -12,8 +12,11 @@
   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 addStepResult from './addStepResult.js';
+*/ import { serializer } from '@lowdefy/helpers';
+import { ConfigError } from '@lowdefy/errors';
+import addStepResult from './addStepResult.js';
 import invokeEndpoint from './invokeEndpoint.js';
+import scheduleBackground from './scheduleBackground.js';
 async function handleEndpointCall(context, routineContext, { step }) {
     const { logger, evaluateOperators } = context;
     logger.debug({
@@ -29,6 +32,51 @@ async function handleEndpointCall(context, routineContext, { step }) {
         state: routineContext.state,
         steps: routineContext.steps
     });
+    // detached: true — fire-and-forget the call back through the deployment's
+    // /api/detached route, so the target runs in its OWN function invocation
+    // with a fresh duration budget (chainable bounded work without a queue).
+    // At-most-once, no retry: targets must be idempotent. The dispatch promise
+    // rides the platform request context so the outgoing request always leaves
+    // before the invocation is reaped; the target's own outcome exists only in
+    // its logs and whatever its routine writes.
+    if (evaluatedProperties.detached === true) {
+        if (!process.env.CRON_SECRET) {
+            throw new ConfigError('CallApi with "detached: true" requires the CRON_SECRET environment variable — the /api/detached route fails closed without it.');
+        }
+        if (!context.origin) {
+            throw new ConfigError('Detached endpoint calls require the request origin on context.');
+        }
+        const targetEndpointId = evaluatedProperties.endpointId;
+        scheduleBackground(context, {
+            event: 'detached_dispatch',
+            endpointId: targetEndpointId
+        }, ()=>fetch(`${context.origin}/api/detached/${targetEndpointId}`, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    authorization: `Bearer ${process.env.CRON_SECRET}`
+                },
+                body: JSON.stringify({
+                    payload: serializer.serialize(evaluatedProperties.payload ?? {})
+                })
+            }));
+        addStepResult(context, routineContext, {
+            result: {
+                detached: true,
+                endpointId: targetEndpointId
+            },
+            stepId: step.stepId
+        });
+        logger.debug({
+            event: 'debug_end_endpoint_call',
+            stepId: step.stepId,
+            targetEndpointId,
+            detached: true
+        });
+        return {
+            status: 'continue'
+        };
+    }
     const result = await invokeEndpoint(context, {
         endpointId: evaluatedProperties.endpointId,
         payload: evaluatedProperties.payload,