@posthog/core 1.41.0 → 1.42.0

package/dist/types.js

@@ -89,82 +89,71 @@ const FeatureFlagError = {
     UNKNOWN_ERROR: 'unknown_error',
     apiError: (status)=>`api_error_${status}`
 };
-var SurveyPosition = /*#__PURE__*/ function(SurveyPosition) {
-    SurveyPosition["TopLeft"] = "top_left";
-    SurveyPosition["TopCenter"] = "top_center";
-    SurveyPosition["TopRight"] = "top_right";
-    SurveyPosition["MiddleLeft"] = "middle_left";
-    SurveyPosition["MiddleCenter"] = "middle_center";
-    SurveyPosition["MiddleRight"] = "middle_right";
-    SurveyPosition["Left"] = "left";
-    SurveyPosition["Right"] = "right";
-    SurveyPosition["Center"] = "center";
-    return SurveyPosition;
-}({});
-var SurveyWidgetType = /*#__PURE__*/ function(SurveyWidgetType) {
-    SurveyWidgetType["Button"] = "button";
-    SurveyWidgetType["Tab"] = "tab";
-    SurveyWidgetType["Selector"] = "selector";
-    return SurveyWidgetType;
-}({});
-var SurveyType = /*#__PURE__*/ function(SurveyType) {
-    SurveyType["Popover"] = "popover";
-    SurveyType["API"] = "api";
-    SurveyType["Widget"] = "widget";
-    SurveyType["ExternalSurvey"] = "external_survey";
-    return SurveyType;
-}({});
-var SurveyQuestionDescriptionContentType = /*#__PURE__*/ function(SurveyQuestionDescriptionContentType) {
-    SurveyQuestionDescriptionContentType["Html"] = "html";
-    SurveyQuestionDescriptionContentType["Text"] = "text";
-    return SurveyQuestionDescriptionContentType;
-}({});
-var SurveyValidationType = /*#__PURE__*/ function(SurveyValidationType) {
-    SurveyValidationType["MinLength"] = "min_length";
-    SurveyValidationType["MaxLength"] = "max_length";
-    return SurveyValidationType;
-}({});
-var SurveyRatingDisplay = /*#__PURE__*/ function(SurveyRatingDisplay) {
-    SurveyRatingDisplay["Number"] = "number";
-    SurveyRatingDisplay["Emoji"] = "emoji";
-    return SurveyRatingDisplay;
-}({});
-var SurveyQuestionType = /*#__PURE__*/ function(SurveyQuestionType) {
-    SurveyQuestionType["Open"] = "open";
-    SurveyQuestionType["MultipleChoice"] = "multiple_choice";
-    SurveyQuestionType["SingleChoice"] = "single_choice";
-    SurveyQuestionType["Rating"] = "rating";
-    SurveyQuestionType["Link"] = "link";
-    return SurveyQuestionType;
-}({});
-var SurveyQuestionBranchingType = /*#__PURE__*/ function(SurveyQuestionBranchingType) {
-    SurveyQuestionBranchingType["NextQuestion"] = "next_question";
-    SurveyQuestionBranchingType["End"] = "end";
-    SurveyQuestionBranchingType["ResponseBased"] = "response_based";
-    SurveyQuestionBranchingType["SpecificQuestion"] = "specific_question";
-    return SurveyQuestionBranchingType;
-}({});
-var SurveyMatchType = /*#__PURE__*/ function(SurveyMatchType) {
-    SurveyMatchType["Regex"] = "regex";
-    SurveyMatchType["NotRegex"] = "not_regex";
-    SurveyMatchType["Exact"] = "exact";
-    SurveyMatchType["IsNot"] = "is_not";
-    SurveyMatchType["Icontains"] = "icontains";
-    SurveyMatchType["NotIcontains"] = "not_icontains";
-    return SurveyMatchType;
-}({});
-var SurveySchedule = /*#__PURE__*/ function(SurveySchedule) {
-    SurveySchedule["Once"] = "once";
-    SurveySchedule["Recurring"] = "recurring";
-    SurveySchedule["Always"] = "always";
-    return SurveySchedule;
-}({});
-var ActionStepStringMatching = /*#__PURE__*/ function(ActionStepStringMatching) {
-    ActionStepStringMatching["Contains"] = "contains";
-    ActionStepStringMatching["Exact"] = "exact";
-    ActionStepStringMatching["Regex"] = "regex";
-    return ActionStepStringMatching;
-}({});
+const SurveyPosition = {
+    TopLeft: 'top_left',
+    TopCenter: 'top_center',
+    TopRight: 'top_right',
+    MiddleLeft: 'middle_left',
+    MiddleCenter: 'middle_center',
+    MiddleRight: 'middle_right',
+    Left: 'left',
+    Right: 'right',
+    Center: 'center'
+};
+const SurveyWidgetType = {
+    Button: 'button',
+    Tab: 'tab',
+    Selector: 'selector'
+};
+const SurveyType = {
+    Popover: 'popover',
+    API: 'api',
+    Widget: 'widget',
+    ExternalSurvey: 'external_survey'
+};
+const SurveyQuestionDescriptionContentType = {
+    Html: 'html',
+    Text: 'text'
+};
+const SurveyValidationType = {
+    MinLength: 'min_length',
+    MaxLength: 'max_length'
+};
+const SurveyRatingDisplay = {
+    Number: 'number',
+    Emoji: 'emoji'
+};
+const SurveyQuestionType = {
+    Open: 'open',
+    MultipleChoice: 'multiple_choice',
+    SingleChoice: 'single_choice',
+    Rating: 'rating',
+    Link: 'link'
+};
+const SurveyQuestionBranchingType = {
+    NextQuestion: 'next_question',
+    End: 'end',
+    ResponseBased: 'response_based',
+    SpecificQuestion: 'specific_question'
+};
+const SurveyMatchType = {
+    Regex: 'regex',
+    NotRegex: 'not_regex',
+    Exact: 'exact',
+    IsNot: 'is_not',
+    Icontains: 'icontains',
+    NotIcontains: 'not_icontains'
+};
+const SurveySchedule = {
+    Once: 'once',
+    Recurring: 'recurring',
+    Always: 'always'
+};
+const ActionStepStringMatching = {
+    Contains: 'contains',
+    Exact: 'exact',
+    Regex: 'regex'
+};
 const knownUnsafeEditableEvent = [
     '$snapshot',
     '$pageview',

package/dist/types.mjs

@@ -46,82 +46,71 @@ const FeatureFlagError = {
     UNKNOWN_ERROR: 'unknown_error',
     apiError: (status)=>`api_error_${status}`
 };
-var types_SurveyPosition = /*#__PURE__*/ function(SurveyPosition) {
-    SurveyPosition["TopLeft"] = "top_left";
-    SurveyPosition["TopCenter"] = "top_center";
-    SurveyPosition["TopRight"] = "top_right";
-    SurveyPosition["MiddleLeft"] = "middle_left";
-    SurveyPosition["MiddleCenter"] = "middle_center";
-    SurveyPosition["MiddleRight"] = "middle_right";
-    SurveyPosition["Left"] = "left";
-    SurveyPosition["Right"] = "right";
-    SurveyPosition["Center"] = "center";
-    return SurveyPosition;
-}({});
-var types_SurveyWidgetType = /*#__PURE__*/ function(SurveyWidgetType) {
-    SurveyWidgetType["Button"] = "button";
-    SurveyWidgetType["Tab"] = "tab";
-    SurveyWidgetType["Selector"] = "selector";
-    return SurveyWidgetType;
-}({});
-var types_SurveyType = /*#__PURE__*/ function(SurveyType) {
-    SurveyType["Popover"] = "popover";
-    SurveyType["API"] = "api";
-    SurveyType["Widget"] = "widget";
-    SurveyType["ExternalSurvey"] = "external_survey";
-    return SurveyType;
-}({});
-var types_SurveyQuestionDescriptionContentType = /*#__PURE__*/ function(SurveyQuestionDescriptionContentType) {
-    SurveyQuestionDescriptionContentType["Html"] = "html";
-    SurveyQuestionDescriptionContentType["Text"] = "text";
-    return SurveyQuestionDescriptionContentType;
-}({});
-var types_SurveyValidationType = /*#__PURE__*/ function(SurveyValidationType) {
-    SurveyValidationType["MinLength"] = "min_length";
-    SurveyValidationType["MaxLength"] = "max_length";
-    return SurveyValidationType;
-}({});
-var types_SurveyRatingDisplay = /*#__PURE__*/ function(SurveyRatingDisplay) {
-    SurveyRatingDisplay["Number"] = "number";
-    SurveyRatingDisplay["Emoji"] = "emoji";
-    return SurveyRatingDisplay;
-}({});
-var types_SurveyQuestionType = /*#__PURE__*/ function(SurveyQuestionType) {
-    SurveyQuestionType["Open"] = "open";
-    SurveyQuestionType["MultipleChoice"] = "multiple_choice";
-    SurveyQuestionType["SingleChoice"] = "single_choice";
-    SurveyQuestionType["Rating"] = "rating";
-    SurveyQuestionType["Link"] = "link";
-    return SurveyQuestionType;
-}({});
-var types_SurveyQuestionBranchingType = /*#__PURE__*/ function(SurveyQuestionBranchingType) {
-    SurveyQuestionBranchingType["NextQuestion"] = "next_question";
-    SurveyQuestionBranchingType["End"] = "end";
-    SurveyQuestionBranchingType["ResponseBased"] = "response_based";
-    SurveyQuestionBranchingType["SpecificQuestion"] = "specific_question";
-    return SurveyQuestionBranchingType;
-}({});
-var types_SurveyMatchType = /*#__PURE__*/ function(SurveyMatchType) {
-    SurveyMatchType["Regex"] = "regex";
-    SurveyMatchType["NotRegex"] = "not_regex";
-    SurveyMatchType["Exact"] = "exact";
-    SurveyMatchType["IsNot"] = "is_not";
-    SurveyMatchType["Icontains"] = "icontains";
-    SurveyMatchType["NotIcontains"] = "not_icontains";
-    return SurveyMatchType;
-}({});
-var types_SurveySchedule = /*#__PURE__*/ function(SurveySchedule) {
-    SurveySchedule["Once"] = "once";
-    SurveySchedule["Recurring"] = "recurring";
-    SurveySchedule["Always"] = "always";
-    return SurveySchedule;
-}({});
-var types_ActionStepStringMatching = /*#__PURE__*/ function(ActionStepStringMatching) {
-    ActionStepStringMatching["Contains"] = "contains";
-    ActionStepStringMatching["Exact"] = "exact";
-    ActionStepStringMatching["Regex"] = "regex";
-    return ActionStepStringMatching;
-}({});
+const SurveyPosition = {
+    TopLeft: 'top_left',
+    TopCenter: 'top_center',
+    TopRight: 'top_right',
+    MiddleLeft: 'middle_left',
+    MiddleCenter: 'middle_center',
+    MiddleRight: 'middle_right',
+    Left: 'left',
+    Right: 'right',
+    Center: 'center'
+};
+const SurveyWidgetType = {
+    Button: 'button',
+    Tab: 'tab',
+    Selector: 'selector'
+};
+const SurveyType = {
+    Popover: 'popover',
+    API: 'api',
+    Widget: 'widget',
+    ExternalSurvey: 'external_survey'
+};
+const SurveyQuestionDescriptionContentType = {
+    Html: 'html',
+    Text: 'text'
+};
+const SurveyValidationType = {
+    MinLength: 'min_length',
+    MaxLength: 'max_length'
+};
+const SurveyRatingDisplay = {
+    Number: 'number',
+    Emoji: 'emoji'
+};
+const SurveyQuestionType = {
+    Open: 'open',
+    MultipleChoice: 'multiple_choice',
+    SingleChoice: 'single_choice',
+    Rating: 'rating',
+    Link: 'link'
+};
+const SurveyQuestionBranchingType = {
+    NextQuestion: 'next_question',
+    End: 'end',
+    ResponseBased: 'response_based',
+    SpecificQuestion: 'specific_question'
+};
+const SurveyMatchType = {
+    Regex: 'regex',
+    NotRegex: 'not_regex',
+    Exact: 'exact',
+    IsNot: 'is_not',
+    Icontains: 'icontains',
+    NotIcontains: 'not_icontains'
+};
+const SurveySchedule = {
+    Once: 'once',
+    Recurring: 'recurring',
+    Always: 'always'
+};
+const ActionStepStringMatching = {
+    Contains: 'contains',
+    Exact: 'exact',
+    Regex: 'regex'
+};
 const knownUnsafeEditableEvent = [
     '$snapshot',
     '$pageview',
@@ -141,4 +130,4 @@ const knownUnsafeEditableEvent = [
 const knownUnsafeEditableEventProperty = [
     'token'
 ];
-export { types_ActionStepStringMatching as ActionStepStringMatching, types_Compression as Compression, FeatureFlagError, types_PostHogPersistedProperty as PostHogPersistedProperty, types_SurveyMatchType as SurveyMatchType, types_SurveyPosition as SurveyPosition, types_SurveyQuestionBranchingType as SurveyQuestionBranchingType, types_SurveyQuestionDescriptionContentType as SurveyQuestionDescriptionContentType, types_SurveyQuestionType as SurveyQuestionType, types_SurveyRatingDisplay as SurveyRatingDisplay, types_SurveySchedule as SurveySchedule, types_SurveyType as SurveyType, types_SurveyValidationType as SurveyValidationType, types_SurveyWidgetType as SurveyWidgetType, knownUnsafeEditableEvent, knownUnsafeEditableEventProperty };
+export { ActionStepStringMatching, types_Compression as Compression, FeatureFlagError, types_PostHogPersistedProperty as PostHogPersistedProperty, SurveyMatchType, SurveyPosition, SurveyQuestionBranchingType, SurveyQuestionDescriptionContentType, SurveyQuestionType, SurveyRatingDisplay, SurveySchedule, SurveyType, SurveyValidationType, SurveyWidgetType, knownUnsafeEditableEvent, knownUnsafeEditableEventProperty };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/core",
-  "version": "1.41.0",
+  "version": "1.42.0",
   "bugs": {
     "url": "https://github.com/PostHog/posthog-js/issues"
   },
@@ -70,7 +70,7 @@
     }
   },
   "dependencies": {
-    "@posthog/types": "^1.394.0"
+    "@posthog/types": "^1.395.0"
   },
   "devDependencies": {
     "@rslib/core": "0.10.6",

package/src/index.ts

@@ -45,6 +45,7 @@ export {
   buildOtlpMetricsPayload,
   buildMetricsResourceAttributes,
   DEFAULT_HISTOGRAM_BOUNDS,
+  resolveMetricsConfig,
 } from './metrics'
 export type {
   MetricsHost,
@@ -59,6 +60,8 @@ export type {
   MetricAttributeValue,
   MetricSample,
   MetricType,
+  Metrics,
+  MetricsConfig,
 } from './metrics/types'
 export { uuidv7 } from './vendor/uuidv7'
 export * from './cookie'

package/src/metrics/config.ts

@@ -0,0 +1,23 @@
+import type { MetricsConfig } from '@posthog/types'
+import type { ResolvedPostHogMetricsConfig } from './types'
+
+const DEFAULT_FLUSH_INTERVAL_MS = 10000
+const DEFAULT_MAX_SERIES_PER_FLUSH = 1000
+
+/**
+ * Resolves the public `metrics` config into the shape `PostHogMetrics`
+ * consumes. Same precedence rule as logs: OTLP keys in `resourceAttributes`
+ * win over the named config fields.
+ */
+export function resolveMetricsConfig(config: MetricsConfig | undefined): ResolvedPostHogMetricsConfig {
+  const resourceAttributes = config?.resourceAttributes
+  return {
+    serviceName: (resourceAttributes?.['service.name'] as string | undefined) ?? config?.serviceName,
+    serviceVersion: (resourceAttributes?.['service.version'] as string | undefined) ?? config?.serviceVersion,
+    environment: (resourceAttributes?.['deployment.environment'] as string | undefined) ?? config?.environment,
+    resourceAttributes,
+    beforeSend: config?.beforeSend,
+    flushIntervalMs: config?.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS,
+    maxSeriesPerFlush: config?.maxSeriesPerFlush ?? DEFAULT_MAX_SERIES_PER_FLUSH,
+  }
+}

package/src/metrics/index.spec.ts

@@ -349,6 +349,34 @@ describe('PostHogMetrics', () => {
       expect((logger.warn as jest.Mock).mock.calls.length).toBe(1)
     })
 
+    it('re-applies the series cap when merging a failed window back', async () => {
+      let resolveSend!: (outcome: SendMetricsBatchOutcome) => void
+      mockInstance._sendMetricsBatch
+        .mockImplementationOnce(() => new Promise<SendMetricsBatchOutcome>((resolve) => (resolveSend = resolve)))
+        .mockResolvedValue({ kind: 'ok' })
+
+      const metrics = createMetrics({ maxSeriesPerFlush: 2 })
+      metrics.count('a', 1)
+      metrics.count('b', 1)
+      const inflight = metrics.flush()
+      // New series captured while the failing send is in flight fill the fresh window to the cap.
+      metrics.count('c', 1)
+      metrics.count('d', 1)
+      resolveSend({ kind: 'retry-later', error: new Error('offline') })
+      await inflight
+
+      await metrics.flush()
+
+      const payloads = sentPayloads()
+      expect(payloads).toHaveLength(2)
+      const dataPointCount = payloads[1].resourceMetrics[0].scopeMetrics[0].metrics.reduce(
+        (n, m) => n + (m.sum?.dataPoints.length ?? 0),
+        0
+      )
+      expect(dataPointCount).toBeLessThanOrEqual(2)
+      expect((logger.warn as jest.Mock).mock.calls.some((c) => String(c[0]).includes('series cap'))).toBe(true)
+    })
+
     it('drops non-finite values and negative counts', async () => {
       const metrics = createMetrics()
       metrics.count('a', NaN)
@@ -365,6 +393,27 @@ describe('PostHogMetrics', () => {
       expect(sent[0].gauge!.dataPoints[0].asDouble).toBe(-5)
     })
 
+    it('drops samples with unserializable attributes instead of throwing', async () => {
+      const metrics = createMetrics()
+      const throwingAttrs = {}
+      Object.defineProperty(throwingAttrs, 'bad', {
+        enumerable: true,
+        get() {
+          throw new Error('boom')
+        },
+      })
+
+      expect(() => metrics.count('good', 1, { attributes: { plan: 'free' } })).not.toThrow()
+      expect(() => metrics.count('bigint_attr', 1, { attributes: { jobId: BigInt(1) } as any })).not.toThrow()
+      expect(() => metrics.count('throwing_attr', 1, { attributes: throwingAttrs as any })).not.toThrow()
+      await metrics.flush()
+
+      // Only the well-formed sample ships; the malformed ones are dropped with a warning.
+      expect(sentMetrics().map((m) => m.name)).toEqual(['good'])
+      const attrWarns = (logger.warn as jest.Mock).mock.calls.filter((c) => String(c[0]).includes('attributes'))
+      expect(attrWarns).toHaveLength(2)
+    })
+
     it('drops samples with an empty name', async () => {
       const metrics = createMetrics()
       metrics.count('', 1)

package/src/metrics/index.ts

@@ -73,6 +73,10 @@ export class PostHogMetrics {
   // types under one name produces charts that blend both series.
   private _typeByName = new Map<string, MetricType>()
   private _typeCollisionWarned = new Set<string>()
+  // Bumped by reset(). A flush that was in flight when reset() ran (e.g. it
+  // lost a shutdown race) sees a stale generation when its send settles and
+  // discards its window instead of merging it back and re-arming the timer.
+  private _generation = 0
 
   constructor(
     private readonly _instance: MetricsHost,
@@ -129,8 +133,9 @@ export class PostHogMetrics {
     return this._buildPayload(window)
   }
 
-  /** Clears the flush timer and drops the current window. */
+  /** Clears the flush timer, drops the current window, and invalidates in-flight flushes. */
   reset(): void {
+    this._generation++
     this._clearFlushTimer()
     this._series = new Map()
     this._flushPromise = null
@@ -163,46 +168,70 @@ export class PostHogMetrics {
       return
     }
 
-    const seenType = this._typeByName.get(filtered.name)
-    if (seenType === undefined) {
-      this._typeByName.set(filtered.name, filtered.type)
-    } else if (seenType !== filtered.type && !this._typeCollisionWarned.has(filtered.name)) {
-      this._typeCollisionWarned.add(filtered.name)
-      this._logger.warn(
-        `Metric name '${filtered.name}' is already used as a ${seenType}; ` +
-          `recording it as a ${filtered.type} too will blend both series in charts. Use a distinct name.`
-      )
+    // Snapshot: the key is computed from these values, so a caller mutating
+    // the object after capture must not change the stored series. Reading and
+    // serializing the attributes can throw (BigInt values, throwing
+    // getters/proxies) — a malformed sample is dropped, never thrown.
+    let attributes: MetricAttributes | undefined
+    let key: string
+    try {
+      attributes = filtered.attributes ? { ...filtered.attributes } : undefined
+      key = seriesKey(filtered.type, filtered.name, filtered.unit, attributes)
+    } catch (e) {
+      this._logger.warn(`Dropping metric '${filtered.name}': attributes could not be serialized`, e)
+      return
     }
 
-    const key = seriesKey(filtered.type, filtered.name, filtered.unit, filtered.attributes)
     let state = this._series.get(key)
     if (!state) {
-      if (this._series.size >= this._config.maxSeriesPerFlush) {
-        if (!this._seriesCapWarned) {
-          this._seriesCapWarned = true
-          this._logger.warn(
-            `Metric series cap reached (${this._config.maxSeriesPerFlush} per flush window); ` +
-              `dropping new series until the next flush. Reduce attribute cardinality.`
-          )
-        }
+      if (!this._admitNewSeries()) {
         return
       }
       state = {
         name: filtered.name,
         type: filtered.type,
         unit: filtered.unit,
-        // Snapshot: the key was computed from these values, so a caller
-        // mutating the object after capture must not change the stored series.
-        attributes: filtered.attributes ? { ...filtered.attributes } : undefined,
+        attributes,
         windowStartMs: Date.now(),
       }
       this._series.set(key, state)
     }
 
+    // Bookkeeping only for admitted samples, so name-cardinality misuse (IDs
+    // interpolated into metric names) can't grow this map past the series cap.
+    const seenType = this._typeByName.get(filtered.name)
+    if (seenType === undefined) {
+      this._typeByName.set(filtered.name, filtered.type)
+    } else if (seenType !== filtered.type && !this._typeCollisionWarned.has(filtered.name)) {
+      this._typeCollisionWarned.add(filtered.name)
+      this._logger.warn(
+        `Metric name '${filtered.name}' is already used as a ${seenType}; ` +
+          `recording it as a ${filtered.type} too will blend both series in charts. Use a distinct name.`
+      )
+    }
+
     this._fold(state, filtered.value)
     this._armFlushTimer()
   }
 
+  /**
+   * Cardinality gate for adding a series to the live window — warns once per
+   * window when the cap is hit. Applied on capture and on merge-back alike.
+   */
+  private _admitNewSeries(): boolean {
+    if (this._series.size < this._config.maxSeriesPerFlush) {
+      return true
+    }
+    if (!this._seriesCapWarned) {
+      this._seriesCapWarned = true
+      this._logger.warn(
+        `Metric series cap reached (${this._config.maxSeriesPerFlush} per flush window); ` +
+          `dropping new series until the next flush. Reduce attribute cardinality.`
+      )
+    }
+    return false
+  }
+
   private _fold(state: SeriesState, value: number): void {
     switch (state.type) {
       case 'count':
@@ -261,7 +290,9 @@ export class PostHogMetrics {
     }
     this._flushTimer = safeSetTimeout(() => {
       this._flushTimer = undefined
-      this.flush().catch(() => {})
+      this.flush().catch((e) => {
+        this._logger.error('Metrics flush failed:', e)
+      })
     }, this._config.flushIntervalMs)
   }
 
@@ -285,7 +316,13 @@ export class PostHogMetrics {
     this._typeByName = new Map()
     this._typeCollisionWarned = new Set()
 
+    const generation = this._generation
     const outcome = await this._instance._sendMetricsBatch(this._buildPayload(window))
+    if (generation !== this._generation) {
+      // reset() ran while the send was in flight — the client was torn down or
+      // reconfigured, so this window is dropped whatever the outcome was.
+      return
+    }
     switch (outcome.kind) {
       case 'ok':
         return
@@ -379,7 +416,11 @@ export class PostHogMetrics {
     for (const [key, old] of window) {
       const current = this._series.get(key)
       if (!current) {
-        this._series.set(key, old)
+        // The cap still applies here: an unbounded merge-back would let a
+        // failed flush reintroduce series past maxSeriesPerFlush.
+        if (this._admitNewSeries()) {
+          this._series.set(key, old)
+        }
         continue
       }
       current.windowStartMs = Math.min(current.windowStartMs, old.windowStartMs)
@@ -411,4 +452,5 @@ export class PostHogMetrics {
 }
 
 export { buildOtlpMetricsPayload, buildMetricsResourceAttributes, DEFAULT_HISTOGRAM_BOUNDS } from './metrics-utils'
+export { resolveMetricsConfig } from './config'
 export type { MetricsHost, PostHogMetricsConfig, ResolvedPostHogMetricsConfig, SendMetricsBatchOutcome } from './types'

package/src/metrics/types.ts

@@ -4,6 +4,7 @@ export type {
   MetricAttributeValue,
   MetricAttributes,
   MetricType,
+  MetricsConfig,
   CaptureMetricOptions,
   MetricSample,
   BeforeSendMetricFn,

package/src/posthog-core-stateless.ts

@@ -1,4 +1,5 @@
-import type { OtlpLogsPayload } from '@posthog/types'
+import type { OtlpLogsPayload, OtlpMetricsPayload } from '@posthog/types'
+import type { SendMetricsBatchOutcome } from './metrics/types'
 import { SimpleEventEmitter } from './eventemitter'
 import { getFeatureFlagValue, normalizeFlagsResponse } from './featureFlagUtils'
 import { gzipCompress, isGzipSupported } from './gzip'
@@ -1534,6 +1535,55 @@ export abstract class PostHogCoreStateless {
     }
   }
 
+  /**
+   * Sends a pre-built OTLP metrics payload to `/i/v1/metrics`. Same tagged
+   * outcome contract and error classification as `_sendLogsBatch` — this is
+   * the `MetricsHost._sendMetricsBatch` implementation, so `PostHogMetrics`
+   * can use any core-based SDK as its host.
+   */
+  async _sendMetricsBatch(payload: OtlpMetricsPayload): Promise<SendMetricsBatchOutcome> {
+    if (this.disabled) {
+      return { kind: 'fatal', error: new Error('The client is disabled') }
+    }
+
+    const serialized = JSON.stringify(payload)
+    const url = `${this.host}/i/v1/metrics?token=${encodeURIComponent(this.apiKey)}`
+
+    const gzippedPayload = !this.disableCompression ? await gzipCompress(serialized, this.isDebug) : null
+    const fetchOptions: PostHogFetchOptions = {
+      method: 'POST',
+      headers: {
+        ...this.getCustomHeaders(),
+        'Content-Type': 'application/json',
+        ...(gzippedPayload !== null && { 'Content-Encoding': 'gzip' }),
+      },
+      body: gzippedPayload || serialized,
+    }
+
+    try {
+      await this.fetchWithRetry(url, fetchOptions, {
+        retryCheck: (err) => {
+          if (isPostHogFetchContentTooLargeError(err)) {
+            return false
+          }
+          return isPostHogFetchRetryableError(err)
+        },
+      })
+      return { kind: 'ok' }
+    } catch (err) {
+      if (isPostHogFetchContentTooLargeError(err)) {
+        return { kind: 'too-large' }
+      }
+      // Exhausted retries on a retryable failure (network error, 408/429/5xx)
+      // still classify as retry-later so the window rides the next flush; only
+      // non-retryable HTTP errors (and 413 above) drop the batch.
+      if (isPostHogFetchRetryableError(err)) {
+        return { kind: 'retry-later', error: err }
+      }
+      return { kind: 'fatal', error: err }
+    }
+  }
+
   private async fetchWithRetry(
     url: string,
     options: PostHogFetchOptions,