@posthog/core 1.33.0 → 1.35.0

package/src/logs/logs-utils.ts

@@ -9,7 +9,7 @@ import type {
   OtlpSeverityEntry,
   OtlpSeverityText,
 } from '@posthog/types'
-import type { LogSdkContext } from './types'
+import type { LogSdkContext, ResolvedPostHogLogsConfig } from './types'
 import { isArray, isBoolean, isNull, isUndefined } from '../utils'
 
 // ============================================================================
@@ -168,6 +168,35 @@ export function buildOtlpLogRecord(options: CaptureLogOptions, sdkContext: LogSd
 // OTLP envelope construction
 // ============================================================================
 
+/**
+ * OTLP resource attributes for every batch, shared by the core flush path and
+ * SDK-specific paths that bypass it (e.g. the browser's synchronous sendBeacon
+ * drain). Having one builder keeps those paths from drifting.
+ *
+ * Layout: user `resourceAttributes` spread first, then SDK-controlled keys
+ * (`service.name`, `deployment.environment`, `service.version`,
+ * `telemetry.sdk.*`) layered on top so a stray user key can't clobber the
+ * ingestion-attribution keys. The dedicated `serviceName` / `environment` /
+ * `serviceVersion` config fields are the supported way to override the first
+ * three; each SDK resolves its own `service.name` default before this point, so
+ * the `unknown_service` fallback here only fires if a config slips through with
+ * an empty `serviceName`.
+ */
+export function buildResourceAttributes(
+  config: ResolvedPostHogLogsConfig,
+  scopeName: string,
+  scopeVersion: string
+): Record<string, LogAttributeValue> {
+  return {
+    ...config.resourceAttributes,
+    'service.name': config.serviceName || 'unknown_service',
+    ...(config.environment && { 'deployment.environment': config.environment }),
+    ...(config.serviceVersion && { 'service.version': config.serviceVersion }),
+    'telemetry.sdk.name': scopeName,
+    'telemetry.sdk.version': scopeVersion,
+  }
+}
+
 /**
  * Wraps a list of records in the OTLP `resourceLogs` envelope.
  *

package/src/logs/types.ts

@@ -11,6 +11,7 @@ export type {
   OtlpKeyValue,
   OtlpLogRecord,
   OtlpLogsPayload,
+  BeforeSendLogFn,
 } from '@posthog/types'
 
 /**
@@ -39,44 +40,34 @@ export interface LogSdkContext {
 import type { Logger as CaptureLoggerType } from '@posthog/types'
 export type CaptureLogger = CaptureLoggerType
 
-import type { LogAttributeValue, CaptureLogOptions, OtlpLogRecord } from '@posthog/types'
+import type {
+  LogAttributeValue,
+  CaptureLogOptions,
+  OtlpLogRecord,
+  OtlpLogsPayload,
+  BeforeSendLogFn,
+} from '@posthog/types'
+import type { PostHogPersistedProperty } from '../types'
+import type { SendLogsBatchOutcome } from '../posthog-core-stateless'
 
 export interface BufferedLogEntry {
   record: OtlpLogRecord
 }
 
 /**
- * Pre-send filter. Inspect, mutate, or drop a captured record before it
- * enters the rate-cap or the queue. Return the (possibly transformed) record
- * to keep it; return `null` to drop it.
- *
- * Configure as a single fn or an array. Arrays form a left-to-right chain:
- * each fn receives the previous fn's return value. A `null` from any link
- * short-circuits the chain and drops the record.
- *
- * Runs *before* the rate cap so dropped records don't consume the
- * per-interval budget. Throwing fns are logged and skipped — the chain
- * continues with the previous return value, so a buggy filter degrades to a
- * no-op rather than crashing `captureLog()`.
- *
- * @example Redact secrets from log bodies
- * ```ts
- * logs: {
- *   beforeSend: (record) => ({
- *     ...record,
- *     body: record.body.replace(/api_key=\S+/g, 'api_key=[REDACTED]'),
- *   }),
- * }
- * ```
- *
- * @example Drop noisy debug logs in production
- * ```ts
- * logs: {
- *   beforeSend: (record) => (record.level === 'debug' ? null : record),
- * }
- * ```
+ * The minimal host surface `PostHogLogs` depends on. `PostHogCoreStateless`
+ * satisfies it structurally (mobile/node); the browser supplies an adapter
+ * backed by its own persistence and request layer.
  */
-export type BeforeSendLogFn = (record: CaptureLogOptions) => CaptureLogOptions | null
+export interface LogsHost {
+  readonly isDisabled: boolean
+  readonly optedOut: boolean
+  getPersistedProperty<T>(key: PostHogPersistedProperty): T | undefined
+  setPersistedProperty<T>(key: PostHogPersistedProperty, value: T | null): void
+  _sendLogsBatch(payload: OtlpLogsPayload): Promise<SendLogsBatchOutcome>
+  getLibraryId(): string
+  getLibraryVersion(): string
+}
 
 /**
  * Configuration for the logs feature on `new PostHog(key, { logs: ... })`.
@@ -87,7 +78,7 @@ export interface PostHogLogsConfig {
   /**
    * Service name attached to every record as the OTLP `service.name`
    * resource attribute. Used by the Logs UI for filtering / grouping.
-   * Default: `'unknown_service'`.
+   * Defaults to `'unknown_service'` when unset.
    */
   serviceName?: string
 
@@ -121,11 +112,11 @@ export interface PostHogLogsConfig {
   flushIntervalMs?: number
 
   /**
-   * Max records held in memory before the queue evicts the oldest on push
-   * (FIFO). Bounds memory footprint and on-disk-queue size. When the buffer
-   * hits this size, an immediate flush is triggered to reclaim space; if
-   * the flush hasn't completed before the next capture, the oldest record
-   * is shifted out. Default: 100.
+   * Number of buffered records that triggers an immediate flush. Records also
+   * flush on the periodic interval and on `shutdown()`. The queue can grow past
+   * this while an async flush is in flight (e.g. during a synchronous burst); a
+   * separate, larger memory backstop evicts the oldest only once the queue
+   * exceeds the per-interval rate cap. Default: 100.
    */
   maxBufferSize?: number
 
@@ -182,6 +173,10 @@ export interface PostHogLogsConfig {
 // Flat names internally — public API uses `rateCap: { maxLogs, windowMs }`.
 export interface ResolvedPostHogLogsConfig extends Omit<PostHogLogsConfig, 'rateCap'> {
   maxBufferSize: number
+  // Eviction cap: the queue drops the oldest record once it exceeds this. Separate
+  // from `maxBufferSize` (the flush trigger) so a burst is held, not evicted, while
+  // the async flush drains. Defaults to `maxBufferSize` when unset.
+  maxQueueSize?: number
   flushIntervalMs: number
   maxBatchRecordsPerPost: number
   rateCapWindowMs: number

package/src/posthog-core.ts

@@ -53,6 +53,7 @@ interface PendingFlagsRequest extends FlagsAsyncOptions {
 export abstract class PostHogCore extends PostHogCoreStateless {
   // options
   private sendFeatureFlagEvent: boolean
+  private disableRemoteFeatureFlags: boolean
   private flagCallReported: { [key: string]: boolean } = {}
   private _beforeSend?: BeforeSendFn | BeforeSendFn[]
 
@@ -82,6 +83,7 @@ export abstract class PostHogCore extends PostHogCoreStateless {
     super(apiKey, { ...options, disableGeoip: disableGeoipOption, featureFlagsRequestTimeoutMs })
 
     this.sendFeatureFlagEvent = options?.sendFeatureFlagEvent ?? true
+    this.disableRemoteFeatureFlags = options?.disableRemoteFeatureFlags ?? false
     this._sessionExpirationTimeSeconds = options?.sessionExpirationTimeSeconds ?? 1800 // 30 minutes
     this._personProfiles = options?.personProfiles ?? 'identified_only'
     this._beforeSend = options?.before_send
@@ -178,7 +180,17 @@ export abstract class PostHogCore extends PostHogCoreStateless {
         }
       }
 
-      this.reloadFeatureFlags()
+      if (this.disableRemoteFeatureFlags && !this.disabled) {
+        // No reload runs to emit the change, so emit the now-cleared flags directly
+        // (drives onFeatureFlags listeners, e.g. session replay re-arm). Callers re-push
+        // the new identity's flags via updateFlags(). Skip when the caller kept
+        // FeatureFlagDetails — those flags stay as-is, so there's nothing to emit.
+        if (!allPropertiesToKeep.includes(PostHogPersistedProperty.FeatureFlagDetails)) {
+          this.setKnownFeatureFlagDetails({ flags: {} })
+        }
+      } else {
+        this.reloadFeatureFlags()
+      }
     })
   }
 
@@ -585,6 +597,11 @@ export abstract class PostHogCore extends PostHogCoreStateless {
     if (this.disabled) {
       return undefined
     }
+    // Config-fetching requests still go out (carrying disable_flags); only pure reloads no-op.
+    if (this.disableRemoteFeatureFlags && !fetchConfig) {
+      this._logger.info('Feature flags are disabled (disableRemoteFeatureFlags), skipping reload.')
+      return undefined
+    }
     if (this._flagsResponsePromise) {
       // Queue the reload request instead of dropping it
       // This ensures that requests with $anon_distinct_id (from identify()) are not lost
@@ -696,11 +713,12 @@ export abstract class PostHogCore extends PostHogCoreStateless {
             // we only dont load flags if the remote config has no feature flags
             let willLoadFlags = false
             if (response.hasFeatureFlags === false) {
-              // resetting flags to empty object
-              this.setKnownFeatureFlagDetails({ flags: {} })
+              if (!this.disableRemoteFeatureFlags) {
+                this.setKnownFeatureFlagDetails({ flags: {} })
+              }
 
               this._logger.warn('Remote config has no feature flags, will not load feature flags.')
-            } else if (this.preloadFeatureFlags !== false) {
+            } else if (this.preloadFeatureFlags !== false && !this.disableRemoteFeatureFlags) {
               willLoadFlags = true
               this.flagsAsync({ sendAnonDistinctId: true, fetchConfig: true, triggerOnRemoteConfig: true })
             }
@@ -746,6 +764,7 @@ export abstract class PostHogCore extends PostHogCoreStateless {
           $anon_distinct_id: sendAnonDistinctId ? this.getAnonymousId() : undefined,
           // Only set by the React Native SDK; omitted from JSON when DeviceId is not persisted
           $device_id: deviceId ?? undefined,
+          ...(this.disableRemoteFeatureFlags ? { disable_flags: true } : {}),
         }
 
         const result = await super.getFlags(
@@ -758,20 +777,24 @@ export abstract class PostHogCore extends PostHogCoreStateless {
         )
 
         if (!result.success) {
-          this.setKnownFeatureFlagDetails({
-            flags: this.getKnownFeatureFlagDetails()?.flags ?? {},
-            requestError: result.error,
-          })
+          if (!this.disableRemoteFeatureFlags) {
+            this.setKnownFeatureFlagDetails({
+              flags: this.getKnownFeatureFlagDetails()?.flags ?? {},
+              requestError: result.error,
+            })
+          }
           return undefined
         }
 
         const res = result.response
 
         if (res?.quotaLimited?.includes(QuotaLimitedFeature.FeatureFlags)) {
-          this.setKnownFeatureFlagDetails({
-            flags: this.getKnownFeatureFlagDetails()?.flags ?? {},
-            quotaLimited: res.quotaLimited,
-          })
+          if (!this.disableRemoteFeatureFlags) {
+            this.setKnownFeatureFlagDetails({
+              flags: this.getKnownFeatureFlagDetails()?.flags ?? {},
+              quotaLimited: res.quotaLimited,
+            })
+          }
           this._logger.warn(
             '[FEATURE FLAGS] Feature flags quota limit exceeded. Learn more about billing limits at https://posthog.com/docs/billing/limits-alerts'
           )
@@ -779,6 +802,12 @@ export abstract class PostHogCore extends PostHogCoreStateless {
           return res
         }
         if (res?.featureFlags) {
+          if (this.disableRemoteFeatureFlags) {
+            this.cacheSessionReplay('flags', res)
+            this.maybeNotifyRemoteConfig(triggerOnRemoteConfig, res)
+            return res
+          }
+
           // clear flag call reported if we have new flags since they might have changed
           if (this.sendFeatureFlagEvent) {
             this.flagCallReported = {}
@@ -1052,7 +1081,8 @@ export abstract class PostHogCore extends PostHogCoreStateless {
 
     details = details ?? { featureFlags: {}, featureFlagPayloads: {}, flags: {} }
 
-    const flags: Record<string, FeatureFlagDetail> = details.flags ?? {}
+    // Copy before applying overrides so reads don't mutate the stored flags in place.
+    const flags: Record<string, FeatureFlagDetail> = { ...(details.flags ?? {}) }
 
     for (const key in overriddenFlags) {
       if (!overriddenFlags[key]) {
@@ -1093,6 +1123,10 @@ export abstract class PostHogCore extends PostHogCoreStateless {
 
   // Used when we want to trigger the reload but we don't care about the result
   reloadFeatureFlags(options?: { cb?: (err?: Error, flags?: PostHogFlagsResponse['featureFlags']) => void }): void {
+    if (this.disableRemoteFeatureFlags && !this.disabled) {
+      this._initPromise.then(() => options?.cb?.(undefined, this.getFeatureFlags()))
+      return
+    }
     this.flagsAsync({ sendAnonDistinctId: true })
       .then((res) => {
         options?.cb?.(undefined, res?.featureFlags)
@@ -1112,6 +1146,10 @@ export abstract class PostHogCore extends PostHogCoreStateless {
   async reloadFeatureFlagsAsync(
     sendAnonDistinctId?: boolean
   ): Promise<PostHogFlagsResponse['featureFlags'] | undefined> {
+    if (this.disableRemoteFeatureFlags && !this.disabled) {
+      await this._initPromise
+      return this.getFeatureFlags()
+    }
     return (await this.flagsAsync({ sendAnonDistinctId: sendAnonDistinctId }))?.featureFlags
   }
 
@@ -1142,6 +1180,75 @@ export abstract class PostHogCore extends PostHogCoreStateless {
     })
   }
 
+  /**
+   * Replaces (or merges into) the stored feature flags and payloads with locally supplied
+   * values, exactly as if they had been returned by the flags endpoint: the values are
+   * persisted, `getFeatureFlag()`/`getFeatureFlagPayload()` read them back, and
+   * `onFeatureFlags` listeners fire. Makes no network request.
+   *
+   * Intended for apps that evaluate flags outside the SDK (e.g. server-side local
+   * evaluation) and push the results in at runtime, typically together with the
+   * `disableRemoteFeatureFlags` option so the SDK never fetches flags itself.
+   *
+   * The values are cleared by `reset()`, so push them again after an identity change.
+   *
+   * @param flags - Flag keys mapped to their values (boolean, or a variant string)
+   * @param payloads - Optional flag keys mapped to their JSON payloads
+   * @param options - Set `merge: true` to merge with the currently stored flags instead of replacing them
+   */
+  updateFlags(
+    flags: Record<string, FeatureFlagValue>,
+    payloads?: Record<string, JsonType>,
+    options?: { merge?: boolean }
+  ): void {
+    this.wrap(() => {
+      // Merge against the raw stored flags, not the override-applied view.
+      const existingDetails = options?.merge ? this.getKnownFeatureFlagDetails()?.flags : undefined
+      const existingFlags = existingDetails ? getFlagValuesFromFlags(existingDetails) : {}
+      const existingPayloads: Record<string, JsonType> = {}
+      for (const key in existingDetails) {
+        const storedPayload = existingDetails[key].metadata?.payload
+        if (storedPayload !== undefined) {
+          existingPayloads[key] = parsePayload(storedPayload)
+        }
+      }
+      const finalFlags = { ...existingFlags, ...flags }
+      const finalPayloads = { ...existingPayloads, ...(payloads ?? {}) }
+
+      // Built by hand, not via createFlagsResponseFromFlagsAndPayloads, which drops false flags.
+      const flagDetails: Record<string, FeatureFlagDetail> = {}
+      for (const [key, value] of Object.entries(finalFlags)) {
+        const payload = finalPayloads[key]
+        let serializedPayload: string | undefined
+        if (payload !== undefined) {
+          try {
+            serializedPayload = JSON.stringify(payload)
+          } catch (e) {
+            this._logger.error(`updateFlags: could not serialize the payload for flag "${key}", dropping it.`, e)
+          }
+        }
+        flagDetails[key] = {
+          key,
+          enabled: getEnabledFromValue(value),
+          variant: getVariantFromValue(value),
+          reason: undefined,
+          // Locally supplied flags have no server-side id/version
+          metadata: {
+            id: undefined,
+            version: undefined,
+            description: undefined,
+            payload: serializedPayload,
+          },
+        }
+      }
+
+      if (this.sendFeatureFlagEvent) {
+        this.flagCallReported = {}
+      }
+      this.setKnownFeatureFlagDetails({ flags: flagDetails })
+    })
+  }
+
   /**
    * Capture a caught exception manually
    *

package/src/types.ts

@@ -53,6 +53,25 @@ export type PostHogCoreOptions = {
    * @default true
    */
   preloadFeatureFlags?: boolean
+  /**
+   * Advanced: whether to disable fetching and evaluating feature flags from PostHog entirely.
+   *
+   * When set to true, `reloadFeatureFlags()` and the reloads triggered by `identify()`,
+   * `group()`, `setPersonPropertiesForFlags()` and `reset()` become no-ops, and any request
+   * to the flags endpoint that still goes out (e.g. to fetch remote config or surveys)
+   * carries `disable_flags: true` so the server skips flag evaluation. Flag values must be
+   * supplied via the `bootstrap` option or `updateFlags()` instead; `getFeatureFlag()` and
+   * related methods keep working against those values. Until `updateFlags()` runs, reads
+   * return their not-loaded defaults, so use `bootstrap` for any flags needed at startup.
+   * Equivalent to the web SDK's `advanced_disable_feature_flags`.
+   *
+   * Note: surveys gated on feature flags will not evaluate unless the survey targeting
+   * flags are also provided via `updateFlags()`. This option cannot be toggled at runtime.
+   * `posthog-node` inherits this option but does not implement it (no-op).
+   *
+   * @default false
+   */
+  disableRemoteFeatureFlags?: boolean
   /**
    * Whether to load remote config when initialized or not
    * Experimental support