@lowdefy/plugin-posthog 0.0.0-experimental-20260925135632

package/dist/actions/PostHogSetPersonProperties.schema.js

@@ -0,0 +1,43 @@
+/*
+  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: 'object',
+        properties: {
+            set: {
+                type: 'object',
+                description: 'Person properties to set.'
+            },
+            setOnce: {
+                type: 'object',
+                description: 'Person properties that are only set if the person does not have them yet.'
+            }
+        },
+        anyOf: [
+            {
+                required: [
+                    'set'
+                ]
+            },
+            {
+                required: [
+                    'setOnce'
+                ]
+            }
+        ],
+        additionalProperties: false
+    }
+};

package/dist/actions.js

@@ -0,0 +1,27 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ export { default as PostHogAlias } from './actions/PostHogAlias.js';
+export { default as PostHogCapture } from './actions/PostHogCapture.js';
+export { default as PostHogCapturePageLeave } from './actions/PostHogCapturePageLeave.js';
+export { default as PostHogFeatureFlag } from './actions/PostHogFeatureFlag.js';
+export { default as PostHogGroup } from './actions/PostHogGroup.js';
+export { default as PostHogIdentify } from './actions/PostHogIdentify.js';
+export { default as PostHogInit } from './actions/PostHogInit.js';
+export { default as PostHogOptIn } from './actions/PostHogOptIn.js';
+export { default as PostHogOptOut } from './actions/PostHogOptOut.js';
+export { default as PostHogPageview } from './actions/PostHogPageview.js';
+export { default as PostHogReloadFeatureFlags } from './actions/PostHogReloadFeatureFlags.js';
+export { default as PostHogReset } from './actions/PostHogReset.js';
+export { default as PostHogSetPersonProperties } from './actions/PostHogSetPersonProperties.js';

package/dist/lib/cleanProperties.js

@@ -0,0 +1,22 @@
+/*
+  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';
+// Drops null and undefined values so an absent property does not overwrite a
+// value PostHog already has for the person.
+function cleanProperties(properties) {
+    if (!type.isObject(properties)) return {};
+    return Object.fromEntries(Object.entries(properties).filter(([, value])=>!type.isNone(value)));
+}
+export default cleanProperties;

package/dist/lib/getPostHog.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 postHogState from './postHogState.js';
+import warnUninitialized from './warnUninitialized.js';
+// Returns the posthog-js instance, or null when the calling action should do
+// nothing. Analytics must never break an app, so a disabled, failed or missing
+// PostHog is never an error here. Callers validate their params first, so
+// invalid config is still caught in environments where PostHog is off.
+async function getPostHog({ action }) {
+    if (postHogState.status === 'loading') {
+        await postHogState.loading;
+    }
+    if (postHogState.status === 'enabled') {
+        return postHogState.client;
+    }
+    if (postHogState.status === 'uninitialized') {
+        warnUninitialized({
+            action
+        });
+    }
+    return null;
+}
+export default getPostHog;

package/dist/lib/initPostHog.js

@@ -0,0 +1,45 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import loadPostHog from './loadPostHog.js';
+import postHogState from './postHogState.js';
+// PostHogInit runs from every page's onInit, so a repeat call with the same
+// params must be a no-op. A disabled PostHog was never loaded, so a later call
+// with enabled: true may still load it.
+async function initPostHog({ apiKey, config, enabled, superProperties }) {
+    const { status } = postHogState;
+    if (enabled === false) {
+        if (status === 'uninitialized' || status === 'disabled') {
+            postHogState.status = 'disabled';
+            return;
+        }
+        throw new Error('PostHogInit was called with "enabled: false" after PostHog was already initialised. Use the same PostHogInit params on every page, and PostHogOptOut to stop capturing for a person.');
+    }
+    if (status === 'uninitialized' || status === 'disabled') {
+        postHogState.apiKey = apiKey;
+        postHogState.status = 'loading';
+        postHogState.loading = loadPostHog({
+            apiKey,
+            config,
+            superProperties
+        });
+        await postHogState.loading;
+        return;
+    }
+    if (postHogState.apiKey !== apiKey) {
+        throw new Error(`PostHogInit was already called with a different "apiKey". PostHog can only be initialised once per browser session. Received ${JSON.stringify(apiKey)}.`);
+    }
+    await postHogState.loading;
+}
+export default initPostHog;

package/dist/lib/loadPostHog.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.
+*/ import postHogState from './postHogState.js';
+// posthog-js is imported here, and only here, so an app that runs with
+// enabled: false never downloads or runs the SDK.
+async function loadPostHog({ apiKey, config, superProperties = {} }) {
+    let posthog;
+    try {
+        ({ default: posthog } = await import('posthog-js'));
+    } catch (error) {
+        // The SDK chunk failed to download, for example on a flaky network.
+        // Analytics must never break an app, so the other actions become no-ops.
+        postHogState.status = 'failed';
+        // eslint-disable-next-line no-console
+        console.warn('PostHogInit could not load posthog-js. PostHog actions will do nothing.', error);
+        return;
+    }
+    posthog.init(apiKey, config);
+    if (Object.keys(superProperties).length > 0) {
+        posthog.register(superProperties);
+    }
+    postHogState.client = posthog;
+    postHogState.status = 'enabled';
+}
+export default loadPostHog;

package/dist/lib/postHogState.js

@@ -0,0 +1,32 @@
+/*
+  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 singleton behind every action in this package. PostHogInit fills it in
+// once per browser session; every other action reads it.
+//
+// status is one of:
+// - uninitialized: PostHogInit has not run. Actions do nothing and warn once,
+//   because a missing PostHogInit is a config mistake.
+// - disabled: PostHogInit ran with enabled: false. Actions do nothing, silently.
+// - loading: PostHogInit is downloading posthog-js. Actions wait for it.
+// - failed: posthog-js could not be downloaded. Actions do nothing, silently.
+// - enabled: client is the initialised posthog-js instance.
+const postHogState = {
+    apiKey: null,
+    client: null,
+    loading: null,
+    status: 'uninitialized',
+    warnedUninitialized: false
+};
+export default postHogState;

package/dist/lib/warnUninitialized.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 postHogState from './postHogState.js';
+// A PostHog action running before PostHogInit is a config mistake, but
+// analytics must never throw, so the browser console is the only place left to
+// report it. Once is enough to point at the fix without flooding the console.
+function warnUninitialized({ action }) {
+    if (postHogState.warnedUninitialized) return;
+    postHogState.warnedUninitialized = true;
+    // eslint-disable-next-line no-console
+    console.warn(`${action} ran before PostHogInit, so it did nothing. Run PostHogInit in the page onInit event, with "enabled: false" where analytics should be off.`);
+}
+export default warnUninitialized;

package/dist/schemas.js

@@ -0,0 +1,27 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ export { default as PostHogAlias } from './actions/PostHogAlias.schema.js';
+export { default as PostHogCapture } from './actions/PostHogCapture.schema.js';
+export { default as PostHogCapturePageLeave } from './actions/PostHogCapturePageLeave.schema.js';
+export { default as PostHogFeatureFlag } from './actions/PostHogFeatureFlag.schema.js';
+export { default as PostHogGroup } from './actions/PostHogGroup.schema.js';
+export { default as PostHogIdentify } from './actions/PostHogIdentify.schema.js';
+export { default as PostHogInit } from './actions/PostHogInit.schema.js';
+export { default as PostHogOptIn } from './actions/PostHogOptIn.schema.js';
+export { default as PostHogOptOut } from './actions/PostHogOptOut.schema.js';
+export { default as PostHogPageview } from './actions/PostHogPageview.schema.js';
+export { default as PostHogReloadFeatureFlags } from './actions/PostHogReloadFeatureFlags.schema.js';
+export { default as PostHogReset } from './actions/PostHogReset.schema.js';
+export { default as PostHogSetPersonProperties } from './actions/PostHogSetPersonProperties.schema.js';

package/dist/test/resetPostHogState.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 postHogState from '../lib/postHogState.js';
+// The singleton lives for the life of the module registry, so each test starts
+// by putting it back to its "PostHogInit has not run" state.
+function resetPostHogState() {
+    postHogState.apiKey = null;
+    postHogState.client = null;
+    postHogState.loading = null;
+    postHogState.status = 'uninitialized';
+    postHogState.warnedUninitialized = false;
+}
+export default resetPostHogState;

package/dist/types.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.
+*/ export default {
+    actions: [
+        'PostHogAlias',
+        'PostHogCapture',
+        'PostHogCapturePageLeave',
+        'PostHogFeatureFlag',
+        'PostHogGroup',
+        'PostHogIdentify',
+        'PostHogInit',
+        'PostHogOptIn',
+        'PostHogOptOut',
+        'PostHogPageview',
+        'PostHogReloadFeatureFlags',
+        'PostHogReset',
+        'PostHogSetPersonProperties'
+    ]
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@lowdefy/plugin-posthog",
+  "version": "0.0.0-experimental-20260925135632",
+  "license": "Apache-2.0",
+  "description": "Lowdefy PostHog product analytics plugin: initialise posthog-js, capture events, identify people and groups, manage consent and read feature flags.",
+  "homepage": "https://lowdefy.com",
+  "keywords": [
+    "lowdefy",
+    "lowdefy actions",
+    "lowdefy plugin",
+    "posthog",
+    "analytics"
+  ],
+  "bugs": {
+    "url": "https://github.com/lowdefy/lowdefy/issues"
+  },
+  "contributors": [
+    {
+      "name": "Gerrie van Wyk",
+      "url": "https://github.com/Gervwyk"
+    }
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lowdefy/lowdefy.git"
+  },
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    "./actions": "./dist/actions.js",
+    "./schemas": "./dist/schemas.js",
+    "./types": "./dist/types.js"
+  },
+  "files": [
+    "dist/*"
+  ],
+  "dependencies": {
+    "@lowdefy/helpers": "0.0.0-experimental-20260925135632",
+    "posthog-js": "1.434.7"
+  },
+  "devDependencies": {
+    "@jest/globals": "28.1.3",
+    "@lowdefy/node-utils": "0.0.0-experimental-20260925135632",
+    "@swc/cli": "0.8.1",
+    "@swc/core": "1.15.32",
+    "@swc/jest": "0.2.39",
+    "jest": "28.1.3",
+    "jest-environment-jsdom": "28.1.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "swc src --out-dir dist --config-file ../../../../.swcrc --cli-config-file ../../../../.swc-cli.json --copy-files",
+    "clean": "rm -rf dist",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
+  }
+}