@puzzle-section/sdk-typescript 1.0.0 → 1.0.1

package/README.md

@@ -2,6 +2,13 @@
 
 Official TypeScript SDK for the Puzzle Section Platform API.
 
+The SDK provides access to:
+- **Puzzle content** — daily puzzles, by type, by ID, solution validation
+- **Admin tools** — puzzle and variant management, content moderation
+- **Health monitoring** — API status and connectivity checks
+
+User management and progress tracking are tenant responsibilities. Implement your own backend for user-specific features.
+
 ## Installation
 
 ```bash
@@ -12,219 +19,196 @@ yarn add @puzzle-section/sdk-typescript
 pnpm add @puzzle-section/sdk-typescript
 ```
 
+**Requirements:** Node.js 18+, TypeScript 5.0+ (recommended), or any modern browser with ES2020+ support.
+
 ## 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);
+const { data: puzzles } = await client.puzzles.getDaily();
 ```
 
 ## Configuration
 
 ```typescript
 const client = new PuzzleSectionClient({
-  // Required: Your API key
-  apiKey: 'ps_live_xxxxxxxxxxxx',
+  apiKey: 'ps_live_xxxxxxxxxxxx',   // Required — tenant API key
+  baseUrl: 'https://api.puzzlesection.app', // Optional — default shown
+  timeout: 30000,                    // Optional — request timeout in ms
+  retryCount: 3,                     // Optional — max retries on 5xx / 429
+  fetch: customFetch,                // Optional — custom fetch implementation
+});
+```
 
-  // Optional: Override base URL (for sandbox or self-hosted)
-  baseUrl: 'https://sandbox.puzzlesection.app',
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | string | — | Tenant API key (required). Sent as `X-API-Key`. |
+| `baseUrl` | string | `https://api.puzzlesection.app` | API base URL. All requests go to `{baseUrl}/api/v1{path}`. |
+| `timeout` | number | `30000` | Request timeout in milliseconds. |
+| `retryCount` | number | `3` | Max retries for 5xx and 429 responses. |
+| `fetch` | typeof fetch | `globalThis.fetch` | Custom fetch for environments without native fetch. |
 
-  // Optional: Request timeout in milliseconds
-  timeout: 30000,
+## Response Envelope
 
-  // Optional: Number of retry attempts for failed requests
-  retryCount: 3,
+Every SDK method returns `Promise<ResponseWithRateLimit<T>>`:
 
-  // Optional: End-user token for user-specific operations
-  userToken: 'usr_xxxxxxxxxxxx',
-});
+```typescript
+interface ResponseWithRateLimit<T> {
+  data: T;
+  rateLimit: RateLimitInfo;
+}
+
+interface RateLimitInfo {
+  limit: number;     // Max requests per window
+  remaining: number; // Requests remaining
+  reset: number;     // Unix timestamp when window resets
+}
+
+const { data, rateLimit } = await client.puzzles.getDaily();
+console.log(rateLimit.remaining); // 999
 ```
 
 ## API Reference
 
-### Puzzles
+### client.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'],
+// All daily puzzles
+const { data } = await client.puzzles.getDaily();
+// data: Puzzle[]
+
+// Filtered by type, difficulty, and date
+const { data } = await client.puzzles.getDaily({
+  date: '2026-03-05',               // YYYY-MM-DD (default: today)
+  types: ['sudoku', 'kakuro'],      // PuzzleType[]
+  difficulties: ['medium', 'hard'], // PuzzleDifficulty[]
 });
 
-// Get puzzle by ID
-const puzzle = await client.puzzles.getById('puzzle-id');
+// Fetch a single puzzle by UUID
+const { data: puzzle } = await client.puzzles.getById('550e8400-e29b-...');
 
-// Get puzzles by type with pagination
-const sudokus = await client.puzzles.getByType('sudoku', {
-  difficulty: 'medium',
+// Paginated list by type
+const { data } = await client.puzzles.getByType('sudoku', {
+  difficulty: 'hard',
   limit: 10,
   page: 1,
 });
+// data.data: Puzzle[], data.pagination: { page, limit, total, totalPages }
 
-// Get puzzle by date and type
-const datePuzzle = await client.puzzles.getByDate('2026-01-15', 'sudoku', 'medium');
+// Specific puzzle for a date and type
+const { data } = await client.puzzles.getByDate('2026-03-05', 'sudoku', 'medium');
 
-// Get available puzzle types
-const types = await client.puzzles.getTypes();
+// All available puzzle types
+const { data: 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
-}
+// Validate a solution
+const { data } = await client.puzzles.validateSolution(
+  '550e8400-...',
+  { grid: [[5, 3, 4, 6, 7, 8, 9, 1, 2], ...] }
+);
+// data: { valid: boolean, errors?: string[] }
 ```
 
-### Users
+### client.health
 
 ```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();
+// Full health check
+const { data } = await client.health.check();
+// data: {
+//   status: 'healthy' | 'degraded' | 'unhealthy',
+//   version: '1.0.0',
+//   timestamp: '2026-03-05T12:00:00Z',
+//   checks: { database: 'up' | 'down', redis: 'up' | 'down' }
+// }
+
+// Simple connectivity ping
+const { data } = await client.health.ping();
+// data: { pong: true, timestamp: '2026-03-05T12:00:00Z' }
 ```
 
-### Progress
+### client.admin
+
+Admin methods are scoped to your tenant and are intended for puzzle content management — typically used by internal tools and the dashboard, not end-user applications.
 
 ```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,
+// List puzzles with filters
+const { data } = await client.admin.listPuzzles({
+  type: 'nonogram',
+  status: 'draft',
+  search: 'cat',
+  page: 1,
+  pageSize: 20,
 });
+// data: PaginatedResponse<AdminPuzzle>
 
-// 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,
+// Create a puzzle
+const { data: puzzle } = await client.admin.createPuzzle({
+  title: 'Cat Nonogram',
+  type: 'nonogram',
 });
-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,
+// Update puzzle metadata
+const { data: updated } = await client.admin.updatePuzzle('puzzle-id', {
+  title: 'Updated Title',
+  status: 'published',
+  event_tags: ['spring-2026'],
 });
 
-// Delete saved progress (start fresh)
-await client.progress.delete('puzzle-id');
-```
+// Get a single puzzle
+const { data: puzzle } = await client.admin.getPuzzle('puzzle-id');
 
-### Health
+// Lifecycle
+await client.admin.publishPuzzle('puzzle-id');
+await client.admin.unpublishPuzzle('puzzle-id');
+await client.admin.deletePuzzle('puzzle-id');            // soft delete
+await client.admin.restorePuzzle('puzzle-id');           // restore from bin
+await client.admin.permanentlyDeletePuzzle('puzzle-id');
+await client.admin.removeFromLibrary('puzzle-id');       // deactivate all variants
 
-```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`:
+// List deleted puzzles
+const { data } = await client.admin.listDeletedPuzzles();
 
-```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
+// Create or update a puzzle variant
+const { data: variant } = await client.admin.upsertVariant('puzzle-id', {
+  difficulty: 'medium',
+  enabled: true,
+  width: 15,
+  height: 15,
+  grid_data: [[0, 1, 1, ...], ...],
+  color_grid: [[0, 1, 2, ...], ...], // for color nonograms
+  palette: ['#000', '#ff0000', '#0000ff'],
+});
 
-The `Puzzle` object contains:
+// Delete a variant
+await client.admin.deleteVariant('puzzle-id', 'variant-id');
 
-```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
-}
+// Evaluate nonogram fun factor
+const { data: result } = await client.admin.evaluateFunFactor({
+  grid_data: [[0, 1, 1, ...], ...],
+  difficulty: 'medium',
+  width: 15,
+  height: 15,
+});
+// result.funScore, result.meetsThreshold, result.recommendation, ...
+
+// Filter an offensive word from a wordsearch puzzle
+await client.admin.filterWordFromPuzzle('puzzle-id', {
+  word: 'offensive',
+  reason: 'inappropriate',
+  addedByName: 'Content Moderator',
+  addedByEmail: 'mod@example.com',
+});
 ```
 
-## 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
 
+The SDK throws typed error classes that extend `ApiError`. Use `instanceof` to branch:
+
 ```typescript
 import {
   PuzzleSectionClient,
@@ -233,56 +217,109 @@ import {
   RateLimitError,
   NotFoundError,
   ValidationError,
+  ServerError,
 } from '@puzzle-section/sdk-typescript';
 
 try {
-  const puzzle = await client.puzzles.getById('invalid-id');
+  const { data } = await client.puzzles.getById('nonexistent');
 } 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`);
+  if (error instanceof RateLimitError) {
+    // 429 — SDK retries automatically; this fires when retries are exhausted
+    console.log(`Retry after ${error.retryAfter}s`);
+    console.log(`Limit: ${error.limit}, Remaining: ${error.remaining}`);
+
   } else if (error instanceof AuthenticationError) {
-    console.log('Invalid API key');
+    // 401 — invalid or missing API key
+    console.error('Check your API key configuration');
+
+  } else if (error instanceof NotFoundError) {
+    // 404 — resource does not exist
+    console.log(error.message);
+
   } else if (error instanceof ValidationError) {
-    console.log(`Validation error: ${error.message}`);
+    // 400 — request validation failed
+    console.log(error.details); // Record<string, string[]>
+
+  } else if (error instanceof ServerError) {
+    // 500–504 — thrown after retries are exhausted
+    console.error('Server error');
+
   } else if (error instanceof ApiError) {
-    console.log(`API error: ${error.code} - ${error.message}`);
+    // Catch-all for any other API error
+    console.error(`[${error.code}] ${error.message} (HTTP ${error.statusCode})`);
   }
 }
 ```
 
-## TypeScript Support
+| Class | HTTP Status | Extra Properties |
+|-------|-------------|-----------------|
+| `ApiError` | any | `message`, `code`, `statusCode`, `details?` |
+| `AuthenticationError` | 401 | — |
+| `ValidationError` | 400 | `details: Record<string, string[]>` |
+| `NotFoundError` | 404 | — |
+| `RateLimitError` | 429 | `retryAfter`, `limit`, `remaining`, `reset` |
+| `ServerError` | 500–504 | — |
 
-This SDK is written in TypeScript and provides full type definitions:
+**Retry behaviour:**
+- **5xx errors** are retried up to `retryCount` times with exponential backoff (2<sup>attempt</sup> seconds).
+- **429 errors** are retried using the `Retry-After` header value when present.
+- **4xx errors** (except 429) are not retried.
+- **Timeouts** throw `ApiError` with code `TIMEOUT` (status 408).
+- **Network failures** throw `ApiError` with code `NETWORK_ERROR` (status 0).
 
-```typescript
-import type { 
-  Puzzle, 
-  PuzzleType, 
-  PuzzleDifficulty,
-  User,
-  UserStats,
-  PuzzleProgress,
-  PuzzleCompletion,
-} from '@puzzle-section/sdk-typescript';
+## TypeScript Types
 
-// Type-safe puzzle handling
-const response = await client.puzzles.getById('id');
-const puzzle: Puzzle = response.data;
+All types are exported from the package:
 
-if (puzzle.type === 'sudoku') {
-  // Access puzzle-specific data
-  const grid = puzzle.data.grid as number[][];
-}
+```typescript
+import type {
+  // Puzzle types
+  Puzzle,
+  PuzzleType,         // 'sudoku' | 'wordsearch' | 'crossword' | ... (14 types)
+  PuzzleDifficulty,   // 'easy' | 'medium' | 'hard' | 'expert'
+  PuzzleData,
+  PuzzleSolution,
+
+  // Response types
+  RateLimitInfo,
+  HealthStatus,
+
+  // Admin types
+  AdminPuzzle,
+  AdminPuzzleVariant,
+  AdminPuzzleType,
+  AdminPuzzleStatus,
+  CreateAdminPuzzleRequest,
+  UpdateAdminPuzzleRequest,
+  UpsertPuzzleVariantRequest,
+  FunFactorResult,
+
+  // Config
+  ClientConfig,
+} from '@puzzle-section/sdk-typescript';
 ```
 
-## Browser Support
+## Available Puzzle Types
 
-The SDK works in both Node.js and browser environments:
+- `sudoku` — Classic 9×9 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 step by step
+- `wordpath` — Connect letters into a path
+- `nonogram` — Picture logic (black and white)
+- `colornonogram` — Picture logic (colour)
+- `mosaic` — Fill-in picture puzzle
+- `picturepath` — Draw a path through a picture
+
+## Browser and Module Support
 
 ```typescript
-// ES Modules (Browser/Node.js)
+// ES Modules (browser / Node.js)
 import { PuzzleSectionClient } from '@puzzle-section/sdk-typescript';
 
 // CommonJS (Node.js)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@puzzle-section/sdk-typescript",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "TypeScript SDK for the Puzzle Section Platform API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",