@lowdefy/helpers 6.2.0 → 7.1.0

package/dist/listHash.js

@@ -0,0 +1,25 @@
+/*
+  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 list whose order carries no meaning (the organization ids
+// a person belongs to): sorted first, so the same set always hashes the same,
+// and JSON-encoded, so no separator inside an entry can make two lists read as
+// one.
+function listHash({ values }) {
+    return stampHash(JSON.stringify([
+        ...values
+    ].sort()));
+}
+export default listHash;

package/dist/normalizeCaller.js

@@ -0,0 +1,30 @@
+/*
+  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 { snakeCase } from 'change-case';
+import type from './type.js';
+// Shallow snake_cases every own top-level key of the resolved caller - the
+// object mirror of the adapter's schema-wide fieldName derive. Values are
+// copied by reference: the attributes and profile bags (and the roles array)
+// ride through whole, so their inner keys - app/module-owned, not platform
+// surface - are never transformed.
+function normalizeCaller(user) {
+    if (type.isNone(user)) return user;
+    const normalized = {};
+    for (const [key, value] of Object.entries(user)){
+        normalized[snakeCase(key)] = value;
+    }
+    return normalized;
+}
+export default normalizeCaller;

package/dist/pageInstanceKey.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 buildPagePath from './buildPagePath.js';
+import parsePathPattern from './parsePathPattern.js';
+import type from './type.js';
+// The key a page instance's context and input are stored under. A page with placeholders has one
+// instance per set of decoded values, keyed by the path the builder writes for them, so every
+// spelling of the same values in an arriving URL gives one key. "#" cannot appear in a page id and
+// the builder encodes it in values, so no instance key equals another page's key.
+function pageInstanceKey({ pageId, path, pathParams }) {
+    if (type.isUndefined(path)) {
+        return `page:${pageId}`;
+    }
+    const hasPlaceholders = parsePathPattern(path).some((segment)=>type.isString(segment.name));
+    if (!hasPlaceholders) {
+        return `page:${pageId}`;
+    }
+    return `page:${pageId}#${buildPagePath({
+        pageId,
+        path,
+        pathParams
+    })}`;
+}
+export default pageInstanceKey;

package/dist/pairTraceEvents.js

@@ -0,0 +1,102 @@
+/*
+  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 isMountEventName from './isMountEventName.js';
+import type from './type.js';
+// Absorbs event-loop and render delay between the DOM interaction and the
+// moment the engine starts the event's actions, without reaching back to an
+// unrelated earlier click.
+const PAIRING_SLACK_MS = 1000;
+function canBeCaused({ event }) {
+    return event.scope !== 'app' && !isMountEventName({
+        eventName: event.eventName
+    });
+}
+// An interaction can have caused an event when the event's block encloses the
+// interaction's target (the handler is on the clicked block or an ancestor of
+// it) and the event started no later than its debounce plus the slack after
+// the interaction.
+function couldCause({ event, interaction }) {
+    if (!interaction.blockIds.includes(event.blockId)) return false;
+    const delay = event.startTimestamp - interaction.t;
+    const windowMs = (event.debounceMs ?? 0) + PAIRING_SLACK_MS;
+    return delay >= 0 && delay <= windowMs;
+}
+function findCause({ event, interactions }) {
+    let cause;
+    interactions.forEach((interaction)=>{
+        if (!couldCause({
+            event,
+            interaction
+        })) return;
+        if (type.isUndefined(cause) || interaction.t >= cause.t) {
+            cause = interaction;
+        }
+    });
+    return cause;
+}
+// Decides which DOM interaction caused which engine event, so a trace record
+// means the same thing whichever source wrote it: the dev recorder runs this in
+// the browser, the production pull in Node.
+//
+// - interactions: [{ id, t, blockIds }], `t` epoch ms, `blockIds` innermost first.
+// - events: [{ id, blockId, eventName, startTimestamp, debounceMs, scope }].
+//
+// Mount-class and app events are never paired. Any other event pairs with the
+// latest interaction that could have caused it; an event with none is
+// programmatic and goes to `unpaired`. Within a pair, events on the innermost
+// block come first, then the earliest, so the record builder takes the first
+// as `event` and the rest as `also`.
+function pairTraceEvents({ interactions, events }) {
+    const byInteraction = new Map();
+    const unpaired = [];
+    events.forEach((event, order)=>{
+        const cause = canBeCaused({
+            event
+        }) ? findCause({
+            event,
+            interactions
+        }) : undefined;
+        if (type.isUndefined(cause)) {
+            unpaired.push(event.id);
+            return;
+        }
+        if (!byInteraction.has(cause)) byInteraction.set(cause, []);
+        byInteraction.get(cause).push({
+            depth: cause.blockIds.indexOf(event.blockId),
+            event,
+            order
+        });
+    });
+    const pairs = interactions.filter((interaction)=>byInteraction.has(interaction)).map((interaction)=>{
+        const paired = [
+            ...byInteraction.get(interaction)
+        ].sort((a, b)=>{
+            if (a.depth !== b.depth) return a.depth - b.depth;
+            if (a.event.startTimestamp !== b.event.startTimestamp) {
+                return a.event.startTimestamp - b.event.startTimestamp;
+            }
+            return a.order - b.order;
+        });
+        return {
+            interactionId: interaction.id,
+            eventIds: paired.map((entry)=>entry.event.id)
+        };
+    });
+    return {
+        pairs,
+        unpaired
+    };
+}
+export default pairTraceEvents;

package/dist/parseCallerStamp.js

@@ -0,0 +1,46 @@
+/*
+  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 './type.js';
+const FIELDS = [
+    'session',
+    'roles',
+    'memberships'
+];
+// Reads an x-lowdefy-caller header (see callerStamp) into
+// { caller, session, roles, memberships }. A field the header does not carry is
+// null; an anonymous caller is { caller: '' } with every field null. No header
+// is null: the response was not answered by a route that resolved a caller (it
+// failed before, or came from a proxy), so it claims no caller.
+function parseCallerStamp(header) {
+    if (type.isNone(header)) {
+        return null;
+    }
+    const [caller, ...fields] = header.split(';').map((part)=>part.trim());
+    const stamp = {
+        caller,
+        session: null,
+        roles: null,
+        memberships: null
+    };
+    fields.forEach((field)=>{
+        const separator = field.indexOf('=');
+        const name = field.slice(0, separator);
+        if (separator > 0 && FIELDS.includes(name)) {
+            stamp[name] = field.slice(separator + 1);
+        }
+    });
+    return stamp;
+}
+export default parseCallerStamp;

package/dist/parseElementsChain.js

@@ -0,0 +1,58 @@
+/*
+  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 isChainHeaderEnd from './isChainHeaderEnd.js';
+import readChainValue from './readChainValue.js';
+function parseHeader(header) {
+    const [tag, ...classes] = header.split('.');
+    return {
+        tag: tag.toLowerCase(),
+        classes: classes.filter((name)=>name !== '')
+    };
+}
+// Splits a posthog-js `$elements_chain` into entries, target first. Each entry is
+// `tag.class1.class2:` followed by sorted `key="value"` pairs, and entries are joined by `;`.
+// Total: a malformed chain gives the entries read before the fault.
+function parseElementsChain(chain) {
+    const entries = [];
+    let index = 0;
+    while(index < chain.length){
+        let headerEnd = index;
+        while(headerEnd < chain.length && chain[headerEnd] !== ';' && !isChainHeaderEnd(chain, headerEnd)){
+            headerEnd += 1;
+        }
+        const entry = {
+            ...parseHeader(chain.slice(index, headerEnd)),
+            attributes: {}
+        };
+        entries.push(entry);
+        if (chain[headerEnd] !== ':') {
+            index = headerEnd + 1;
+            continue;
+        }
+        index = headerEnd + 1;
+        while(index < chain.length && chain[index] !== ';'){
+            const keyEnd = chain.indexOf('="', index);
+            if (keyEnd === -1) {
+                return entries;
+            }
+            const { value, end } = readChainValue(chain, keyEnd + 2);
+            entry.attributes[chain.slice(index, keyEnd)] = value;
+            index = end;
+        }
+        index += 1;
+    }
+    return entries;
+}
+export default parseElementsChain;

package/dist/parsePageId.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.
+*/ // The page path a URL shows: its pathname without the basePath and the outer slashes. It is the
+// page id only for pages without a `path` pattern. The app root gives null.
+function parsePageId(url, basePath = '') {
+    const pathname = new URL(url, 'http://localhost').pathname;
+    const stripped = basePath && pathname.startsWith(basePath) ? pathname.slice(basePath.length) : pathname;
+    const pageId = stripped.replace(/^\//, '').replace(/\/$/, '');
+    return pageId === '' ? null : pageId;
+}
+export default parsePageId;

package/dist/parsePathPattern.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 type from './type.js';
+// The page id character set without "/", which separates segments.
+const fixedSegmentPattern = /^[A-Za-z0-9\-_:]+$/;
+const placeholderNamePattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function parsePlaceholder({ path, segment }) {
+    const name = segment.slice(1, -1);
+    if (name.startsWith('...')) {
+        throw new Error(`Page path "${path}" has a catch-all placeholder "${segment}". Catch-all placeholders are not supported.`);
+    }
+    if (name.startsWith('?') || name.endsWith('?')) {
+        throw new Error(`Page path "${path}" has an optional placeholder "${segment}". Optional placeholders are not supported.`);
+    }
+    if (!placeholderNamePattern.test(name)) {
+        throw new Error(`Page path "${path}" has an invalid placeholder "${segment}". Placeholder names must start with a letter or "_" and only contain A-Z, a-z, 0-9 and "_".`);
+    }
+    return {
+        name
+    };
+}
+function parseSegment({ path, segment }) {
+    if (segment === '') {
+        throw new Error(`Page path "${path}" has an empty segment.`);
+    }
+    if (segment.startsWith('{') && segment.endsWith('}')) {
+        return parsePlaceholder({
+            path,
+            segment
+        });
+    }
+    if (segment.includes('{') || segment.includes('}')) {
+        throw new Error(`Page path "${path}" has a placeholder inside segment "${segment}". A placeholder must be a whole segment, like "{id}".`);
+    }
+    if (!fixedSegmentPattern.test(segment)) {
+        throw new Error(`Page path "${path}" segment "${segment}" contains invalid characters. Fixed segments must only contain A-Z, a-z, 0-9, "-", "_" and ":".`);
+    }
+    return {
+        fixed: segment
+    };
+}
+function parseSegments(path) {
+    if (path.startsWith('/') || path.endsWith('/')) {
+        throw new Error(`Page path "${path}" must not start or end with "/".`);
+    }
+    const names = new Set();
+    return path.split('/').map((segment)=>{
+        const parsed = parseSegment({
+            path,
+            segment
+        });
+        if (type.isString(parsed.name)) {
+            if (names.has(parsed.name)) {
+                throw new Error(`Page path "${path}" uses placeholder "${segment}" more than once.`);
+            }
+            names.add(parsed.name);
+        }
+        return Object.freeze(parsed);
+    });
+}
+// Patterns come from build config, so the cache holds at most one entry per page path.
+const cache = new Map();
+// Splits a page path pattern into segments, each { fixed } or { name }. The result is shared
+// between callers and frozen.
+function parsePathPattern(path) {
+    if (!type.isString(path)) {
+        throw new Error(`Page path must be a string. Received ${JSON.stringify(path)}.`);
+    }
+    if (cache.has(path)) {
+        return cache.get(path);
+    }
+    const segments = Object.freeze(parseSegments(path));
+    cache.set(path, segments);
+    return segments;
+}
+export default parsePathPattern;

package/dist/parseRowIndex.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 type from './type.js';
+// An ag-grid `row-index` as a journey target row. Pinned rows (`t-0`, `b-0`) are not zero-based
+// integers, so they give null.
+function parseRowIndex(value) {
+    if (!type.isString(value) || !/^\d+$/.test(value)) {
+        return null;
+    }
+    return Number(value);
+}
+export default parseRowIndex;

package/dist/projectCaughtError.js

@@ -50,7 +50,10 @@ function projectNode(error, scrub, seen) {
         // 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
+        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;
@@ -69,7 +72,8 @@ function projectNode(error, scrub, seen) {
     return projected;
 }
 // The value `_error` reads: the caught error rebuilt with only the fields a
-// routine or catch list branches on. `received`, `configKey`, `location`,
+// 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.

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

@@ -206,11 +206,12 @@ 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,
+        skipMarkers: options.skipMarkers,
         projectError: options.projectError
     })));
 };