@lowdefy/operators-js 6.0.0 → 7.0.0

package/dist/checks.js

@@ -0,0 +1,24 @@
+/*
+  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 ifTest from './operators/shared/if.check.js';
+// Build check rules, run by the Lowdefy build on each config node of these
+// types. Import only what the rules need, never operator runtime code.
+export default {
+    operators: {
+        _if: [
+            ifTest
+        ]
+    }
+};

package/dist/metas.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.
+*/ // Operator metas carry only `hazards`: behaviours of an operator that its
+// schema cannot express. The build writes them to plugins/operatorMetas.json
+// for the dev MCP; operators without hazards need no entry here.
+export const _js = {
+    hazards: [
+        {
+            id: 'js-two-prototypes',
+            message: 'A _js body in a page receives { actions, args, event, input, location, lowdefyApp, lowdefyGlobal, pathParams, request, state, urlQuery, user }, while the same body in a request, connection or endpoint receives { args, item, lowdefyApp, payload, secret, state, step, user }. Only where the operator sits in the config decides which, so a body written for one place fails silently in the other.',
+            see: 'operators/_js'
+        }
+    ]
+};

package/dist/operators/build/authConfig.js

@@ -0,0 +1,62 @@
+/*
+  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 { get, type } from '@lowdefy/helpers';
+// The curated catalog of readable projection paths. Extending it is a
+// deliberate addition to this list — never a fall-through.
+const readablePaths = [
+    'emailAndPassword.enabled',
+    'magicLink.enabled',
+    'emailOTP.enabled',
+    'twoFactor.enabled',
+    'twoFactor.required',
+    'twoFactor.trustDevice',
+    'passkey.enabled',
+    'phoneNumber.enabled',
+    'phoneNumber.signUpOnVerification',
+    'captcha.enabled',
+    'captcha.provider',
+    'captcha.siteKey',
+    'providers',
+    'organizations.policy',
+    'organizations.signup',
+    'roles'
+];
+// Build-only operator, addressed as { _build.authConfig: '<path>' }. Reads the
+// auth config projection the build computes in a scoped pre-pass before
+// buildRefs. It deliberately has no runtime sibling — none of this data ships
+// to the client or server at runtime.
+function _authConfig({ authConfig, params }) {
+    if (type.isUndefined(authConfig)) {
+        // The projection is present on the build context after the pre-pass, so an
+        // undefined projection means the operator ran somewhere it can never
+        // exist: inside the auth: block during the pre-pass (self-reference), or
+        // in app metadata (app:), which resolves earlier and is never re-walked.
+        // Walks whose output IS re-walked post-projection (module entry vars,
+        // deferred-record bodies) defer the fold instead of reaching this throw.
+        throw new ConfigError("_build.authConfig is not available here. The auth config projection is computed from the app's auth: block, so the operator can not resolve inside that block itself (a self-reference), nor in app metadata (app:), which resolves earlier.");
+    }
+    if (!readablePaths.includes(params)) {
+        throw new ConfigError(`_build.authConfig received an unreadable path ${JSON.stringify(params)}. Readable paths are: ${readablePaths.map((path)=>`"${path}"`).join(', ')}.`);
+    }
+    return get(authConfig, params, {
+        copy: true
+    });
+}
+// dynamic true keeps the bare _authConfig spelling out of build-time static
+// evaluation — the only supported address is the explicit _build.authConfig,
+// which evaluates regardless of dynamic (matching _build.app).
+_authConfig.dynamic = true;
+export default _authConfig;

package/dist/operators/build/authConfig.schema.js

@@ -0,0 +1,37 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ export default {
+    type: 'object',
+    params: {
+        type: 'string',
+        enum: [
+            'emailAndPassword.enabled',
+            'magicLink.enabled',
+            'emailOTP.enabled',
+            'twoFactor.enabled',
+            'passkey.enabled',
+            'phoneNumber.enabled',
+            'phoneNumber.signUpOnVerification',
+            'captcha.enabled',
+            'captcha.provider',
+            'captcha.siteKey',
+            'providers',
+            'organizations.policy',
+            'organizations.signup',
+            'roles'
+        ],
+        description: 'Curated auth config projection path to read at build time.'
+    }
+};

package/dist/operators/client/_index.js

@@ -23,4 +23,10 @@ function _index({ arrayIndices, location, params }) {
     });
 }
 _index.dynamic = true;
+_index.tracking = {
+    kind: 'read',
+    keys: ()=>[
+            'index'
+        ]
+};
 export default _index;

package/dist/operators/client/actions.js

@@ -23,4 +23,8 @@ function _actions({ actions, arrayIndices, location, params }) {
     });
 }
 _actions.dynamic = true;
+// Reads only the action results of its own parse frame, which no update changes.
+_actions.tracking = {
+    kind: 'pure'
+};
 export default _actions;

package/dist/operators/client/api.js

@@ -41,4 +41,13 @@ function _api({ params, apiResponses }) {
     return null;
 }
 _api.dynamic = true;
+// Keyed by endpoint id, the first path segment, which is what an API call update reports.
+_api.tracking = {
+    kind: 'read',
+    keys: ({ params })=>type.isString(params) ? [
+            `api:${params.split('.')[0]}`
+        ] : [
+            'api:*'
+        ]
+};
 export default _api;

package/dist/operators/client/base64.js

@@ -48,4 +48,7 @@ function _base64({ params, location, methodName }) {
     });
 }
 _base64.dynamic = true;
+_base64.tracking = {
+    kind: 'pure'
+};
 export default _base64;

package/dist/operators/client/event.js

@@ -23,4 +23,8 @@ function _event({ arrayIndices, event, location, params }) {
     });
 }
 _event.dynamic = true;
+// Reads only the event of its own parse frame, which no update changes.
+_event.tracking = {
+    kind: 'pure'
+};
 export default _event;

package/dist/operators/client/event_log.js

@@ -23,4 +23,8 @@ function _event_log({ arrayIndices, eventLog, location, params }) {
     });
 }
 _event_log.dynamic = true;
+// The event log is written with no change reported.
+_event_log.tracking = {
+    kind: 'untracked'
+};
 export default _event_log;

package/dist/operators/client/global.js

@@ -12,7 +12,7 @@
   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 { getFromObject } from '@lowdefy/operators';
+*/ import { getFromObject, getObjectReadKeys } from '@lowdefy/operators';
 function _global({ arrayIndices, location, lowdefyGlobal, params }) {
     return getFromObject({
         arrayIndices,
@@ -23,4 +23,12 @@ function _global({ arrayIndices, location, lowdefyGlobal, params }) {
     });
 }
 _global.dynamic = true;
+_global.tracking = {
+    kind: 'read',
+    keys: ({ arrayIndices, params })=>getObjectReadKeys({
+            arrayIndices,
+            namespace: 'global',
+            params
+        })
+};
 export default _global;

package/dist/operators/client/input.js

@@ -12,7 +12,7 @@
   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 { getFromObject } from '@lowdefy/operators';
+*/ import { getFromObject, getObjectReadKeys } from '@lowdefy/operators';
 function _input({ arrayIndices, input, location, params }) {
     return getFromObject({
         arrayIndices,
@@ -23,4 +23,12 @@ function _input({ arrayIndices, input, location, params }) {
     });
 }
 _input.dynamic = true;
+_input.tracking = {
+    kind: 'read',
+    keys: ({ arrayIndices, params })=>getObjectReadKeys({
+            arrayIndices,
+            namespace: 'input',
+            params
+        })
+};
 export default _input;

package/dist/operators/client/js.js

@@ -18,7 +18,7 @@ function js(operatorContext) {
     const hash = type.isString(params) ? params : params?.fn;
     const args = type.isObject(params) ? params.args : undefined;
     if (!jsMap[hash]) {
-        throw new Error(`_js function not found. The function may not have been built yet. Received hash: ${hash}`);
+        throw new Error(`_js function not found. The function may not have been built yet, or the page is running a client bundle from an older build - reload the page to update. Received hash: ${hash}`);
     }
     try {
         return jsMap[hash]({
@@ -47,6 +47,10 @@ function js(operatorContext) {
                     ...operatorContext,
                     params: p
                 }),
+            pathParams: (p)=>operators._path_params({
+                    ...operatorContext,
+                    params: p
+                }),
             request: (p)=>operators._request({
                     ...operatorContext,
                     params: p
@@ -65,10 +69,20 @@ function js(operatorContext) {
                 })
         });
     } catch (error) {
-        throw new Error(`_js function execution error. Function: ${jsMap[hash].toString()}`, {
+        throw new Error(`_js function execution error. ${error.name}: ${error.message}`, {
             cause: error
         });
     }
 }
 js.dynamic = true;
+// The accessors call operators through the tracked registry view, so the function's reads record
+// themselves. The build marks a function volatile when its source references a browser or clock
+// global. A returned closure, even nested in an object, reads context only when it is called.
+js.tracking = ({ jsMap, params })=>{
+    const hash = type.isString(params) ? params : params?.fn;
+    return {
+        kind: jsMap?.[hash]?.volatile === true ? 'volatile' : 'pure',
+        resultMayContainFunctions: true
+    };
+};
 export default js;

package/dist/operators/client/location.js

@@ -58,4 +58,17 @@ function _location({ arrayIndices, basePath, home, location, pageId, params, glo
     });
 }
 _location.dynamic = true;
+// pageId, basePath and homePageId come from the page's context, which never changes them while
+// it lives (navigation runs a full pass). Everything else reads window.location live, which
+// changes (a hash link, navigation) with no update to report it.
+const contextProperties = [
+    'pageId',
+    'basePath',
+    'homePageId'
+];
+_location.tracking = ({ params })=>contextProperties.includes(params) ? {
+        kind: 'pure'
+    } : {
+        kind: 'volatile'
+    };
 export default _location;

package/dist/operators/client/media.js

@@ -12,50 +12,23 @@
   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 { getFromObject } from '@lowdefy/operators';
+*/ import { getFromObject, getMediaViewport, getObjectReadKeys } from '@lowdefy/operators';
+// The client keeps the preference it reads from storage, under the app's key.
 function getDarkModePreference(window) {
-    return window.localStorage?.getItem('lowdefy_darkMode') ?? 'system';
+    return window.__lowdefy_darkModePreference ?? 'system';
 }
 function getDarkMode(window) {
     return window.__lowdefy_isDark ?? false;
 }
-const breakpoints = {
-    xs: 640,
-    sm: 768,
-    md: 1024,
-    lg: 1280,
-    xl: 1536
-};
 function _media({ arrayIndices, location, params, globals }) {
     const { window } = globals;
     if (!window?.innerWidth) {
         throw new Error(`device window width not available for _media.`);
     }
-    let size;
-    switch(true){
-        case window.innerWidth < breakpoints.xs:
-            size = 'xs';
-            break;
-        case window.innerWidth < breakpoints.sm:
-            size = 'sm';
-            break;
-        case window.innerWidth < breakpoints.md:
-            size = 'md';
-            break;
-        case window.innerWidth < breakpoints.lg:
-            size = 'lg';
-            break;
-        case window.innerWidth < breakpoints.xl:
-            size = 'xl';
-            break;
-        default:
-            size = '2xl';
-            break;
-    }
     const media = {
-        size,
-        width: window.innerWidth,
-        height: window.innerHeight,
+        ...getMediaViewport({
+            window
+        }),
         darkMode: getDarkMode(window),
         darkModePreference: getDarkModePreference(window)
     };
@@ -68,4 +41,15 @@ function _media({ arrayIndices, location, params, globals }) {
     });
 }
 _media.dynamic = true;
+// The page's resize listener reports media:size, media:width and media:height when they change, so
+// a block reading _media: size re-evaluates only when the breakpoint changes. Dark mode changes
+// re-render the app, and that render-time full pass evaluates every block (as for _theme).
+_media.tracking = {
+    kind: 'read',
+    keys: ({ arrayIndices, params })=>getObjectReadKeys({
+            arrayIndices,
+            namespace: 'media',
+            params
+        })
+};
 export default _media;

package/dist/operators/client/menu.js

@@ -46,4 +46,10 @@ function _menu({ params, arrayIndices, menus, location }) {
     return result;
 }
 _menu.dynamic = true;
+_menu.tracking = {
+    kind: 'read',
+    keys: ()=>[
+            'menu'
+        ]
+};
 export default _menu;

package/dist/operators/client/path_params.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 { getFromObject } from '@lowdefy/operators';
+function _path_params({ arrayIndices, location, params, pathParams }) {
+    return getFromObject({
+        arrayIndices,
+        location,
+        object: pathParams,
+        operator: '_path_params',
+        params
+    });
+}
+_path_params.dynamic = true;
+// A page instance's path values are fixed for the instance's context: a different value is a
+// different instance.
+_path_params.tracking = {
+    kind: 'pure'
+};
+export default _path_params;

package/dist/operators/client/path_params.schema.js

@@ -0,0 +1,49 @@
+/*
+  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.
+*/ export default {
+    type: 'object',
+    params: {
+        oneOf: [
+            {
+                type: 'string',
+                description: 'Name of the path placeholder to return, or a dot-notation path into the values.'
+            },
+            {
+                type: 'boolean',
+                enum: [
+                    true
+                ],
+                description: 'Return all path params.'
+            },
+            {
+                type: 'object',
+                properties: {
+                    key: {
+                        type: 'string',
+                        description: 'Name of the path placeholder to return, or a dot-notation path into the values.'
+                    },
+                    default: {
+                        description: 'Default value if key does not exist.'
+                    },
+                    all: {
+                        type: 'boolean',
+                        description: 'Return all path params.'
+                    }
+                },
+                additionalProperties: false
+            }
+        ]
+    }
+};

package/dist/operators/client/request.js

@@ -41,4 +41,13 @@ function _request({ arrayIndices, params, requests }) {
     return null;
 }
 _request.dynamic = true;
+// Keyed by request id, the first path segment, which is what a request update reports.
+_request.tracking = {
+    kind: 'read',
+    keys: ({ params })=>type.isString(params) ? [
+            `request:${params.split('.')[0]}`
+        ] : [
+            'request:*'
+        ]
+};
 export default _request;

package/dist/operators/client/request_details.js

@@ -12,7 +12,7 @@
   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 { getFromObject } from '@lowdefy/operators';
+*/ import { getFromObject, getObjectReadKeys } from '@lowdefy/operators';
 function _request_details({ params, requests, arrayIndices, location }) {
     return getFromObject({
         arrayIndices,
@@ -23,4 +23,13 @@ function _request_details({ params, requests, arrayIndices, location }) {
     });
 }
 _request_details.dynamic = true;
+// Keyed by request id, the first path segment, which is what a request update reports.
+_request_details.tracking = {
+    kind: 'read',
+    keys: ({ arrayIndices, params })=>getObjectReadKeys({
+            arrayIndices,
+            namespace: 'request',
+            params
+        }).map((key)=>key.split('.')[0])
+};
 export default _request_details;

package/dist/operators/client/theme.js

@@ -23,4 +23,11 @@ function _theme({ arrayIndices, location, theme, params }) {
     });
 }
 _theme.dynamic = true;
+// Theme changes reach the engine through the full render-time pass, which evaluates every block.
+_theme.tracking = {
+    kind: 'read',
+    keys: ()=>[
+            'theme'
+        ]
+};
 export default _theme;

package/dist/operators/client/url_query.js

@@ -28,4 +28,8 @@ function _url_query({ arrayIndices, globals, location, params }) {
     });
 }
 _url_query.dynamic = true;
+// Reads window.location.search live, which changes with no update to report it.
+_url_query.tracking = {
+    kind: 'volatile'
+};
 export default _url_query;

package/dist/operators/client/websocket.js

@@ -44,4 +44,8 @@ function _websocket({ arrayIndices, params, websockets }) {
     }
 }
 _websocket.dynamic = true;
+// No change key is reported for websocket channels yet.
+_websocket.tracking = {
+    kind: 'untracked'
+};
 export default _websocket;

package/dist/operators/server/agent.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 { getFromObject } from '@lowdefy/operators';
+// Reads the agent ({ id, conversationId, files, sharedState }) the engine put on the routine when an agent
+// called the endpoint as a tool or hook. On any other call there is no agent, and every read
+// resolves to null or its default, the way `_error` does outside a catch.
+function _agent({ agent, arrayIndices, location, params }) {
+    return getFromObject({
+        arrayIndices,
+        location,
+        object: agent ?? null,
+        operator: '_agent',
+        params
+    });
+}
+_agent.dynamic = true;
+export default _agent;

package/dist/operators/server/agent.schema.js

@@ -0,0 +1,61 @@
+/*
+  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.
+*/ export default {
+    type: 'object',
+    params: {
+        oneOf: [
+            {
+                type: 'string',
+                enum: [
+                    'id',
+                    'conversationId',
+                    'files',
+                    'sharedState'
+                ],
+                description: 'Field of the calling agent to return: its id in agents, the id of the conversation it runs in, the files attached in that conversation, or the shared state of the chat.'
+            },
+            {
+                type: 'boolean',
+                enum: [
+                    true
+                ],
+                description: 'Return the calling agent as { id, conversationId, files, sharedState }, or null.'
+            },
+            {
+                type: 'object',
+                properties: {
+                    key: {
+                        type: 'string',
+                        enum: [
+                            'id',
+                            'conversationId',
+                            'files',
+                            'sharedState'
+                        ],
+                        description: 'Field of the calling agent to return.'
+                    },
+                    default: {
+                        description: 'Value to return when the endpoint was not called by an agent.'
+                    },
+                    all: {
+                        type: 'boolean',
+                        description: 'Return the calling agent as { id, conversationId, files, sharedState }, or null.'
+                    }
+                },
+                additionalProperties: false
+            }
+        ]
+    }
+};