@launchdarkly/o11y 1.3.1 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [1.4.0](https://github.com/launchdarkly/observability-sdk/compare/o11y-1.3.1...o11y-1.4.0) (2026-10-28)
+
+
+### Features
+
+* **o11y:** add sessionCookieDomain option and session docs ([#848](https://github.com/launchdarkly/observability-sdk/issues/848)) ([4ac4ccb](https://github.com/launchdarkly/observability-sdk/commit/4ac4ccb24b270f910c20b6e434569e507405e510))
+* **o11y:** deprecate H.addSessionFeedback and ReportDialog ([#843](https://github.com/launchdarkly/observability-sdk/issues/843)) ([6d0273d](https://github.com/launchdarkly/observability-sdk/commit/6d0273d21cec5fba528f74dae89db53d38126f2a))
+
+
+### Bug Fixes
+
+* **o11y:** buffer telemetry until start() with manualStart ([#846](https://github.com/launchdarkly/observability-sdk/issues/846)) ([b851d78](https://github.com/launchdarkly/observability-sdk/commit/b851d7832bd5905d77c9ca2d41a2de6064ed364b))
+* **o11y:** export metrics with delta temporality ([#845](https://github.com/launchdarkly/observability-sdk/issues/845)) ([22e7201](https://github.com/launchdarkly/observability-sdk/commit/22e7201d29eaefe22c286272fd250a07dce421ff))
+* **o11y:** refresh observe-only sessions on telemetry activity ([#847](https://github.com/launchdarkly/observability-sdk/issues/847)) ([7799eb3](https://github.com/launchdarkly/observability-sdk/commit/7799eb368a2ca1d3dda01e8517d650ccfbe6f450))
+
 ## [1.3.1](https://github.com/launchdarkly/observability-sdk/compare/o11y-1.3.0...o11y-1.3.1) (2026-10-21)
 
 

package/dist/LDObserve-BQr7RYVC.js

@@ -0,0 +1,130 @@
+var i = (e, r, t) => new Promise((a, s) => {
+  var n = (o) => {
+    try {
+      l(t.next(o));
+    } catch (d) {
+      s(d);
+    }
+  }, b = (o) => {
+    try {
+      l(t.throw(o));
+    } catch (d) {
+      s(d);
+    }
+  }, l = (o) => o.done ? a(o.value) : Promise.resolve(o.value).then(n, b);
+  l((t = t.apply(e, r)).next());
+});
+import { B as _, d as h } from "./buffer-CwCRPuMA.js";
+const f = () => {
+  const e = {
+    end: () => {
+    },
+    spanContext: () => ({
+      traceId: "",
+      spanId: "",
+      traceFlags: 0
+    }),
+    setAttribute: (r, t) => e,
+    setAttributes: (r) => e,
+    addEvent: (r, t, a) => e,
+    addLinks: (r) => e,
+    setStatus: (r) => e,
+    recordException: () => {
+    },
+    addLink: () => e,
+    updateName: () => e,
+    isRecording: () => !1
+  };
+  return e;
+};
+function c(e, r, t) {
+  if (typeof t == "function")
+    return t;
+  if (typeof r == "function")
+    return r;
+  if (typeof e == "function")
+    return e;
+}
+class p extends _ {
+  _startSdk() {
+    return i(this, null, function* () {
+      yield this._sdk.start();
+    });
+  }
+  // Never buffered: with `manualStart`, `start()` may run before the plugin
+  // has attached an SDK. It then stays pending and resolves once `load`
+  // attaches and starts the SDK.
+  start() {
+    return i(this, null, function* () {
+      return this._start();
+    });
+  }
+  // Never buffered, and never throws: before an SDK is attached it just
+  // cancels a start that has not run yet.
+  stop() {
+    return i(this, null, function* () {
+      yield this._stop(() => this._sdk.stop());
+    });
+  }
+  recordGauge(r) {
+    return this._bufferCall("recordGauge", [r]);
+  }
+  recordCount(r) {
+    return this._bufferCall("recordCount", [r]);
+  }
+  recordIncr(r) {
+    return this._bufferCall("recordIncr", [r]);
+  }
+  recordHistogram(r) {
+    return this._bufferCall("recordHistogram", [r]);
+  }
+  recordUpDownCounter(r) {
+    return this._bufferCall("recordUpDownCounter", [r]);
+  }
+  // The callback holds the caller's own work, so it must never be buffered:
+  // deferring it would replay that work at an arbitrary later time, or drop it.
+  startSpan(r, t, a, s) {
+    var n;
+    return this._isReady ? this._bufferCall("startSpan", [r, t, a, s]) : (this._logNoopSpanWarning(), (n = c(t, a, s)) == null ? void 0 : n(f()));
+  }
+  startManualSpan(r, t, a, s) {
+    var n;
+    return this._isReady ? this._bufferCall("startManualSpan", [r, t, a, s]) : (this._logNoopSpanWarning(), (n = c(t, a, s)) == null ? void 0 : n(f()));
+  }
+  _logNoopSpanWarning() {
+    h(
+      "startSpan/startManualSpan called before start()",
+      "span-before-start",
+      "warn",
+      "The span callback runs on a no-op span and the span is not recorded."
+    );
+  }
+  register(r, t) {
+    return this._bufferCall("register", [r, t]);
+  }
+  recordLog(r, t, a) {
+    return this._bufferCall("recordLog", [r, t, a]);
+  }
+  recordError(r, t, a, s, n) {
+    return this._bufferCall("recordError", [
+      r,
+      t,
+      a,
+      s,
+      n
+    ]);
+  }
+  setLDContextKeyAttributes(r) {
+    return this._bufferCall("setLDContextKeyAttributes", [r]);
+  }
+  getLDContextKeyAttributes() {
+    return this._isLoaded ? this._callSdk("getLDContextKeyAttributes", []) : void 0;
+  }
+}
+let u;
+typeof globalThis != "undefined" ? globalThis.LDObserve ? u = globalThis.LDObserve : (u = new p(), globalThis.LDObserve = u) : u = new p();
+export {
+  u as L,
+  f as g
+};
+//# sourceMappingURL=LDObserve-BQr7RYVC.js.map

package/dist/LDObserve-BQr7RYVC.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LDObserve-BQr7RYVC.js","sources":["../src/client/otel/utils.ts","../src/sdk/LDObserve.ts"],"sourcesContent":["import {\n\tAttributes,\n\tAttributeValue,\n\tLink,\n\tSpan,\n\tSpanStatus,\n\tTimeInput,\n} from '@opentelemetry/api'\n\nexport const getNoopSpan = () => {\n\tconst noopSpan: Span = {\n\t\tend: () => {},\n\t\tspanContext: () => ({\n\t\t\ttraceId: '',\n\t\t\tspanId: '',\n\t\t\ttraceFlags: 0,\n\t\t}),\n\t\tsetAttribute: (_key: string, _value: AttributeValue) => noopSpan,\n\t\tsetAttributes: (_attributes: Attributes) => noopSpan,\n\t\taddEvent: (\n\t\t\t_name: string,\n\t\t\t_attributesOrStartTime?: Attributes | TimeInput,\n\t\t\t_startTime?: TimeInput,\n\t\t) => noopSpan,\n\t\taddLinks: (_links: Link[]) => noopSpan,\n\t\tsetStatus: (_status: SpanStatus) => noopSpan,\n\t\trecordException: () => {},\n\t\taddLink: () => noopSpan,\n\t\tupdateName: () => noopSpan,\n\t\tisRecording: () => false,\n\t}\n\n\treturn noopSpan\n}\n","import type { Observe } from '../api/observe'\nimport type { LDClient } from '../integrations/launchdarkly'\nimport type { ErrorMessageType } from '../client/types/shared-types'\nimport type { OTelMetric as Metric } from '../client/types/types'\nimport type { Attributes, Context, Span, SpanOptions } from '@opentelemetry/api'\nimport type { LDPluginEnvironmentMetadata } from '../plugins/plugin'\nimport { BufferedClass } from './buffer'\nimport { getNoopSpan } from '../client/otel/utils'\nimport { ConsoleMethods } from '../client/types/client'\nimport { internalLogOnce } from './util'\n\n/**\n * Resolves the span callback from whichever argument position it was passed in,\n * matching the overloads `startSpan` and `startManualSpan` accept.\n */\nfunction resolveSpanCallback(\n\toptions: unknown,\n\tcontext: unknown,\n\tfn: unknown,\n): ((span: Span) => any) | undefined {\n\tif (typeof fn === 'function') {\n\t\treturn fn as (span: Span) => any\n\t}\n\tif (typeof context === 'function') {\n\t\treturn context as (span: Span) => any\n\t}\n\tif (typeof options === 'function') {\n\t\treturn options as (span: Span) => any\n\t}\n\treturn undefined\n}\n\nclass _LDObserve extends BufferedClass<Observe> implements Observe {\n\tprotected async _startSdk() {\n\t\tawait this._sdk.start()\n\t}\n\n\t// Never buffered: with `manualStart`, `start()` may run before the plugin\n\t// has attached an SDK. It then stays pending and resolves once `load`\n\t// attaches and starts the SDK.\n\tasync start() {\n\t\treturn this._start()\n\t}\n\n\t// Never buffered, and never throws: before an SDK is attached it just\n\t// cancels a start that has not run yet.\n\tasync stop() {\n\t\tawait this._stop(() => this._sdk.stop())\n\t}\n\n\trecordGauge(metric: Metric) {\n\t\treturn this._bufferCall('recordGauge', [metric])\n\t}\n\n\trecordCount(metric: Metric) {\n\t\treturn this._bufferCall('recordCount', [metric])\n\t}\n\n\trecordIncr(metric: Omit<Metric, 'value'>) {\n\t\treturn this._bufferCall('recordIncr', [metric])\n\t}\n\n\trecordHistogram(metric: Metric) {\n\t\treturn this._bufferCall('recordHistogram', [metric])\n\t}\n\n\trecordUpDownCounter(metric: Metric) {\n\t\treturn this._bufferCall('recordUpDownCounter', [metric])\n\t}\n\n\t// The callback holds the caller's own work, so it must never be buffered:\n\t// deferring it would replay that work at an arbitrary later time, or drop it.\n\tstartSpan(\n\t\tname: string,\n\t\toptions: SpanOptions | ((span?: Span) => any),\n\t\tcontext?: Context | ((span?: Span) => any),\n\t\tfn?: (span?: Span) => any,\n\t) {\n\t\tif (!this._isReady) {\n\t\t\tthis._logNoopSpanWarning()\n\t\t\treturn resolveSpanCallback(options, context, fn)?.(getNoopSpan())\n\t\t}\n\t\treturn this._bufferCall('startSpan', [name, options, context, fn])\n\t}\n\n\tstartManualSpan(\n\t\tname: string,\n\t\toptions: SpanOptions | ((span: Span) => any),\n\t\tcontext?: Context | ((span: Span) => any),\n\t\tfn?: (span: Span) => any,\n\t) {\n\t\tif (!this._isReady) {\n\t\t\tthis._logNoopSpanWarning()\n\t\t\treturn resolveSpanCallback(options, context, fn)?.(getNoopSpan())\n\t\t}\n\t\treturn this._bufferCall('startManualSpan', [name, options, context, fn])\n\t}\n\n\tprivate _logNoopSpanWarning() {\n\t\tinternalLogOnce(\n\t\t\t'startSpan/startManualSpan called before start()',\n\t\t\t'span-before-start',\n\t\t\t'warn',\n\t\t\t'The span callback runs on a no-op span and the span is not recorded.',\n\t\t)\n\t}\n\n\tregister(\n\t\tclient: LDClient,\n\t\tenvironmentMetadata: LDPluginEnvironmentMetadata,\n\t) {\n\t\treturn this._bufferCall('register', [client, environmentMetadata])\n\t}\n\n\trecordLog(message: any, level: ConsoleMethods, metadata?: Attributes) {\n\t\treturn this._bufferCall('recordLog', [message, level, metadata])\n\t}\n\n\trecordError(\n\t\terror: Error,\n\t\tmessage?: string,\n\t\tpayload?: { [key: string]: string },\n\t\tsource?: string,\n\t\ttype?: ErrorMessageType,\n\t) {\n\t\treturn this._bufferCall('recordError', [\n\t\t\terror,\n\t\t\tmessage,\n\t\t\tpayload,\n\t\t\tsource,\n\t\t\ttype,\n\t\t])\n\t}\n\n\tsetLDContextKeyAttributes(contextKeys: Attributes) {\n\t\treturn this._bufferCall('setLDContextKeyAttributes', [contextKeys])\n\t}\n\n\tgetLDContextKeyAttributes(): Attributes | undefined {\n\t\t// A getter: read directly once attached rather than buffering.\n\t\treturn this._isLoaded\n\t\t\t? this._callSdk('getLDContextKeyAttributes', [])\n\t\t\t: undefined\n\t}\n}\n\ninterface GlobalThis {\n\tLDObserve?: _LDObserve\n}\ndeclare var globalThis: GlobalThis\n\nexport let LDObserve!: _LDObserve\nif (typeof globalThis !== 'undefined') {\n\tif (globalThis.LDObserve) {\n\t\tLDObserve = globalThis.LDObserve\n\t} else {\n\t\tLDObserve = new _LDObserve()\n\t\tglobalThis.LDObserve = LDObserve\n\t}\n} else {\n\tLDObserve = new _LDObserve()\n}\n"],"names":["getNoopSpan","noopSpan","_key","_value","_attributes","_name","_attributesOrStartTime","_startTime","_links","_status","resolveSpanCallback","options","context","fn","_LDObserve","BufferedClass","__async","metric","name","_a","internalLogOnce","client","environmentMetadata","message","level","metadata","error","payload","source","type","contextKeys","LDObserve"],"mappings":"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"}

package/dist/LDObserve.d.ts

@@ -25,15 +25,80 @@ declare type AttributeValue = string | number | boolean | Array<null | undefined
 
 declare class BufferedClass<T extends object> {
     protected _sdk: T;
+    /** True once an SDK instance has been attached via `load`. */
     protected _isLoaded: boolean;
+    /** True once the attached SDK has started and the buffer has drained. */
+    protected _isReady: boolean;
     protected _callBuffer: Array<Event_2>;
     protected _capacity: number;
     protected _droppedEvents: number;
     protected _exceededCapacity: boolean;
     protected _logger: Logger;
+    private _pendingStart?;
+    /**
+     * The last start or stop queued on the attached SDK while it runs. Starts
+     * and stops run in call order, so the final state follows the last call.
+     */
+    private _lastOp?;
     protected _bufferCall(method: string, args: any[]): any;
+    /** Calls the attached SDK directly, logging instead of throwing. */
+    protected _callSdk(method: string, args: any[]): any;
     protected _enqueue(event: Event_2): void;
-    load(sdk: T): void;
+    /**
+     * Attach an SDK implementation. With `ready: false` (e.g. `manualStart`
+     * mode, or an SDK whose `start` is still running), telemetry keeps
+     * buffering until `markReady()` is called.
+     */
+    load(sdk: T, { ready, started }?: BufferedLoadOptions): void;
+    private _runPendingStart;
+    /**
+     * Starts the attached SDK and drains the buffer. Before `load` the start
+     * is deferred. Starts and stops run in call order: a start made while a
+     * stop is queued runs after that stop, while overlapping starts with no
+     * stop between them share one SDK start.
+     */
+    protected _start(): Promise<void>;
+    /**
+     * Stops the attached SDK. Before `load` it cancels a deferred start. Once
+     * attached, every stop is queued: it waits for an earlier start or stop,
+     * and a later start waits for the SDK's stop (including any async
+     * shutdown) to finish. Errors are logged rather than thrown.
+     */
+    protected _stop(stopSdk: () => unknown): Promise<void>;
+    /** Runs `op` once the previously queued start or stop has settled. */
+    private _queueOp;
+    /**
+     * Starts the attached SDK. Subclasses whose SDK owns a `start` method
+     * override this so a deferred start reaches the real implementation.
+     */
+    protected _startSdk(): Promise<void>;
+    /**
+     * Drains the buffered calls into the attached SDK and lets subsequent
+     * calls run directly.
+     */
+    protected markReady(): void;
+    /**
+     * Defers a start until `load` attaches an SDK. Returns a promise that
+     * resolves once the SDK has been attached, started and drained.
+     */
+    protected _deferStart(): Promise<void>;
+    /** Cancels a deferred start so it never runs; awaiting callers resolve. */
+    protected _cancelPendingStart(): void;
+}
+
+declare interface BufferedLoadOptions {
+    /**
+     * Whether the attached SDK has already been started.
+     * When `false` (e.g. `manualStart` mode), calls keep buffering until the
+     * SDK is started; a `start()` made before `load` runs at `load` time.
+     */
+    ready?: boolean;
+    /**
+     * With `ready: true`, the attached SDK's own start while it is still
+     * running. It is queued like a `start()`, so a `stop()` made meanwhile
+     * waits for it instead of being undone by it.
+     */
+    started?: Promise<unknown>;
 }
 
 declare type ConsoleMethods = ConsoleMethodsTuple[number];
@@ -161,6 +226,7 @@ declare interface LDClientMin {
 export declare let LDObserve: _LDObserve;
 
 declare class _LDObserve extends BufferedClass<Observe> implements Observe {
+    protected _startSdk(): Promise<void>;
     start(): Promise<void>;
     stop(): Promise<void>;
     recordGauge(metric: OTelMetric): any;
@@ -170,6 +236,7 @@ declare class _LDObserve extends BufferedClass<Observe> implements Observe {
     recordUpDownCounter(metric: OTelMetric): any;
     startSpan(name: string, options: SpanOptions | ((span?: Span) => any), context?: Context | ((span?: Span) => any), fn?: (span?: Span) => any): any;
     startManualSpan(name: string, options: SpanOptions | ((span: Span) => any), context?: Context | ((span: Span) => any), fn?: (span: Span) => any): any;
+    private _logNoopSpanWarning;
     register(client: LDClientMin, environmentMetadata: LDPluginEnvironmentMetadata): any;
     recordLog(message: any, level: ConsoleMethods, metadata?: Attributes): any;
     recordError(error: Error, message?: string, payload?: {
@@ -219,10 +286,15 @@ declare class Logger {
 declare interface Observe {
     /**
      * Start the observability data capture when running in `manualStart` mode.
+     * Can safely be called before the SDK has initialized (e.g. before the
+     * plugin registers): the call resolves once the SDK is attached and
+     * started, without throwing.
      */
     start: () => Promise<void>;
     /**
      * Stop the observability data capture.
+     * Can safely be called before the SDK has initialized; before `start()`
+     * it cancels a pending start instead of throwing.
      */
     stop: () => Promise<void>;
     /**

package/dist/LDObserve.js

@@ -1,5 +1,5 @@
-import "./buffer-BjzLorpP.js";
-import { L as m } from "./LDObserve-DhF3vCDR.js";
+import "./buffer-CwCRPuMA.js";
+import { L as m } from "./LDObserve-BQr7RYVC.js";
 export {
   m as LDObserve
 };

package/dist/LDRecord.d.ts

@@ -7,15 +7,80 @@ import { LDPluginEnvironmentMetadata } from '@launchdarkly/js-client-sdk';
 
 declare class BufferedClass<T extends object> {
     protected _sdk: T;
+    /** True once an SDK instance has been attached via `load`. */
     protected _isLoaded: boolean;
+    /** True once the attached SDK has started and the buffer has drained. */
+    protected _isReady: boolean;
     protected _callBuffer: Array<Event_2>;
     protected _capacity: number;
     protected _droppedEvents: number;
     protected _exceededCapacity: boolean;
     protected _logger: Logger;
+    private _pendingStart?;
+    /**
+     * The last start or stop queued on the attached SDK while it runs. Starts
+     * and stops run in call order, so the final state follows the last call.
+     */
+    private _lastOp?;
     protected _bufferCall(method: string, args: any[]): any;
+    /** Calls the attached SDK directly, logging instead of throwing. */
+    protected _callSdk(method: string, args: any[]): any;
     protected _enqueue(event: Event_2): void;
-    load(sdk: T): void;
+    /**
+     * Attach an SDK implementation. With `ready: false` (e.g. `manualStart`
+     * mode, or an SDK whose `start` is still running), telemetry keeps
+     * buffering until `markReady()` is called.
+     */
+    load(sdk: T, { ready, started }?: BufferedLoadOptions): void;
+    private _runPendingStart;
+    /**
+     * Starts the attached SDK and drains the buffer. Before `load` the start
+     * is deferred. Starts and stops run in call order: a start made while a
+     * stop is queued runs after that stop, while overlapping starts with no
+     * stop between them share one SDK start.
+     */
+    protected _start(): Promise<void>;
+    /**
+     * Stops the attached SDK. Before `load` it cancels a deferred start. Once
+     * attached, every stop is queued: it waits for an earlier start or stop,
+     * and a later start waits for the SDK's stop (including any async
+     * shutdown) to finish. Errors are logged rather than thrown.
+     */
+    protected _stop(stopSdk: () => unknown): Promise<void>;
+    /** Runs `op` once the previously queued start or stop has settled. */
+    private _queueOp;
+    /**
+     * Starts the attached SDK. Subclasses whose SDK owns a `start` method
+     * override this so a deferred start reaches the real implementation.
+     */
+    protected _startSdk(): Promise<void>;
+    /**
+     * Drains the buffered calls into the attached SDK and lets subsequent
+     * calls run directly.
+     */
+    protected markReady(): void;
+    /**
+     * Defers a start until `load` attaches an SDK. Returns a promise that
+     * resolves once the SDK has been attached, started and drained.
+     */
+    protected _deferStart(): Promise<void>;
+    /** Cancels a deferred start so it never runs; awaiting callers resolve. */
+    protected _cancelPendingStart(): void;
+}
+
+declare interface BufferedLoadOptions {
+    /**
+     * Whether the attached SDK has already been started.
+     * When `false` (e.g. `manualStart` mode), calls keep buffering until the
+     * SDK is started; a `start()` made before `load` runs at `load` time.
+     */
+    ready?: boolean;
+    /**
+     * With `ready: true`, the attached SDK's own start while it is still
+     * running. It is queued like a `start()`, so a `stop()` made meanwhile
+     * waits for it instead of being undone by it.
+     */
+    started?: Promise<unknown>;
 }
 
 declare type Event_2 = {
@@ -71,7 +136,9 @@ declare interface LDClientMin {
 export declare let LDRecord: _LDRecord;
 
 declare class _LDRecord extends BufferedClass<Record_2> implements Record_2 {
+    private _deferredStartOptions?;
     getSession(): SessionDetails | null;
+    protected _startSdk(): Promise<void>;
     start(options?: StartOptions): Promise<void>;
     stop(): void;
     addSessionProperties(properties: {
@@ -99,11 +166,16 @@ declare interface Record_2 {
     /**
      * Start the session when running in `manualStart` mode.
      * Can be used to force start a new session.
+     * Can safely be called before the SDK has initialized (e.g. before the
+     * plugin registers): the call resolves once the SDK is attached and
+     * started, without throwing.
      * @param options the session start options.
      */
     start: (options?: StartOptions) => Promise<void>;
     /**
      * Stop the session recording.
+     * Can safely be called before the SDK has initialized; before `start()`
+     * it cancels a pending start instead of throwing.
      */
     stop: () => void;
     /**

package/dist/LDRecord.js

@@ -1,48 +1,67 @@
-var a = (l, e, r) => new Promise((f, d) => {
-  var h = (s) => {
+var p = Object.defineProperty;
+var S = (s, t, e) => t in s ? p(s, t, { enumerable: !0, configurable: !0, writable: !0, value: e }) : s[t] = e;
+var h = (s, t, e) => S(s, typeof t != "symbol" ? t + "" : t, e);
+var n = (s, t, e) => new Promise((o, l) => {
+  var c = (r) => {
     try {
-      i(r.next(s));
-    } catch (o) {
-      d(o);
+      d(e.next(r));
+    } catch (a) {
+      l(a);
     }
-  }, u = (s) => {
+  }, f = (r) => {
     try {
-      i(r.throw(s));
-    } catch (o) {
-      d(o);
+      d(e.throw(r));
+    } catch (a) {
+      l(a);
     }
-  }, i = (s) => s.done ? f(s.value) : Promise.resolve(s.value).then(h, u);
-  i((r = r.apply(l, e)).next());
+  }, d = (r) => r.done ? o(r.value) : Promise.resolve(r.value).then(c, f);
+  d((e = e.apply(s, t)).next());
 });
-import { B as g } from "./buffer-BjzLorpP.js";
-class n extends g {
+import { B as g } from "./buffer-CwCRPuMA.js";
+class _ extends g {
+  constructor() {
+    super(...arguments);
+    h(this, "_deferredStartOptions");
+  }
   getSession() {
-    return this._isLoaded ? this._bufferCall("getSession", []) : null;
+    return this._isLoaded ? this._callSdk("getSession", []) : null;
+  }
+  _startSdk() {
+    return n(this, null, function* () {
+      const e = this._deferredStartOptions;
+      this._deferredStartOptions = void 0, yield this._sdk.start(e);
+    });
   }
+  // Never buffered: with `manualStart`, `start()` may run before the plugin
+  // has attached an SDK. It then stays pending and resolves once `load`
+  // attaches and starts the SDK.
   start(e) {
-    return a(this, null, function* () {
-      return this._sdk.start(e);
+    return n(this, null, function* () {
+      return this._deferredStartOptions = e, this._start();
     });
   }
+  // Never buffered, and never throws: before an SDK is attached it just
+  // cancels a start that has not run yet. Once attached, the stop is queued
+  // after any running start or stop, so it may complete asynchronously.
   stop() {
-    return this._sdk.stop();
+    this._stop(() => this._sdk.stop());
   }
   addSessionProperties(e) {
     return this._bufferCall("addSessionProperties", [e]);
   }
   getRecordingState() {
-    return this._isLoaded ? this._bufferCall("getRecordingState", []) : "NotRecording";
+    return this._isLoaded ? this._callSdk("getRecordingState", []) : "NotRecording";
   }
   snapshot(e) {
-    return this._isLoaded ? this._bufferCall("snapshot", [e]) : Promise.resolve(void 0);
+    return this._isLoaded ? this._callSdk("snapshot", [e]) : Promise.resolve(void 0);
   }
-  register(e, r) {
-    return this._bufferCall("register", [e, r]);
+  register(e, o) {
+    return this._bufferCall("register", [e, o]);
   }
 }
-let t;
-typeof globalThis != "undefined" ? globalThis.LDRecord ? t = globalThis.LDRecord : (t = new n(), globalThis.LDRecord = t) : t = new n();
+let i;
+typeof globalThis != "undefined" ? globalThis.LDRecord ? i = globalThis.LDRecord : (i = new _(), globalThis.LDRecord = i) : i = new _();
 export {
-  t as LDRecord
+  i as LDRecord
 };
 //# sourceMappingURL=LDRecord.js.map

package/dist/LDRecord.js.map

@@ -1 +1 @@
-{"version":3,"file":"LDRecord.js","sources":["../src/sdk/LDRecord.ts"],"sourcesContent":["import type { Record } from '../api/record'\nimport type { SessionDetails } from '../client'\nimport type { LDClient } from '../integrations/launchdarkly'\nimport type { StartOptions } from '../client/types/types'\nimport type { LDPluginEnvironmentMetadata } from '../plugins/plugin'\nimport { BufferedClass } from './buffer'\n\nclass _LDRecord extends BufferedClass<Record> implements Record {\n\tgetSession(): SessionDetails | null {\n\t\treturn this._isLoaded ? this._bufferCall('getSession', []) : null\n\t}\n\n\tasync start(options?: StartOptions) {\n\t\t// avoid buffering the start call\n\t\treturn this._sdk.start(options)\n\t}\n\n\tstop() {\n\t\t// avoid buffering the stop call\n\t\treturn this._sdk.stop()\n\t}\n\n\taddSessionProperties(properties: { [key: string]: any }) {\n\t\treturn this._bufferCall('addSessionProperties', [properties])\n\t}\n\n\tgetRecordingState() {\n\t\treturn this._isLoaded\n\t\t\t? this._bufferCall('getRecordingState', [])\n\t\t\t: ('NotRecording' as const)\n\t}\n\n\tsnapshot(element: HTMLCanvasElement) {\n\t\treturn this._isLoaded\n\t\t\t? this._bufferCall('snapshot', [element])\n\t\t\t: Promise.resolve(undefined)\n\t}\n\n\tregister(\n\t\tclient: LDClient,\n\t\tenvironmentMetadata: LDPluginEnvironmentMetadata,\n\t) {\n\t\treturn this._bufferCall('register', [client, environmentMetadata])\n\t}\n}\n\ninterface GlobalThis {\n\tLDRecord?: _LDRecord\n}\ndeclare var globalThis: GlobalThis\n\nexport let LDRecord!: _LDRecord\nif (typeof globalThis !== 'undefined') {\n\tif (globalThis.LDRecord) {\n\t\tLDRecord = globalThis.LDRecord\n\t} else {\n\t\tLDRecord = new _LDRecord()\n\t\tglobalThis.LDRecord = LDRecord\n\t}\n} else {\n\tLDRecord = new _LDRecord()\n}\n"],"names":["_LDRecord","BufferedClass","options","__async","properties","element","client","environmentMetadata","LDRecord"],"mappings":";;;;;;;;;;;;;;;;;AAOA,MAAMA,UAAkBC,EAAwC;AAAA,EAC/D,aAAoC;AACnC,WAAO,KAAK,YAAY,KAAK,YAAY,cAAc,CAAA,CAAE,IAAI;AAAA,EAC9D;AAAA,EAEM,MAAMC,GAAwB;AAAA,WAAAC,EAAA;AAEnC,aAAO,KAAK,KAAK,MAAMD,CAAO;AAAA,IAC/B;AAAA;AAAA,EAEA,OAAO;AAEN,WAAO,KAAK,KAAK,KAAA;AAAA,EAClB;AAAA,EAEA,qBAAqBE,GAAoC;AACxD,WAAO,KAAK,YAAY,wBAAwB,CAACA,CAAU,CAAC;AAAA,EAC7D;AAAA,EAEA,oBAAoB;AACnB,WAAO,KAAK,YACT,KAAK,YAAY,qBAAqB,CAAA,CAAE,IACvC;AAAA,EACL;AAAA,EAEA,SAASC,GAA4B;AACpC,WAAO,KAAK,YACT,KAAK,YAAY,YAAY,CAACA,CAAO,CAAC,IACtC,QAAQ,QAAQ,MAAS;AAAA,EAC7B;AAAA,EAEA,SACCC,GACAC,GACC;AACD,WAAO,KAAK,YAAY,YAAY,CAACD,GAAQC,CAAmB,CAAC;AAAA,EAClE;AACD;AAOO,IAAIC;AACP,OAAO,cAAe,cACrB,WAAW,WACdA,IAAW,WAAW,YAEtBA,IAAW,IAAIR,EAAA,GACf,WAAW,WAAWQ,KAGvBA,IAAW,IAAIR,EAAA;"}
+{"version":3,"file":"LDRecord.js","sources":["../src/sdk/LDRecord.ts"],"sourcesContent":["import type { Record } from '../api/record'\nimport type { SessionDetails } from '../client'\nimport type { LDClient } from '../integrations/launchdarkly'\nimport type { StartOptions } from '../client/types/types'\nimport type { LDPluginEnvironmentMetadata } from '../plugins/plugin'\nimport { BufferedClass } from './buffer'\n\nclass _LDRecord extends BufferedClass<Record> implements Record {\n\tprivate _deferredStartOptions?: StartOptions\n\n\tgetSession(): SessionDetails | null {\n\t\treturn this._isLoaded ? this._callSdk('getSession', []) : null\n\t}\n\n\tprotected async _startSdk() {\n\t\t// Take the options before awaiting so a start queued meanwhile keeps\n\t\t// its own options.\n\t\tconst options = this._deferredStartOptions\n\t\tthis._deferredStartOptions = undefined\n\t\tawait this._sdk.start(options)\n\t}\n\n\t// Never buffered: with `manualStart`, `start()` may run before the plugin\n\t// has attached an SDK. It then stays pending and resolves once `load`\n\t// attaches and starts the SDK.\n\tasync start(options?: StartOptions) {\n\t\tthis._deferredStartOptions = options\n\t\treturn this._start()\n\t}\n\n\t// Never buffered, and never throws: before an SDK is attached it just\n\t// cancels a start that has not run yet. Once attached, the stop is queued\n\t// after any running start or stop, so it may complete asynchronously.\n\tstop() {\n\t\tvoid this._stop(() => this._sdk.stop())\n\t}\n\n\taddSessionProperties(properties: { [key: string]: any }) {\n\t\treturn this._bufferCall('addSessionProperties', [properties])\n\t}\n\n\tgetRecordingState() {\n\t\treturn this._isLoaded\n\t\t\t? this._callSdk('getRecordingState', [])\n\t\t\t: ('NotRecording' as const)\n\t}\n\n\tsnapshot(element: HTMLCanvasElement) {\n\t\treturn this._isLoaded\n\t\t\t? this._callSdk('snapshot', [element])\n\t\t\t: Promise.resolve(undefined)\n\t}\n\n\tregister(\n\t\tclient: LDClient,\n\t\tenvironmentMetadata: LDPluginEnvironmentMetadata,\n\t) {\n\t\treturn this._bufferCall('register', [client, environmentMetadata])\n\t}\n}\n\ninterface GlobalThis {\n\tLDRecord?: _LDRecord\n}\ndeclare var globalThis: GlobalThis\n\nexport let LDRecord!: _LDRecord\nif (typeof globalThis !== 'undefined') {\n\tif (globalThis.LDRecord) {\n\t\tLDRecord = globalThis.LDRecord\n\t} else {\n\t\tLDRecord = new _LDRecord()\n\t\tglobalThis.LDRecord = LDRecord\n\t}\n} else {\n\tLDRecord = new _LDRecord()\n}\n"],"names":["_LDRecord","BufferedClass","__publicField","__async","options","properties","element","client","environmentMetadata","LDRecord"],"mappings":";;;;;;;;;;;;;;;;;;;;AAOA,MAAMA,UAAkBC,EAAwC;AAAA,EAAhE;AAAA;AACS,IAAAC,EAAA;AAAA;AAAA,EAER,aAAoC;AACnC,WAAO,KAAK,YAAY,KAAK,SAAS,cAAc,CAAA,CAAE,IAAI;AAAA,EAC3D;AAAA,EAEgB,YAAY;AAAA,WAAAC,EAAA;AAG3B,YAAMC,IAAU,KAAK;AACrB,WAAK,wBAAwB,QAC7B,MAAM,KAAK,KAAK,MAAMA,CAAO;AAAA,IAC9B;AAAA;AAAA;AAAA;AAAA;AAAA,EAKM,MAAMA,GAAwB;AAAA,WAAAD,EAAA;AACnC,kBAAK,wBAAwBC,GACtB,KAAK,OAAA;AAAA,IACb;AAAA;AAAA;AAAA;AAAA;AAAA,EAKA,OAAO;AACN,IAAK,KAAK,MAAM,MAAM,KAAK,KAAK,MAAM;AAAA,EACvC;AAAA,EAEA,qBAAqBC,GAAoC;AACxD,WAAO,KAAK,YAAY,wBAAwB,CAACA,CAAU,CAAC;AAAA,EAC7D;AAAA,EAEA,oBAAoB;AACnB,WAAO,KAAK,YACT,KAAK,SAAS,qBAAqB,CAAA,CAAE,IACpC;AAAA,EACL;AAAA,EAEA,SAASC,GAA4B;AACpC,WAAO,KAAK,YACT,KAAK,SAAS,YAAY,CAACA,CAAO,CAAC,IACnC,QAAQ,QAAQ,MAAS;AAAA,EAC7B;AAAA,EAEA,SACCC,GACAC,GACC;AACD,WAAO,KAAK,YAAY,YAAY,CAACD,GAAQC,CAAmB,CAAC;AAAA,EAClE;AACD;AAOO,IAAIC;AACP,OAAO,cAAe,cACrB,WAAW,WACdA,IAAW,WAAW,YAEtBA,IAAW,IAAIT,EAAA,GACf,WAAW,WAAWS,KAGvBA,IAAW,IAAIT,EAAA;"}