skillprint-js-sdk 1.1.0-beta.1

package/dist/index.d.mts

@@ -0,0 +1,456 @@
+/**
+ * Skillprint API environments
+ */
+declare enum ApiEnvironment {
+    PRODUCTION = "production",
+    STAGING = "staging"
+}
+/**
+ * Supported game parameter types
+ */
+declare enum ParameterType {
+    FLOAT = "Float",
+    INTEGER = "Integer",
+    BOOLEAN = "Boolean"
+}
+/**
+ * Skillprint target mood optimization categories
+ */
+declare enum Mood {
+    RELAX = "relax",
+    FOCUS = "focus",
+    CREATIVITY = "creativity",
+    COLLABORATE = "collaborate",
+    GRIT = "grit",
+    JOY = "joy",
+    CURIOSITY = "curiosity",
+    EMPATHY = "empathy",
+    AWE = "awe"
+}
+/**
+ * SDK Logger log severity levels
+ */
+declare enum LogLevel {
+    INFO = "info",
+    WARNING = "warning",
+    ERROR = "error"
+}
+
+/**
+ * Options for configuring SkillprintConfig
+ */
+interface SkillprintConfigOptions {
+    /** Unique game identifier slug registered in Skillprint */
+    gameName?: string;
+    /** Environment target: production or staging */
+    targetEnvironment?: ApiEnvironment | string;
+    /** API key for production environment */
+    productionPartnerApiKey?: string;
+    /** Base URL for production API */
+    productionApiBaseUrl?: string;
+    /** API key for staging environment */
+    stagingPartnerApiKey?: string;
+    /** Base URL for staging API */
+    stagingApiBaseUrl?: string;
+    /** List of initial game parameter definitions */
+    gameParameters?: ParameterDefinitionOptions[];
+    /** Interval in seconds between screenshot captures */
+    screenshotIntervalSeconds?: number;
+    /** Interval in seconds between posting screenshot batches */
+    screenshotPostIntervalSeconds?: number;
+    /** Interval in seconds between polling API parameter results */
+    pollResultsIntervalSeconds?: number;
+    /** Enable console log outputs for SDK operation */
+    enableDebugLogging?: boolean;
+}
+/**
+ * Options for defining a game parameter
+ */
+interface ParameterDefinitionOptions {
+    /** Unique name of the parameter */
+    parameterName?: string;
+    /** Description of what this parameter controls */
+    description?: string;
+    /** Explanation of how Skillprint modifies this parameter */
+    howSDKChangesIt?: string;
+    /** Parameter data type: FLOAT, INTEGER, or BOOLEAN */
+    type?: ParameterType | string;
+    /** Minimum allowed numerical value */
+    minValue?: number;
+    /** Maximum allowed numerical value */
+    maxValue?: number;
+    /** Default value of the parameter */
+    defaultValue?: string | number | boolean;
+}
+/**
+ * Function type for canvas provider callback
+ */
+type CanvasProvider = () => HTMLCanvasElement | null | undefined;
+/**
+ * Function type for parameter update modifier action
+ */
+type ParameterModifierAction = (value: number | boolean | string) => void;
+/**
+ * Options for capturing screenshots
+ */
+interface ScreenshotOptions {
+    /** Image MIME type format ('image/jpeg' or 'image/png') */
+    format?: string;
+    /** Image compression quality (0.0 to 1.0) */
+    quality?: number;
+    /** Maximum width to downscale image */
+    maxWidth?: number | null;
+    /** Maximum height to downscale image */
+    maxHeight?: number | null;
+}
+/**
+ * Response payload structure from parameter polling API
+ */
+interface RawParameterUpdateData {
+    parameterName?: string;
+    newValue?: number | boolean | string;
+    [key: string]: unknown;
+}
+/**
+ * Response payload structure from polling endpoint
+ */
+interface RawPollResultsData {
+    gameplayTips?: string;
+    state?: string;
+    parameterUpdates?: RawParameterUpdateData[];
+}
+/**
+ * Logger callback function signature
+ */
+type SDKLogger = (message: string, level?: LogLevel) => void;
+/**
+ * Extracted URL parameter values
+ */
+interface UrlParametersInfo {
+    targetMood: Mood | string | null;
+    playerId: string | null;
+}
+
+/**
+ * Configuration options for initializing the Skillprint SDK.
+ */
+declare class SkillprintConfig {
+    gameName: string;
+    targetEnvironment: ApiEnvironment | string;
+    productionPartnerApiKey: string;
+    productionApiBaseUrl: string;
+    stagingPartnerApiKey: string;
+    stagingApiBaseUrl: string;
+    gameParameters: ParameterDefinitionOptions[];
+    screenshotIntervalSeconds: number;
+    screenshotPostIntervalSeconds: number;
+    pollResultsIntervalSeconds: number;
+    enableDebugLogging: boolean;
+    constructor(options?: SkillprintConfigOptions);
+    /**
+     * Resolves the active partner API key based on current targetEnvironment.
+     */
+    get activePartnerApiKey(): string;
+    /**
+     * Resolves the active API base URL based on current targetEnvironment.
+     */
+    get activeApiBaseUrl(): string;
+}
+
+/**
+ * Defines a game parameter that Skillprint's AI model can modify.
+ */
+declare class ParameterDefinition {
+    parameterName: string;
+    description: string;
+    howSDKChangesIt: string;
+    type: ParameterType | string;
+    minValue: number;
+    maxValue: number;
+    defaultValue: string | number | boolean;
+    updateAction: ParameterModifierAction | null;
+    constructor(options?: ParameterDefinitionOptions);
+    /**
+     * Checks if a converted value is valid for this parameter type and range.
+     * @param value The value to validate
+     */
+    isValid(value: unknown): boolean;
+    /**
+     * Converts a raw API value into the defined type for this parameter.
+     * @param rawValue Raw incoming value from API
+     */
+    convertValue(rawValue: unknown): number | boolean | string | null;
+}
+
+/**
+ * Request payload structure for starting a game session.
+ */
+declare class StartSessionRequest {
+    sessionId: string;
+    game: string;
+    targetMood: string;
+    constructor(sessionId: string, game: string, targetMood: string);
+}
+/**
+ * Parameter info sent to Skillprint during session start.
+ */
+declare class ParameterInfo {
+    name: string;
+    type: string;
+    description: string;
+    minValue: string | null;
+    maxValue: string | null;
+    constructor(name: string, type: string, description: string, minValue?: string | null, maxValue?: string | null);
+}
+/**
+ * Result model representing a single parameter update from Skillprint API.
+ */
+declare class ParameterUpdateResult {
+    parameterName: string;
+    newValue: unknown;
+    _rawJson: string;
+    [key: string]: unknown;
+    constructor(data?: RawParameterUpdateData);
+    /**
+     * Extracts parsed new value from response payload.
+     */
+    getParsedValue(): unknown;
+    /**
+     * Converts value to target primitive type.
+     * @param targetType Target primitive type string ('number', 'integer', 'boolean', 'string')
+     */
+    convertToType(targetType: string): number | boolean | string | null;
+    /**
+     * Converts value based on parameter definition type and applies range clamping if necessary.
+     * @param paramDef Parameter definition object
+     */
+    convertToParameterType(paramDef: ParameterDefinition): number | boolean | string | null;
+}
+/**
+ * Poll results API response object.
+ */
+declare class PollResultsResponse {
+    gameplayTips: string;
+    state: string;
+    parameterUpdates: ParameterUpdateResult[];
+    constructor(data?: RawPollResultsData);
+}
+
+interface ApiCallResult<T> {
+    success: boolean;
+    data: T;
+}
+declare class SkillprintAPIClient {
+    baseUrl: string;
+    partnerApiKey: string;
+    private logger?;
+    readonly START_SESSION_ENDPOINT = "/games/api/sessions/";
+    readonly UPLOAD_SCREENSHOTS_ENDPOINT = "/games/api/record-session/{sessionId}/";
+    readonly POLL_RESULTS_ENDPOINT = "/games/api/sessions/{sessionId}/";
+    readonly CREATE_USER_ENDPOINT = "/partners/api/users/add/";
+    readonly GET_USER_TOKEN_ENDPOINT = "/partners/api/users/auth/token/";
+    constructor(baseUrl: string, partnerApiKey: string, logger?: SDKLogger);
+    /**
+     * Starts a new Skillprint session.
+     */
+    startSession(sessionId: string, targetMood: Mood | string, customPlayerId?: string | null, gameName?: string, _gameParameters?: ParameterInfo[]): Promise<ApiCallResult<string>>;
+    /**
+     * Uploads a batch of captured screenshots for an active session.
+     */
+    postScreenshots(sessionId: string, screenshots: (Blob | null)[], isLastChunk?: boolean): Promise<ApiCallResult<string>>;
+    /**
+     * Polls API for updated parameter values for the active session.
+     */
+    pollParameterResults(sessionId: string): Promise<ApiCallResult<ParameterUpdateResult[]>>;
+    /**
+     * Creates or fetches user auth token for custom player ID.
+     */
+    createOrGetUserToken(customPlayerId: string): Promise<string>;
+    /**
+     * Registers a new user with Skillprint API.
+     */
+    createUser(internalId: string): Promise<string>;
+    /**
+     * Obtains auth token for existing user internalId.
+     */
+    getUserToken(internalId: string): Promise<string>;
+}
+
+/**
+ * Utility for capturing screenshots from HTML Canvas and WebGL contexts.
+ */
+declare class ScreenshotUtility {
+    private logger?;
+    constructor(logger?: SDKLogger);
+    /**
+     * Captures a screenshot from a standard HTML canvas element as a Blob.
+     * @param canvas Target HTML Canvas element
+     * @param options Screenshot options (format, quality, max dimensions)
+     */
+    captureScreenshot(canvas: HTMLCanvasElement | null | undefined, options?: ScreenshotOptions): Promise<Blob | null>;
+    /**
+     * Alternative method for WebGL contexts that don't preserve drawing buffer.
+     * Reads pixel data directly from WebGL rendering context and flips vertically.
+     * @param gl WebGL rendering context (WebGLRenderingContext | WebGL2RenderingContext)
+     * @param canvas Target HTML Canvas element
+     * @param options Screenshot options
+     */
+    captureScreenshotWebGL(gl: WebGLRenderingContext | WebGL2RenderingContext, canvas: HTMLCanvasElement, options?: ScreenshotOptions): Promise<Blob | null>;
+}
+
+declare class WebGLUrlParameterExtractor {
+    /**
+     * Retrieves a URL query parameter by key.
+     * @param parameterName Name of the URL query parameter
+     */
+    static getUrlParameter(parameterName: string): string | null;
+    /**
+     * Gets current window URL string.
+     */
+    static getCurrentUrl(): string | null;
+    /**
+     * Extracts targetMood and playerId from URL query parameters.
+     */
+    static getSkillprintUrlParameters(): UrlParametersInfo;
+    /**
+     * Returns true if running in browser context with URL access.
+     */
+    static isUrlParameterSupported(): boolean;
+}
+/**
+ * Interface defining minimum required SkillprintManager methods for session helper
+ */
+interface ISkillprintManagerSessionTarget {
+    log(message: string, level?: LogLevel): void;
+    startGameSession(targetMood: Mood | string, playerId?: string | null): Promise<void>;
+}
+declare class SkillprintSessionHelper {
+    /**
+     * Starts a Skillprint session, attempting to auto-extract parameters from URL.
+     * @param manager SkillprintManager instance
+     * @param fallbackMood Mood to use if not found in URL
+     * @param fallbackPlayerId Player ID to use if not found in URL
+     * @param overrideMood Forced mood override
+     * @param overridePlayerId Forced player ID override
+     */
+    static startSessionWithUrlParams(manager: ISkillprintManagerSessionTarget | null | undefined, fallbackMood?: Mood | string, fallbackPlayerId?: string | null, overrideMood?: Mood | string | null, overridePlayerId?: string | null): void;
+}
+
+declare class SkillprintManager {
+    static instance: SkillprintManager | null;
+    config: SkillprintConfig;
+    canvasProvider?: CanvasProvider;
+    currentSessionId: string | null;
+    isSessionActive: boolean;
+    apiClient: SkillprintAPIClient | null;
+    screenshotUtility: ScreenshotUtility | null;
+    screenshotQueue: (Blob | null)[];
+    registeredParameters: Map<string, ParameterDefinition>;
+    private screenshotCaptureTimer;
+    private screenshotPostTimer;
+    private pollResultsTimer;
+    constructor(config: SkillprintConfig, canvasProvider?: CanvasProvider);
+    static getInstance(): SkillprintManager | null;
+    initializeSDK(): void;
+    /**
+     * Registers a modifier callback action for a named parameter.
+     * @param parameterName Unique parameter identifier
+     * @param updateAction Callback invoked when Skillprint modifies this parameter
+     * @param expectedType Optional type check string ('number', 'integer', 'boolean')
+     */
+    registerParameterModifier(parameterName: string, updateAction: ParameterModifierAction, expectedType?: string | null): void;
+    /**
+     * Starts a new Skillprint AI gameplay session.
+     * @param targetMood Target optimization mood category
+     * @param customPlayerId Optional external player identifier
+     */
+    startGameSession(targetMood: Mood | string, customPlayerId?: string | null): Promise<void>;
+    /**
+     * Stops the active Skillprint session and clears all loop timers.
+     */
+    stopGameSession(): void;
+    private startScreenshotCaptureLoop;
+    private startScreenshotPostLoop;
+    private startPollResultsLoop;
+    applyParameterUpdates(updates: ParameterUpdateResult[]): void;
+    generateSessionId(): string;
+    log(message: string, level?: LogLevel): void;
+    getCurrentSessionId(): string | null;
+    getConfig(): SkillprintConfig;
+    startGameSessionFromUrl(fallbackMood?: Mood | string, fallbackPlayerId?: string | null): void;
+    startGameSessionWithOverrides(fallbackMood?: Mood | string, fallbackPlayerId?: string | null, overrideMood?: Mood | string | null, overridePlayerId?: string | null): void;
+    getUrlParametersInfo(): string;
+}
+
+/** Minimal interface representing Phaser Scene & Game */
+interface PhaserSceneLike {
+    game: {
+        canvas: HTMLCanvasElement;
+    };
+}
+declare class PhaserSkillprintAdapter {
+    scene: PhaserSceneLike;
+    config: SkillprintConfig;
+    manager: SkillprintManager;
+    constructor(scene: PhaserSceneLike, config: SkillprintConfig);
+    static create(scene: PhaserSceneLike, config: SkillprintConfig): PhaserSkillprintAdapter;
+    startSession(targetMood: Mood | string, customPlayerId?: string | null): Promise<void>;
+    stopSession(): void;
+    registerParameter(parameterName: string, updateAction: ParameterModifierAction, expectedType?: string | null): void;
+    /**
+     * Phaser-specific helper to register sprite property updates directly.
+     */
+    registerSpriteProperty(parameterName: string, sprite: Record<string, unknown>, propertyName: string): void;
+}
+
+/** Minimal interface representing Three.js WebGLRenderer */
+interface ThreeRendererLike {
+    domElement: HTMLCanvasElement;
+}
+declare class ThreeSkillprintAdapter {
+    renderer: ThreeRendererLike;
+    config: SkillprintConfig;
+    manager: SkillprintManager;
+    constructor(renderer: ThreeRendererLike, config: SkillprintConfig);
+    static create(renderer: ThreeRendererLike, config: SkillprintConfig): ThreeSkillprintAdapter;
+    startSession(targetMood: Mood | string, customPlayerId?: string | null): Promise<void>;
+    stopSession(): void;
+    registerParameter(parameterName: string, updateAction: ParameterModifierAction, expectedType?: string | null): void;
+    /**
+     * Three.js-specific helper to register object or nested material property updates.
+     */
+    registerObjectProperty(parameterName: string, object: Record<string, any>, propertyName: string): void;
+}
+
+/** Minimal interface representing PixiJS Application */
+interface PixiApplicationLike {
+    view?: HTMLCanvasElement;
+    canvas?: HTMLCanvasElement;
+}
+declare class PixiSkillprintAdapter {
+    app: PixiApplicationLike;
+    config: SkillprintConfig;
+    manager: SkillprintManager;
+    constructor(app: PixiApplicationLike, config: SkillprintConfig);
+    static create(app: PixiApplicationLike, config: SkillprintConfig): PixiSkillprintAdapter;
+    startSession(targetMood: Mood | string, customPlayerId?: string | null): Promise<void>;
+    stopSession(): void;
+    registerParameter(parameterName: string, updateAction: ParameterModifierAction, expectedType?: string | null): void;
+    /**
+     * PixiJS-specific helper to register display object property updates.
+     */
+    registerDisplayObjectProperty(parameterName: string, displayObject: Record<string, any>, propertyName: string): void;
+}
+
+declare class GenericCanvasSkillprintAdapter {
+    canvas: HTMLCanvasElement;
+    config: SkillprintConfig;
+    manager: SkillprintManager;
+    constructor(canvas: HTMLCanvasElement, config: SkillprintConfig);
+    static create(canvas: HTMLCanvasElement, config: SkillprintConfig): GenericCanvasSkillprintAdapter;
+    startSession(targetMood: Mood | string, customPlayerId?: string | null): Promise<void>;
+    stopSession(): void;
+    registerParameter(parameterName: string, updateAction: ParameterModifierAction, expectedType?: string | null): void;
+}
+
+export { ApiEnvironment, type CanvasProvider, GenericCanvasSkillprintAdapter, LogLevel, Mood, ParameterDefinition, type ParameterDefinitionOptions, ParameterInfo, type ParameterModifierAction, ParameterType, ParameterUpdateResult, PhaserSkillprintAdapter, PixiSkillprintAdapter, PollResultsResponse, type RawParameterUpdateData, type RawPollResultsData, type SDKLogger, type ScreenshotOptions, ScreenshotUtility, SkillprintAPIClient, SkillprintConfig, type SkillprintConfigOptions, SkillprintManager, SkillprintSessionHelper, StartSessionRequest, ThreeSkillprintAdapter, type UrlParametersInfo, WebGLUrlParameterExtractor };