@msquared/pixel-streaming-client/dist/types/client.d.ts

Browser client for viewing pixel-streamed content from MSquared events

import { type TypedEvent, TypedEventTarget } from "./events";
import { type GeforceStreamConfig } from "./gfn";
import { type SessionState, type StreamConfig } from "./session";
import type { Fetch, Logger, Token } from "./types";
/**
 * Supported streaming service providers.
 */
export declare enum StreamProvider {
    /** Use the GeForce Now streaming service via the SDK or as a Redirect */
    GeforceNow = "gdn",
    /** Use the Ubitus streaming service (currently unsupported) */
    Ubitus = "ubitus"
}
/**
 * Available stream targets.
 */
export declare enum StreamTarget {
    /** Load stream into it's own window via a full-page redirect or new tab */
    Window = 0,
    /** Embed stream into an HTML Element in the DOM */
    Embedded = 1
}
/**
 * Configuration settings for GeForce Now Digital Network.
 */
export type GDNSettings = {
    /** Client ID for authentication */
    clientId: string;
    /** Catalog client ID for content access */
    catalogClientId: string;
    /** Partner ID for service integration */
    partnerId: string;
    /** Version number for overriding the default version of GFN */
    versionNumber?: string;
};
/** Default GDN configuration settings */
export declare const DEFAULT_GDN_SETTINGS: GDNSettings;
type ClientAuth = {
    /** The bearer token or a factory to obtain one */
    token: Token;
    /** The ID of organization to authenticate against */
    organizationId?: string;
};
/**
 * Configuration options for initializing the streaming client.
 */
export type ClientOptions = {
    /** Morpheus Platform API credentials */
    auth: ClientAuth;
    /** Custom GDN settings to override defaults for testing */
    gdn?: Partial<GDNSettings>;
    /** Logger instance for debugging and monitoring */
    logger?: Logger;
    /**
     * Ignore any browser incompatibilies and attempt to load the stream in all cases
     * @default false
     */
    skipBrowserSupportChecks?: boolean;
    /**
     * Custom fetch implementation for testing.
     * @default {@link globalThis.fetch}
     */
    fetch?: Fetch;
    /**
     * MSquared server that requests will be made to
     */
    server?: {
        /**
         * Server host. May include port.
         * @default the current window's origin
         */
        host?: string;
        /**
         * Protocol.
         * @default "https"
         */
        protocol?: "http" | "https";
    };
};
/**
 * Provider-specific configuration options.
 */
export type ProviderOpts = {
    /** Streaming service provider */
    provider: StreamProvider.GeforceNow;
    /** GeForce Now specific configuration */
    config: GeforceStreamConfig;
};
/**
 * Target-specific configuration options.
 */
export type TargetOpts = {
    /** Embedded target configuration */
    target: StreamTarget.Embedded;
    /** DOM element or CSS selector for element in which to embed the stream */
    container: HTMLElement | string;
} | {
    /** Window target configuration */
    target: StreamTarget.Window;
    /**
     * The Window in which to load the stream
     * @default {@link globalThis.window}
     */
    container?: Window;
    /**
     * Whether the stream should run in fullscreen mode on load
     * @default true
     */
    fullscreen?: boolean;
};
/**
 * Configuration required to initiate a stream
 */
export type StartStreamConfig = {
    streamId: string;
    projectId: string;
    worldId: string;
    sessionId: string;
    config?: StreamConfig;
};
/**
 * Stream configuration options
 */
export type StartOptions = StartStreamConfig & ProviderOpts & TargetOpts;
/**
 * Base error class for errors returned from the StreamClient
 */
export declare class StreamingClientError extends Error {
    readonly name: string;
}
/**
 * Error produced when the element specified by the CSS selector is not found */
export declare const ElementNotFound: StreamingClientError;
/**
 * Error produced when the stream terminates unexpectedly
 */
export declare class StreamTerminationError extends StreamingClientError {
    readonly name: string;
}
/**
 * Error produced when a popup/new tab is blocked by the browser
 */
export declare const PopupBlocked: StreamingClientError;
/** Error produced when requesting a stream for an unsupported provider */
export declare const UnsupportedProvider: StreamingClientError;
/**
 * Possible states for the stream.
 */
export declare enum StreamState {
    /** Initial state, no stream active. */
    Idle = 0,
    /** Stream is being initialized and connection is being established */
    Loading = 1,
    /** Streaming is active and running */
    Streaming = 2,
    /** Stream has terminated, possibly in error */
    Terminated = 3,
    /** Stream is in an indeterminate state */
    Unknown = 4
}
/**
 * The {@link CustomEvent} emitted when the state of the stream is updated
 */
export type StreamStateUpdatedEvent = TypedEvent<"streamStateUpdated", {
    state: Exclude<StreamState, StreamState.Terminated>;
} | {
    state: StreamState.Terminated;
    error?: StreamingClientError;
}>;
/**
 * The {@link CustomEvent} emitted when the state of the session is updated
 */
export type SessionStateUpdatedEvent = TypedEvent<"sessionStateUpdated", SessionState>;
/**
 * The {@link CustomEvent} emitted when an error occurs during streaming
 */
export type StreamingClientErrorEvent = TypedEvent<"error", StreamingClientError>;
type StreamingClientEvents = [
    StreamStateUpdatedEvent,
    StreamingClientErrorEvent,
    SessionStateUpdatedEvent
];
/**
 * Main client class for managing game streaming sessions.
 * Handles stream lifecycle, state management, and error handling.
 *
 * @example
 * ```typescript
 * // Initialize client
 * const client = new StreamingClient({
 *   logger: console,
 *   gdn: { clientId: 'your-client-id' }
 * });
 *
 * // Listen for state changes
 * client.addEventListener('streamStateUpdated', (event) => {
 *   console.log('Stream state:', event.detail.state);
 * });
 *
 * // Start embedded stream
 * await client.start({
 *   provider: StreamProvider.GeforceNow,
 *   target: StreamTarget.Embedded,
 *   container: '#game-container',
 *   config: {
 *     cmsId: '12345',
 *     nonce: 'abc123'
 *   }
 * });
 * ```
 *
 * @fires {StreamStateUpdatedEvent} streamStateUpdated - Emitted when stream state changes
 * @fires {StreamingClientErrorEvent} error - Emitted when an error occurs during streaming
 *
 * @event streamStateUpdated - Fired when the stream state changes
 * Example payload:
 * ```typescript
 * {
 *   detail: {
 *     state: StreamState.Streaming
 *   }
 * }
 * ```
 *
 * @event error - Fired when a streaming error occurs
 * Example payload:
 * ```typescript
 * {
 *   detail: new StreamTerminationError("Stream terminated with error")
 * }
 * ```
 */
export declare class StreamingClient extends TypedEventTarget<StreamingClientEvents> {
    readonly skipBrowserSupportChecks: boolean;
    private readonly gdnSettings;
    private readonly logger;
    private readonly sessionClient;
    constructor(opts: ClientOptions);
    getBrowserSupport(): Record<StreamProvider, boolean>;
    setAuthToken(token: Token): void;
    setup({ projectId, worldId, forceProvider, }: {
        projectId: string;
        worldId: string;
        forceProvider?: StreamProvider;
    }): Promise<StartStreamConfig | undefined>;
    /**
     * Requests a new streaming session.
     * @param {StartOptions} options - Configuration options for the streaming session
     * @returns {Promise<Window | HTMLElement | StreamingClientError>} A Promise that resolves to the stream container or an error
     * @throws {never} This method catches all errors and returns them
     * @emits streamStateUpdated
     * @emits error
     */
    start({ streamId, projectId, worldId, sessionId, provider, ...opts }: StartOptions): Promise<Window | HTMLElement | StreamingClientError>;
    /**
     * Stops the current streaming session.
     * @returns {void | Error} Returns void if successful, or an error if the client cannot be retrieved
     * @throws {never} This method catches all errors and returns them
     */
    stop(): undefined | Error;
    /**
     * Cleans up the remote streaming session.
     * @returns {void} Returns void.
     * @param projectId The Project ID for the current project.
     * @param worldId The World ID for the current session.
     * @param sessionId The Session ID for the current session.
     * @param reason An optional reason to report as the cause of the deletion.
     * @throws {never} This method does not throw any errors.
     */
    cleanup({ projectId, worldId, sessionId, reason, }: {
        projectId: string;
        worldId: string;
        sessionId: string;
        reason?: Error | string;
    }): Promise<undefined>;
    /**
     * Opens a new window or redirects existing window for streaming.
     * @param {Object} opts - Options for opening the stream window
     * @param {Window} [opts.container] - Existing window to use
     * @param {string} opts.href - URL to load
     * @param {string} opts.target - Target window name
     * @returns {Window | typeof PopupBlocked} Window object or PopupBlocked error
     */
    private open;
}
export { GFNTerminationError } from "./gfn";
//# sourceMappingURL=client.d.ts.map