@sanseng/liveavatar-js-sdk-skywalking 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,286 @@
+import { AvSyncAlertEvent, AvSyncLogRetention, AvSyncAnalysisReport, SDKPlugin, SDKPluginRegistrar } from '@sanseng/liveavatar-js-sdk';
+
+/** 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;
+interface SkyWalkingHooks {
+    reportHook?: (type: string, data: Array<Record<string, string>>) => boolean;
+    filterHook?: (data: Record<string, string>) => boolean;
+    requestParamsHook?: (params: unknown) => unknown;
+}
+interface SkyWalkingSlowInteractionConfig {
+    enable?: boolean;
+    threshold?: number;
+    reportInterval?: number;
+}
+/**
+ * Registration options accepted by SkyWalking js-sdk 1.1.27, plus the
+ * plugin-level overseas switch. `service` is deliberately fixed by the plugin.
+ */
+interface SkyWalkingPluginConfig {
+    /** Explicit collector URL. It takes precedence over `isOverseas`. */
+    collector?: string;
+    /** `false` selects the domestic collector; `true` selects the overseas one. */
+    isOverseas?: boolean;
+    jsErrors?: boolean;
+    apiErrors?: boolean;
+    resourceErrors?: boolean;
+    autoTracePerf?: boolean;
+    useFmp?: boolean;
+    detailMode?: boolean;
+    perfEntries?: boolean;
+    rate?: number;
+    enableSPA?: boolean;
+    vue?: false | unknown;
+    traceSDKInternal?: boolean;
+    noTrace?: boolean;
+    noTraceUrls?: readonly SkyWalkingUrlMatcher[] | null;
+    noErrorPaths?: readonly SkyWalkingUrlMatcher[];
+    sendErrorTime?: number;
+    sendSegmentsTime?: number;
+    sendPerfTime?: number;
+    extraMsg?: string | (() => string);
+    hooks?: SkyWalkingHooks;
+    pagePath?: string;
+    serviceVersion?: string;
+    pageKey?: string;
+    group?: string;
+    subGroup?: string;
+    whiteScreen?: boolean;
+    whiteScreenTimeout?: number;
+    maxReqCostTime?: number;
+    collectRequestParams?: boolean;
+    maxRequestBodySize?: number;
+    slowInteraction?: SkyWalkingSlowInteractionConfig;
+}
+/** Fully normalized registration object passed to `ClientMonitor.register`. */
+interface SkyWalkingRegistrationOptions {
+    collector: string;
+    service: typeof SKYWALKING_SERVICE;
+    jsErrors: boolean;
+    apiErrors: boolean;
+    resourceErrors: boolean;
+    autoTracePerf: boolean;
+    useFmp: boolean;
+    detailMode: boolean;
+    perfEntries: boolean;
+    rate: number;
+    enableSPA: boolean;
+    vue: false | unknown;
+    traceSDKInternal: boolean;
+    noTrace: boolean;
+    noTraceUrls: readonly SkyWalkingUrlMatcher[] | null;
+    noErrorPaths: readonly SkyWalkingUrlMatcher[];
+    sendErrorTime: number;
+    sendSegmentsTime: number;
+    sendPerfTime: number;
+    extraMsg?: string | (() => string);
+    hooks: SkyWalkingHooks;
+    pagePath: string;
+    serviceVersion: string;
+    pageKey: string;
+    group: string;
+    subGroup: string;
+    whiteScreen: boolean;
+    whiteScreenTimeout: number;
+    maxReqCostTime: number;
+    collectRequestParams: boolean;
+    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;
+    error: string;
+}
+interface SkyWalkingFrameError {
+    name: string;
+    message: string;
+    stack: string;
+}
+/** Configuration accepted by the exported frame-error reporting helper. */
+interface SkyWalkingFrameErrorReportConfig {
+    category?: string;
+    grade?: string;
+    level?: string;
+    content?: unknown;
+    pagePath?: string;
+    pageKey?: string;
+    collector?: string;
+    serviceVersion?: string;
+    group?: string;
+    subGroup?: string;
+    extraMsg?: string | (() => string);
+    noErrorPaths?: readonly SkyWalkingUrlMatcher[];
+    hooks?: SkyWalkingHooks;
+    maxReqCostTime?: number;
+    timeout?: number;
+}
+/**
+ * Reports LiveAvatar A/V-sync incident lifecycle events through the bundled or
+ * externally provided SkyWalking client.
+ */
+declare class SkyWalkingPlugin implements SDKPlugin {
+    readonly id = "liveavatar.skywalking";
+    /** SDK Plugin API v1 is the registrar-based public plugin contract. */
+    readonly apiVersion = 1;
+    private readonly _skyWalkingConfig;
+    private _installation;
+    private _nextInstallationGeneration;
+    constructor(config?: SkyWalkingPluginConfig);
+    setup(registrar: SDKPluginRegistrar): void;
+    dispose(): void;
+    private _handleAlertNotification;
+    private _handleOperationalLog;
+    private _enqueue;
+    private _reportActiveAlert;
+    private _reportRecovery;
+    private _reportSdkError;
+    private _deactivateInstallation;
+    private _isInvocationActive;
+    private _runObserverTask;
+    private _warnInvocationFailure;
+    private _warnInvocation;
+}
+/** 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;
+/** Triggers a SkyWalking HRT report through an already registered client. */
+declare function setSkyWalkingHRT(config?: Partial<SkyWalkingPluginConfig>, customMetrics?: Record<string, unknown>): void;
+/** Reports a frame error through an already registered SkyWalking client. */
+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, SkyWalkingFrameError, SkyWalkingFrameErrorReportConfig, SkyWalkingHooks, SkyWalkingPluginConfig, SkyWalkingRegistrationOptions, SkyWalkingSdkErrorPayload, SkyWalkingSlowInteractionConfig };