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

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**: Optional `logEvent()` for precise, low-latency gameplay signals (a fixed vocabulary, or your own custom event names) alongside screenshot capture. 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,38 @@ manager.startGameSessionWithOverrides(
 
 ---
 
+## Discrete Telemetry Events
+
+Screenshot capture is the SDK's primary telemetry mechanism and covers every game automatically. `logEvent()` is an **optional, additive** layer on top of it for games that want precise, low-latency event signals alongside the vision-based scoring — it doesn't replace or interact with the screenshot loop.
+
+```typescript
+import { GameEvent } from 'skillprint-js-sdk';
+
+manager.logEvent(GameEvent.LEVEL_START);
+manager.logEvent(GameEvent.LEVEL_COMPLETE, { level: 3, score: 1200 });
+```
+
+`logEvent` is fire-and-forget: a failed request is logged as a warning and does not throw, so it can never interrupt gameplay. Calling it with no active session is a no-op (also just a warning).
+
+### Two ways to use it
+
+**1. The fixed `GameEvent` vocabulary** — recommended for most integrations. Events logged with one of these names are automatically read as a clear positive or negative signal, with nothing else to configure:
+
+| Event | Signal |
+|---|---|
+| `LEVEL_START`, `LEVEL_COMPLETE` | Positive |
+| `LEVEL_QUIT`, `LEVEL_FAILED`, `LEVEL_RESTART`, `HINT` | Negative |
+| `GENERIC_POSITIVE`, `GENERIC_NEGATIVE` | Use for anything else that's clearly good or bad for the player and doesn't fit the events above |
+
+**2. A custom event name** (any string) — for a richer, game-specific vocabulary:
+
+```typescript
+manager.logEvent('CLOCKWISE_TAP', { comboCount: 4 });
+manager.logEvent('TWO_COLORS_MATCHED', { color: 'red' });
+```
+
+Custom event names don't need to be registered in advance — send whatever your game already tracks. They're picked up by Skillprint's scoring as additional context alongside screenshots. If you want a custom event to map to a specific improvement in scoring accuracy for your game, talk to your Skillprint contact about setting up a custom scoring configuration.
+
 ## API Reference
 
 ### Core Classes
@@ -202,7 +235,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 +245,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? })`: `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