@lowdefy/helpers 6.0.0 → 7.0.0

package/dist/projectCaughtError.js

@@ -0,0 +1,88 @@
+/*
+  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 { lowdefyErrorTypes, readErrorCodes } from '@lowdefy/errors';
+import mapPlainValues from './mapPlainValues.js';
+import type from './type.js';
+function identity(value) {
+    return value;
+}
+function scrubStrings(value, scrub) {
+    return mapPlainValues(value, (item)=>type.isString(item) ? scrub(item) : item);
+}
+// Own-key lookup: an error named after an Object.prototype member, such as
+// 'constructor', must fall back to Error rather than pick up that member.
+function prototypeFor(name) {
+    if (Object.hasOwn(lowdefyErrorTypes, name)) {
+        return lowdefyErrorTypes[name].prototype;
+    }
+    return Error.prototype;
+}
+function projectNode(error, scrub, seen) {
+    seen.add(error);
+    const projected = Object.create(prototypeFor(error.name));
+    // Non-enumerable, as on a constructed Error, so JSON.stringify skips it: an
+    // `_error` sent to a plugin as data (an HTTP body, a database insert) then
+    // carries no message. Assigning it would make it enumerable, which is also
+    // why this does not go through serializer.copy.
+    Object.defineProperty(projected, 'message', {
+        value: scrub(error.message),
+        enumerable: false,
+        writable: true,
+        configurable: true
+    });
+    const { code, statusCode } = readErrorCodes(error);
+    const fields = {
+        name: error.name,
+        code: type.isString(code) ? scrub(code) : code,
+        statusCode,
+        // The server's error sink sets `handled` once it has logged the error, and
+        // the client skips reporting a handled error back to the server. A rethrown
+        // `_error` without it would be logged a second time.
+        handled: error.handled,
+        // A ServiceError's Retry-After (seconds, or an HTTP date), so a routine can wait as long
+        // as the service asked before retrying, such as an enrichment worker's backoff.
+        retryAfter: error.name === 'ServiceError' ? error.retryAfter ?? undefined : undefined
+    };
+    for (const [key, value] of Object.entries(fields)){
+        if (!type.isUndefined(value)) projected[key] = value;
+    }
+    const { cause } = error;
+    if (type.isError(cause)) {
+        if (!seen.has(cause)) projected.cause = projectNode(cause, scrub, seen);
+    } else if (error.name === 'UserError') {
+        // The author wrote a UserError's cause and metaData in config; any other
+        // class's non-Error cause is library data, such as a response body.
+        if (!type.isUndefined(cause)) projected.cause = scrubStrings(cause, scrub);
+    }
+    if (error.name === 'UserError' && !type.isUndefined(error.metaData)) {
+        projected.metaData = scrubStrings(error.metaData, scrub);
+    }
+    return projected;
+}
+// The value `_error` reads: the caught error rebuilt with only the fields a
+// routine or catch list branches on (name, message, code, statusCode, handled, a
+// ServiceError's retryAfter, and the cause). `received`, `configKey`, `location`,
+// `source`, `config` and `stack` are left out - `received` can hold a token
+// fetched at runtime that the scrub does not know. The result is an Error, so
+// wherever config sends it on, the serializer's wire policy applies to it.
+function projectCaughtError(error, { scrub = identity } = {}) {
+    if (!type.isError(error)) {
+        return projectCaughtError(new Error(String(error)), {
+            scrub
+        });
+    }
+    return projectNode(error, scrub, new Set());
+}
+export default projectCaughtError;

package/dist/readChainValue.js

@@ -0,0 +1,42 @@
+/*
+  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.
+*/ // Reads a quoted value from `start` (just past its opening quote). posthog-js escapes a quote
+// in a value as \". Returns the value and the index past its closing quote, or the end of the
+// chain when the quote is never closed.
+function readChainValue(chain, start) {
+    let value = '';
+    let index = start;
+    while(index < chain.length){
+        const char = chain[index];
+        if (char === '\\' && chain[index + 1] === '"') {
+            value += '"';
+            index += 2;
+            continue;
+        }
+        if (char === '"') {
+            return {
+                value,
+                end: index + 1
+            };
+        }
+        value += char;
+        index += 1;
+    }
+    return {
+        value,
+        end: index
+    };
+}
+export default readChainValue;

package/dist/rolesHash.js

@@ -0,0 +1,34 @@
+/*
+  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 stampHash from './stampHash.js';
+// The stamp hash of a caller's roles in their active organization: the app
+// roles (_user.roles, which page and endpoint auth gates match) and the
+// organization role tier (_user.org_roles: owner, admin or member), since app
+// config can gate blocks on either. Each list is sorted, so the same set always
+// hashes the same, and the pair is JSON-encoded, so no separator inside a role
+// can make two lists read as one. The server stamps it on every response
+// (callerStamp) and the client compares it with the roles of the caller it
+// renders, so both sides use this one function.
+function rolesHash({ user }) {
+    return stampHash(JSON.stringify({
+        roles: [
+            ...user.roles ?? []
+        ].sort(),
+        org_roles: [
+            ...user.org_roles ?? []
+        ].sort()
+    }));
+}
+export default rolesHash;

package/dist/serializer.js

@@ -12,23 +12,10 @@
   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 { ActionError, BlockError, BuildError, ConfigError, ConfigWarning, LowdefyInternalError, OperatorError, PluginError, RequestError, ServiceError, UserError } from '@lowdefy/errors';
+*/ import { lowdefyErrorTypes } from '@lowdefy/errors';
 import extractErrorProps from './extractErrorProps.js';
 import type from './type.js';
 import stableStringify from './stableStringify.js';
-const lowdefyErrorTypes = {
-    ActionError,
-    BlockError,
-    BuildError,
-    ConfigError,
-    ConfigWarning,
-    LowdefyInternalError,
-    OperatorError,
-    PluginError,
-    RequestError,
-    ServiceError,
-    UserError
-};
 function propsToError(data) {
     const ErrorClass = lowdefyErrorTypes[data.name] || Error;
     const error = Object.create(ErrorClass.prototype);
@@ -41,7 +28,7 @@ function propsToError(data) {
     }
     return error;
 }
-const makeReplacer = ({ replacer, isoStringDates, skipMarkers, omitErrorProps } = {})=>(key, value)=>{
+const makeReplacer = ({ replacer, isoStringDates, skipMarkers, projectError } = {})=>(key, value)=>{
         let dateReplacer = (date)=>({
                 '~d': date.valueOf()
             });
@@ -57,7 +44,7 @@ const makeReplacer = ({ replacer, isoStringDates, skipMarkers, omitErrorProps }
         if (type.isError(newValue)) {
             return {
                 '~e': extractErrorProps(newValue, {
-                    omit: omitErrorProps
+                    project: projectError
                 })
             };
         }
@@ -219,12 +206,13 @@ const serialize = (json, options = {})=>{
             '~d': json.valueOf()
         };
     }
-    // skipMarkers is deliberately not threaded here - serialize has never applied
-    // it, and its callers depend on markers surviving.
+    // Markers survive unless the caller passes skipMarkers: config sent to the
+    // client needs them to resolve error locations, data does not.
     return JSON.parse(JSON.stringify(json, makeReplacer({
         replacer: options.replacer,
         isoStringDates: options.isoStringDates,
-        omitErrorProps: options.omitErrorProps
+        skipMarkers: options.skipMarkers,
+        projectError: options.projectError
     })));
 };
 const serializeToString = (json, options = {})=>{
@@ -240,7 +228,7 @@ const serializeToString = (json, options = {})=>{
             replacer: makeReplacer({
                 replacer: options.replacer,
                 skipMarkers: options.skipMarkers,
-                omitErrorProps: options.omitErrorProps
+                projectError: options.projectError
             }),
             space: options.space
         });
@@ -249,7 +237,7 @@ const serializeToString = (json, options = {})=>{
         replacer: options.replacer,
         isoStringDates: options.isoStringDates,
         skipMarkers: options.skipMarkers,
-        omitErrorProps: options.omitErrorProps
+        projectError: options.projectError
     }), options.space);
 };
 const deserialize = (json, options = {})=>{
@@ -265,7 +253,7 @@ const copy = (json, options = {})=>{
     if (type.isDate(json)) return new Date(json.valueOf());
     return JSON.parse(JSON.stringify(json, makeReplacer({
         replacer: options.replacer,
-        omitErrorProps: options.omitErrorProps
+        projectError: options.projectError
     })), makeReviver(options.reviver));
 };
 const serializer = {

package/dist/sha256Hex.js

@@ -0,0 +1,170 @@
+/*
+  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.
+*/ // SHA-256 round constants: the first 32 bits of the fractional parts of the
+// cube roots of the first 64 primes.
+const K = [
+    0x428a2f98,
+    0x71374491,
+    0xb5c0fbcf,
+    0xe9b5dba5,
+    0x3956c25b,
+    0x59f111f1,
+    0x923f82a4,
+    0xab1c5ed5,
+    0xd807aa98,
+    0x12835b01,
+    0x243185be,
+    0x550c7dc3,
+    0x72be5d74,
+    0x80deb1fe,
+    0x9bdc06a7,
+    0xc19bf174,
+    0xe49b69c1,
+    0xefbe4786,
+    0x0fc19dc6,
+    0x240ca1cc,
+    0x2de92c6f,
+    0x4a7484aa,
+    0x5cb0a9dc,
+    0x76f988da,
+    0x983e5152,
+    0xa831c66d,
+    0xb00327c8,
+    0xbf597fc7,
+    0xc6e00bf3,
+    0xd5a79147,
+    0x06ca6351,
+    0x14292967,
+    0x27b70a85,
+    0x2e1b2138,
+    0x4d2c6dfc,
+    0x53380d13,
+    0x650a7354,
+    0x766a0abb,
+    0x81c2c92e,
+    0x92722c85,
+    0xa2bfe8a1,
+    0xa81a664b,
+    0xc24b8b70,
+    0xc76c51a3,
+    0xd192e819,
+    0xd6990624,
+    0xf40e3585,
+    0x106aa070,
+    0x19a4c116,
+    0x1e376c08,
+    0x2748774c,
+    0x34b0bcb5,
+    0x391c0cb3,
+    0x4ed8aa4a,
+    0x5b9cca4f,
+    0x682e6ff3,
+    0x748f82ee,
+    0x78a5636f,
+    0x84c87814,
+    0x8cc70208,
+    0x90befffa,
+    0xa4506ceb,
+    0xbef9a3f7,
+    0xc67178f2
+];
+// SHA-256 initial hash values: the first 32 bits of the fractional parts of the
+// square roots of the first 8 primes.
+const H0 = [
+    0x6a09e667,
+    0xbb67ae85,
+    0x3c6ef372,
+    0xa54ff53a,
+    0x510e527f,
+    0x9b05688c,
+    0x1f83d9ab,
+    0x5be0cd19
+];
+function rotateRight(value, bits) {
+    return value >>> bits | value << 32 - bits;
+}
+function utf8Bytes(text) {
+    const bytes = [];
+    for (const character of text){
+        const code = character.codePointAt(0);
+        if (code < 0x80) {
+            bytes.push(code);
+        } else if (code < 0x800) {
+            bytes.push(0xc0 | code >> 6, 0x80 | code & 0x3f);
+        } else if (code < 0x10000) {
+            bytes.push(0xe0 | code >> 12, 0x80 | code >> 6 & 0x3f, 0x80 | code & 0x3f);
+        } else {
+            bytes.push(0xf0 | code >> 18, 0x80 | code >> 12 & 0x3f, 0x80 | code >> 6 & 0x3f, 0x80 | code & 0x3f);
+        }
+    }
+    return bytes;
+}
+// SHA-256 (FIPS 180-4) of a string's UTF-8 bytes, as lowercase hex.
+function sha256Hex(text) {
+    const bytes = utf8Bytes(text);
+    const bitLength = bytes.length * 8;
+    bytes.push(0x80);
+    while(bytes.length % 64 !== 56){
+        bytes.push(0);
+    }
+    // The message length in bits as a 64-bit big-endian integer. Stamp inputs
+    // (ids, role and organization lists) are far below 2^32 bits, so the high
+    // word is zero.
+    bytes.push(0, 0, 0, 0);
+    bytes.push(bitLength >>> 24 & 0xff, bitLength >>> 16 & 0xff, bitLength >>> 8 & 0xff);
+    bytes.push(bitLength & 0xff);
+    const hash = [
+        ...H0
+    ];
+    const w = new Array(64);
+    for(let offset = 0; offset < bytes.length; offset += 64){
+        for(let i = 0; i < 16; i += 1){
+            const j = offset + i * 4;
+            w[i] = (bytes[j] << 24 | bytes[j + 1] << 16 | bytes[j + 2] << 8 | bytes[j + 3]) >>> 0;
+        }
+        for(let i = 16; i < 64; i += 1){
+            const s0 = rotateRight(w[i - 15], 7) ^ rotateRight(w[i - 15], 18) ^ w[i - 15] >>> 3;
+            const s1 = rotateRight(w[i - 2], 17) ^ rotateRight(w[i - 2], 19) ^ w[i - 2] >>> 10;
+            w[i] = w[i - 16] + s0 + w[i - 7] + s1 >>> 0;
+        }
+        let [a, b, c, d, e, f, g, h] = hash;
+        for(let i = 0; i < 64; i += 1){
+            const S1 = rotateRight(e, 6) ^ rotateRight(e, 11) ^ rotateRight(e, 25);
+            const choice = e & f ^ ~e & g;
+            const temp1 = h + S1 + choice + K[i] + w[i] >>> 0;
+            const S0 = rotateRight(a, 2) ^ rotateRight(a, 13) ^ rotateRight(a, 22);
+            const majority = a & b ^ a & c ^ b & c;
+            const temp2 = S0 + majority >>> 0;
+            h = g;
+            g = f;
+            f = e;
+            e = d + temp1 >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = temp1 + temp2 >>> 0;
+        }
+        hash[0] = hash[0] + a >>> 0;
+        hash[1] = hash[1] + b >>> 0;
+        hash[2] = hash[2] + c >>> 0;
+        hash[3] = hash[3] + d >>> 0;
+        hash[4] = hash[4] + e >>> 0;
+        hash[5] = hash[5] + f >>> 0;
+        hash[6] = hash[6] + g >>> 0;
+        hash[7] = hash[7] + h >>> 0;
+    }
+    return hash.map((word)=>word.toString(16).padStart(8, '0')).join('');
+}
+export default sha256Hex;

package/dist/stampHash.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 sha256Hex from './sha256Hex.js';
+// A short fingerprint for one part of a response's caller stamp (see
+// callerStamp): the first 16 hex characters of SHA-256 of the text. It is an
+// identity comparison, not a secret: SHA-256 is implemented in sha256Hex rather
+// than taken from WebCrypto, which browsers expose only on https and localhost
+// pages, so the server and every page compute the same value synchronously.
+function stampHash(text) {
+    return sha256Hex(text).slice(0, 16);
+}
+export default stampHash;

package/dist/targetFromElementsChain.js

@@ -0,0 +1,103 @@
+/*
+  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 journeyTargetSelectors from './journeyTargetSelectors.js';
+import parseElementsChain from './parseElementsChain.js';
+import parseRowIndex from './parseRowIndex.js';
+import type from './type.js';
+const { blockWrapperPrefix, cellAttribute, interactiveRoles, rowAttribute } = journeyTargetSelectors;
+function blockIdOf(entry) {
+    const id = entry.attributes.attr__id;
+    if (!type.isString(id) || !id.startsWith(blockWrapperPrefix)) {
+        return null;
+    }
+    return id.slice(blockWrapperPrefix.length);
+}
+function normaliseText(value) {
+    if (!type.isString(value)) {
+        return null;
+    }
+    const text = value.replace(/\s+/g, ' ').trim();
+    return text === '' ? null : text;
+}
+function isOption(entry) {
+    return entry.classes.includes('ant-select-item-option') || entry.attributes.attr__role === 'option';
+}
+// The chain form of the interactive-control selector. A radio or checkbox input inside a label
+// is reached through the label, as the selector does.
+function isInteractive(entry, position, scope) {
+    const { attributes, tag } = entry;
+    if (interactiveRoles.includes(attributes.attr__role)) {
+        return true;
+    }
+    if (tag === 'input') {
+        if (attributes.attr__type === 'hidden') {
+            return false;
+        }
+        const isToggle = attributes.attr__type === 'radio' || attributes.attr__type === 'checkbox';
+        return !(isToggle && scope.slice(position + 1).some((outer)=>outer.tag === 'label'));
+    }
+    if (tag === 'a') {
+        return type.isString(attributes.href) || type.isString(attributes.attr__href);
+    }
+    return [
+        'button',
+        'textarea',
+        'select',
+        'label'
+    ].includes(tag);
+}
+// The text of the control the click reached (an interactive control or a dropdown option): its
+// own text, else (a label or option whose text sits in a child) the first text between the
+// clicked element and it. posthog-js records the clicked element's direct text and the text of
+// buttons, links and other form elements. A click that reached no control has no text, as in
+// describeElement: its block alone targets it.
+function textOf(scope) {
+    const controlIndex = scope.findIndex((entry, position)=>isInteractive(entry, position, scope) || isOption(entry));
+    if (controlIndex === -1) {
+        return null;
+    }
+    for (const entry of [
+        scope[controlIndex],
+        ...scope.slice(0, controlIndex)
+    ]){
+        const text = normaliseText(entry.attributes.text);
+        if (text !== null) {
+            return text;
+        }
+    }
+    return null;
+}
+// The journey target a posthog-js `$elements_chain` describes: the block wrappers the click
+// passed through (innermost first), the grid row and column, the control's text, and whether it
+// was a dropdown option. Pure, so the production pull runs it in Node on captured events. Total:
+// any string gives a target and never throws.
+function targetFromElementsChain(chain) {
+    const entries = type.isString(chain) ? parseElementsChain(chain) : [];
+    const blockIds = entries.map(blockIdOf).filter((blockId)=>blockId !== null);
+    const blockIndex = entries.findIndex((entry)=>blockIdOf(entry) !== null);
+    const inner = blockIndex === -1 ? entries : entries.slice(0, blockIndex);
+    const scope = blockIndex === -1 ? entries : entries.slice(0, blockIndex + 1);
+    const rowEntry = inner.find((entry)=>`attr__${rowAttribute}` in entry.attributes);
+    const cellEntry = inner.find((entry)=>`attr__${cellAttribute}` in entry.attributes);
+    return {
+        block_id: blockIds[0] ?? null,
+        row: rowEntry ? parseRowIndex(rowEntry.attributes[`attr__${rowAttribute}`]) : null,
+        column: cellEntry ? cellEntry.attributes[`attr__${cellAttribute}`] : null,
+        text: textOf(scope),
+        option: inner.some(isOption),
+        block_ids: blockIds
+    };
+}
+export default targetFromElementsChain;

package/dist/traceIdDate.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 isTraceId from './isTraceId.js';
+// The date directory a trace id's file lives in: `yyyy-mm-dd`.
+function traceIdDate(id) {
+    if (!isTraceId(id)) {
+        throw new Error(`Invalid trace id. Received ${JSON.stringify(id)}.`);
+    }
+    return `${id.slice(0, 4)}-${id.slice(4, 6)}-${id.slice(6, 8)}`;
+}
+export default traceIdDate;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lowdefy/helpers",
-  "version": "6.0.0",
+  "version": "7.0.0",
   "license": "Apache-2.0",
   "description": "",
   "homepage": "https://lowdefy.com",
@@ -31,7 +31,8 @@
     "dist/*"
   ],
   "dependencies": {
-    "@lowdefy/errors": "6.0.0",
+    "@lowdefy/errors": "7.0.0",
+    "change-case": "5.4.0",
     "intl-messageformat": "11.2.7"
   },
   "devDependencies": {
@@ -40,7 +41,8 @@
     "@swc/core": "1.15.32",
     "@swc/jest": "0.2.39",
     "jest": "28.1.3",
-    "jest-diff": "28.1.3"
+    "jest-diff": "28.1.3",
+    "jest-environment-jsdom": "28.1.3"
   },
   "publishConfig": {
     "access": "public"