@posthog/browser-common 0.5.1 → 0.6.0

package/README.md

@@ -56,17 +56,37 @@ What an extension is given in `setup` — the adapter shared by extensions on th
 
 - **identity and session**: `distinctId`, `anonymousId`, `deviceId`, `groups`, `session`, `initialPersonProperties`
 - **SDK metadata**: `library`
+- **capture permission**: `canCapture`
 - **events**: `capture(...)`, `registerDynamicEventProperties(...)`, `onEvent(...)`
+- **extensions**: `getExtension(token)`
 - **server config**: `onRemoteConfig(...)`
 - **transport**: `projectToken`, `sendRequest(path, init?)`, including `compression` and `sentAt` options
 - **storage and logging**: `kv`, `logger`
 
-Identity, session, SDK metadata, and the public project token are always-ready synchronous reads. `capture` and
-`sendRequest` are awaitable. For `sendRequest`, `sentAt` controls `sent_at` placement on POST requests; GET query mode
+Identity, session, SDK metadata, capture permission, and the public project token are always-ready synchronous reads.
+`capture` and `sendRequest` are awaitable. For `sendRequest`, `sentAt` controls `sent_at` placement on POST requests; GET query mode
 uses the cache-busting `_` parameter instead, and GET body mode has no effect. `onRemoteConfig` immediately replays the
 latest known success or failure and then reports subsequent outcomes. Extensions that want a named log prefix can
 create a child with `client.logger.createLogger('[myExtension]')`.
 
+Extensions that expose controls to other extensions should export a typed stable-name token:
+
+```ts
+import type { Extension, ExtensionToken } from '@posthog/browser-common'
+
+export interface DiagnosticsExtension extends Extension {
+    flush(): void
+}
+
+export const DiagnosticsExtension = 'diagnostics' as ExtensionToken<DiagnosticsExtension>
+
+const diagnostics = client.getExtension(DiagnosticsExtension)
+diagnostics?.flush()
+```
+
+Tokens are strings at runtime and must match the installed extension's `Extension.name`. Lookup is per-client and optional; a
+returned extension may still be running `setup`, so consumers must not create mandatory startup cycles.
+
 Initialize KV during asynchronous setup before using its synchronous buffer:
 
 ```ts
@@ -89,9 +109,10 @@ store sensitive values unless their transmission is approved.
 PostHog browser SDK implementations share extension registration and teardown
 through `ExtensionRuntime`, imported from the dedicated
 `@posthog/browser-common/extension-runtime` subpath. It reserves extension names
-during setup, rolls back failed setup, and disposes extensions once in reverse
-registration order without waiting for pending setup. Concrete SDKs still own
-their `Client` adapter and SDK lifecycle hooks.
+during setup, exposes registered extensions by typed stable name through `Client`,
+rolls back failed setup, and disposes extensions once in reverse registration
+order without waiting for pending setup. Concrete SDKs still own their `Client`
+adapter and SDK lifecycle hooks.
 
 `ExtensionRuntime` is host infrastructure, not part of the extension-author
 surface exported from the package root.

package/dist/client.d.ts

@@ -2,7 +2,9 @@ import type { Logger } from '@posthog/core';
 import type { Properties } from '@posthog/types';
 import type { Compression } from './types/compression';
 import type { Disposable } from './disposable';
+import type { Extension } from './extension';
 import type { KeyValueStore } from './persistence';
+import type { ExtensionToken } from './token';
 import type { Listener } from './pubsub';
 import type { RemoteConfigResult } from './types/remote-config';
 /** Recursively marks object properties as readonly while preserving callable values. */
@@ -95,10 +97,16 @@ export interface Client {
     readonly groups: DeepReadonly<Record<string, string>>;
     /** The current session, created on first read if needed. */
     readonly session: SessionContext;
+    /** Whether the host currently permits data capture. */
+    readonly canCapture: boolean;
     /** Records an analytics event through the client's normal pipeline. */
     capture(event: string, properties?: Properties | null, options?: CaptureOptions): Promise<void>;
     /** Registers a synchronous producer of properties merged into every captured event. */
     registerDynamicEventProperties(producer: () => Record<string, unknown>): Disposable;
+    /** Returns the extension registered under a typed stable name, or `undefined` when it is not installed. */
+    getExtension<T extends Extension>(token: ExtensionToken<T>): T | undefined;
+    /** Returns the extension registered under a stable name, or `undefined` when it is not installed. */
+    getExtension<T extends Extension = Extension>(name: string): T | undefined;
     /** Fires for every captured event through a deeply readonly view. */
     readonly onEvent: Listener<CapturedEventInfo>;
     /** Replays the latest remote-config outcome on subscription and fires for subsequent outcomes. */

package/dist/config.js

@@ -26,7 +26,7 @@ __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
     default: ()=>__WEBPACK_DEFAULT_EXPORT__
 });
-const packageVersion = "0.5.1";
+const packageVersion = "0.6.0";
 const Config = {
     DEBUG: false,
     LIB_VERSION: packageVersion,

package/dist/config.mjs

@@ -1,4 +1,4 @@
-const packageVersion = "0.5.1";
+const packageVersion = "0.6.0";
 const Config = {
     DEBUG: false,
     LIB_VERSION: packageVersion,

package/dist/extension-runtime.d.ts

@@ -2,6 +2,7 @@ import { type Logger } from '@posthog/core';
 import type { Client } from './client';
 import type { Disposable } from './disposable';
 import type { Extension } from './extension';
+import type { ExtensionToken } from './token';
 /** Shared setup and lifecycle registry for browser extension hosts. */
 export declare class ExtensionRuntime implements Disposable {
     private readonly _logger;
@@ -11,6 +12,10 @@ export declare class ExtensionRuntime implements Disposable {
     constructor(_logger: Logger, _client: Client);
     /** Reserves an extension name and sets it up with the host client adapter. */
     add(extension: Extension): Promise<void>;
+    /** Returns a registered extension by its typed stable name, including while setup is in progress. */
+    getExtension<T extends Extension>(token: ExtensionToken<T>): T | undefined;
+    /** Returns a registered extension by its stable name, including while setup is in progress. */
+    getExtension<T extends Extension = Extension>(name: string): T | undefined;
     /** Releases every registered extension once in reverse registration order without waiting for pending setup. */
     dispose(): void;
     private _disposeExtension;

package/dist/extension-runtime.js

@@ -48,6 +48,9 @@ class ExtensionRuntime {
             if (active) this._disposeExtension(extension);
         }
     }
+    getExtension(name) {
+        return this._extensions.get(name);
+    }
     dispose() {
         if (this._disposed) return;
         this._disposed = true;

package/dist/extension-runtime.mjs

@@ -20,6 +20,9 @@ class ExtensionRuntime {
             if (active) this._disposeExtension(extension);
         }
     }
+    getExtension(name) {
+        return this._extensions.get(name);
+    }
     dispose() {
         if (this._disposed) return;
         this._disposed = true;

package/dist/index.d.ts

@@ -3,6 +3,7 @@
  * clients.
  */
 export type { Extension } from './extension';
+export type { ExtensionToken } from './token';
 export * from './types';
 export { createDisposable, type Disposable } from './disposable';
 export type { Listener } from './pubsub';

package/dist/token.d.ts

@@ -0,0 +1,14 @@
+/** Phantom brand carrying an extension type without emitting runtime code. */
+declare const extensionTokenType: unique symbol;
+/**
+ * A typed stable name for resolving an installed extension.
+ *
+ * Tokens are plain strings at runtime, so independently compiled scripts can
+ * share them without a registry or object-identity contract. The generic brand
+ * lets `Client.getExtension` infer the extension type. A token's string
+ * value must exactly match its extension's stable `name`.
+ */
+export type ExtensionToken<T> = string & {
+    readonly [extensionTokenType]: T;
+};
+export {};

package/dist/token.js

@@ -0,0 +1,18 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+for(var __webpack_i__ in __webpack_exports__)exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/types/surveys.d.ts

@@ -1,4 +1,5 @@
-import type { SurveyAppearance as CoreSurveyAppearance, SurveyQuestionTranslation, SurveyTranslation, SurveyValidationRule } from '@posthog/core';
+import type { PropertyMatchType, SurveyAppearance as CoreSurveyAppearance, SurveyEventWithFilters, SurveyQuestionTranslation, SurveyTranslation, SurveyValidationRule } from '@posthog/core';
+export type { PropertyFilters, PropertyMatchType, PropertyOperator, SurveyEventWithFilters } from '@posthog/core';
 export declare const SurveyEventType: {
     readonly Activation: "events";
     readonly Cancellation: "cancelEvents";
@@ -85,19 +86,6 @@ export declare const DisplaySurveyType: {
     readonly Inline: "inline";
 };
 export type DisplaySurveyType = (typeof DisplaySurveyType)[keyof typeof DisplaySurveyType];
-export type PropertyMatchType = 'regex' | 'not_regex' | 'exact' | 'is_not' | 'icontains' | 'not_icontains';
-/** Extended survey operator type with numeric comparisons. */
-export type PropertyOperator = PropertyMatchType | 'gt' | 'lt';
-export type PropertyFilters = {
-    [propertyName: string]: {
-        values: string[];
-        operator: PropertyOperator;
-    };
-};
-export interface SurveyEventWithFilters {
-    name: string;
-    propertyFilters?: PropertyFilters;
-}
 export type SurveyQuestionDescriptionContentType = 'html' | 'text';
 /** Browser survey appearance, including browser-only placement and rendering options. */
 export interface SurveyAppearance extends Omit<CoreSurveyAppearance, 'position' | 'widgetType'> {
@@ -240,4 +228,3 @@ export interface ActionStepType {
         type?: string;
     }[];
 }
-export {};

package/dist/utils/property-utils.d.ts

@@ -1,12 +1,7 @@
+import type { PropertyOperator } from '@posthog/core';
 import type { Properties } from '@posthog/types';
-export type PropertyMatchType = 'exact' | 'is_not' | 'regex' | 'not_regex' | 'icontains' | 'not_icontains';
-export type PropertyOperator = PropertyMatchType | 'gt' | 'lt';
-export type PropertyFilters = {
-    [propertyName: string]: {
-        values: string[];
-        operator: PropertyOperator;
-    };
-};
+export type { PropertyFilters, PropertyMatchType, PropertyOperator } from '@posthog/core';
+export { matchPropertyFilters, propertyComparisons } from '@posthog/core/surveys';
 export interface SessionRecordingTriggerPropertyFilter {
     key: string;
     value?: string | number | boolean | (string | number | boolean)[] | null;
@@ -14,10 +9,8 @@ export interface SessionRecordingTriggerPropertyFilter {
     type?: string | null;
 }
 export declare function getPersonPropertiesHash(distinct_id: string, userPropertiesToSet?: Properties, userPropertiesToSetOnce?: Properties): string;
-export declare const propertyComparisons: Record<PropertyOperator, (targets: string[], values: string[]) => boolean>;
 /**
  * Evaluate trigger property filters (WHERE clauses) against event and person properties.
  * All filters must match (implicit AND). Returns true if no filters are present.
  */
 export declare function matchTriggerPropertyFilters(filters: SessionRecordingTriggerPropertyFilter[] | undefined, eventProperties: Properties | undefined, personProperties: Properties | undefined): boolean;
-export declare function matchPropertyFilters(propertyFilters: PropertyFilters | undefined, eventProperties: Properties | undefined): boolean;

package/dist/utils/property-utils.js

@@ -24,14 +24,14 @@ var __webpack_require__ = {};
 var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
-    matchPropertyFilters: ()=>matchPropertyFilters,
-    propertyComparisons: ()=>propertyComparisons,
+    matchPropertyFilters: ()=>surveys_namespaceObject.matchPropertyFilters,
+    propertyComparisons: ()=>surveys_namespaceObject.propertyComparisons,
     getPersonPropertiesHash: ()=>getPersonPropertiesHash,
     matchTriggerPropertyFilters: ()=>matchTriggerPropertyFilters
 });
 const core_namespaceObject = require("@posthog/core");
+const surveys_namespaceObject = require("@posthog/core/surveys");
 const external_request_utils_js_namespaceObject = require("./request-utils.js");
-const external_regex_utils_js_namespaceObject = require("./regex-utils.js");
 function getPersonPropertiesHash(distinct_id, userPropertiesToSet, userPropertiesToSetOnce) {
     return (0, external_request_utils_js_namespaceObject.jsonStringify)({
         distinct_id,
@@ -39,23 +39,6 @@ function getPersonPropertiesHash(distinct_id, userPropertiesToSet, userPropertie
         userPropertiesToSetOnce
     });
 }
-const propertyComparisons = {
-    exact: (targets, values)=>values.some((value)=>targets.some((target)=>value === target)),
-    is_not: (targets, values)=>values.every((value)=>targets.every((target)=>value !== target)),
-    regex: (targets, values)=>values.some((value)=>targets.some((target)=>(0, external_regex_utils_js_namespaceObject.isMatchingRegex)(value, target))),
-    not_regex: (targets, values)=>values.every((value)=>targets.every((target)=>!(0, external_regex_utils_js_namespaceObject.isMatchingRegex)(value, target))),
-    icontains: (targets, values)=>values.map(toLowerCase).some((value)=>targets.map(toLowerCase).some((target)=>value.includes(target))),
-    not_icontains: (targets, values)=>values.map(toLowerCase).every((value)=>targets.map(toLowerCase).every((target)=>!value.includes(target))),
-    gt: (targets, values)=>values.some((value)=>{
-            const numValue = parseFloat(value);
-            return !isNaN(numValue) && targets.some((t)=>numValue > parseFloat(t));
-        }),
-    lt: (targets, values)=>values.some((value)=>{
-            const numValue = parseFloat(value);
-            return !isNaN(numValue) && targets.some((t)=>numValue < parseFloat(t));
-        })
-};
-const toLowerCase = (v)=>v.toLowerCase();
 const NEGATIVE_OPERATORS = new Set([
     'is_not',
     'not_icontains',
@@ -68,7 +51,7 @@ function matchTriggerPropertyFilters(filters, eventProperties, personProperties)
         const propertyValue = source?.[filter.key];
         const operator = filter.operator || 'exact';
         if ((0, core_namespaceObject.isUndefined)(propertyValue) || (0, core_namespaceObject.isNull)(propertyValue)) return NEGATIVE_OPERATORS.has(operator);
-        const comparisonFunction = propertyComparisons[operator];
+        const comparisonFunction = surveys_namespaceObject.propertyComparisons[operator];
         if (!comparisonFunction) return false;
         if ((0, core_namespaceObject.isUndefined)(filter.value) || (0, core_namespaceObject.isNull)(filter.value)) return false;
         const targetValues = (0, core_namespaceObject.isArray)(filter.value) ? filter.value.map(String) : [
@@ -80,19 +63,6 @@ function matchTriggerPropertyFilters(filters, eventProperties, personProperties)
         return comparisonFunction(targetValues, actualValues);
     });
 }
-function matchPropertyFilters(propertyFilters, eventProperties) {
-    if (!propertyFilters) return true;
-    return Object.entries(propertyFilters).every(([propertyName, filter])=>{
-        const eventPropertyValue = eventProperties?.[propertyName];
-        if ((0, core_namespaceObject.isUndefined)(eventPropertyValue) || (0, core_namespaceObject.isNull)(eventPropertyValue)) return false;
-        const eventValues = [
-            String(eventPropertyValue)
-        ];
-        const comparisonFunction = propertyComparisons[filter.operator];
-        if (!comparisonFunction) return false;
-        return comparisonFunction(filter.values, eventValues);
-    });
-}
 exports.getPersonPropertiesHash = __webpack_exports__.getPersonPropertiesHash;
 exports.matchPropertyFilters = __webpack_exports__.matchPropertyFilters;
 exports.matchTriggerPropertyFilters = __webpack_exports__.matchTriggerPropertyFilters;

package/dist/utils/property-utils.mjs

@@ -1,6 +1,6 @@
 import { isArray, isNull, isUndefined } from "@posthog/core";
+import { matchPropertyFilters, propertyComparisons } from "@posthog/core/surveys";
 import { jsonStringify } from "./request-utils.mjs";
-import { isMatchingRegex } from "./regex-utils.mjs";
 function getPersonPropertiesHash(distinct_id, userPropertiesToSet, userPropertiesToSetOnce) {
     return jsonStringify({
         distinct_id,
@@ -8,23 +8,6 @@ function getPersonPropertiesHash(distinct_id, userPropertiesToSet, userPropertie
         userPropertiesToSetOnce
     });
 }
-const propertyComparisons = {
-    exact: (targets, values)=>values.some((value)=>targets.some((target)=>value === target)),
-    is_not: (targets, values)=>values.every((value)=>targets.every((target)=>value !== target)),
-    regex: (targets, values)=>values.some((value)=>targets.some((target)=>isMatchingRegex(value, target))),
-    not_regex: (targets, values)=>values.every((value)=>targets.every((target)=>!isMatchingRegex(value, target))),
-    icontains: (targets, values)=>values.map(toLowerCase).some((value)=>targets.map(toLowerCase).some((target)=>value.includes(target))),
-    not_icontains: (targets, values)=>values.map(toLowerCase).every((value)=>targets.map(toLowerCase).every((target)=>!value.includes(target))),
-    gt: (targets, values)=>values.some((value)=>{
-            const numValue = parseFloat(value);
-            return !isNaN(numValue) && targets.some((t)=>numValue > parseFloat(t));
-        }),
-    lt: (targets, values)=>values.some((value)=>{
-            const numValue = parseFloat(value);
-            return !isNaN(numValue) && targets.some((t)=>numValue < parseFloat(t));
-        })
-};
-const toLowerCase = (v)=>v.toLowerCase();
 const NEGATIVE_OPERATORS = new Set([
     'is_not',
     'not_icontains',
@@ -49,17 +32,4 @@ function matchTriggerPropertyFilters(filters, eventProperties, personProperties)
         return comparisonFunction(targetValues, actualValues);
     });
 }
-function matchPropertyFilters(propertyFilters, eventProperties) {
-    if (!propertyFilters) return true;
-    return Object.entries(propertyFilters).every(([propertyName, filter])=>{
-        const eventPropertyValue = eventProperties?.[propertyName];
-        if (isUndefined(eventPropertyValue) || isNull(eventPropertyValue)) return false;
-        const eventValues = [
-            String(eventPropertyValue)
-        ];
-        const comparisonFunction = propertyComparisons[filter.operator];
-        if (!comparisonFunction) return false;
-        return comparisonFunction(filter.values, eventValues);
-    });
-}
 export { getPersonPropertiesHash, matchPropertyFilters, matchTriggerPropertyFilters, propertyComparisons };

package/dist/utils/regex-utils.d.ts

@@ -1,2 +1 @@
-export declare const isValidRegex: (str: string) => boolean;
-export declare const isMatchingRegex: (value: string, pattern: string) => boolean;
+export { isMatchingRegex, isValidRegex } from '@posthog/core/surveys';

package/dist/utils/regex-utils.js

@@ -24,25 +24,10 @@ var __webpack_require__ = {};
 var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
-    isMatchingRegex: ()=>isMatchingRegex,
-    isValidRegex: ()=>isValidRegex
+    isMatchingRegex: ()=>surveys_namespaceObject.isMatchingRegex,
+    isValidRegex: ()=>surveys_namespaceObject.isValidRegex
 });
-const isValidRegex = function(str) {
-    try {
-        new RegExp(str);
-    } catch  {
-        return false;
-    }
-    return true;
-};
-const isMatchingRegex = function(value, pattern) {
-    if (!isValidRegex(pattern)) return false;
-    try {
-        return new RegExp(pattern).test(value);
-    } catch  {
-        return false;
-    }
-};
+const surveys_namespaceObject = require("@posthog/core/surveys");
 exports.isMatchingRegex = __webpack_exports__.isMatchingRegex;
 exports.isValidRegex = __webpack_exports__.isValidRegex;
 for(var __webpack_i__ in __webpack_exports__)if (-1 === [

package/dist/utils/regex-utils.mjs

@@ -1,17 +1,2 @@
-const isValidRegex = function(str) {
-    try {
-        new RegExp(str);
-    } catch  {
-        return false;
-    }
-    return true;
-};
-const isMatchingRegex = function(value, pattern) {
-    if (!isValidRegex(pattern)) return false;
-    try {
-        return new RegExp(pattern).test(value);
-    } catch  {
-        return false;
-    }
-};
+import { isMatchingRegex, isValidRegex } from "@posthog/core/surveys";
 export { isMatchingRegex, isValidRegex };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/browser-common",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Internal shared browser utilities and extension primitives for PostHog Browser SDKs",
   "license": "MIT",
   "repository": {
@@ -65,8 +65,8 @@
     }
   },
   "dependencies": {
-    "@posthog/core": "^1.48.10",
-    "@posthog/types": "^1.405.2"
+    "@posthog/core": "^1.48.11",
+    "@posthog/types": "^1.406.1"
   },
   "devDependencies": {
     "@rslib/core": "0.10.6",