Sign In

@posthog/browser-common

Package Overview
Dependencies
Maintainers
22
Versions
12
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@posthog/browser-common - npm Package Compare versions

Comparing version
0.4.0
 to
0.5.0
+15
-1
dist/client.d.ts
import type { Logger } from '@posthog/core';
import type { Properties } from '@posthog/types';
import type { Compression } from './types/compression';
import type { Disposable } from './disposable';

@@ -69,2 +70,6 @@ import type { KeyValueStore } from './persistence';

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';
}

@@ -81,2 +86,11 @@ /**

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`. */

@@ -98,3 +112,3 @@ readonly groups: DeepReadonly<Record<string, string>>;

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;

@@ -101,0 +115,0 @@ /** Logger that follows the host client's debug/noise policy. */

+1
-1
dist/config.js

@@ -29,3 +29,3 @@ "use strict";

});
const packageVersion = "0.4.0";
const packageVersion = "0.5.0";
const Config = {

@@ -32,0 +32,0 @@ DEBUG: false,

+1
-1
dist/config.mjs

@@ -1,2 +0,2 @@

const packageVersion = "0.4.0";
const packageVersion = "0.5.0";
const Config = {

@@ -3,0 +3,0 @@ DEBUG: false,

+17
-14
dist/persistence.d.ts
/**
* 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.
*

@@ -14,15 +15,17 @@ * Keys map verbatim to the host client's shared persistence. In browser-v1,

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;
}
+3
-3
package.json
{
"name": "@posthog/browser-common",
"version": "0.4.0",
"version": "0.5.0",
"description": "Internal shared browser utilities and extension primitives for PostHog Browser SDKs",

@@ -68,4 +68,4 @@ "license": "MIT",

"dependencies": {
"@posthog/core": "^1.46.8",
"@posthog/types": "^1.402.0"
"@posthog/core": "^1.47.0",
"@posthog/types": "^1.402.2"
},

@@ -72,0 +72,0 @@ "devDependencies": {

+25
-7
README.md

@@ -57,14 +57,32 @@ # @posthog/browser-common

- **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

@@ -71,0 +89,0 @@