@posthog/browser-common 0.4.0 → 0.5.1

package/README.md

@@ -54,17 +54,35 @@ synchronous callback into idempotent teardown.
 
 What an extension is given in `setup` — the adapter shared by extensions on that host SDK instance:
 
-- **identity and session**: `distinctId`, `anonymousId`, `groups`, `session`
+- **identity and session**: `distinctId`, `anonymousId`, `deviceId`, `groups`, `session`, `initialPersonProperties`
+- **SDK metadata**: `library`
 - **events**: `capture(...)`, `registerDynamicEventProperties(...)`, `onEvent(...)`
 - **server config**: `onRemoteConfig(...)`
-- **transport**: `projectToken`, `sendRequest(path, init?)`
+- **transport**: `projectToken`, `sendRequest(path, init?)`, including `compression` and `sentAt` options
 - **storage and logging**: `kv`, `logger`
 
-Identity, session, and the public project token are always-ready synchronous
-reads. Operations that may perform I/O, including `capture`, `sendRequest`,
-and `kv`, are awaitable. `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]')`.
+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
+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]')`.
+
+Initialize KV during asynchronous setup before using its synchronous buffer:
+
+```ts
+await client.kv.initialize()
+const state = client.kv.get<{ first: boolean; second: string }>(['first', 'second'])
+client.kv.set({ ...state, first: true })
+client.kv.remove(['first', 'second'])
+```
+
+Initialization is idempotent and may be asynchronous while a host hydrates its buffer. After it completes, reads,
+writes, and removals are synchronous; batch reads, object writes, and multi-key removals operate on related values
+coherently. The host owns ordered durable flushing.
+
+KV keys map directly to shared host persistence: reset clears them, collisions can overwrite host state, and unknown
+keys may be captured as event properties. Use stable extension-owned keys with an explicit exposure policy, and do not
+store sensitive values unless their transmission is approved.
 
 ### Host runtime
 

package/dist/client.d.ts

@@ -1,5 +1,6 @@
 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 { KeyValueStore } from './persistence';
 import type { Listener } from './pubsub';
@@ -26,7 +27,7 @@ export interface CapturedEventInfo {
 }
 /** Per-call capture overrides, mirroring the client's public capture options. */
 export interface CaptureOptions {
-    /** Override the event timestamp sent to PostHog. */
+    /** Override the event timestamp sent to PostHog. UTC is preferred; non-UTC input is converted to UTC. */
     timestamp?: Date;
     /** Override the event UUID used for de-duplication. */
     uuid?: string;
@@ -66,6 +67,10 @@ export interface SendRequestInit {
     transport?: RequestTransport;
     /** Abort the request if it does not complete within this many milliseconds. */
     timeoutMs?: number;
+    /** Compression used by the browser transport. */
+    compression?: Compression | 'best-available';
+    /** Where POST requests add `sent_at`. For GET, `query` adds the cache-busting `_` parameter and `body` has no effect. */
+    sentAt?: 'body' | 'query';
 }
 /**
  * The host SDK surface handed to an extension in `setup`. A conforming host
@@ -77,6 +82,15 @@ export interface Client {
     readonly distinctId: string;
     /** The anonymous device id carried across identify calls. */
     readonly anonymousId: string;
+    /** The actual persisted device id, absent in cookieless contexts. */
+    readonly deviceId: string | undefined;
+    /** Live host SDK metadata. */
+    readonly library: {
+        readonly name: string;
+        readonly version: string;
+    };
+    /** Initial person properties used for feature evaluation. */
+    readonly initialPersonProperties: DeepReadonly<Record<string, unknown>>;
     /** Active group memberships attached to events as `$groups`. */
     readonly groups: DeepReadonly<Record<string, string>>;
     /** The current session, created on first read if needed. */
@@ -93,7 +107,7 @@ export interface Client {
     readonly projectToken: string;
     /** Sends a request through the host SDK's transport. */
     sendRequest(path: string, init?: SendRequestInit): Promise<ApiResponse>;
-    /** Awaitable key-value storage backed by the host client's persistence. */
+    /** Initializable, synchronously buffered key-value storage backed by the host client's persistence. */
     readonly kv: KeyValueStore;
     /** Logger that follows the host client's debug/noise policy. */
     readonly logger: Logger;

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.4.0";
+const packageVersion = "0.5.1";
 const Config = {
     DEBUG: false,
     LIB_VERSION: packageVersion,

package/dist/config.mjs

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

package/dist/persistence.d.ts

@@ -1,7 +1,8 @@
 /**
- * Key-value store for small extension state. Implementations backed by
- * synchronous persistence may return immediately, while asynchronous stores
- * (for example IndexedDB) may return promises. Consumers can await either.
+ * Key-value store for small extension state. A host may initialize an asynchronous
+ * backend before exposing synchronous operations over its in-memory buffer. Writes
+ * must update that buffer before returning; ordered durable flushing remains the
+ * host's responsibility. Reads treat `undefined` values as absent.
  *
  * Keys map verbatim to the host client's shared persistence. In browser-v1,
  * unknown keys are normally included as event properties, collisions overwrite
@@ -11,17 +12,19 @@
  * JSON-serializable.
  */
 export interface KeyValueStore {
+    /** Populate the in-memory buffer from durable storage. Calls are idempotent. */
+    initialize(): void | Promise<void>;
+    /** Read several initialized values in one operation. Missing keys are omitted. */
+    get<T extends object>(keys: readonly (keyof T & string)[]): Partial<T>;
+    /** Read one initialized value by key, returning `undefined` when it is missing. */
+    get<T = unknown>(key: string): T | undefined;
     /**
-     * Read a value by key.
-     *
-     * @returns The stored value, or `undefined` when the key is missing.
+     * Immediately update the initialized buffer. `null` is durable; `undefined` is
+     * accepted for compatibility but treated as absent by reads and is not portable.
      */
-    get<T = unknown>(key: string): T | undefined | Promise<T | undefined>;
-    /**
-     * Forward a JSON-serializable value, including nullish values, to the host's
-     * native persistence. `undefined` is not portable or durable storage.
-     */
-    set(key: string, value: unknown): void | Promise<void>;
-    /** Remove a value by key. This is the portable deletion operation. */
-    remove(key: string): void | Promise<void>;
+    set(key: string, value: unknown): void;
+    /** Coherently update several related values in the initialized buffer. */
+    set(values: Record<string, unknown>): void;
+    /** Remove one or several values from the initialized buffer in one operation. */
+    remove(keyOrKeys: string | readonly string[]): void;
 }

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

@@ -0,0 +1,3 @@
+export type MaybePromise<T> = T | Promise<T>;
+/** Chain sync and async values without deferring synchronous work to a microtask. */
+export declare const continueWith: <T, R>(result: MaybePromise<T>, callback: (value: T) => MaybePromise<R>) => MaybePromise<R>;

package/dist/utils/promise-utils.js

@@ -0,0 +1,39 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __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__);
+__webpack_require__.d(__webpack_exports__, {
+    continueWith: ()=>continueWith
+});
+const continueWith = (result, callback)=>{
+    const promise = result;
+    return promise?.then ? promise.then(callback) : callback(result);
+};
+exports.continueWith = __webpack_exports__.continueWith;
+for(var __webpack_i__ in __webpack_exports__)if (-1 === [
+    "continueWith"
+].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/utils/promise-utils.mjs

@@ -0,0 +1,5 @@
+const continueWith = (result, callback)=>{
+    const promise = result;
+    return promise?.then ? promise.then(callback) : callback(result);
+};
+export { continueWith };

package/package.json

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