@arcware-cloud/pixelstreaming-websdk 1.2.16 → 1.2.18

package/types/lib/DiagnosticsCollector.d.ts

@@ -0,0 +1,181 @@
+/**
+ * DiagnosticsCollector.ts
+ * Lightweight, privacy-aware client diagnostics for troubleshooting + analytics.
+ * WebRTC collection intentionally omitted (to add later).
+ *
+ * Notes:
+ * - Some fields are best-effort due to browser restrictions; they're nullable.
+ * - Bandwidth probe requires a small binary served with:
+ *     Content-Type: application/octet-stream
+ *     Content-Encoding: identity
+ *     Cache-Control: no-store
+ *   Default location: /diag/probe.bin
+ */
+/**
+ * These interfaces need to be copied manually from ITicket.ts for now if the interface changes there
+ * The way how webpack, rollup and this whole mono repo is setup up, I cannot just import it......
+ */
+export interface IDiagnostics {
+    device?: Device;
+    network?: Network;
+    powerHints?: PowerHints;
+    runtime?: Runtime;
+    timestamps?: Timestamps;
+    webrtc?: Webrtc;
+}
+export interface Device {
+    architecture?: null | string;
+    bitness?: null | string;
+    codecs?: Codecs;
+    deviceMemory?: number | null;
+    hardwareConcurrency?: number | null;
+    model?: null | string;
+    orientation?: Orientation | null;
+    touchSupport?: boolean;
+    type?: Type;
+    vendor?: null | string;
+    webgl?: boolean | null;
+}
+export interface Codecs {
+    h264?: boolean;
+    hevc?: boolean;
+}
+export declare enum Orientation {
+    Landscape = "landscape",
+    Portrait = "portrait"
+}
+export declare enum Type {
+    Desktop = "desktop",
+    Mobile = "mobile",
+    Tablet = "tablet"
+}
+export interface Network {
+    downlinkMbps?: number | null;
+    effectiveType?: null | string;
+    measuredDownlinkMbps?: number | null;
+    rttMs?: number | null;
+    type?: null | string;
+}
+export interface PowerHints {
+    prefersReducedData?: boolean | null;
+    prefersReducedMotion?: boolean | null;
+    saveData?: boolean | null;
+}
+export interface Runtime {
+    browser?: Browser;
+    os?: OS;
+}
+export interface Browser {
+    family?: string;
+    version?: null | string;
+}
+export interface OS {
+    family?: string;
+    version?: null | string;
+}
+export interface Timestamps {
+    collectedAt?: number;
+}
+export interface Webrtc {
+    candidatePairId?: null | string;
+    dtlsCipher?: null | string;
+    localCandidateType?: null | string;
+    networkType?: null | string;
+    protocol?: null | string;
+    remoteCandidateType?: null | string;
+}
+/**
+ * Options that control how the DiagnosticsCollector behaves.
+ *
+ * You don’t *need* to set these for a basic Pixel Streaming website — the defaults
+ * are good enough. But in production, these knobs let you control cost, UX impact,
+ * and flexibility without changing the code.
+ */
+export interface DiagnosticsCollectorOptions {
+    /**
+     * Run a synthetic bandwidth probe? (default: true)
+     *
+     * - When true: the collector fetches a small binary file (see `probeUrl`)
+     *   and measures download speed to estimate available bandwidth.
+     * - Why it matters: gives you a ground-truth Mbps measurement that the
+     *   browser doesn’t always expose.
+     * - Downsides: adds one extra network request per session.
+     * - When to disable: if you want *zero* extra traffic (e.g. privacy-sensitive
+     *   deployments, embedded use cases).
+     */
+    enableBandwidthProbe?: boolean;
+    /**
+     * URL of the probe file used for bandwidth measurement. (default: "/diag/probe.bin")
+     *
+     * - Must be served as raw binary with headers:
+     *     Content-Type: application/octet-stream
+     *     Content-Encoding: identity
+     *     Cache-Control: no-store
+     * - Size: keep small (200–500 KB) for quick, accurate tests.
+     * - Why you’d override: if you host assets on a CDN or want different probe
+     *   files per region/environment.
+     */
+    probeUrl?: string;
+    /**
+     * Respect the user’s "Data Saver" mode? (default: true)
+     *
+     * - The browser exposes `navigator.connection.saveData`.
+     * - When true: if saveData === true, the collector skips the bandwidth probe
+     *   (to avoid wasting data).
+     * - Why it matters: good UX and respectful to users on metered/limited data.
+     * - When to disable: if accurate bandwidth numbers are critical even for
+     *   Data Saver users (rare).
+     */
+    respectSaveData?: boolean;
+    /**
+     * Sampling rate for diagnostics collection. (range: 0.0–1.0, default: 1.0)
+     *
+     * - 1.0 (100%): collect diagnostics for every session (ideal in dev/beta).
+     * - 0.1 (10%): collect for ~10% of sessions (reduces storage & processing costs).
+     * - Why it matters: in production, detailed telemetry from *every* session
+     *   may be too costly or noisy. Sampling still gives you trends.
+     * - How it works: collector rolls a random number per session; only collects
+     *   if value < sampleRate.
+     */
+    sampleRate?: number;
+}
+/**
+ * DiagnosticsCollector
+ */
+export declare class DiagnosticsCollector {
+    private opts;
+    constructor(opts?: DiagnosticsCollectorOptions);
+    /**
+     * Collect the diagnostics payload.
+     */
+    collect(): Promise<IDiagnostics>;
+    /**
+     * Collect a safe subset of WebRTC stats once PC is connected.
+     */
+    collectWebRTC(pc: RTCPeerConnection): Promise<IDiagnostics["webrtc"]>;
+    /**
+     * Helper to embed diagnostics in a hello envelope.
+     */
+    buildHelloEnvelope(base: Record<string, any>, pc?: RTCPeerConnection): Promise<{
+        ext: {
+            diag: IDiagnostics;
+        };
+    }>;
+    private shouldSample;
+    private hasTouch;
+    private getOrientation;
+    private hasWebGL;
+    /**
+     * Heuristic device type: best-effort only.
+     * Tries UA-CH, then UA fallback, then touch + screen size heuristics.
+     */
+    private inferDeviceType;
+    private getPowerHints;
+    private getNetworkInfo;
+    private maybeMeasureBandwidth;
+    private withCacheBuster;
+    private getCodecSupport;
+    private supportsCodec;
+    private uaInfoCache;
+    private getUAInfo;
+}

package/types/lib/MessageTypes.d.ts

@@ -0,0 +1,4 @@
+import { Messages } from "@arcware-cloud/shared-pixelstreaming-websdk";
+export type ErrorMessage = Messages.ErrorMessage;
+export type Queue = Messages.Queue;
+export type LoveLetter = Messages.LoveLetter;

package/types/lib/domain/ArcwareSettingsSchema.d.ts

@@ -0,0 +1,209 @@
+import { z } from "zod";
+/** Arcware Settings. */
+export declare const ArcwareSettingsSchema: z.ZodObject<{
+    /** Overwrites the Session-Tool and uses the provided session instead. */
+    session: z.ZodOptional<z.ZodString>;
+    /** Can be used to be added to the request in order to verify access to private projects.
+     * For internal use only. => Preview page.
+     */
+    token: z.ZodOptional<z.ZodString>;
+    /** @deprecated in there for legacy use. Can only be used when token is provided. */
+    bypass: z.ZodOptional<z.ZodBoolean>;
+    /** Handler for server side error messages. */
+    errorHandler: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodObject<{
+        type: z.ZodLiteral<"error">;
+        code: z.ZodNumber;
+        reason: z.ZodString;
+        verbosity: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        type?: "error";
+        code?: number;
+        reason?: string;
+        verbosity?: number;
+    }, {
+        type?: "error";
+        code?: number;
+        reason?: string;
+        verbosity?: number;
+    }>], z.ZodUnknown>, z.ZodVoid>>;
+    /** Handler for queue events. */
+    queueHandler: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodObject<{
+        type: z.ZodLiteral<"queue">;
+        queue: z.ZodObject<{
+            index: z.ZodOptional<z.ZodNumber>;
+            /** Can be used to be added to the request in order to verify access to private projects.
+             * For internal use only. => Preview page.
+             */
+            queueLength: z.ZodOptional<z.ZodNumber>;
+            waited: z.ZodOptional<z.ZodNumber>;
+            estimatedWaitTime: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+            averageWaitTime: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+            valueType: z.ZodEnum<["milliseconds", "seconds", "minutes", "hours", "days"]>;
+        }, "strip", z.ZodTypeAny, {
+            index?: number;
+            queueLength?: number;
+            waited?: number;
+            estimatedWaitTime?: number;
+            averageWaitTime?: number;
+            valueType?: "milliseconds" | "seconds" | "minutes" | "hours" | "days";
+        }, {
+            index?: number;
+            queueLength?: number;
+            waited?: number;
+            estimatedWaitTime?: number;
+            averageWaitTime?: number;
+            valueType?: "milliseconds" | "seconds" | "minutes" | "hours" | "days";
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        type?: "queue";
+        queue?: {
+            index?: number;
+            queueLength?: number;
+            waited?: number;
+            estimatedWaitTime?: number;
+            averageWaitTime?: number;
+            valueType?: "milliseconds" | "seconds" | "minutes" | "hours" | "days";
+        };
+    }, {
+        type?: "queue";
+        queue?: {
+            index?: number;
+            queueLength?: number;
+            waited?: number;
+            estimatedWaitTime?: number;
+            averageWaitTime?: number;
+            valueType?: "milliseconds" | "seconds" | "minutes" | "hours" | "days";
+        };
+    }>], z.ZodUnknown>, z.ZodVoid>>;
+    /** Handler for sessionId message. */
+    sessionIdHandler: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodString], z.ZodUnknown>, z.ZodVoid>>;
+    /** Handler for love letters.
+     * "LoveLetters" are send from backend to the SDK to state what phase the connection currently is in. */
+    loveLetterHandler: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodObject<{
+        type: z.ZodLiteral<"letter">;
+        reason: z.ZodString;
+        code: z.ZodNumber;
+        verbosity: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        type?: "letter";
+        reason?: string;
+        code?: number;
+        verbosity?: number;
+    }, {
+        type?: "letter";
+        reason?: string;
+        code?: number;
+        verbosity?: number;
+    }>], z.ZodUnknown>, z.ZodVoid>>;
+    /** Show or hide the fullscreen button. */
+    fullscreenButton: z.ZodOptional<z.ZodBoolean>;
+    /** Show or hide the settings button. */
+    settingsButton: z.ZodOptional<z.ZodBoolean>;
+    /** Show or hide the info button. */
+    infoButton: z.ZodOptional<z.ZodBoolean>;
+    /** Show or hide the audio button. */
+    audioButton: z.ZodOptional<z.ZodBoolean>;
+    /** Show or hide the microphone button. */
+    micButton: z.ZodOptional<z.ZodBoolean>;
+    /** Show or hide the microphone button. */
+    stopButton: z.ZodOptional<z.ZodBoolean>;
+    /** Show or hide the connectionStrengthIcon button. */
+    connectionStrengthIcon: z.ZodOptional<z.ZodBoolean>;
+    /** ShareId, used for sharing your project.
+     * Using ArcwareInit will set this required property for you. */
+    shareId: z.ZodOptional<z.ZodString>;
+    /** Id of your project, only required if your shareId refers to multiple projects.
+     * Using ArcwareInit will set this required property for you. */
+    projectId: z.ZodOptional<z.ZodString>;
+    /** Enable/Disable LoveLetter logging to the console. */
+    loveLetterLogging: z.ZodOptional<z.ZodBoolean>;
+    /** Enable/Disable Connection Identifier logging to the console. */
+    connectionIdentifierLoggingDisabled: z.ZodOptional<z.ZodBoolean>;
+    /** Width with which instance should be started */
+    startWidth: z.ZodOptional<z.ZodNumber>;
+    /** Height with which instance should be started */
+    startHeight: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    session?: string;
+    token?: string;
+    bypass?: boolean;
+    errorHandler?: (args_0: {
+        type?: "error";
+        code?: number;
+        reason?: string;
+        verbosity?: number;
+    }, ...args_1: unknown[]) => void;
+    queueHandler?: (args_0: {
+        type?: "queue";
+        queue?: {
+            index?: number;
+            queueLength?: number;
+            waited?: number;
+            estimatedWaitTime?: number;
+            averageWaitTime?: number;
+            valueType?: "milliseconds" | "seconds" | "minutes" | "hours" | "days";
+        };
+    }, ...args_1: unknown[]) => void;
+    sessionIdHandler?: (args_0: string, ...args_1: unknown[]) => void;
+    loveLetterHandler?: (args_0: {
+        type?: "letter";
+        reason?: string;
+        code?: number;
+        verbosity?: number;
+    }, ...args_1: unknown[]) => void;
+    fullscreenButton?: boolean;
+    settingsButton?: boolean;
+    infoButton?: boolean;
+    audioButton?: boolean;
+    micButton?: boolean;
+    stopButton?: boolean;
+    connectionStrengthIcon?: boolean;
+    shareId?: string;
+    projectId?: string;
+    loveLetterLogging?: boolean;
+    connectionIdentifierLoggingDisabled?: boolean;
+    startWidth?: number;
+    startHeight?: number;
+}, {
+    session?: string;
+    token?: string;
+    bypass?: boolean;
+    errorHandler?: (args_0: {
+        type?: "error";
+        code?: number;
+        reason?: string;
+        verbosity?: number;
+    }, ...args_1: unknown[]) => void;
+    queueHandler?: (args_0: {
+        type?: "queue";
+        queue?: {
+            index?: number;
+            queueLength?: number;
+            waited?: number;
+            estimatedWaitTime?: number;
+            averageWaitTime?: number;
+            valueType?: "milliseconds" | "seconds" | "minutes" | "hours" | "days";
+        };
+    }, ...args_1: unknown[]) => void;
+    sessionIdHandler?: (args_0: string, ...args_1: unknown[]) => void;
+    loveLetterHandler?: (args_0: {
+        type?: "letter";
+        reason?: string;
+        code?: number;
+        verbosity?: number;
+    }, ...args_1: unknown[]) => void;
+    fullscreenButton?: boolean;
+    settingsButton?: boolean;
+    infoButton?: boolean;
+    audioButton?: boolean;
+    micButton?: boolean;
+    stopButton?: boolean;
+    connectionStrengthIcon?: boolean;
+    shareId?: string;
+    projectId?: string;
+    loveLetterLogging?: boolean;
+    connectionIdentifierLoggingDisabled?: boolean;
+    startWidth?: number;
+    startHeight?: number;
+}>;
+export type Settings = z.infer<typeof ArcwareSettingsSchema>;

package/types/lib/domain/ConnectionIdentifier.d.ts

@@ -0,0 +1,27 @@
+import { ArcwarePixelStreaming } from "../ArcwarePixelStreaming";
+export declare enum WebsocketState {
+    CONNECTING = 0,
+    OPEN = 1,
+    CLOSING = 2,
+    CLOSED = 3
+}
+export declare class ConnectionIdentifier {
+    private static instance;
+    static get Instance(): ConnectionIdentifier;
+    private interval;
+    private aps;
+    get WebsocketStates(): WebsocketState[];
+    private constructor();
+    register(ps: ArcwarePixelStreaming): void;
+    GetWebSocketStates(): WebsocketState[];
+    ActiveInstances(): number;
+    private enabled;
+    disable(): void;
+    /**
+     * The purpose of this method is to periodically tell the developer the amount of connected instances.
+     * This way the developer can figure out, when they messed up the implementation and there's shadow instances still running.
+     * Or when they accidentally set up multiple connections!
+     * Things like that can happen, for example if the React.useEffect was not setup perfectly!
+     */
+    private connectionWatcher;
+}

package/types/lib/domain/EventHandler.d.ts

@@ -0,0 +1,11 @@
+/** A helper class to spread the event to additional event handlers added from external sources. */
+export declare class EventHandler<Type> {
+    private callbacks;
+    /** Returns the added callback on success or null, if something went wrong. */
+    add<Callback extends (arg: Type) => void>(callback: Callback): Callback | null;
+    /** Returns true if the input callback has been found and removed and false if not. */
+    remove<Callback extends (arg: Type) => void>(callback: Callback): boolean;
+    constructor();
+    /** Emits the event-data for each of the existing handlers. */
+    static Emit<Type>(handler: EventHandler<Type>, event: Type): void;
+}

package/types/lib/domain/Session.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+declare const ZOptions: z.ZodObject<{
+    localStorageKey: z.ZodDefault<z.ZodString>;
+    keepSession: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    localStorageKey?: string;
+    keepSession?: number;
+}, {
+    localStorageKey?: string;
+    keepSession?: number;
+}>;
+type Options = z.infer<typeof ZOptions>;
+/** The sessionId is stored in the localStorage to allow for reconnection and
+ * to prevent spamming start requests of instances, when smashing F5.
+ */
+export declare class Session {
+    private _current?;
+    get current(): string;
+    get noSession(): boolean;
+    get id(): string | null;
+    private options;
+    private get localStorageKey();
+    constructor(options?: Options);
+    /** Set's the session with creation date for the given storage key to the localStorage. */
+    set(sessionId: string): void;
+    /** Removes a session from the localStorage. */
+    unset(): void;
+}
+export {};

package/types/lib/domain/Stats.d.ts

@@ -0,0 +1,36 @@
+import { AggregatedStats, CandidatePairStats } from "@epicgames-ps/lib-pixelstreamingfrontend-ue5.5";
+export declare function Stats(stats: AggregatedStats): import("zod").objectOutputType<{
+    codecs: import("zod").ZodOptional<import("zod").ZodType<Map<string, import("@epicgames-ps/lib-pixelstreamingfrontend-ue5.5/dist/types/PeerConnectionController/CodecStats").CodecStats>, import("zod").ZodTypeDef, Map<string, import("@epicgames-ps/lib-pixelstreamingfrontend-ue5.5/dist/types/PeerConnectionController/CodecStats").CodecStats>>>;
+    candidatePair: import("zod").ZodOptional<import("zod").ZodType<CandidatePairStats[], import("zod").ZodTypeDef, CandidatePairStats[]>>;
+    localCandidates: import("zod").ZodOptional<import("zod").ZodType<import("@epicgames-ps/lib-pixelstreamingfrontend-ue5.5").CandidateStat[], import("zod").ZodTypeDef, import("@epicgames-ps/lib-pixelstreamingfrontend-ue5.5").CandidateStat[]>>;
+    remoteCandidates: import("zod").ZodOptional<import("zod").ZodType<import("@epicgames-ps/lib-pixelstreamingfrontend-ue5.5").CandidateStat[], import("zod").ZodTypeDef, import("@epicgames-ps/lib-pixelstreamingfrontend-ue5.5").CandidateStat[]>>;
+    DataChannelStats: import("zod").ZodOptional<import("zod").ZodType<import("@epicgames-ps/lib-pixelstreamingfrontend-ue5.5").DataChannelStats, import("zod").ZodTypeDef, import("@epicgames-ps/lib-pixelstreamingfrontend-ue5.5").DataChannelStats>>;
+    bytesReceived: import("zod").ZodOptional<import("zod").ZodNumber>;
+    packetsLost: import("zod").ZodOptional<import("zod").ZodNumber>;
+    frameWidth: import("zod").ZodOptional<import("zod").ZodNumber>;
+    frameHeight: import("zod").ZodOptional<import("zod").ZodNumber>;
+    framesDecoded: import("zod").ZodOptional<import("zod").ZodNumber>;
+    framesPerSecond: import("zod").ZodOptional<import("zod").ZodNumber>;
+    framesDropped: import("zod").ZodOptional<import("zod").ZodNumber>;
+    videoCodec: import("zod").ZodOptional<import("zod").ZodString>;
+    audioCodec: import("zod").ZodOptional<import("zod").ZodString>;
+    browserInfo: import("zod").ZodOptional<import("zod").ZodObject<{
+        userAgent: import("zod").ZodOptional<import("zod").ZodString>;
+        platform: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
+        language: import("zod").ZodOptional<import("zod").ZodString>;
+    }, "passthrough", import("zod").ZodTypeAny, import("zod").objectOutputType<{
+        userAgent: import("zod").ZodOptional<import("zod").ZodString>;
+        platform: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
+        language: import("zod").ZodOptional<import("zod").ZodString>;
+    }, import("zod").ZodTypeAny, "passthrough">, import("zod").objectInputType<{
+        userAgent: import("zod").ZodOptional<import("zod").ZodString>;
+        platform: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
+        language: import("zod").ZodOptional<import("zod").ZodString>;
+    }, import("zod").ZodTypeAny, "passthrough">>>;
+    currentRTT: import("zod").ZodOptional<import("zod").ZodNumber>;
+    sessionRunTime: import("zod").ZodOptional<import("zod").ZodString>;
+    controlsStreamInput: import("zod").ZodOptional<import("zod").ZodEffects<import("zod").ZodString, string, string>>;
+    videoEncoderAvgQP: import("zod").ZodOptional<import("zod").ZodNumber>;
+    videoBitrate: import("zod").ZodOptional<import("zod").ZodNumber>;
+    audioBitrate: import("zod").ZodOptional<import("zod").ZodNumber>;
+}, import("zod").ZodTypeAny, "passthrough">;

package/types/lib/domain/debounce.d.ts

@@ -0,0 +1 @@
+export default function debounce<T extends (...args: any[]) => void>(func: T, wait: number): (...args: Parameters<T>) => void;

package/types/lib/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./ArcwareApplication";
+export * from "./ArcwareConfig";
+export * from "./ArcwarePixelStreaming";
+export * from "./ArcwareInit";
+export type * from "./MessageTypes";
+export * from "./styles/ArcwarePixelStreamingApplicationStyles";