@posthog/core 1.25.3 → 1.26.0

package/dist/error-tracking/exception-steps.d.ts

@@ -0,0 +1,38 @@
+export declare const EXCEPTION_STEP_INTERNAL_FIELDS: {
+    readonly MESSAGE: "$message";
+    readonly TIMESTAMP: "$timestamp";
+};
+export type ExceptionStep = {
+    [EXCEPTION_STEP_INTERNAL_FIELDS.MESSAGE]: string;
+    [EXCEPTION_STEP_INTERNAL_FIELDS.TIMESTAMP]: string | number;
+    [key: string]: unknown;
+};
+/** NOTE: This type is also defined in `@posthog/types` (posthog-config.ts). Keep both in sync. */
+export type ExceptionStepsConfig = {
+    enabled?: boolean;
+    max_bytes?: number;
+};
+export type ResolvedExceptionStepsConfig = {
+    enabled: boolean;
+    max_bytes: number;
+};
+export declare const DEFAULT_EXCEPTION_STEPS_CONFIG: ResolvedExceptionStepsConfig;
+export declare function resolveExceptionStepsConfig(config?: ExceptionStepsConfig | null): ResolvedExceptionStepsConfig;
+export declare function stripReservedExceptionStepFields(properties?: Record<string, unknown> | null): {
+    sanitizedProperties: Record<string, unknown>;
+    droppedKeys: string[];
+};
+export declare class ExceptionStepsBuffer {
+    private _entries;
+    private _totalBytes;
+    private _config;
+    constructor(config?: ExceptionStepsConfig | null);
+    setConfig(config?: ExceptionStepsConfig | null): void;
+    add(step: ExceptionStep): void;
+    getAttachable(): ExceptionStep[];
+    clear(): void;
+    size(): number;
+    private _trimToMaxBytes;
+}
+export declare function getUtf8ByteLength(value: string): number;
+//# sourceMappingURL=exception-steps.d.ts.map

package/dist/error-tracking/exception-steps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exception-steps.d.ts","sourceRoot":"","sources":["../../src/error-tracking/exception-steps.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,8BAA8B;;;CAGjC,CAAA;AAOV,MAAM,MAAM,aAAa,GAAG;IAC1B,CAAC,8BAA8B,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChD,CAAC,8BAA8B,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAC3D,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB,CAAA;AAED,kGAAkG;AAClG,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,4BAA4B,GAAG;IACzC,OAAO,EAAE,OAAO,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,eAAO,MAAM,8BAA8B,EAAE,4BAG5C,CAAA;AAED,wBAAgB,2BAA2B,CAAC,MAAM,CAAC,EAAE,oBAAoB,GAAG,IAAI,GAAG,4BAA4B,CAS9G;AAED,wBAAgB,gCAAgC,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG;IAC7F,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC5C,WAAW,EAAE,MAAM,EAAE,CAAA;CACtB,CAmBA;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAA+C;IAC/D,OAAO,CAAC,WAAW,CAAY;IAC/B,OAAO,CAAC,OAAO,CAA8B;gBAEjC,MAAM,CAAC,EAAE,oBAAoB,GAAG,IAAI;IAIzC,SAAS,CAAC,MAAM,CAAC,EAAE,oBAAoB,GAAG,IAAI,GAAG,IAAI;IAKrD,GAAG,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;IAgB9B,aAAa,IAAI,aAAa,EAAE;IAIhC,KAAK,IAAI,IAAI;IAKb,IAAI,IAAI,MAAM;IAIrB,OAAO,CAAC,eAAe;CAQxB;AAuFD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAiBvD"}

package/dist/error-tracking/exception-steps.js

@@ -0,0 +1,187 @@
+"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__, {
+    stripReservedExceptionStepFields: ()=>stripReservedExceptionStepFields,
+    ExceptionStepsBuffer: ()=>ExceptionStepsBuffer,
+    EXCEPTION_STEP_INTERNAL_FIELDS: ()=>EXCEPTION_STEP_INTERNAL_FIELDS,
+    resolveExceptionStepsConfig: ()=>resolveExceptionStepsConfig,
+    getUtf8ByteLength: ()=>getUtf8ByteLength,
+    DEFAULT_EXCEPTION_STEPS_CONFIG: ()=>DEFAULT_EXCEPTION_STEPS_CONFIG
+});
+const index_js_namespaceObject = require("../utils/index.js");
+const EXCEPTION_STEP_INTERNAL_FIELDS = {
+    MESSAGE: '$message',
+    TIMESTAMP: '$timestamp'
+};
+const RESERVED_EXCEPTION_STEP_KEYS = new Set([
+    EXCEPTION_STEP_INTERNAL_FIELDS.MESSAGE,
+    EXCEPTION_STEP_INTERNAL_FIELDS.TIMESTAMP
+]);
+const DEFAULT_EXCEPTION_STEPS_CONFIG = {
+    enabled: true,
+    max_bytes: 32768
+};
+function resolveExceptionStepsConfig(config) {
+    if (!config) return {
+        ...DEFAULT_EXCEPTION_STEPS_CONFIG
+    };
+    return {
+        enabled: config.enabled ?? DEFAULT_EXCEPTION_STEPS_CONFIG.enabled,
+        max_bytes: normalizePositiveInteger(config.max_bytes, DEFAULT_EXCEPTION_STEPS_CONFIG.max_bytes)
+    };
+}
+function stripReservedExceptionStepFields(properties) {
+    if (!properties) return {
+        sanitizedProperties: {},
+        droppedKeys: []
+    };
+    const droppedKeys = [];
+    const sanitizedProperties = Object.keys(properties).reduce((acc, key)=>{
+        if (RESERVED_EXCEPTION_STEP_KEYS.has(key)) {
+            droppedKeys.push(key);
+            return acc;
+        }
+        acc[key] = properties[key];
+        return acc;
+    }, {});
+    return {
+        sanitizedProperties,
+        droppedKeys
+    };
+}
+class ExceptionStepsBuffer {
+    constructor(config){
+        this._entries = [];
+        this._totalBytes = 0;
+        this._config = resolveExceptionStepsConfig(config);
+    }
+    setConfig(config) {
+        this._config = resolveExceptionStepsConfig(config);
+        this._trimToMaxBytes();
+    }
+    add(step) {
+        const serialized = normalizeAndSerializeStep(step);
+        if (!serialized) return;
+        const bytes = getUtf8ByteLength(serialized.json);
+        if (bytes > this._config.max_bytes) return;
+        this._entries.push({
+            step: serialized.step,
+            bytes
+        });
+        this._totalBytes += bytes;
+        this._trimToMaxBytes();
+    }
+    getAttachable() {
+        return this._entries.map((e)=>e.step);
+    }
+    clear() {
+        this._entries = [];
+        this._totalBytes = 0;
+    }
+    size() {
+        return this._entries.length;
+    }
+    _trimToMaxBytes() {
+        while(this._totalBytes > this._config.max_bytes && this._entries.length > 0){
+            const evicted = this._entries.shift();
+            if (evicted) this._totalBytes -= evicted.bytes;
+        }
+    }
+}
+function normalizePositiveInteger(input, fallback) {
+    if (!(0, index_js_namespaceObject.isNumber)(input) || input === 1 / 0 || input === -1 / 0) return fallback;
+    const normalized = Math.floor(input);
+    if (normalized < 0) return fallback;
+    return normalized;
+}
+function normalizeAndSerializeStep(step) {
+    const json = safeStringify(step);
+    if (!json) return;
+    try {
+        const parsed = JSON.parse(json);
+        if (!(0, index_js_namespaceObject.isObject)(parsed)) return;
+        const parsedStep = parsed;
+        const message = parsedStep[EXCEPTION_STEP_INTERNAL_FIELDS.MESSAGE];
+        const timestamp = parsedStep[EXCEPTION_STEP_INTERNAL_FIELDS.TIMESTAMP];
+        if (!(0, index_js_namespaceObject.isString)(message) || 0 === message.trim().length) return;
+        if (!(0, index_js_namespaceObject.isString)(timestamp) && !(0, index_js_namespaceObject.isNumber)(timestamp)) return;
+        return {
+            step: parsedStep,
+            json
+        };
+    } catch  {
+        return;
+    }
+}
+function safeStringify(value) {
+    const seen = new WeakSet();
+    try {
+        return JSON.stringify(value, (_key, replacementValue)=>{
+            if ('bigint' == typeof replacementValue) return replacementValue.toString();
+            if ('function' == typeof replacementValue || 'symbol' == typeof replacementValue) return;
+            if (replacementValue instanceof Date) return replacementValue.toISOString();
+            if (replacementValue instanceof Error) return {
+                name: replacementValue.name,
+                message: replacementValue.message,
+                stack: replacementValue.stack
+            };
+            if (replacementValue && 'object' == typeof replacementValue) {
+                if (seen.has(replacementValue)) return '[Circular]';
+                seen.add(replacementValue);
+            }
+            return replacementValue;
+        });
+    } catch  {
+        return;
+    }
+}
+function getUtf8ByteLength(value) {
+    if ('undefined' != typeof TextEncoder) return new TextEncoder().encode(value).length;
+    const encoded = encodeURIComponent(value);
+    let byteLength = 0;
+    for(let i = 0; i < encoded.length; i++)if ('%' === encoded[i]) {
+        byteLength += 1;
+        i += 2;
+    } else byteLength += 1;
+    return byteLength;
+}
+exports.DEFAULT_EXCEPTION_STEPS_CONFIG = __webpack_exports__.DEFAULT_EXCEPTION_STEPS_CONFIG;
+exports.EXCEPTION_STEP_INTERNAL_FIELDS = __webpack_exports__.EXCEPTION_STEP_INTERNAL_FIELDS;
+exports.ExceptionStepsBuffer = __webpack_exports__.ExceptionStepsBuffer;
+exports.getUtf8ByteLength = __webpack_exports__.getUtf8ByteLength;
+exports.resolveExceptionStepsConfig = __webpack_exports__.resolveExceptionStepsConfig;
+exports.stripReservedExceptionStepFields = __webpack_exports__.stripReservedExceptionStepFields;
+for(var __webpack_i__ in __webpack_exports__)if (-1 === [
+    "DEFAULT_EXCEPTION_STEPS_CONFIG",
+    "EXCEPTION_STEP_INTERNAL_FIELDS",
+    "ExceptionStepsBuffer",
+    "getUtf8ByteLength",
+    "resolveExceptionStepsConfig",
+    "stripReservedExceptionStepFields"
+].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/error-tracking/exception-steps.mjs

@@ -0,0 +1,138 @@
+import { isNumber, isObject, isString } from "../utils/index.mjs";
+const EXCEPTION_STEP_INTERNAL_FIELDS = {
+    MESSAGE: '$message',
+    TIMESTAMP: '$timestamp'
+};
+const RESERVED_EXCEPTION_STEP_KEYS = new Set([
+    EXCEPTION_STEP_INTERNAL_FIELDS.MESSAGE,
+    EXCEPTION_STEP_INTERNAL_FIELDS.TIMESTAMP
+]);
+const DEFAULT_EXCEPTION_STEPS_CONFIG = {
+    enabled: true,
+    max_bytes: 32768
+};
+function resolveExceptionStepsConfig(config) {
+    if (!config) return {
+        ...DEFAULT_EXCEPTION_STEPS_CONFIG
+    };
+    return {
+        enabled: config.enabled ?? DEFAULT_EXCEPTION_STEPS_CONFIG.enabled,
+        max_bytes: normalizePositiveInteger(config.max_bytes, DEFAULT_EXCEPTION_STEPS_CONFIG.max_bytes)
+    };
+}
+function stripReservedExceptionStepFields(properties) {
+    if (!properties) return {
+        sanitizedProperties: {},
+        droppedKeys: []
+    };
+    const droppedKeys = [];
+    const sanitizedProperties = Object.keys(properties).reduce((acc, key)=>{
+        if (RESERVED_EXCEPTION_STEP_KEYS.has(key)) {
+            droppedKeys.push(key);
+            return acc;
+        }
+        acc[key] = properties[key];
+        return acc;
+    }, {});
+    return {
+        sanitizedProperties,
+        droppedKeys
+    };
+}
+class ExceptionStepsBuffer {
+    constructor(config){
+        this._entries = [];
+        this._totalBytes = 0;
+        this._config = resolveExceptionStepsConfig(config);
+    }
+    setConfig(config) {
+        this._config = resolveExceptionStepsConfig(config);
+        this._trimToMaxBytes();
+    }
+    add(step) {
+        const serialized = normalizeAndSerializeStep(step);
+        if (!serialized) return;
+        const bytes = getUtf8ByteLength(serialized.json);
+        if (bytes > this._config.max_bytes) return;
+        this._entries.push({
+            step: serialized.step,
+            bytes
+        });
+        this._totalBytes += bytes;
+        this._trimToMaxBytes();
+    }
+    getAttachable() {
+        return this._entries.map((e)=>e.step);
+    }
+    clear() {
+        this._entries = [];
+        this._totalBytes = 0;
+    }
+    size() {
+        return this._entries.length;
+    }
+    _trimToMaxBytes() {
+        while(this._totalBytes > this._config.max_bytes && this._entries.length > 0){
+            const evicted = this._entries.shift();
+            if (evicted) this._totalBytes -= evicted.bytes;
+        }
+    }
+}
+function normalizePositiveInteger(input, fallback) {
+    if (!isNumber(input) || input === 1 / 0 || input === -1 / 0) return fallback;
+    const normalized = Math.floor(input);
+    if (normalized < 0) return fallback;
+    return normalized;
+}
+function normalizeAndSerializeStep(step) {
+    const json = safeStringify(step);
+    if (!json) return;
+    try {
+        const parsed = JSON.parse(json);
+        if (!isObject(parsed)) return;
+        const parsedStep = parsed;
+        const message = parsedStep[EXCEPTION_STEP_INTERNAL_FIELDS.MESSAGE];
+        const timestamp = parsedStep[EXCEPTION_STEP_INTERNAL_FIELDS.TIMESTAMP];
+        if (!isString(message) || 0 === message.trim().length) return;
+        if (!isString(timestamp) && !isNumber(timestamp)) return;
+        return {
+            step: parsedStep,
+            json
+        };
+    } catch  {
+        return;
+    }
+}
+function safeStringify(value) {
+    const seen = new WeakSet();
+    try {
+        return JSON.stringify(value, (_key, replacementValue)=>{
+            if ('bigint' == typeof replacementValue) return replacementValue.toString();
+            if ('function' == typeof replacementValue || 'symbol' == typeof replacementValue) return;
+            if (replacementValue instanceof Date) return replacementValue.toISOString();
+            if (replacementValue instanceof Error) return {
+                name: replacementValue.name,
+                message: replacementValue.message,
+                stack: replacementValue.stack
+            };
+            if (replacementValue && 'object' == typeof replacementValue) {
+                if (seen.has(replacementValue)) return '[Circular]';
+                seen.add(replacementValue);
+            }
+            return replacementValue;
+        });
+    } catch  {
+        return;
+    }
+}
+function getUtf8ByteLength(value) {
+    if ('undefined' != typeof TextEncoder) return new TextEncoder().encode(value).length;
+    const encoded = encodeURIComponent(value);
+    let byteLength = 0;
+    for(let i = 0; i < encoded.length; i++)if ('%' === encoded[i]) {
+        byteLength += 1;
+        i += 2;
+    } else byteLength += 1;
+    return byteLength;
+}
+export { DEFAULT_EXCEPTION_STEPS_CONFIG, EXCEPTION_STEP_INTERNAL_FIELDS, ExceptionStepsBuffer, getUtf8ByteLength, resolveExceptionStepsConfig, stripReservedExceptionStepFields };

package/dist/error-tracking/index.d.ts

@@ -3,4 +3,5 @@ export type * from './types';
 export * from './parsers';
 export * from './coercers';
 export * from './utils';
+export * from './exception-steps';
 //# sourceMappingURL=index.d.ts.map

package/dist/error-tracking/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/error-tracking/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAA;AAC1C,mBAAmB,SAAS,CAAA;AAC5B,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/error-tracking/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAA;AAC1C,mBAAmB,SAAS,CAAA;AAC5B,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,mBAAmB,CAAA"}

package/dist/error-tracking/index.js

@@ -6,6 +6,9 @@ var __webpack_modules__ = {
     "./error-properties-builder": function(module) {
         module.exports = require("./error-properties-builder.js");
     },
+    "./exception-steps": function(module) {
+        module.exports = require("./exception-steps.js");
+    },
     "./parsers": function(module) {
         module.exports = require("./parsers/index.js");
     },
@@ -80,6 +83,12 @@ var __webpack_exports__ = {};
         return _utils__WEBPACK_IMPORTED_MODULE_3__[key];
     }).bind(0, __WEBPACK_IMPORT_KEY__);
     __webpack_require__.d(__webpack_exports__, __WEBPACK_REEXPORT_OBJECT__);
+    var _exception_steps__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__("./exception-steps");
+    var __WEBPACK_REEXPORT_OBJECT__ = {};
+    for(var __WEBPACK_IMPORT_KEY__ in _exception_steps__WEBPACK_IMPORTED_MODULE_4__)if ("default" !== __WEBPACK_IMPORT_KEY__) __WEBPACK_REEXPORT_OBJECT__[__WEBPACK_IMPORT_KEY__] = (function(key) {
+        return _exception_steps__WEBPACK_IMPORTED_MODULE_4__[key];
+    }).bind(0, __WEBPACK_IMPORT_KEY__);
+    __webpack_require__.d(__webpack_exports__, __WEBPACK_REEXPORT_OBJECT__);
 })();
 for(var __webpack_i__ in __webpack_exports__)exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
 Object.defineProperty(exports, '__esModule', {

package/dist/error-tracking/index.mjs

@@ -2,3 +2,4 @@ export * from "./error-properties-builder.mjs";
 export * from "./parsers/index.mjs";
 export * from "./coercers/index.mjs";
 export * from "./utils.mjs";
+export * from "./exception-steps.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/core",
-  "version": "1.25.3",
+  "version": "1.26.0",
   "license": "MIT",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/error-tracking/exception-steps.spec.ts

@@ -0,0 +1,90 @@
+import {
+  EXCEPTION_STEP_INTERNAL_FIELDS,
+  ExceptionStep,
+  ExceptionStepsBuffer,
+  getUtf8ByteLength,
+  resolveExceptionStepsConfig,
+  stripReservedExceptionStepFields,
+} from './exception-steps'
+
+describe('exception steps', () => {
+  describe('resolveExceptionStepsConfig', () => {
+    it('uses defaults when no config is passed', () => {
+      expect(resolveExceptionStepsConfig()).toEqual({
+        enabled: true,
+        max_bytes: 32768,
+      })
+    })
+
+    it('falls back to defaults for invalid values', () => {
+      expect(resolveExceptionStepsConfig({ max_bytes: Number.NaN })).toEqual({
+        enabled: true,
+        max_bytes: 32768,
+      })
+    })
+  })
+
+  describe('stripReservedExceptionStepFields', () => {
+    it('strips reserved fields and keeps custom properties', () => {
+      const result = stripReservedExceptionStepFields({
+        [EXCEPTION_STEP_INTERNAL_FIELDS.MESSAGE]: 'should-strip',
+        [EXCEPTION_STEP_INTERNAL_FIELDS.TIMESTAMP]: 'should-strip',
+        custom: true,
+      })
+
+      expect(result).toEqual({
+        sanitizedProperties: { custom: true },
+        droppedKeys: [EXCEPTION_STEP_INTERNAL_FIELDS.MESSAGE, EXCEPTION_STEP_INTERNAL_FIELDS.TIMESTAMP],
+      })
+    })
+  })
+
+  describe('ExceptionStepsBuffer', () => {
+    const makeStep = (message: string): ExceptionStep => ({
+      [EXCEPTION_STEP_INTERNAL_FIELDS.MESSAGE]: message,
+      [EXCEPTION_STEP_INTERNAL_FIELDS.TIMESTAMP]: '2026-01-01T00:00:00.000Z',
+    })
+
+    const bytesOf = (step: ExceptionStep) => getUtf8ByteLength(JSON.stringify(step))
+
+    it.each([
+      {
+        desc: 'evicts oldest steps when max bytes are exceeded',
+        config: { max_bytes: bytesOf(makeStep('two')) + bytesOf(makeStep('three')) },
+        steps: [makeStep('one'), makeStep('two'), makeStep('three')],
+        expected: ['two', 'three'],
+      },
+      {
+        desc: 'keeps the most recent step when budget fits only one',
+        config: { max_bytes: bytesOf(makeStep('one')) },
+        steps: [makeStep('one'), makeStep('two')],
+        expected: ['two'],
+      },
+      {
+        desc: 'skips malformed steps that cannot be normalized',
+        config: { max_bytes: 10000 },
+        steps: [{ $message: '', $timestamp: '2026-01-01T00:00:00.000Z' } as ExceptionStep, makeStep('valid')],
+        expected: ['valid'],
+      },
+      {
+        desc: 'drops a step that exceeds the entire budget on its own',
+        config: { max_bytes: 10 },
+        steps: [makeStep('this message is way too long for the tiny budget')],
+        expected: [],
+      },
+    ])('$desc', ({ config, steps, expected }) => {
+      const buffer = new ExceptionStepsBuffer(config)
+      for (const step of steps) {
+        buffer.add(step)
+      }
+      expect(buffer.getAttachable().map((s) => s.$message)).toEqual(expected)
+    })
+
+    it('clears all steps', () => {
+      const buffer = new ExceptionStepsBuffer({ max_bytes: 10000 })
+      buffer.add(makeStep('one'))
+      buffer.clear()
+      expect(buffer.size()).toBe(0)
+    })
+  })
+})

package/src/error-tracking/exception-steps.ts

@@ -0,0 +1,225 @@
+import { isArray, isNumber, isObject, isString } from '@/utils'
+
+export const EXCEPTION_STEP_INTERNAL_FIELDS = {
+  MESSAGE: '$message',
+  TIMESTAMP: '$timestamp',
+} as const
+
+const RESERVED_EXCEPTION_STEP_KEYS = new Set<string>([
+  EXCEPTION_STEP_INTERNAL_FIELDS.MESSAGE,
+  EXCEPTION_STEP_INTERNAL_FIELDS.TIMESTAMP,
+])
+
+export type ExceptionStep = {
+  [EXCEPTION_STEP_INTERNAL_FIELDS.MESSAGE]: string
+  [EXCEPTION_STEP_INTERNAL_FIELDS.TIMESTAMP]: string | number
+  [key: string]: unknown
+}
+
+/** NOTE: This type is also defined in `@posthog/types` (posthog-config.ts). Keep both in sync. */
+export type ExceptionStepsConfig = {
+  enabled?: boolean
+  max_bytes?: number
+}
+
+export type ResolvedExceptionStepsConfig = {
+  enabled: boolean
+  max_bytes: number
+}
+
+export const DEFAULT_EXCEPTION_STEPS_CONFIG: ResolvedExceptionStepsConfig = {
+  enabled: true,
+  max_bytes: 32768, // ~32KB
+}
+
+export function resolveExceptionStepsConfig(config?: ExceptionStepsConfig | null): ResolvedExceptionStepsConfig {
+  if (!config) {
+    return { ...DEFAULT_EXCEPTION_STEPS_CONFIG }
+  }
+
+  return {
+    enabled: config.enabled ?? DEFAULT_EXCEPTION_STEPS_CONFIG.enabled,
+    max_bytes: normalizePositiveInteger(config.max_bytes, DEFAULT_EXCEPTION_STEPS_CONFIG.max_bytes),
+  }
+}
+
+export function stripReservedExceptionStepFields(properties?: Record<string, unknown> | null): {
+  sanitizedProperties: Record<string, unknown>
+  droppedKeys: string[]
+} {
+  if (!properties) {
+    return { sanitizedProperties: {}, droppedKeys: [] }
+  }
+
+  const droppedKeys: string[] = []
+  const sanitizedProperties = Object.keys(properties).reduce<Record<string, unknown>>((acc, key) => {
+    if (RESERVED_EXCEPTION_STEP_KEYS.has(key)) {
+      droppedKeys.push(key)
+      return acc
+    }
+    acc[key] = properties[key]
+    return acc
+  }, {})
+
+  return {
+    sanitizedProperties,
+    droppedKeys,
+  }
+}
+
+export class ExceptionStepsBuffer {
+  private _entries: { step: ExceptionStep; bytes: number }[] = []
+  private _totalBytes: number = 0
+  private _config: ResolvedExceptionStepsConfig
+
+  constructor(config?: ExceptionStepsConfig | null) {
+    this._config = resolveExceptionStepsConfig(config)
+  }
+
+  public setConfig(config?: ExceptionStepsConfig | null): void {
+    this._config = resolveExceptionStepsConfig(config)
+    this._trimToMaxBytes()
+  }
+
+  public add(step: ExceptionStep): void {
+    const serialized = normalizeAndSerializeStep(step)
+    if (!serialized) {
+      return
+    }
+
+    const bytes = getUtf8ByteLength(serialized.json)
+    if (bytes > this._config.max_bytes) {
+      return
+    }
+
+    this._entries.push({ step: serialized.step, bytes })
+    this._totalBytes += bytes
+    this._trimToMaxBytes()
+  }
+
+  public getAttachable(): ExceptionStep[] {
+    return this._entries.map((e) => e.step)
+  }
+
+  public clear(): void {
+    this._entries = []
+    this._totalBytes = 0
+  }
+
+  public size(): number {
+    return this._entries.length
+  }
+
+  private _trimToMaxBytes(): void {
+    while (this._totalBytes > this._config.max_bytes && this._entries.length > 0) {
+      const evicted = this._entries.shift()
+      if (evicted) {
+        this._totalBytes -= evicted.bytes
+      }
+    }
+  }
+}
+
+function normalizePositiveInteger(input: number | undefined, fallback: number): number {
+  if (!isNumber(input) || input === Infinity || input === -Infinity) {
+    return fallback
+  }
+
+  const normalized = Math.floor(input)
+  if (normalized < 0) {
+    return fallback
+  }
+
+  return normalized
+}
+
+function normalizeAndSerializeStep(step: ExceptionStep): { step: ExceptionStep; json: string } | undefined {
+  const json = safeStringify(step)
+  if (!json) {
+    return undefined
+  }
+
+  try {
+    const parsed = JSON.parse(json)
+    if (!isObject(parsed)) {
+      return undefined
+    }
+
+    const parsedStep = parsed as Record<string, unknown>
+    const message = parsedStep[EXCEPTION_STEP_INTERNAL_FIELDS.MESSAGE]
+    const timestamp = parsedStep[EXCEPTION_STEP_INTERNAL_FIELDS.TIMESTAMP]
+
+    if (!isString(message) || message.trim().length === 0) {
+      return undefined
+    }
+
+    if (!isString(timestamp) && !isNumber(timestamp)) {
+      return undefined
+    }
+
+    return {
+      step: parsedStep as ExceptionStep,
+      json,
+    }
+  } catch {
+    return undefined
+  }
+}
+
+function safeStringify(value: unknown): string | undefined {
+  const seen = new WeakSet<object>()
+
+  try {
+    return JSON.stringify(value, (_key, replacementValue: unknown) => {
+      if (typeof replacementValue === 'bigint') {
+        return replacementValue.toString()
+      }
+
+      if (typeof replacementValue === 'function' || typeof replacementValue === 'symbol') {
+        return undefined
+      }
+
+      if (replacementValue instanceof Date) {
+        return replacementValue.toISOString()
+      }
+
+      if (replacementValue instanceof Error) {
+        return {
+          name: replacementValue.name,
+          message: replacementValue.message,
+          stack: replacementValue.stack,
+        }
+      }
+
+      if (replacementValue && typeof replacementValue === 'object') {
+        if (seen.has(replacementValue)) {
+          return '[Circular]'
+        }
+        seen.add(replacementValue)
+      }
+
+      return replacementValue
+    })
+  } catch {
+    return undefined
+  }
+}
+
+export function getUtf8ByteLength(value: string): number {
+  if (typeof TextEncoder !== 'undefined') {
+    return new TextEncoder().encode(value).length
+  }
+
+  const encoded = encodeURIComponent(value)
+  let byteLength = 0
+  for (let i = 0; i < encoded.length; i++) {
+    if (encoded[i] === '%') {
+      byteLength += 1
+      i += 2
+    } else {
+      byteLength += 1
+    }
+  }
+
+  return byteLength
+}

package/src/error-tracking/index.ts

@@ -3,3 +3,4 @@ export type * from './types'
 export * from './parsers'
 export * from './coercers'
 export * from './utils'
+export * from './exception-steps'