skillprint-js-sdk 1.1.0-beta.1

package/README.md

@@ -0,0 +1,265 @@
+# Skillprint JavaScript & TypeScript SDK
+
+[![npm version](https://img.shields.io/npm/v/skillprint-js-sdk.svg?style=flat-square)](https://www.npmjs.com/package/skillprint-js-sdk)
+[![license](https://img.shields.io/npm/l/skillprint-js-sdk.svg?style=flat-square)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg?style=flat-square)](https://www.typescriptlang.org/)
+
+A professional JavaScript & TypeScript SDK for integrating Skillprint's real-time AI gameplay adjustment engine into web games. Compatible with popular game engines including **Phaser.js**, **Three.js**, **PixiJS**, **Babylon.js**, and **Generic HTML5 Canvas** applications.
+
+---
+
+## Key Features
+
+- ⚡ **Dual JS & TS Support**: Native TypeScript types with `.d.ts` declarations, ESM (`.js`), CommonJS (`.cjs`), and Browser CDN (`.global.js`) builds.
+- 📸 **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.
+- 🌐 **WebGL & URL Extraction**: Automatic query parameter extraction for web deployments (`mood`, `playerId`).
+- 🧪 **100% Test Coverage Ready**: Fully tested with Vitest and jsdom.
+
+---
+
+## Installation
+
+### NPM (Recommended for TypeScript & Bundlers)
+
+```bash
+npm install skillprint-js-sdk
+```
+
+### Browser CDN (Vanilla JavaScript)
+
+```html
+<!-- ES Module Import -->
+<script type="module">
+  import { SkillprintManager, SkillprintConfig, Mood } from 'https://cdn.jsdelivr.net/npm/skillprint-js-sdk/dist/index.js';
+</script>
+
+<!-- Script Tag Global (UMD/IIFE) -->
+<script src="https://cdn.jsdelivr.net/npm/skillprint-js-sdk/dist/index.global.js"></script>
+<script>
+  const { SkillprintManager, SkillprintConfig, Mood } = window.SkillprintSDK;
+</script>
+```
+
+---
+
+## Quick Start
+
+### TypeScript / ES Modules Usage
+
+```typescript
+import { 
+  SkillprintConfig, 
+  SkillprintManager, 
+  ParameterDefinition, 
+  ParameterType, 
+  Mood 
+} from 'skillprint-js-sdk';
+
+// 1. Configure the SDK
+const config = new SkillprintConfig({
+  gameName: 'my-awesome-game',
+  targetEnvironment: 'production',
+  productionPartnerApiKey: 'YOUR_PARTNER_API_KEY',
+  enableDebugLogging: true,
+  gameParameters: [
+    new ParameterDefinition({
+      parameterName: 'difficulty',
+      description: 'Game difficulty factor',
+      type: ParameterType.FLOAT,
+      minValue: 0.5,
+      maxValue: 2.0,
+      defaultValue: 1.0
+    })
+  ]
+});
+
+// 2. Initialize Manager with canvas provider
+const canvasProvider = () => document.getElementById('gameCanvas') as HTMLCanvasElement;
+const manager = new SkillprintManager(config, canvasProvider);
+
+// 3. Register parameter update handler
+manager.registerParameterModifier('difficulty', (newValue) => {
+  console.log(`AI adjusted difficulty to: ${newValue}`);
+  // Apply newValue (typed as number | boolean | string) to your game engine
+});
+
+// 4. Start AI session
+manager.startGameSession(Mood.FOCUS, 'player_123');
+```
+
+### CommonJS (Node / Older Bundlers)
+
+```javascript
+const { SkillprintConfig, SkillprintManager, Mood } = require('skillprint-js-sdk');
+
+const config = new SkillprintConfig({
+  gameName: 'my-awesome-game',
+  productionPartnerApiKey: 'YOUR_PARTNER_API_KEY'
+});
+
+const manager = new SkillprintManager(config, () => document.getElementById('gameCanvas'));
+manager.startGameSession(Mood.RELAX);
+```
+
+---
+
+## Game Engine Integrations
+
+### 1. Phaser.js
+
+```typescript
+import { PhaserSkillprintAdapter, SkillprintConfig, Mood } from 'skillprint-js-sdk';
+
+class MainScene extends Phaser.Scene {
+  private skillprint!: PhaserSkillprintAdapter;
+  private enemySpeed = 5;
+
+  create() {
+    const config = new SkillprintConfig({
+      gameName: 'phaser-space-shooter',
+      productionPartnerApiKey: 'YOUR_API_KEY'
+    });
+
+    // Pass Phaser scene context
+    this.skillprint = PhaserSkillprintAdapter.create(this, config);
+
+    // Register custom parameter update handler
+    this.skillprint.registerParameter('enemySpeed', (value) => {
+      this.enemySpeed = Number(value);
+    });
+
+    // Start session
+    this.skillprint.startSession(Mood.FOCUS);
+  }
+}
+```
+
+### 2. Three.js
+
+```typescript
+import { ThreeSkillprintAdapter, SkillprintConfig, Mood } from 'skillprint-js-sdk';
+
+// Pass Three.js WebGLRenderer instance
+const skillprint = ThreeSkillprintAdapter.create(renderer, config);
+
+// Bind target object property directly
+skillprint.registerObjectProperty('lightIntensity', directionalLight, 'intensity');
+skillprint.registerObjectProperty('fogDensity', scene.fog, 'density');
+
+skillprint.startSession(Mood.CREATIVITY);
+```
+
+### 3. PixiJS
+
+```typescript
+import { PixiSkillprintAdapter, SkillprintConfig, Mood } from 'skillprint-js-sdk';
+
+// Pass PixiJS Application instance
+const skillprint = PixiSkillprintAdapter.create(app, config);
+
+// Bind display object property
+skillprint.registerDisplayObjectProperty('playerAlpha', playerSprite, 'alpha');
+
+skillprint.startSession(Mood.JOY);
+```
+
+---
+
+## WebGL & URL Parameter Handling
+
+When deploying WebGL games, the SDK can extract initial session parameters directly from the browser URL:
+
+```typescript
+// Example URL: https://yourgame.com/?mood=focus&playerId=user_999
+
+// Automatically extract parameters or use fallbacks
+manager.startGameSessionFromUrl(Mood.RELAX, 'default_player');
+
+// Force overrides if necessary
+manager.startGameSessionWithOverrides(
+  Mood.RELAX,         // Fallback mood
+  'default_player',   // Fallback player ID
+  Mood.FOCUS,         // Forced mood override
+  'player_override'   // Forced player ID override
+);
+```
+
+---
+
+## API Reference
+
+### Core Classes
+
+#### `SkillprintConfig`
+- `constructor(options?: SkillprintConfigOptions)`
+- **Properties**: `gameName`, `targetEnvironment`, `productionPartnerApiKey`, `productionApiBaseUrl`, `stagingPartnerApiKey`, `stagingApiBaseUrl`, `screenshotIntervalSeconds`, `screenshotPostIntervalSeconds`, `pollResultsIntervalSeconds`, `enableDebugLogging`.
+- **Getters**: `activePartnerApiKey`, `activeApiBaseUrl`.
+
+#### `SkillprintManager` (Singleton)
+- `constructor(config: SkillprintConfig, canvasProvider?: CanvasProvider)`
+- `static getInstance(): SkillprintManager | null`
+- `registerParameterModifier(parameterName: string, updateAction: ParameterModifierAction, expectedType?: string | null): void`
+- `startGameSession(targetMood: Mood | string, customPlayerId?: string | null): Promise<void>`
+- `stopGameSession(): void`
+- `getCurrentSessionId(): string | null`
+- `getConfig(): SkillprintConfig`
+
+#### `ParameterDefinition`
+- `constructor(options?: ParameterDefinitionOptions)`
+- `isValid(value: unknown): boolean`
+- `convertValue(rawValue: unknown): number | boolean | string | null`
+
+---
+
+## Development & Testing
+
+### Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Run TypeScript type check
+npm run typecheck
+
+# Run Vitest unit test suite
+npm run test
+
+# Run test coverage report
+npm run test:coverage
+
+# Build ESM, CJS, IIFE & .d.ts outputs
+npm run build
+```
+
+---
+
+## Repository Structure
+
+```
+skillprint-js-sdk/
+├── src/
+│   ├── index.ts                     # Main entrypoint re-exporting public API
+│   ├── types.ts                     # TypeScript interface definitions
+│   ├── constants.ts                 # Enums: ApiEnvironment, ParameterType, Mood, LogLevel
+│   ├── config.ts                    # SkillprintConfig class
+│   ├── parameter-definition.ts      # ParameterDefinition class
+│   ├── api-models.ts                # DTO models & value convertors
+│   ├── api-client.ts                # SkillprintAPIClient HTTP implementation
+│   ├── screenshot-utility.ts        # ScreenshotUtility for Canvas & WebGL
+│   ├── url-parameter-extractor.ts   # WebGLUrlParameterExtractor & session helper
+│   ├── manager.ts                   # SkillprintManager core singleton
+│   └── adapters/                    # Game engine adapters (Phaser, Three, Pixi, Canvas)
+├── tests/                           # Vitest automated unit test suite
+├── dist/                            # Built ESM, CJS, IIFE & .d.ts files
+├── tsup.config.ts                   # tsup build configuration
+└── vitest.config.ts                 # Vitest test configuration
+```
+
+---
+
+## License
+
+MIT © [Skillprint Inc.](https://skillprint.com)