@meshstream/p2p-web 0.0.0-stage → 0.2.0

package/dist/capabilities.d.ts

@@ -0,0 +1,27 @@
+export type WebP2pProtocol = "hls" | "dash" | "mp4" | "mp3";
+export type WebP2pBrowser = "safari" | "chrome" | "firefox" | "edge" | "unknown";
+export type WebP2pOs = "ios" | "macos" | "android" | "windows" | "unknown";
+export type WebP2pUnavailableReason = "WEBRTC_UNSUPPORTED" | "MSE_UNSUPPORTED" | "SAFARI_HLS_MSE_UNSUPPORTED";
+export type WebP2pRecommendedMode = "p2p" | "cdn" | "native-hls-cdn";
+export interface WebP2pCapabilityInput {
+    protocol?: WebP2pProtocol;
+    userAgent?: string;
+    hasWebSocket?: boolean;
+    hasRtcPeerConnection?: boolean;
+    hasRtcDataChannel?: boolean;
+    hasMediaSource?: boolean;
+    hasServiceWorker?: boolean;
+    hasSecureContext?: boolean;
+}
+export interface WebP2pCapabilityResult {
+    supported: boolean;
+    recommendedMode: WebP2pRecommendedMode;
+    browser: WebP2pBrowser;
+    os: WebP2pOs;
+    reason?: WebP2pUnavailableReason;
+    mseSupported?: boolean;
+    webrtcSupported?: boolean;
+    serviceWorkerSupported?: boolean;
+    secureContext?: boolean;
+}
+export declare function detectWebP2pCapability(input?: WebP2pCapabilityInput): WebP2pCapabilityResult;

package/dist/config.d.ts

@@ -0,0 +1,100 @@
+export interface SdkTrackerNode {
+    url: string;
+    region?: string | null;
+    isp?: string | null;
+    weight?: number;
+}
+export interface SdkTrackerPoolStatus {
+    readinessCheckEnabled?: boolean;
+    totalCount?: number;
+    readyCount?: number;
+    selectedCount?: number;
+    matchedCount?: number;
+    fallbackToUnfiltered?: boolean;
+    unhealthyCount?: number;
+    degraded?: boolean;
+    selectionMode?: string;
+    preferredLocality?: string;
+}
+export interface SdkBootstrapStatus {
+    accountEnabled?: boolean;
+    applicationEnabled?: boolean;
+    keyEnabled?: boolean;
+    platformEnabled?: boolean;
+    effectiveP2pEnabled?: boolean;
+    reason?: "OK" | "APP_DISABLED" | "KEY_DISABLED" | "PLATFORM_DISABLED" | "P2P_DISABLED" | string;
+}
+export interface SdkQuotaStatus {
+    mode?: "metered" | "sponsored" | "contract-daily" | "contract-unlimited" | string;
+    status?: "available" | "exhausted" | "unlimited" | "disabled" | string;
+    source?: "gift" | "daily-plan" | "topup" | "contract" | string | null;
+    remainingBytes?: number | null;
+    resetAtMs?: number | null;
+    expiresAtMs?: number | null;
+}
+export interface SdkConfigResponse {
+    configVersion?: string;
+    appId?: string;
+    applicationId?: string;
+    /** Authoritative tenant registration/data-home region. */
+    homeRegion?: string;
+    /** Config API replica that accepted the bootstrap request. */
+    edgeRegion?: string;
+    keyId?: string;
+    keyName?: string;
+    keyEnabled?: boolean;
+    keyPlatform?: string;
+    p2pEnabled?: boolean;
+    ttlSeconds?: number;
+    refreshAfterSeconds?: number;
+    applyMode?: "next-session" | string;
+    status?: SdkBootstrapStatus;
+    quota?: SdkQuotaStatus;
+    accessUrl?: string;
+    trackerUrls: string[];
+    /** Authoritative primary selected by Config API after locality and health filtering. */
+    primaryTrackerUrl?: string;
+    iceServers?: string[];
+    trackerNodes?: SdkTrackerNode[];
+    trackerPool?: SdkTrackerPoolStatus;
+    reportUrl?: string;
+    scheduling?: {
+        homeRegion?: string | null;
+        region?: string | null;
+        country?: string | null;
+        countrySource?: string;
+    };
+    playbackAuth?: SdkPlaybackAuthPolicy;
+    defaults?: {
+        uploadSlots?: number;
+        downloadSlots?: number;
+        reportIntervalMs?: number;
+        swarmBucketCount?: number;
+        swarmBucketId?: number;
+    };
+}
+export interface SdkPlaybackAuthPolicy {
+    mode: "none" | "signed-url" | string;
+    signatureQueryKeys?: string[];
+    expiresQueryKeys?: string[];
+    clockSkewSeconds?: number;
+}
+export interface SdkConfigRequest {
+    bootstrapUrl?: string;
+    key?: string;
+    platform?: "web" | string;
+    contentId?: string;
+    expectedPeers?: number;
+}
+export interface LoadSdkConfigOptions {
+    forceRefresh?: boolean;
+    fetcher?: typeof fetch;
+    now?: () => number;
+    timeoutMs?: number;
+}
+export declare const DEFAULT_BOOTSTRAP_URL = "https://api.meshstream.net/config-api/v1/sdk/bootstrap";
+export declare const DEFAULT_BOOTSTRAP_TIMEOUT_MS = 3000;
+export declare function loadSdkConfig(request: SdkConfigRequest, options?: LoadSdkConfigOptions): Promise<SdkConfigResponse | undefined>;
+export declare function normalizeSdkConfig(config: Partial<SdkConfigResponse>): SdkConfigResponse;
+export declare function isSdkP2pConfigUsable(config: SdkConfigResponse | undefined): config is SdkConfigResponse;
+export declare function normalizeTtlSeconds(config: Pick<SdkConfigResponse, "refreshAfterSeconds" | "ttlSeconds">): number;

package/dist/dash-p2p.d.ts

@@ -0,0 +1,116 @@
+import type { WebP2pCapabilityResult } from "./capabilities.js";
+import type { SdkConfigResponse } from "./config.js";
+import { type P2pEventListener } from "./hls.js";
+import { type P2pDiagnostics, type P2pStats } from "./report.js";
+import { type OriginHeaders, type OriginHeadersProvider } from "./origin-headers.js";
+export interface DashP2pConfig {
+    shakaPlayer: ShakaPlayerLike;
+    shakaLibrary?: unknown;
+    streamUrl: string;
+    /** Shaka supports both HLS and DASH. Used for telemetry only. */
+    protocol?: "hls" | "dash";
+    contentId?: string;
+    originHeaders?: OriginHeaders;
+    originHeadersProvider?: OriginHeadersProvider;
+    sdkConfig?: Pick<SdkConfigResponse, "applicationId" | "keyId" | "reportUrl" | "trackerUrls" | "primaryTrackerUrl" | "iceServers" | "playbackAuth" | "defaults">;
+    trackerUrl?: string;
+    trackerUrls?: string[];
+    appId?: string;
+    sessionId?: string;
+    iceServers?: RTCIceServer[];
+    p2pEnabled?: boolean;
+    /** Optional integration override. `0` starts CDN requests immediately. */
+    httpDownloadInitialTimeoutMs?: number;
+    uploadSlots?: number;
+    downloadSlots?: number;
+    networkType?: string;
+    liveWindowBucket?: string;
+    capability?: WebP2pCapabilityResult;
+    sessionTokenManager?: {
+        getAuthorizationHeader(): Promise<string | undefined>;
+        diagnostics?(): {
+            attempts: number;
+            successes: number;
+            failures: number;
+            durationMs: number;
+        };
+    };
+}
+export interface ShakaPlayerLike {
+    configure?(key: string, value: unknown): void;
+    getNetworkingEngine?(): unknown;
+    getVariantTracks?(): Array<{
+        active?: boolean;
+        bandwidth?: number;
+    }>;
+    getMediaElement?(): HTMLMediaElement | null;
+    isLive?(): boolean;
+    addEventListener?(event: string, listener: EventListenerOrEventListenerObject): void;
+    removeEventListener?(event: string, listener: EventListenerOrEventListenerObject): void;
+    load(url: string): Promise<unknown>;
+    destroy?(): Promise<unknown> | void;
+}
+type PublicEvent = "peer-connect" | "peer-close" | "p2p-download" | "p2p-upload" | "http-download" | "tracker-error" | "segment-error";
+type Listener = (payload: unknown) => void;
+export declare class DashP2pClient {
+    private engine;
+    private readonly shakaPlayer;
+    private readonly shakaLibrary?;
+    private readonly engineConfig;
+    private readonly trackerCandidates;
+    private failoverInFlight;
+    private activeTrackerIndex;
+    private disposed;
+    private engineGeneration;
+    readonly swarmId: string;
+    private readonly streamUrl;
+    private readonly protocol;
+    private readonly contentId?;
+    private readonly appId?;
+    private readonly keyId?;
+    private readonly uploadSlots;
+    private readonly downloadSlots;
+    private readonly reportIntervalMs;
+    private readonly capability?;
+    private readonly reportUrl?;
+    private readonly sessionId;
+    private readonly sessionTokenManager?;
+    private readonly startedAtMs;
+    private readonly listeners;
+    private readonly eventListeners;
+    private readonly activePeers;
+    private readonly pagehideHandler;
+    private reportTimer;
+    private reportInFlight;
+    private pendingFinalReport;
+    private hasReportedContext;
+    private eventTimer;
+    private p2pEnabled;
+    private p2pReady;
+    private peerOptimizedWindows;
+    /** Remains unknown until Shaka has loaded media metadata from its manifest. */
+    private playbackIsLive;
+    private readonly mediaMetadataHandler;
+    private readonly stats;
+    private readonly diagnosticState;
+    constructor(config: DashP2pConfig);
+    on(event: PublicEvent, listener: Listener): void;
+    off(event: PublicEvent, listener: Listener): void;
+    addEventListener(listener: P2pEventListener): void;
+    removeEventListener(listener: P2pEventListener): void;
+    setP2pEnabled(enabled: boolean): void;
+    statistics(): P2pStats;
+    diagnostics(): P2pDiagnostics;
+    dispose(): void;
+    private emit;
+    private bindEvents;
+    private createEngine;
+    private failoverTracker;
+    private trackDownloadedBytes;
+    private notify;
+    private notifyPlaybackState;
+    private startStatsReporting;
+    private applyPeerOptimizedWindows;
+    private reportStats;
+}
+export {};

package/dist/dash.d.ts

@@ -0,0 +1,110 @@
+import type { WebP2pCapabilityResult } from "./capabilities.js";
+import type { LoadSdkConfigOptions, SdkConfigRequest, SdkConfigResponse } from "./config.js";
+import type { DashP2pConfig, ShakaPlayerLike } from "./dash-p2p.js";
+import { type DashJsP2pConfig } from "./dashjs-p2p.js";
+import { reportWebP2pFallback } from "./fallback.js";
+import type { P2pEventListener } from "./hls.js";
+import { type MeshStreamP2pFallbackReason } from "./player.js";
+import { type P2pDiagnostics, type P2pStats } from "./report.js";
+import { type MeshStreamQoeSnapshot } from "./qoe.js";
+import { type OriginHeaders, type OriginHeadersProvider } from "./origin-headers.js";
+export type MeshStreamDashPlaybackMode = "p2p-hls" | "p2p-dash" | "cdn-hls" | "cdn-dash" | "unsupported";
+export interface MeshStreamDashPlayerOptions {
+    url: string;
+    video: HTMLMediaElement;
+    contentId?: string;
+    mimeType?: "m3u8" | "mpd";
+    originHeaders?: OriginHeaders;
+    originHeadersProvider?: OriginHeadersProvider;
+    bootstrapUrl?: string;
+    key?: string;
+    networkType?: string;
+    liveWindowBucket?: string;
+    autoplay?: boolean;
+    p2pEnabled?: boolean;
+    iceServers?: RTCIceServer[];
+    /** Optional test/integration override. Keep zero for immediate CDN cold starts. */
+    httpDownloadInitialTimeoutMs?: number;
+    /** Existing dash.js instance. When supplied, P2P is bound through XHRLoader. */
+    dashjsInstance?: DashLike;
+    /** Existing Shaka instance. MeshStream binds P2P but never destroys it. */
+    shakaInstance?: ShakaPlayerLike;
+    dependencies?: MeshStreamDashPlayerDependencies;
+}
+export interface MeshStreamDashStartResult {
+    mode: MeshStreamDashPlaybackMode;
+    capability: WebP2pCapabilityResult;
+    sdkConfig?: SdkConfigResponse;
+    fallbackReason?: MeshStreamP2pFallbackReason;
+}
+export interface MeshStreamDashPlayerDependencies {
+    loadSdkConfig?: (request: SdkConfigRequest, options?: LoadSdkConfigOptions) => Promise<SdkConfigResponse | undefined>;
+    detectCapability?: () => WebP2pCapabilityResult;
+    createDash?: () => DashLike | Promise<DashLike>;
+    createShakaPlayer?: (video: HTMLMediaElement) => ShakaPlayerLike | Promise<ShakaPlayerLike>;
+    createCdnShakaPlayer?: () => ShakaPlayerLike | Promise<ShakaPlayerLike>;
+    createP2pClient?: (config: DashP2pConfig) => DashP2pClientLike | Promise<DashP2pClientLike>;
+    createDashJsP2pClient?: (config: DashJsP2pConfig) => DashP2pClientLike | Promise<DashP2pClientLike>;
+    reportFallback?: typeof reportWebP2pFallback;
+}
+export interface DashLike {
+    initialize(video: HTMLMediaElement, url: string, autoplay?: boolean): void;
+    extend?: (parentName: string, childInstance: (this: {
+        parent?: unknown;
+    }) => unknown, override: boolean) => void;
+    addRequestInterceptor?(interceptor: Function): void;
+    removeRequestInterceptor?(interceptor: Function): void;
+    reset?(): void;
+}
+export interface DashP2pClientLike {
+    swarmId: string;
+    addEventListener(listener: P2pEventListener): void;
+    removeEventListener(listener: P2pEventListener): void;
+    statistics(): Partial<P2pStats>;
+    diagnostics(): Partial<P2pDiagnostics>;
+    setP2pEnabled(enabled: boolean): void;
+    dispose(): void;
+}
+export declare class MeshStreamDashPlayer {
+    readonly key: string;
+    readonly url: string;
+    readonly video: HTMLMediaElement;
+    private readonly options;
+    private readonly protocol;
+    private readonly ownsShakaInstance;
+    private dash?;
+    private shaka?;
+    private p2p?;
+    private dashOriginInterceptor?;
+    private sessionTokenManager?;
+    private mode;
+    private p2pEnabledOverride?;
+    private readonly eventListeners;
+    private playbackState;
+    private readonly lifecycle;
+    private startPromise?;
+    private startResult?;
+    constructor(options: MeshStreamDashPlayerOptions);
+    get dashClient(): DashLike | undefined;
+    get shakaClient(): ShakaPlayerLike | undefined;
+    get p2pClient(): DashP2pClientLike | undefined;
+    get playbackMode(): MeshStreamDashPlaybackMode;
+    start(): Promise<MeshStreamDashStartResult>;
+    private startInternal;
+    statistics(): P2pStats;
+    diagnostics(): Partial<P2pDiagnostics>;
+    qoe(): MeshStreamQoeSnapshot;
+    setP2pEnabled(enabled: boolean): void;
+    dispose(): void;
+    private teardown;
+    private startCdnDash;
+    addEventListener(listener: P2pEventListener): () => void;
+    private startP2pDashJs;
+    private effectiveP2pEnabled;
+    private bindEventListeners;
+    private completeFallbackStart;
+    private removeEventListener;
+    private setPlaybackState;
+    private resolveQoePlaybackState;
+    private releaseShaka;
+}

package/dist/dashjs-p2p.d.ts

@@ -0,0 +1,222 @@
+import { Core, type EngineCallbacks } from "p2p-media-loader-core";
+import type { WebP2pCapabilityResult } from "./capabilities.js";
+import type { SdkConfigResponse } from "./config.js";
+import { type P2pEventListener } from "./hls.js";
+import { type OriginHeaders, type OriginHeadersProvider } from "./origin-headers.js";
+import { type P2pDiagnostics, type P2pStats } from "./report.js";
+export interface DashJsP2pConfig {
+    dashPlayer: DashJsPlayerLike;
+    /**
+     * The media element initialized by dash.js. It lets Core follow actual
+     * playback progress, which is required to schedule its first request.
+     */
+    video?: HTMLMediaElement;
+    streamUrl: string;
+    contentId?: string;
+    originHeaders?: OriginHeaders;
+    originHeadersProvider?: OriginHeadersProvider;
+    sdkConfig?: Pick<SdkConfigResponse, "applicationId" | "keyId" | "reportUrl" | "trackerUrls" | "primaryTrackerUrl" | "iceServers" | "playbackAuth" | "defaults">;
+    trackerUrl?: string;
+    trackerUrls?: string[];
+    appId?: string;
+    sessionId?: string;
+    iceServers?: RTCIceServer[];
+    p2pEnabled?: boolean;
+    httpDownloadInitialTimeoutMs?: number;
+    uploadSlots?: number;
+    downloadSlots?: number;
+    capability?: WebP2pCapabilityResult;
+    sessionTokenManager?: {
+        getAuthorizationHeader(): Promise<string | undefined>;
+        diagnostics?(): {
+            attempts: number;
+            successes: number;
+            failures: number;
+            durationMs: number;
+        };
+    };
+    /** Internal test seam; customer integrations should not supply this. */
+    dependencies?: DashJsP2pClientDependencies;
+}
+export interface DashJsP2pClientDependencies {
+    createCore?: (config: ConstructorParameters<typeof Core>[0]) => DashCoreLike;
+}
+export interface DashJsPlayerLike {
+    extend?: (parentName: string, childInstance: DashJsExtensionFactory, override: boolean) => void;
+    /** dash.js exposes the loaded MPD mode after manifest parsing. */
+    isDynamic?: () => boolean;
+}
+export interface DashJsExtensionContext {
+    parent?: DashJsXhrLoaderLike;
+}
+export type DashJsExtensionFactory = (this: DashJsExtensionContext) => DashJsXhrLoaderLike;
+export interface DashJsXhrLoaderLike {
+    load(request: DashJsCommonRequest, response: DashJsCommonResponse): boolean | void;
+    abort?(request?: DashJsCommonRequest): void;
+    getXhr?(request?: DashJsCommonRequest, response?: DashJsCommonResponse): unknown;
+    reset?(): void;
+    resetInitialSettings?(): void;
+}
+export interface DashJsCommonRequest {
+    url?: string;
+    method?: string;
+    responseType?: string;
+    credentials?: string;
+    customData?: {
+        request?: DashJsFragmentRequest;
+        abort?: () => void;
+        onloadend?: () => void;
+        onprogress?: (event: DashJsProgressEvent) => void;
+        onabort?: () => void;
+        ontimeout?: (event: DashJsProgressEvent) => void;
+    };
+}
+export interface DashJsCommonResponse {
+    url?: string;
+    status?: number;
+    statusText?: string;
+    headers?: Record<string, string>;
+    data?: ArrayBuffer;
+    resourceTiming?: {
+        responseStart?: number;
+        responseEnd?: number;
+        duration?: number;
+        encodedBodySize?: number;
+    };
+}
+export interface DashJsProgressEvent {
+    lengthComputable: boolean;
+    loaded: number;
+    total: number;
+    time?: number;
+    throughput?: number;
+    noTrace?: boolean;
+}
+export interface DashJsFragmentRequest {
+    type?: string | null;
+    mediaType?: string | null;
+    representation?: {
+        id?: string | number | null;
+        bandwidth?: number;
+        adaptation?: {
+            index?: number;
+            period?: {
+                id?: string | number | null;
+                index?: number;
+            };
+        };
+    } | null;
+    adaptationIndex?: number;
+    bandwidth?: number;
+    index?: number;
+    startTime?: number;
+    duration?: number;
+    range?: string | null;
+    isPartialSegmentRequest?: boolean;
+}
+interface DashCoreLike {
+    addEventListener(event: string, listener: (...args: any[]) => void): void;
+    addStreamIfNoneExists(stream: {
+        runtimeId: string;
+        type: "main" | "secondary";
+        index: string;
+    }): void;
+    updateStream(streamRuntimeId: string, addSegments?: Iterable<DashCoreSegment>, removeSegmentIds?: Iterable<string>): void;
+    updatePlayback(position: number, rate: number): void;
+    loadSegment(segmentRuntimeId: string, callbacks: EngineCallbacks): Promise<void>;
+    abortSegmentLoading(segmentRuntimeId: string): void;
+    setManifestResponseUrl(url: string): void;
+    setIsLive(isLive: boolean): void;
+    applyDynamicConfig(config: Record<string, unknown>): void;
+    destroy(): void;
+}
+interface DashCoreSegment {
+    runtimeId: string;
+    externalId: number;
+    url: string;
+    byteRange?: {
+        start: number;
+        end: number;
+    };
+    startTime: number;
+    endTime: number;
+}
+/**
+ * P2P transport for dash.js. It uses dash.js's documented XHRLoader extension
+ * point and leaves non-segment traffic on the customer's original loader.
+ */
+export declare class DashJsP2pClient {
+    private readonly dashPlayer;
+    private readonly config;
+    private readonly video;
+    private core;
+    private readonly trackerCandidates;
+    private readonly streamSegments;
+    private readonly listeners;
+    private readonly eventListeners;
+    private readonly activePeers;
+    private readonly sessionId;
+    private readonly streamUrl;
+    private readonly contentId?;
+    private readonly appId?;
+    private readonly keyId?;
+    private readonly uploadSlots;
+    private readonly downloadSlots;
+    /** Defaults to VOD until dash.js has parsed the MPD. */
+    private live;
+    private readonly reportIntervalMs;
+    private readonly capability?;
+    private readonly reportUrl?;
+    private readonly sessionTokenManager?;
+    private readonly startedAtMs;
+    private readonly pagehideHandler;
+    private readonly playbackHandler;
+    private readonly stats;
+    private readonly diagnosticState;
+    private activeTrackerIndex;
+    private engineGeneration;
+    private eventTimer;
+    private reportTimer;
+    private reportInFlight;
+    private pendingFinalReport;
+    private hasReportedContext;
+    private failoverInFlight;
+    private p2pEnabled;
+    private p2pReady;
+    private peerOptimizedWindows;
+    private disposed;
+    /** Remains unknown until dash.js requests its first regular media segment. */
+    private playbackIsLive;
+    readonly swarmId: string;
+    constructor(config: DashJsP2pConfig);
+    addEventListener(listener: P2pEventListener): void;
+    removeEventListener(listener: P2pEventListener): void;
+    statistics(): P2pStats;
+    diagnostics(): P2pDiagnostics;
+    setP2pEnabled(enabled: boolean): void;
+    dispose(): void;
+    private createCore;
+    private createXhrLoader;
+    private registerSegment;
+    private updateLiveMode;
+    private updatePlaybackFromMediaElement;
+    /**
+     * dash.js asks its XHR loader for the first segment before a `timeupdate`
+     * event can fire. Core otherwise keeps that initial request pending until a
+     * position change arrives. Seed it within the requested segment so normal
+     * Core scheduling, including HTTP fallback, can begin immediately.
+     */
+    private primeSegmentPlayback;
+    private bindCoreEvents;
+    private failoverTracker;
+    private isCurrentCore;
+    private applyPeerOptimizedWindows;
+    private emit;
+    private notify;
+    private notifyPlaybackState;
+    private startStatsReporting;
+    private reportStats;
+}
+/** @internal Guardrail: partial CMAF requests remain on dash.js/CDN. */
+export declare function isDashJsP2pSegment(fragment: DashJsFragmentRequest, request: DashJsCommonRequest): boolean;
+export {};

package/dist/direct-file.d.ts

@@ -0,0 +1,8 @@
+import { MeshStreamHlsPlayer, type MeshStreamHlsPlayerOptions } from "./player.js";
+/**
+ * Progressive MP4/MP3 player backed by the Service Worker transport. P2P is
+ * limited to bounded byte-range requests; all unsupported requests use CDN.
+ */
+export declare class MeshStreamDirectFilePlayer extends MeshStreamHlsPlayer {
+    constructor(options: MeshStreamHlsPlayerOptions);
+}

package/dist/fallback.d.ts

@@ -0,0 +1,35 @@
+import type { WebP2pCapabilityResult } from "./capabilities.js";
+import type { SdkConfigResponse } from "./config.js";
+import { type OriginHeaders, type OriginHeadersProvider } from "./origin-headers.js";
+export type FallbackPlaybackMode = "live" | "vod";
+export interface WebP2pFallbackReportConfig {
+    appId?: string;
+    keyId?: string;
+    streamUrl: string;
+    contentId?: string;
+    protocol?: "hls" | "dash" | "mp4" | "mp3";
+    playerType?: "hlsjs" | "shaka" | "dashjs" | "native" | string;
+    /** Applied only to the media-origin manifest probe, never to peers. */
+    originHeaders?: OriginHeaders;
+    originHeadersProvider?: OriginHeadersProvider;
+    sdkConfig?: Pick<SdkConfigResponse, "keyId" | "reportUrl" | "playbackAuth">;
+    sessionId?: string;
+    sessionToken?: string;
+    /** Internal deferred token resolver used by non-blocking player fallback telemetry. */
+    sessionTokenProvider?: () => string | undefined | Promise<string | undefined>;
+    capability: WebP2pCapabilityResult;
+}
+export interface WebP2pFallbackReportOptions {
+    fetcher?: typeof fetch;
+    /** Test/integration override for the media manifest probe. */
+    manifestFetcher?: typeof fetch;
+    manifestProbeTimeoutMs?: number;
+    sessionIdFactory?: () => string;
+}
+export declare function reportWebP2pFallback(config: WebP2pFallbackReportConfig, options?: WebP2pFallbackReportOptions): Promise<Response | undefined>;
+/**
+ * Starts fallback telemetry without delaying CDN playback. Player-owned
+ * fallback paths use this; direct callers can await reportWebP2pFallback.
+ */
+export declare function queueWebP2pFallbackReport(config: WebP2pFallbackReportConfig, options?: WebP2pFallbackReportOptions): void;
+export declare function detectFallbackPlaybackMode(config: Pick<WebP2pFallbackReportConfig, "streamUrl" | "protocol" | "originHeaders" | "originHeadersProvider">, options?: Pick<WebP2pFallbackReportOptions, "fetcher" | "manifestFetcher" | "manifestProbeTimeoutMs">): Promise<FallbackPlaybackMode | undefined>;