@sanseng/liveavatar-js-sdk-skywalking 1.0.2 → 1.1.0

package/dist/index.d.ts

@@ -1,6 +1,91 @@
-import { AvSyncAlertEvent, AvSyncLogRetention, AvSyncAnalysisReport, SDKPlugin, SDKPluginRegistrar } from '@sanseng/liveavatar-js-sdk';
+import { SDKLogRecordV2, SDKJsonObject, AvSyncTelemetryQuery, SDKLogEvidencePageV2, PlaybackStatus, SDKPlugin, SDKPluginRegistrar, VERSION } from '@sanseng/liveavatar-js-sdk';
+
+/** Source-owned identities; server and diagnostic sessions are distinct. */
+interface SkyWalkingCorrelation {
+    clientInstanceId?: string;
+    monitoringSessionId?: string;
+    serverSessionId?: string;
+    avsyncSessionId?: string;
+}
+interface SkyWalkingOperationalLogSource extends SkyWalkingCorrelation {
+    sourceSchema: "sdk.log";
+    sourceSchemaVersion: 2;
+    clientInstanceId: string;
+    eventId: string;
+    streamId: string;
+    sequence: number;
+    occurredAtMs: number;
+    observedAtMs?: number;
+    clockId?: string;
+}
+interface SkyWalkingSessionTimelinePayload extends SkyWalkingOperationalLogSource {
+    kind: "liveavatar.session.timeline";
+    schemaVersion: 4;
+    level: SDKLogRecordV2["level"];
+    module: SDKLogRecordV2["module"];
+    event: string;
+    trigger: SDKLogRecordV2["trigger"];
+    operation?: SDKLogRecordV2["operation"];
+    failureRef?: SDKLogRecordV2["failureRef"];
+    snapshot?: SDKJsonObject;
+    correlation?: SDKLogRecordV2["correlation"];
+    data?: SDKJsonObject;
+}
+
+type EvidenceRange = NonNullable<AvSyncTelemetryQuery["range"]>;
+type JsonSafeAlert = SDKLogRecordV2;
+/** Logical document reconstructed from the ordered transport fragments. */
+interface AvSyncEvidence {
+    schema: "liveavatar.avsync.evidence";
+    schemaVersion: 4;
+    alert: SDKLogRecordV2;
+    query: {
+        range: EvidenceRange;
+        retrievedAtWallClockMs: number;
+        complete: boolean;
+    };
+    pages: readonly SDKLogEvidencePageV2[];
+    completeness: {
+        complete: boolean;
+        reasons: readonly string[];
+    };
+}
+/** Wire summary. Third-level containers such as reasons are JSON strings. */
+interface AvSyncAlertEvidencePayload extends SkyWalkingOperationalLogSource {
+    kind: "liveavatar.avsync.alert-evidence";
+    schemaVersion: 4;
+    recordType: "summary";
+    evidenceId: string;
+    alertId: string;
+    evidence: {
+        complete: boolean;
+        reasons: string;
+        logChunkCount: number;
+        logRecordCount: number;
+        byteLength: number;
+    };
+}
+/** A fragment can end inside a source record, but never inside a Unicode pair. */
+interface AvSyncEvidenceLogChunkPayload extends SkyWalkingOperationalLogSource {
+    kind: "liveavatar.avsync.alert-evidence";
+    schemaVersion: 4;
+    recordType: "log-chunk";
+    evidenceId: string;
+    alertId: string;
+    chunk: {
+        index: number;
+        total: number;
+        byteLength: number;
+        data: string;
+    };
+}
+interface AvSyncRecoveryPayload extends SkyWalkingOperationalLogSource {
+    kind: "liveavatar.avsync.recovery";
+    schemaVersion: 4;
+    alertId: string;
+    recoveredAtWallClockMs: number;
+}
 
-/** Stable identifier used by the LiveAvatar SDK plugin host. */
 declare const SKYWALKING_PLUGIN_ID = "liveavatar.skywalking";
 declare const SKYWALKING_SERVICE = "yy-tx::liveavatar-js-sdk";
 type SkyWalkingUrlMatcher = string | RegExp;
@@ -14,23 +99,29 @@ interface SkyWalkingSlowInteractionConfig {
     threshold?: number;
     reportInterval?: number;
 }
-/** Selects which SDK-generated records the plugin sends to SkyWalking. */
+/** Selects automatic SDK fact reports and plugin playback samples. */
 interface SkyWalkingReportingConfig {
     /** Report SDK Operational Log errors. Defaults to `true`. */
     sdkError?: boolean;
+    /** Report allowlisted session lifecycle facts. Defaults to `true`. */
+    timeline?: boolean;
     /** Report terminal SDK first-frame Operational Logs. Defaults to `true`. */
     firstFrame?: boolean;
     /** Report SDK-generated A/V Sync alert lifecycles and evidence. Defaults to `true`. */
     avSync?: boolean;
+    /** Sample playback while connected. Defaults to `true`. */
+    playbackStatus?: boolean;
 }
 /**
  * Registration options accepted by SkyWalking js-sdk 1.1.27, plus the
- * plugin-level reporting controls and overseas switch. `service` is deliberately
- * fixed by the plugin.
+ * plugin-level reporting controls and overseas switch. `service` and
+ * `serviceVersion` are deliberately fixed by the plugin.
  */
 interface SkyWalkingPluginConfig {
-    /** Select automatic SDK log types. Every type is enabled by default. */
+    /** Select automatic report types. Every type is enabled by default. */
     reporting?: SkyWalkingReportingConfig;
+    /** Positive integer milliseconds, at most 2147483647. Defaults to 5000. */
+    playbackStatusIntervalMs?: number;
     /** Explicit collector URL. It takes precedence over `isOverseas`. */
     collector?: string;
     /** `false` selects the domestic collector; `true` selects the overseas one. */
@@ -55,7 +146,6 @@ interface SkyWalkingPluginConfig {
     extraMsg?: string | (() => string);
     hooks?: SkyWalkingHooks;
     pagePath?: string;
-    serviceVersion?: string;
     pageKey?: string;
     group?: string;
     subGroup?: string;
@@ -90,7 +180,7 @@ interface SkyWalkingRegistrationOptions {
     extraMsg?: string | (() => string);
     hooks: SkyWalkingHooks;
     pagePath: string;
-    serviceVersion: string;
+    serviceVersion: typeof VERSION;
     pageKey: string;
     group: string;
     subGroup: string;
@@ -101,136 +191,6 @@ interface SkyWalkingRegistrationOptions {
     maxRequestBodySize: number;
     slowInteraction: Required<SkyWalkingSlowInteractionConfig>;
 }
-type EvidenceUnavailableReason = "initial-query-failed" | "session-mismatch" | "continuation-query-failed" | "cursor-did-not-advance";
-/** JSON-safe representation of an A/V Sync alert in an evidence payload. */
-interface JsonSafeAlert extends Omit<AvSyncAlertEvent, "sessionId"> {
-    sessionId: string | null;
-}
-/** Evidence attached to one raised A/V-sync alert. */
-interface AvSyncEvidence {
-    evidenceSchemaVersion: 2;
-    /** Diagnostic session owning every compact evidence record. */
-    sessionId: string | null;
-    /** Query bounds and whether the SDK could read a complete window. */
-    window: AvSyncEvidenceWindow;
-    /** Only retention facts which affect whether absence can be interpreted. */
-    retention: AvSyncEvidenceRetention | null;
-    /** Small, structured platform-first attribution for the exact alert window. */
-    triage: AvSyncTriage | null;
-    /** Number of separately reported detailed-log records. */
-    logChunkCount: number;
-    /** Number of compact records across all log chunks. */
-    logRecordCount: number;
-    /** Detail projection; each detailed-log record carries its own manifest entry. */
-    detail: AvSyncEvidenceDetail;
-    /** @deprecated Detailed logs are now emitted as separate log records. */
-    logs?: readonly AvSyncCompactLog[];
-    /** @deprecated Detailed logs are now emitted as separate log records. */
-    [logChunk: `logs_${number}`]: readonly AvSyncCompactLog[] | undefined;
-}
-interface AvSyncEvidenceWindow {
-    mode: "recent" | "wall-clock";
-    requestedFromWallClockMs: number | null;
-    requestedToWallClockMs: number | null;
-    availableFromWallClockMs: number | null;
-    availableToWallClockMs: number | null;
-    complete: boolean;
-    truncated: boolean;
-    unavailableReason?: EvidenceUnavailableReason;
-}
-type AvSyncEvidenceRetention = Pick<AvSyncLogRetention, "storageWriteFailed" | "droppedSegmentCount" | "droppedLogCount" | "oldestSegmentAtMs" | "newestSegmentAtMs">;
-/** The trigger is immutable; evaluation is the contemporaneous window result. */
-interface AvSyncTriage {
-    trigger: Pick<JsonSafeAlert, "finding" | "status" | "confidence" | "capturedAtMs">;
-    evaluation: {
-        finding: AvSyncAnalysisReport["finding"];
-        status: AvSyncAnalysisReport["status"];
-        confidence: AvSyncAnalysisReport["confidence"];
-    } | null;
-    layers: Record<keyof AvSyncAnalysisReport["layers"], Pick<AvSyncAnalysisReport["layers"]["binding"], "status" | "finding" | "confidence">> | null;
-    participants: Array<{
-        participantId: string;
-        status: AvSyncAnalysisReport["status"];
-        finding: AvSyncAnalysisReport["finding"];
-        confidence: AvSyncAnalysisReport["confidence"];
-        audioTrackId: string | null;
-        videoTrackId: string | null;
-        metrics: AvSyncAnalysisReport["participants"][number]["metrics"];
-    }>;
-    limitations: readonly string[];
-}
-/** A compact causal fact. `q`, `t`, and `o` preserve source ordering and time domains. */
-interface AvSyncCompactLog {
-    q: number;
-    t: number;
-    o: number;
-    y: string;
-    e: string;
-    c?: Record<string, unknown>;
-    d?: Record<string, unknown>;
-}
-interface AvSyncEvidenceDetail {
-    projectionVersion: 2;
-    sourceRecordCount: number;
-    reportedRecordCount: number;
-    timeSyncInputCount: number;
-    timeSyncReportedCount: number;
-    framePresentationReportedCount: number;
-    verifiedMetadataTimestampCount: number;
-    omittedSetupLifecycleCount: number;
-    oversizeFallbackRecordCount: number;
-    contentByteLimit: number;
-    /** Present only while the plugin prepares the outgoing log records. */
-    chunks?: readonly AvSyncLogChunkManifest[];
-}
-interface AvSyncLogChunkManifest {
-    index: number;
-    byteLength: number;
-    recordCount: number;
-    firstSequence: number | null;
-    lastSequence: number | null;
-}
-/** A/V alert content handed to `ClientMonitor.reportFrameErrors`. */
-interface AvSyncAlertEvidencePayload {
-    schemaVersion: 1;
-    kind: "liveavatar.avsync.alert-evidence";
-    sdkVersion: string;
-    recordType: "summary";
-    /** Correlates this summary with its separately reported log records. */
-    evidenceId: string;
-    /** True when optional summary detail was omitted to keep this record safe. */
-    summaryTruncated?: boolean;
-    alert: JsonSafeAlert;
-    /** Structured A/V evidence; SkyWalking serializes the enclosing error log. */
-    evidence: AvSyncEvidence;
-}
-/** One platform-safe detailed-log record belonging to an A/V alert snapshot. */
-interface AvSyncEvidenceLogChunkPayload {
-    schemaVersion: 1;
-    kind: "liveavatar.avsync.alert-evidence";
-    sdkVersion: string;
-    recordType: "log-chunk";
-    evidenceId: string;
-    alertId: string;
-    sessionId: string | null;
-    chunk: AvSyncLogChunkManifest & {
-        total: number;
-        logs: readonly AvSyncCompactLog[];
-    };
-}
-/** Minimal lifecycle record sent when a previously raised alert recovers. */
-interface AvSyncRecoveryPayload {
-    alertId: string;
-    recoveredAtWallClockMs: number;
-}
-/** JSON-safe strings handed to `ClientMonitor.reportFrameErrors` for SDK errors. */
-interface SkyWalkingSdkErrorPayload {
-    schemaVersion: 2;
-    kind: "liveavatar.sdk.error";
-    sdkVersion: string;
-    /** JSON-encoded error record, including the SDK's optional string `reason`. */
-    error: string;
-}
 interface SkyWalkingFrameError {
     name: string;
     message: string;
@@ -268,10 +228,9 @@ interface SkyWalkingFirstFrameLogNodes {
     firstFrameMs?: number;
 }
 /** Structured content of one terminal SDK `performance.first-frame` log. */
-interface SkyWalkingFirstFrameLogPayload {
-    schemaVersion: 1;
+interface SkyWalkingFirstFrameLogPayload extends SkyWalkingOperationalLogSource {
+    schemaVersion: 4;
     kind: "liveavatar.performance.first-frame";
-    sdkVersion: string;
     occurredAtMs: number;
     attemptId: number;
     outcome: SkyWalkingFirstFrameOutcome;
@@ -279,41 +238,55 @@ interface SkyWalkingFirstFrameLogPayload {
     timeoutAfterRtcMs?: number;
     nodes: SkyWalkingFirstFrameLogNodes;
 }
-/**
- * Reports LiveAvatar A/V-sync incident lifecycle events through the bundled or
- * externally provided SkyWalking client.
- */
+interface SkyWalkingSdkErrorPayload extends SkyWalkingOperationalLogSource {
+    schemaVersion: 4;
+    kind: "liveavatar.sdk.error";
+    /** JSON-encoded, allowlisted v2 source failure. */
+    error: string;
+}
+/** Plugin-owned sample; nested SDK containers are lossless JSON text. */
+interface SkyWalkingPlaybackStatusPayload extends SkyWalkingCorrelation {
+    schemaVersion: 4;
+    kind: "liveavatar.playback.status";
+    clientInstanceId: string;
+    occurredAtMs: number;
+    playback: {
+        sampledAtMs: number;
+        connection: string;
+        ice: string;
+        output: string | null;
+        tracks: string;
+        quality: PlaybackStatus["quality"];
+        qualityReasons: string;
+        presentationSamplingEnabled: boolean;
+    };
+}
+/** Consumes SDK facts and samples playback through the public Plugin API v1. */
 declare class SkyWalkingPlugin implements SDKPlugin {
     readonly id = "liveavatar.skywalking";
-    /** SDK Plugin API v1 is the registrar-based public plugin contract. */
     readonly apiVersion = 1;
+    readonly terminalObserverDelivery = "sync-before-dispose";
     private readonly _skyWalkingConfig;
     private readonly _reporting;
-    private _installation;
-    private _nextInstallationGeneration;
+    private readonly _playbackStatusIntervalMs;
+    private _installation?;
     constructor(config?: SkyWalkingPluginConfig);
     setup(registrar: SDKPluginRegistrar): void;
     dispose(): void;
-    private _handleAlertNotification;
-    private _handleOperationalLog;
-    private _enqueue;
-    private _reportActiveAlert;
-    private _reportRecovery;
-    private _reportSdkError;
-    private _reportFirstFrameLog;
     private _deactivateInstallation;
-    private _isInvocationActive;
-    private _runObserverTask;
-    private _warnInvocationFailure;
-    private _warnInvocation;
+    private _stopPlayback;
+    private _handlePlaybackLifecycle;
+    private _startPlayback;
+    private _samplePlayback;
+    private _isActive;
+    private _warn;
+    private _report;
+    private _handleOperationalLog;
+    private _queueAlert;
+    private _drainAlerts;
+    private _reportAlert;
 }
-/** Creates a fresh plugin instance suitable for `createClient({ plugins })`. */
 declare function createSkyWalkingPlugin(config?: SkyWalkingPluginConfig): SkyWalkingPlugin;
-/**
- * Loads the bundled browser client when needed and registers it exactly once.
- * An application-provided `window.ClientMonitor` is treated as already
- * registered and is never overwritten or registered again.
- */
 declare function registerSkyWalking(config?: SkyWalkingPluginConfig): void;
 /** Triggers a SkyWalking performance report through an already registered client. */
 declare function setSkyWalkingPerformance(config?: Partial<SkyWalkingPluginConfig>, customMetrics?: Record<string, unknown>): void;
@@ -323,4 +296,4 @@ declare function setSkyWalkingHRT(config?: Partial<SkyWalkingPluginConfig>, cust
 declare function reportSkyWalkingFrameErrors(config: SkyWalkingFrameErrorReportConfig, error: SkyWalkingFrameError): Promise<void>;
 
 export { SKYWALKING_PLUGIN_ID, SkyWalkingPlugin, createSkyWalkingPlugin, registerSkyWalking, reportSkyWalkingFrameErrors, setSkyWalkingHRT, setSkyWalkingPerformance };
-export type { AvSyncAlertEvidencePayload, AvSyncEvidence, AvSyncEvidenceLogChunkPayload, AvSyncRecoveryPayload, JsonSafeAlert, SkyWalkingFirstFrameLogNodes, SkyWalkingFirstFrameLogPayload, SkyWalkingFirstFrameOutcome, SkyWalkingFrameError, SkyWalkingFrameErrorReportConfig, SkyWalkingHooks, SkyWalkingPluginConfig, SkyWalkingRegistrationOptions, SkyWalkingReportingConfig, SkyWalkingSdkErrorPayload, SkyWalkingSlowInteractionConfig };
+export type { AvSyncAlertEvidencePayload, AvSyncEvidence, AvSyncEvidenceLogChunkPayload, AvSyncRecoveryPayload, JsonSafeAlert, SkyWalkingCorrelation, SkyWalkingFirstFrameLogNodes, SkyWalkingFirstFrameLogPayload, SkyWalkingFirstFrameOutcome, SkyWalkingFrameError, SkyWalkingFrameErrorReportConfig, SkyWalkingHooks, SkyWalkingOperationalLogSource, SkyWalkingPlaybackStatusPayload, SkyWalkingPluginConfig, SkyWalkingRegistrationOptions, SkyWalkingReportingConfig, SkyWalkingSdkErrorPayload, SkyWalkingSessionTimelinePayload, SkyWalkingSlowInteractionConfig };