@posthog/browser-common 0.5.2 → 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.2";
+const packageVersion = "0.6.0";
 const Config = {
     DEBUG: false,
     LIB_VERSION: packageVersion,

package/dist/config.mjs

@@ -1,4 +1,4 @@
-const packageVersion = "0.5.2";
+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/package.json

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