skillprint-js-sdk 1.1.0-beta.6 → 1.1.0-beta.8

package/README.md

@@ -14,6 +14,7 @@ A professional JavaScript & TypeScript SDK for integrating Skillprint's real-tim
 - 📸 **Automated Screenshot Capture**: Asynchronous, throttled gameplay screenshot captures for Canvas and WebGL contexts without dropping game frame rates.
 - 🔄 **Real-Time Dynamic Parameters**: Receive, convert, clamp, and apply AI-driven parameter modifications seamlessly during active sessions.
 - 🎮 **Built-In Engine Adapters**: Ready-to-use adapter wrappers for Phaser.js, Three.js, PixiJS, and Generic Canvas.
+- 📊 **Discrete Telemetry Events**: `logEvent()` for universal and game-specific gameplay events, sent with the screenshots and timestamped from session start. See [Discrete Telemetry Events](#discrete-telemetry-events).
 - 🌐 **WebGL & URL Extraction**: Automatic query parameter extraction for web deployments (`mood`, `playerId`).
 - 🧪 **100% Test Coverage Ready**: Fully tested with Vitest and jsdom.
 
@@ -188,6 +189,71 @@ manager.startGameSessionWithOverrides(
 
 ---
 
+## Discrete Telemetry Events
+
+Screenshots are the SDK's main telemetry and cover every game automatically. `logEvent()` adds discrete events: what the player did and when. Events and screenshots are both stamped with the **milliseconds since the session started**, so Skillprint can line each event up with the frames around it.
+
+```typescript
+import { GameEvent } from 'skillprint-js-sdk';
+
+manager.logEvent(GameEvent.LEVEL_START, { level: 3 });
+manager.logEvent('ROTATE_CLOCKWISE');
+manager.logEvent(GameEvent.LEVEL_COMPLETE, { level: 3, score: 1200 });
+```
+
+Events are queued and sent with the next screenshot upload, or on their own when there is no screenshot to send. `stopGameSession()` sends the rest with the closing upload, so they arrive before the session closes. `logEvent` never throws, and with no active session it only logs a warning.
+
+### Universal and game-specific events
+
+**Universal events** (`GameEvent`) mean the same thing in every game. Send the ones that apply to yours:
+
+| Event | When | Scoring signal |
+|---|---|---|
+| `GAME_START`, `GAME_END` | The game begins or ends | |
+| `GAME_PAUSE`, `GAME_RESUME` | Play is paused or resumed | |
+| `LEVEL_START`, `LEVEL_COMPLETE` | A level begins or is completed | Positive |
+| `LEVEL_QUIT`, `LEVEL_FAILED`, `LEVEL_RESTART` | A level is abandoned, lost or restarted | Negative |
+| `MATCH`, `UNMATCH` | A match is made or undone, in games built on matching | |
+| `HINT` | The player asks for a hint | Negative |
+| `GENERIC_POSITIVE`, `GENERIC_NEGATIVE` | Anything else clearly good or bad for the player | Positive / Negative |
+
+**Game-specific events** are any other name, for actions only your game has. For Hextris, for example:
+
+```typescript
+manager.logEvent('ROTATE_CLOCKWISE');
+manager.logEvent('ROTATE_ANTICLOCKWISE');
+```
+
+They don't need registering; send what your game already tracks, in `UPPER_SNAKE_CASE`. `isUniversalEvent(name)` tells the two kinds apart.
+
+Each event can carry data (`{ level: 3, score: 1200 }`). `event` and `timestamp` are set by the SDK and can't be overridden.
+
+### What is sent
+
+Each screenshot upload can carry, beside the images:
+- `offset_ms<n>`: when the n-th screenshot was captured, in ms from session start
+- `events`: a JSON array of the events since the last upload (at most 1000), e.g. `[{"event": "ROTATE_CLOCKWISE", "timestamp": 1250}]`, where `timestamp` is ms from session start
+
+### Pages that upload their own frames
+
+A page that captures its own screenshots and calls `SkillprintAPIClient` directly (see [Host mode](#skillprintapiclient)) keeps a `SessionTimeline` itself:
+
+```typescript
+import { SessionTimeline, SkillprintAPIClient } from 'skillprint-js-sdk';
+
+const timeline = new SessionTimeline();
+await client.startSession(sessionId, 'focus', null, 'hextris');
+timeline.start();
+
+const offset = timeline.offsetMs();        // when a frame is captured
+timeline.record('ROTATE_CLOCKWISE');       // when the player acts
+
+await client.postScreenshots(sessionId, [frame], false, {
+  offsetsMs: [offset],
+  events: timeline.takeEvents()
+});
+```
+
 ## API Reference
 
 ### Core Classes
@@ -202,7 +268,8 @@ manager.startGameSessionWithOverrides(
 - `static getInstance(): SkillprintManager | null`
 - `registerParameterModifier(parameterName: string, updateAction: ParameterModifierAction, expectedType?: string | null): void`
 - `startGameSession(targetMood: Mood | string, customPlayerId?: string | null): Promise<void>`
-- `stopGameSession(): void`
+- `stopGameSession(): Promise<void>` — stops capture, uploads any queued screenshots with the final batch marked `is_last_chunk` so the backend scores it and closes the session; never rejects
+- `logEvent(event: GameEvent | string, data?: Record<string, unknown>): Promise<void>` — see [Discrete Telemetry Events](#discrete-telemetry-events) below
 - `getCurrentSessionId(): string | null`
 - `getConfig(): SkillprintConfig`
 
@@ -211,6 +278,21 @@ manager.startGameSessionWithOverrides(
 - `isValid(value: unknown): boolean`
 - `convertValue(rawValue: unknown): number | boolean | string | null`
 
+#### `SkillprintAPIClient`
+The HTTP client `SkillprintManager` uses. Use it directly when your page already captures its own frames, or when you need session scores.
+- `constructor(baseUrl: string, partnerApiKey?: string, logger?: SDKLogger)`
+- `startSession(sessionId, targetMood, customPlayerId?, gameName?, gameParameters?: ParameterInfo[], options?: { deviceContext? })`
+- `postScreenshots(sessionId, screenshots: Blob[], isLastChunk?, options?: { gameStates?, inputCount?, offsetsMs?, events? })`: `offsetsMs[n]` is when the n-th screenshot was captured and `events` are the events since the last upload, both in ms from session start (see [Discrete Telemetry Events](#discrete-telemetry-events)). `gameStates[n]` (for example `{ score: 1200 }`) is sent with the n-th screenshot, and the latest `score` becomes the session's score. `inputCount` is how many player inputs the batch covers; a batch with 0 is left out of skill scores. `isLastChunk: true` scores the batch and closes the session.
+- `getSession(sessionId): Promise<SessionResult>`: the session's `state` (`OPEN`, then `CLOSED` once scored), `skillScores`, `moodScores`, `score`, `telemetry` (adjustments and logged events) and `parameterUpdates`
+- `pollParameterResults(sessionId)`: only the parameter updates
+- `getUserProfile()`: the player's skill profile; needs a player token
+- `setPlayerToken(token: string | null)`: the token of a player your page has already signed in, used when `startSession` gets no `customPlayerId`
+- `createOrGetUserToken(customPlayerId)`, `createUser(internalId)`, `getUserToken(internalId)`: need a partner key
+
+A failed call throws `SkillprintApiError`, which carries the HTTP `status` and response `body`.
+
+**Host mode.** A page on an origin the Skillprint API allows, such as the Skillprint portal, can sign its own players in and skip the partner key: pass `''` as `partnerApiKey` and call `setPlayerToken()`. The client then sends no `Api-Key`, and sends the player token on every session call. Sessions started this way belong to the player, not to a partner organization. When the token expires (a `401`), get a new one, call `setPlayerToken()` and retry.
+
 ---
 
 ## Development & Testing