@puzzle-section/sdk-typescript 1.0.0

package/README.md

@@ -0,0 +1,294 @@
+# @puzzle-section/sdk-typescript
+
+Official TypeScript SDK for the Puzzle Section Platform API.
+
+## Installation
+
+```bash
+npm install @puzzle-section/sdk-typescript
+# or
+yarn add @puzzle-section/sdk-typescript
+# or
+pnpm add @puzzle-section/sdk-typescript
+```
+
+## Quick Start
+
+```typescript
+import { PuzzleSectionClient } from '@puzzle-section/sdk-typescript';
+
+// Initialize the client
+const client = new PuzzleSectionClient({
+  apiKey: 'ps_live_xxxxxxxxxxxx',
+});
+
+// Get today's puzzles
+const response = await client.puzzles.getDaily();
+console.log(response.data);
+
+// Get a specific puzzle
+const puzzle = await client.puzzles.getById('puzzle-id');
+console.log(puzzle.data);
+```
+
+## Configuration
+
+```typescript
+const client = new PuzzleSectionClient({
+  // Required: Your API key
+  apiKey: 'ps_live_xxxxxxxxxxxx',
+
+  // Optional: Override base URL (for sandbox or self-hosted)
+  baseUrl: 'https://sandbox.puzzlesection.app',
+
+  // Optional: Request timeout in milliseconds
+  timeout: 30000,
+
+  // Optional: Number of retry attempts for failed requests
+  retryCount: 3,
+
+  // Optional: End-user token for user-specific operations
+  userToken: 'usr_xxxxxxxxxxxx',
+});
+```
+
+## API Reference
+
+### Puzzles
+
+```typescript
+// Get daily puzzles
+const dailyPuzzles = await client.puzzles.getDaily();
+
+// Get daily puzzles for a specific date
+const puzzles = await client.puzzles.getDaily({ date: '2026-01-15' });
+
+// Get daily puzzles filtered by type and difficulty
+const filtered = await client.puzzles.getDaily({
+  date: '2026-01-15',
+  types: ['sudoku', 'kakuro'],
+  difficulties: ['medium', 'hard'],
+});
+
+// Get puzzle by ID
+const puzzle = await client.puzzles.getById('puzzle-id');
+
+// Get puzzles by type with pagination
+const sudokus = await client.puzzles.getByType('sudoku', {
+  difficulty: 'medium',
+  limit: 10,
+  page: 1,
+});
+
+// Get puzzle by date and type
+const datePuzzle = await client.puzzles.getByDate('2026-01-15', 'sudoku', 'medium');
+
+// Get available puzzle types
+const types = await client.puzzles.getTypes();
+
+// Validate a solution before submitting
+const validation = await client.puzzles.validateSolution('puzzle-id', {
+  grid: [[5, 3, 4, ...], ...],
+});
+if (validation.data.valid) {
+  // Solution is correct
+}
+```
+
+### Users
+
+```typescript
+// Get current user profile (requires user token)
+const user = await client.users.getCurrent();
+
+// Get user statistics
+const stats = await client.users.getStats();
+
+// Get another user by ID (public fields only)
+const otherUser = await client.users.getById('user-id');
+
+// Update current user profile
+const updated = await client.users.update({
+  username: 'NewUsername',
+  avatar: 'https://example.com/avatar.png',
+  preferred_locale: 'en',
+});
+
+// Get user achievements
+const achievements = await client.users.getAchievements();
+```
+
+### Progress
+
+```typescript
+// Save puzzle progress (auto-save)
+await client.progress.save({
+  puzzleId: 'puzzle-id',
+  elapsedTime: 120000,  // milliseconds
+  state: {
+    grid: [[5, 3, 0, ...], ...],
+    notes: [[[], [], [1, 2], ...], ...],
+  },
+  isPaused: false,
+});
+
+// Get saved progress for a puzzle
+const progress = await client.progress.get('puzzle-id');
+if (progress.data) {
+  console.log(`Elapsed time: ${progress.data.elapsedTime}ms`);
+  console.log(`Last saved: ${progress.data.lastSavedAt}`);
+}
+
+// Get all in-progress puzzles
+const allProgress = await client.progress.getAll();
+
+// Complete a puzzle
+const completion = await client.progress.complete({
+  puzzleId: 'puzzle-id',
+  elapsedTime: 300000,  // milliseconds
+  hintsUsed: 0,
+});
+console.log(`Score: ${completion.data.score}`);
+console.log(`Rank: ${completion.data.rank}`);
+
+// Get completion history
+const completions = await client.progress.getCompletions({
+  limit: 20,
+  page: 1,
+});
+
+// Delete saved progress (start fresh)
+await client.progress.delete('puzzle-id');
+```
+
+### Health
+
+```typescript
+// Check API health
+const health = await client.health.check();
+console.log(health.data.status); // 'healthy' | 'degraded' | 'unhealthy'
+```
+
+## Response Format
+
+All API methods return a response object with `data` and `rateLimit`:
+
+```typescript
+const response = await client.puzzles.getById('puzzle-id');
+
+// The actual data
+const puzzle = response.data;
+console.log(puzzle.type);       // 'sudoku'
+console.log(puzzle.difficulty); // 'medium'
+console.log(puzzle.data);       // Puzzle-specific data (grid, clues, etc.)
+
+// Rate limit information
+console.log(response.rateLimit.limit);     // Max requests per window
+console.log(response.rateLimit.remaining); // Remaining requests
+console.log(response.rateLimit.reset);     // Unix timestamp when window resets
+```
+
+## Puzzle Object
+
+The `Puzzle` object contains:
+
+```typescript
+interface Puzzle {
+  id: string;                    // UUID
+  type: PuzzleType;              // 'sudoku', 'kakuro', 'crossword', etc.
+  difficulty: PuzzleDifficulty;  // 'easy', 'medium', 'hard', 'expert'
+  date: string;                  // 'YYYY-MM-DD'
+  estimatedTime: number;         // Estimated completion time in seconds
+  isPremium: boolean;            // Whether premium access is required
+  data: PuzzleData;              // Type-specific puzzle data
+  createdAt: string;             // ISO timestamp
+  updatedAt: string;             // ISO timestamp
+}
+```
+
+## Available Puzzle Types
+
+- `sudoku` - Classic 9x9 Sudoku
+- `kakuro` - Cross-sum puzzles
+- `crossmath` - Arithmetic crossword
+- `slitherlink` - Loop-drawing puzzle
+- `hashi` - Bridge-building puzzle
+- `breadcrumb` - Path-following puzzle
+- `crossword` - Word crossword
+- `wordsearch` - Find hidden words
+- `wordladder` - Transform words
+- `wordpath` - Connect letters
+- `nonogram` - Picture logic (black/white)
+- `colornonogram` - Picture logic (color)
+- `mosaic` - Fill-in picture puzzle
+- `picturepath` - Draw path puzzle
+
+## Error Handling
+
+```typescript
+import {
+  PuzzleSectionClient,
+  ApiError,
+  AuthenticationError,
+  RateLimitError,
+  NotFoundError,
+  ValidationError,
+} from '@puzzle-section/sdk-typescript';
+
+try {
+  const puzzle = await client.puzzles.getById('invalid-id');
+} catch (error) {
+  if (error instanceof NotFoundError) {
+    console.log('Puzzle not found');
+  } else if (error instanceof RateLimitError) {
+    console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
+  } else if (error instanceof AuthenticationError) {
+    console.log('Invalid API key');
+  } else if (error instanceof ValidationError) {
+    console.log(`Validation error: ${error.message}`);
+  } else if (error instanceof ApiError) {
+    console.log(`API error: ${error.code} - ${error.message}`);
+  }
+}
+```
+
+## TypeScript Support
+
+This SDK is written in TypeScript and provides full type definitions:
+
+```typescript
+import type { 
+  Puzzle, 
+  PuzzleType, 
+  PuzzleDifficulty,
+  User,
+  UserStats,
+  PuzzleProgress,
+  PuzzleCompletion,
+} from '@puzzle-section/sdk-typescript';
+
+// Type-safe puzzle handling
+const response = await client.puzzles.getById('id');
+const puzzle: Puzzle = response.data;
+
+if (puzzle.type === 'sudoku') {
+  // Access puzzle-specific data
+  const grid = puzzle.data.grid as number[][];
+}
+```
+
+## Browser Support
+
+The SDK works in both Node.js and browser environments:
+
+```typescript
+// ES Modules (Browser/Node.js)
+import { PuzzleSectionClient } from '@puzzle-section/sdk-typescript';
+
+// CommonJS (Node.js)
+const { PuzzleSectionClient } = require('@puzzle-section/sdk-typescript');
+```
+
+## License
+
+MIT