@launchdarkly/o11y 1.3.1 → 1.4.1

package/dist/index.d.ts

@@ -104,15 +104,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 CanvasArg = SerializedCanvasArg | string | number | boolean | null | CanvasArg[];
@@ -180,14 +245,29 @@ declare type CommonOptions = {
      */
     storageMode?: 'sessionStorage' | 'localStorage';
     /**
-     * By default, session data is stored in the `sessionStorage` of the browser.
+     * By default, session data is stored in the `localStorage` of the browser.
      * Set to `true` to store session data in a cookie instead.
      * This can help with compliance for cookie-consent regulation.
      */
     sessionCookie?: boolean;
+    /**
+     * Set the `Domain` attribute of the session cookie so the same session can
+     * be continued on different subdomains (e.g. `app.example.com` and
+     * `checkout.example.com` both see a cookie set for `example.com`).
+     * Only applies when `sessionCookie` is set to `true`.
+     * By default, the cookie is scoped to the exact host that created it.
+     */
+    sessionCookieDomain?: string;
     /**
      * Specifies if Highlight should not automatically initialize when the class is created.
      * This should be used with `.start()` and `.stop()` if you want to control when Highlight records.
+     *
+     * While `start()` has not been called, calls that can be deferred (logs,
+     * errors, metrics, `track`) are kept in memory and delivered once
+     * `start()` runs. `start()` and `stop()` can safely be called before the
+     * SDK has initialized: a start made too early resolves once the SDK is
+     * attached. Calls that cannot be deferred (synchronous span callbacks) run
+     * their callback on a no-op span while the SDK is not started.
      * @default false
      */
     manualStart?: boolean;
@@ -597,7 +677,8 @@ declare class Highlight_2 {
     getCurrentSessionURLWithTimestamp(): string;
     getCurrentSessionURL(): string | null;
     snapshot(element: HTMLCanvasElement): Promise<void>;
-    addSessionFeedback({ timestamp, verbatim, user_email, user_name, }: {
+    /** @deprecated Session feedback is no longer supported. This is a no-op. */
+    addSessionFeedback(_feedback: {
         verbatim: string;
         timestamp: string;
         user_name?: string;
@@ -658,6 +739,7 @@ declare type HighlightClassOptions = {
     sessionSecureID: string;
     storageMode?: 'sessionStorage' | 'localStorage';
     sessionCookie?: boolean;
+    sessionCookieDomain?: string;
     sendMode?: 'webworker' | 'local';
     otlpEndpoint?: HighlightOptions['otlpEndpoint'];
     otel?: HighlightOptions['otel'];
@@ -1008,7 +1090,8 @@ declare interface HighlightPublicInterface {
     getRecordingState: () => 'NotRecording' | 'Recording';
     options: HighlightOptions | undefined;
     /**
-     * Calling this will add a feedback comment to the session.
+     * @deprecated Session feedback is no longer supported. This is a no-op and
+     * will be removed in a future major version.
      */
     addSessionFeedback: (feedbackOptions: SessionFeedbackOptions) => void;
     snapshot: (element: HTMLCanvasElement) => Promise<void>;
@@ -1157,6 +1240,7 @@ declare interface LDClientMin {
 export declare let LDObserve: _LDObserve;
 
 declare class _LDObserve extends BufferedClass<Observe_2> implements Observe_2 {
+    protected _startSdk(): Promise<void>;
     start(): Promise<void>;
     stop(): Promise<void>;
     recordGauge(metric: OTelMetric): any;
@@ -1166,6 +1250,7 @@ declare class _LDObserve extends BufferedClass<Observe_2> implements Observe_2 {
     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?: {
@@ -1184,7 +1269,9 @@ declare interface LDPlugin {
 export declare let LDRecord: _LDRecord;
 
 declare class _LDRecord extends BufferedClass<Record_3> implements Record_3 {
+    private _deferredStartOptions?;
     getSession(): SessionDetails | null;
+    protected _startSdk(): Promise<void>;
     start(options?: StartOptions): Promise<void>;
     stop(): void;
     addSessionProperties(properties: {
@@ -1543,10 +1630,15 @@ export declare class Observe extends Plugin_2<ObserveOptions> implements LDPlugi
 declare interface Observe_2 {
     /**
      * 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>;
     /**
@@ -1879,11 +1971,16 @@ declare interface Record_3 {
     /**
      * 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;
     /**
@@ -2139,7 +2236,8 @@ declare class RecordSDK implements Record_3 {
     getCurrentSessionURLWithTimestamp(): string;
     getCurrentSessionURL(): string | null;
     snapshot(element: HTMLCanvasElement): Promise<void>;
-    addSessionFeedback({ timestamp, verbatim, user_email, user_name, }: {
+    /** @deprecated Session feedback is no longer supported. This is a no-op. */
+    addSessionFeedback(_feedback: {
         verbatim: string;
         timestamp: string;
         user_name?: string;