@puzzle-section/sdk-typescript 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1019 @@
+/**
+ * SDK Type Definitions
+ *
+ * These types mirror the API response types and provide TypeScript support.
+ * Types are manually maintained to ensure a clean SDK interface.
+ */
+type PuzzleType = 'sudoku' | 'wordsearch' | 'crossword' | 'nonogram' | 'colornonogram' | 'picturepath' | 'crossmath' | 'kakuro' | 'slitherlink' | 'mosaic' | 'wordpath' | 'wordladder' | 'breadcrumb' | 'hashi';
+type PuzzleDifficulty = 'easy' | 'medium' | 'hard' | 'expert';
+interface SudokuData {
+    grid: number[][];
+    given: boolean[][];
+    difficulty: PuzzleDifficulty;
+}
+interface WordsearchData {
+    grid: string[][];
+    words: string[];
+    theme?: string;
+    difficulty: PuzzleDifficulty;
+}
+interface CrosswordData {
+    grid: (string | null)[][];
+    clues: {
+        across: Record<string, string>;
+        down: Record<string, string>;
+    };
+    numbering: (number | null)[][];
+    difficulty: PuzzleDifficulty;
+}
+interface NonogramData {
+    rows: number[][];
+    cols: number[][];
+    size: {
+        width: number;
+        height: number;
+    };
+    difficulty: PuzzleDifficulty;
+}
+type PuzzleData = SudokuData | WordsearchData | CrosswordData | NonogramData | Record<string, unknown>;
+type PuzzleSolution = Record<string, unknown>;
+interface Puzzle {
+    id: string;
+    type: PuzzleType;
+    difficulty: PuzzleDifficulty;
+    date: string;
+    estimatedTime: number;
+    isPremium: boolean;
+    data: PuzzleData;
+    createdAt: string;
+    updatedAt: string;
+}
+/** @deprecated Implement your own user types */
+interface UserPublic {
+    id: string;
+    username: string;
+    avatar: string | null;
+    puzzlesCompleted: number;
+    totalScore: number;
+    achievementCount: number;
+    joinDate: string;
+}
+/** @deprecated Implement your own user types */
+interface User extends UserPublic {
+    email?: string;
+    isVerified: boolean;
+    isPremium: boolean;
+    isBetaTester: boolean;
+    preferredLocale: 'en' | 'es' | null;
+    tokens?: number;
+    lastActiveAt: string | null;
+}
+/** @deprecated Implement your own user statistics */
+interface UserStats {
+    totalPuzzlesCompleted: number;
+    totalScore: number;
+    currentStreak: number;
+    longestStreak: number;
+    byPuzzleType: Record<string, {
+        completed: number;
+        totalScore: number;
+        averageTime: number | null;
+        bestTime: number | null;
+    }>;
+    recentActivity: Array<{
+        date: string;
+        puzzlesCompleted: number;
+        scoreEarned: number;
+    }>;
+}
+/** @deprecated Implement your own progress types */
+interface PuzzleProgress {
+    puzzleId: string;
+    userId: string;
+    stateData: Record<string, unknown>;
+    elapsedTime: number;
+    isPaused: boolean;
+    lastSavedAt: string;
+}
+/** @deprecated Implement your own completion types */
+interface PuzzleCompletion {
+    puzzleId: string;
+    userId: string;
+    completionTime: number;
+    score: number;
+    hintsUsed: number;
+    completedAt: string;
+    rank?: number;
+    achievementsUnlocked?: string[];
+}
+/** @deprecated Implement your own progress types */
+interface SaveProgressInput {
+    puzzleId: string;
+    elapsedTime: number;
+    state: Record<string, unknown>;
+    isPaused?: boolean;
+}
+/** @deprecated Implement your own completion types */
+interface CompleteProgressInput {
+    puzzleId: string;
+    elapsedTime: number;
+    hintsUsed?: number;
+}
+interface RateLimitInfo {
+    limit: number;
+    remaining: number;
+    reset: number;
+}
+interface PaginatedResponse<T> {
+    data: T[];
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages: number;
+    };
+    rateLimit?: RateLimitInfo;
+}
+interface HealthStatus {
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    version: string;
+    timestamp: string;
+    checks?: {
+        database: 'up' | 'down';
+        redis: 'up' | 'down';
+    };
+}
+interface GetDailyPuzzlesParams {
+    date?: string;
+    types?: PuzzleType[];
+    difficulties?: PuzzleDifficulty[];
+}
+interface GetPuzzlesByTypeParams {
+    difficulty?: PuzzleDifficulty;
+    limit?: number;
+    page?: number;
+}
+type AdminPuzzleType = 'nonogram' | 'colornonogram' | 'picturepath';
+type AdminPuzzleStatus = 'draft' | 'published';
+interface AdminPuzzle {
+    id: string;
+    title: string;
+    type: AdminPuzzleType;
+    status: AdminPuzzleStatus;
+    eventTags?: string[];
+    tenantId?: string | null;
+    createdById?: string | null;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt?: string | null;
+    variants?: AdminPuzzleVariant[];
+    createdBy?: {
+        id: string;
+        username: string;
+    };
+}
+interface AdminPuzzleVariant {
+    id: string;
+    puzzleId: string;
+    difficulty: PuzzleDifficulty;
+    enabled: boolean;
+    width: number;
+    height: number;
+    gridData: number[][];
+    colorGrid?: number[][];
+    palette?: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateAdminPuzzleRequest {
+    title: string;
+    type: AdminPuzzleType;
+}
+interface UpdateAdminPuzzleRequest {
+    title?: string;
+    status?: AdminPuzzleStatus;
+    event_tags?: string[];
+}
+interface UpsertPuzzleVariantRequest {
+    difficulty: PuzzleDifficulty;
+    enabled?: boolean;
+    width: number;
+    height: number;
+    grid_data: number[][];
+    color_grid?: number[][];
+    palette?: string[];
+}
+interface FilterWordRequest {
+    word: string;
+    reason?: string;
+    addedByName?: string;
+    addedByEmail?: string;
+}
+interface FilterWordResult {
+    word: string;
+    puzzleId: string;
+    updatedPuzzleData: Record<string, unknown>;
+    updatedSolutionData: Record<string, unknown>;
+    message: string;
+}
+interface FunFactorResult {
+    funScore: number;
+    meetsThreshold: boolean;
+    recommendation: 'accept' | 'regenerate' | 'adjust_difficulty';
+    estimatedDifficulty: string;
+    components: {
+        techniqueDiversity: number;
+        logicalFlow: number;
+        noGuessingBonus: number;
+        gridEngagement: number;
+        difficultyMatch: number;
+    };
+    notes: string[];
+    solveStats: {
+        solved: boolean;
+        steps: number;
+        techniquesUsed: string[];
+        guessesRequired: number;
+        backtrackCount: number;
+        maxTechniqueDifficulty: number;
+        avgTechniqueDifficulty: number;
+        solveTimeMs: number;
+        guessLocations: Array<{
+            row: number;
+            col: number;
+            description: string;
+            isBacktrack: boolean;
+        }>;
+    };
+    report: string;
+}
+
+/**
+ * Puzzles API Module
+ */
+
+type RequestFn$4 = <T>(options: {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined>;
+}) => Promise<ResponseWithRateLimit<T>>;
+/**
+ * Puzzles API
+ *
+ * Methods for retrieving and interacting with puzzles.
+ */
+declare class PuzzlesApi {
+    private request;
+    constructor(request: RequestFn$4);
+    /**
+     * Get daily puzzles
+     *
+     * @param params - Optional parameters
+     * @returns List of daily puzzles
+     *
+     * @example
+     * ```typescript
+     * // Get today's puzzles
+     * const puzzles = await client.puzzles.getDaily();
+     *
+     * // Get puzzles for a specific date
+     * const puzzles = await client.puzzles.getDaily({ date: '2024-01-15' });
+     * ```
+     */
+    getDaily(params?: GetDailyPuzzlesParams): Promise<ResponseWithRateLimit<Puzzle[]>>;
+    /**
+     * Get a specific puzzle by ID
+     *
+     * @param id - Puzzle ID
+     * @returns Puzzle details
+     *
+     * @example
+     * ```typescript
+     * const puzzle = await client.puzzles.getById('puzzle-id');
+     * ```
+     */
+    getById(id: string): Promise<ResponseWithRateLimit<Puzzle>>;
+    /**
+     * Get puzzles by type
+     *
+     * @param type - Puzzle type (sudoku, wordsearch, etc.)
+     * @param params - Optional filtering parameters
+     * @returns Paginated list of puzzles
+     *
+     * @example
+     * ```typescript
+     * const sudokus = await client.puzzles.getByType('sudoku', {
+     *   difficulty: 'medium',
+     *   limit: 10,
+     * });
+     * ```
+     */
+    getByType(type: PuzzleType, params?: GetPuzzlesByTypeParams): Promise<ResponseWithRateLimit<PaginatedResponse<Puzzle>>>;
+    /**
+     * Get available puzzle types
+     *
+     * @returns List of available puzzle types
+     */
+    getTypes(): Promise<ResponseWithRateLimit<PuzzleType[]>>;
+    /**
+     * Get puzzle by date and type
+     *
+     * @param date - Date in YYYY-MM-DD format
+     * @param type - Puzzle type
+     * @param difficulty - Optional difficulty filter
+     * @returns Puzzle for the specified date
+     */
+    getByDate(date: string, type: PuzzleType, difficulty?: PuzzleDifficulty): Promise<ResponseWithRateLimit<Puzzle>>;
+    /**
+     * Validate puzzle solution
+     *
+     * @param id - Puzzle ID
+     * @param solution - User's solution
+     * @returns Validation result
+     */
+    validateSolution(id: string, solution: unknown): Promise<ResponseWithRateLimit<{
+        valid: boolean;
+        errors?: string[];
+    }>>;
+}
+
+/**
+ * Users API Module
+ *
+ * @deprecated This module is deprecated and will be removed in a future version.
+ *
+ * User management is now considered a Client-domain responsibility.
+ * Tenants should implement their own user management systems and databases.
+ *
+ * The Platform API provides:
+ * - Puzzle content delivery
+ * - Tenant authentication
+ * - Anonymized analytics
+ *
+ * For user-specific features (authentication, progress, achievements),
+ * implement your own backend or use the TenantEndUser APIs directly.
+ */
+
+type RequestFn$3 = <T>(options: {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined>;
+}) => Promise<ResponseWithRateLimit<T>>;
+/**
+ * Users API
+ *
+ * @deprecated User management should be handled by your own backend.
+ * This API will be removed in a future SDK version.
+ *
+ * Methods for user management and profile operations.
+ * Most methods require a user token to be set.
+ */
+declare class UsersApi {
+    private request;
+    constructor(request: RequestFn$3);
+    /**
+     * Get current user profile
+     *
+     * Requires a user token to be set.
+     *
+     * @returns Current user profile
+     *
+     * @example
+     * ```typescript
+     * client.setUserToken('usr_xxxxxxxxxxxx');
+     * const user = await client.users.getCurrent();
+     * ```
+     */
+    getCurrent(): Promise<ResponseWithRateLimit<User>>;
+    /**
+     * Get user statistics
+     *
+     * Requires a user token to be set.
+     *
+     * @returns User statistics
+     */
+    getStats(): Promise<ResponseWithRateLimit<UserStats>>;
+    /**
+     * Get user by ID
+     *
+     * @param id - User ID
+     * @returns User profile (public fields only)
+     */
+    getById(id: string): Promise<ResponseWithRateLimit<User>>;
+    /**
+     * Update current user profile
+     *
+     * Requires a user token to be set.
+     *
+     * @param updates - Profile updates
+     * @returns Updated user profile
+     */
+    update(updates: {
+        username?: string;
+        avatar?: string;
+        preferred_locale?: string;
+    }): Promise<ResponseWithRateLimit<User>>;
+    /**
+     * Get user achievements
+     *
+     * Requires a user token to be set.
+     *
+     * @returns List of user achievements
+     */
+    getAchievements(): Promise<ResponseWithRateLimit<Array<{
+        id: string;
+        name: string;
+        description: string;
+        earned_at: string;
+    }>>>;
+}
+
+/**
+ * Progress API Module
+ *
+ * @deprecated This module is deprecated and will be removed in a future version.
+ *
+ * Progress tracking is now considered a Client-domain responsibility.
+ * Tenants should implement their own progress storage and management.
+ *
+ * The Platform API provides:
+ * - Puzzle content delivery (puzzles, solutions, hints)
+ * - Tenant authentication
+ * - Anonymized analytics
+ *
+ * For progress tracking, implement your own backend storage solution.
+ * This ensures you own your user data and can customize the experience.
+ */
+
+type RequestFn$2 = <T>(options: {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined>;
+}) => Promise<ResponseWithRateLimit<T>>;
+/**
+ * Progress API
+ *
+ * @deprecated Progress tracking should be handled by your own backend.
+ * This API will be removed in a future SDK version.
+ *
+ * Methods for saving and retrieving puzzle progress.
+ * All methods require a user token to be set.
+ */
+declare class ProgressApi {
+    private request;
+    constructor(request: RequestFn$2);
+    /**
+     * Get saved progress for a puzzle
+     *
+     * @param puzzleId - Puzzle ID
+     * @returns Saved progress or null if not found
+     *
+     * @example
+     * ```typescript
+     * const progress = await client.progress.get('puzzle-id');
+     * if (progress.data) {
+     *   console.log(`Elapsed time: ${progress.data.elapsed_time}s`);
+     * }
+     * ```
+     */
+    get(puzzleId: string): Promise<ResponseWithRateLimit<PuzzleProgress | null>>;
+    /**
+     * Save puzzle progress
+     *
+     * @param input - Progress data to save
+     * @returns Saved progress
+     *
+     * @example
+     * ```typescript
+     * await client.progress.save({
+     *   puzzleId: 'puzzle-id',
+     *   elapsedTime: 120,
+     *   state: {
+     *     grid: [[1, 2, 3], [4, 5, 6], [7, 8, 9]],
+     *   },
+     * });
+     * ```
+     */
+    save(input: SaveProgressInput): Promise<ResponseWithRateLimit<PuzzleProgress>>;
+    /**
+     * Mark puzzle as complete
+     *
+     * @param input - Completion data
+     * @returns Completion record with score
+     *
+     * @example
+     * ```typescript
+     * const completion = await client.progress.complete({
+     *   puzzleId: 'puzzle-id',
+     *   elapsedTime: 300,
+     *   hintsUsed: 2,
+     * });
+     * console.log(`Score: ${completion.data.score}`);
+     * ```
+     */
+    complete(input: CompleteProgressInput): Promise<ResponseWithRateLimit<PuzzleCompletion>>;
+    /**
+     * Delete saved progress
+     *
+     * @param puzzleId - Puzzle ID
+     */
+    delete(puzzleId: string): Promise<ResponseWithRateLimit<void>>;
+    /**
+     * Get all active progress for current user
+     *
+     * @returns List of in-progress puzzles
+     */
+    getAll(): Promise<ResponseWithRateLimit<PuzzleProgress[]>>;
+    /**
+     * Get completion history for current user
+     *
+     * @param params - Optional pagination params
+     * @returns List of completed puzzles
+     */
+    getCompletions(params?: {
+        limit?: number;
+        page?: number;
+    }): Promise<ResponseWithRateLimit<PuzzleCompletion[]>>;
+}
+
+/**
+ * Health API Module
+ */
+
+type RequestFn$1 = <T>(options: {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined>;
+}) => Promise<ResponseWithRateLimit<T>>;
+/**
+ * Health API
+ *
+ * Methods for checking API health and status.
+ */
+declare class HealthApi {
+    private request;
+    constructor(request: RequestFn$1);
+    /**
+     * Check API health
+     *
+     * @returns Health status
+     *
+     * @example
+     * ```typescript
+     * const health = await client.health.check();
+     * console.log(health.data.status); // 'healthy'
+     * ```
+     */
+    check(): Promise<ResponseWithRateLimit<HealthStatus>>;
+    /**
+     * Simple ping check
+     *
+     * @returns Ping response
+     */
+    ping(): Promise<ResponseWithRateLimit<{
+        pong: boolean;
+        timestamp: string;
+    }>>;
+}
+
+/**
+ * Admin API Module
+ *
+ * Methods for managing admin puzzles (nonograms, color nonograms).
+ * Requires tenant API key authentication.
+ */
+
+type RequestFn = <T>(options: {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined>;
+}) => Promise<ResponseWithRateLimit<T>>;
+/**
+ * Admin API
+ *
+ * Methods for creating and managing admin puzzles.
+ * These endpoints are tenant-scoped and require API key authentication.
+ */
+declare class AdminApi {
+    private request;
+    constructor(request: RequestFn);
+    /**
+     * List admin puzzles
+     *
+     * @param params - Optional filter parameters
+     * @returns Paginated list of admin puzzles
+     *
+     * @example
+     * ```typescript
+     * const result = await client.admin.listPuzzles({
+     *   type: 'nonogram',
+     *   status: 'published',
+     *   page: 1,
+     *   pageSize: 20,
+     * });
+     * ```
+     */
+    listPuzzles(params?: {
+        type?: 'nonogram' | 'colornonogram';
+        status?: 'draft' | 'published';
+        search?: string;
+        page?: number;
+        pageSize?: number;
+    }): Promise<ResponseWithRateLimit<PaginatedResponse<AdminPuzzle>>>;
+    /**
+     * List deleted admin puzzles (recycle bin)
+     *
+     * @param params - Optional filter parameters
+     * @returns Paginated list of deleted admin puzzles
+     *
+     * @example
+     * ```typescript
+     * const result = await client.admin.listDeletedPuzzles();
+     * ```
+     */
+    listDeletedPuzzles(params?: {
+        type?: 'nonogram' | 'colornonogram';
+        search?: string;
+        page?: number;
+        pageSize?: number;
+    }): Promise<ResponseWithRateLimit<PaginatedResponse<AdminPuzzle>>>;
+    /**
+     * Get a single admin puzzle by ID
+     *
+     * @param id - Puzzle ID
+     * @returns Admin puzzle with variants
+     *
+     * @example
+     * ```typescript
+     * const puzzle = await client.admin.getPuzzle('puzzle-id');
+     * ```
+     */
+    getPuzzle(id: string): Promise<ResponseWithRateLimit<AdminPuzzle>>;
+    /**
+     * Create a new admin puzzle
+     *
+     * @param data - Puzzle creation data
+     * @returns Created puzzle
+     *
+     * @example
+     * ```typescript
+     * const puzzle = await client.admin.createPuzzle({
+     *   title: 'My Nonogram',
+     *   type: 'nonogram',
+     * });
+     * ```
+     */
+    createPuzzle(data: CreateAdminPuzzleRequest): Promise<ResponseWithRateLimit<AdminPuzzle>>;
+    /**
+     * Update an admin puzzle
+     *
+     * @param id - Puzzle ID
+     * @param data - Update data
+     * @returns Updated puzzle
+     *
+     * @example
+     * ```typescript
+     * const puzzle = await client.admin.updatePuzzle('puzzle-id', {
+     *   title: 'Updated Title',
+     *   status: 'published',
+     * });
+     * ```
+     */
+    updatePuzzle(id: string, data: UpdateAdminPuzzleRequest): Promise<ResponseWithRateLimit<AdminPuzzle>>;
+    /**
+     * Soft delete an admin puzzle (move to recycle bin)
+     *
+     * @param id - Puzzle ID
+     * @returns Success message
+     *
+     * @example
+     * ```typescript
+     * await client.admin.deletePuzzle('puzzle-id');
+     * ```
+     */
+    deletePuzzle(id: string): Promise<ResponseWithRateLimit<{
+        message: string;
+    }>>;
+    /**
+     * Remove a platform puzzle from the tenant's library.
+     * Deactivates all calendar assignments for this puzzle. Only applies to platform puzzles
+     * (tenantId=null). For tenant-owned puzzles, use deletePuzzle instead.
+     * Requires tenant API key authentication.
+     *
+     * @param id - Admin puzzle ID
+     * @returns Result with deactivatedCount
+     *
+     * @example
+     * ```typescript
+     * const result = await client.admin.removeFromLibrary('puzzle-id');
+     * console.log(`Deactivated ${result.data.deactivatedCount} calendar assignments`);
+     * ```
+     */
+    removeFromLibrary(id: string): Promise<ResponseWithRateLimit<{
+        message: string;
+        data: {
+            deactivatedCount: number;
+        };
+    }>>;
+    /**
+     * Restore a soft-deleted puzzle from recycle bin
+     *
+     * @param id - Puzzle ID
+     * @returns Restored puzzle
+     *
+     * @example
+     * ```typescript
+     * const puzzle = await client.admin.restorePuzzle('puzzle-id');
+     * ```
+     */
+    restorePuzzle(id: string): Promise<ResponseWithRateLimit<AdminPuzzle>>;
+    /**
+     * Permanently delete a puzzle (cannot be undone)
+     *
+     * @param id - Puzzle ID
+     * @returns Success message
+     *
+     * @example
+     * ```typescript
+     * await client.admin.permanentlyDeletePuzzle('puzzle-id');
+     * ```
+     */
+    permanentlyDeletePuzzle(id: string): Promise<ResponseWithRateLimit<{
+        message: string;
+    }>>;
+    /**
+     * Publish an admin puzzle
+     *
+     * @param id - Puzzle ID
+     * @returns Published puzzle
+     *
+     * @example
+     * ```typescript
+     * const puzzle = await client.admin.publishPuzzle('puzzle-id');
+     * ```
+     */
+    publishPuzzle(id: string): Promise<ResponseWithRateLimit<AdminPuzzle>>;
+    /**
+     * Unpublish an admin puzzle
+     *
+     * @param id - Puzzle ID
+     * @returns Unpublished puzzle
+     *
+     * @example
+     * ```typescript
+     * const puzzle = await client.admin.unpublishPuzzle('puzzle-id');
+     * ```
+     */
+    unpublishPuzzle(id: string): Promise<ResponseWithRateLimit<AdminPuzzle>>;
+    /**
+     * Create or update a puzzle variant
+     *
+     * @param puzzleId - Puzzle ID
+     * @param data - Variant data
+     * @returns Created/updated variant
+     *
+     * @example
+     * ```typescript
+     * const variant = await client.admin.upsertVariant('puzzle-id', {
+     *   difficulty: 'medium',
+     *   enabled: true,
+     *   width: 15,
+     *   height: 15,
+     *   grid_data: [[0, 1, 0], ...],
+     * });
+     * ```
+     */
+    upsertVariant(puzzleId: string, data: UpsertPuzzleVariantRequest): Promise<ResponseWithRateLimit<AdminPuzzleVariant>>;
+    /**
+     * Delete a puzzle variant
+     *
+     * @param puzzleId - Puzzle ID
+     * @param variantId - Variant ID
+     * @returns Success message
+     *
+     * @example
+     * ```typescript
+     * await client.admin.deleteVariant('puzzle-id', 'variant-id');
+     * ```
+     */
+    deleteVariant(puzzleId: string, variantId: string): Promise<ResponseWithRateLimit<{
+        message: string;
+    }>>;
+    /**
+     * Evaluate fun factor of a nonogram puzzle
+     *
+     * @param data - Grid data and puzzle metadata
+     * @returns Fun factor evaluation result
+     *
+     * @example
+     * ```typescript
+     * const result = await client.admin.evaluateFunFactor({
+     *   grid_data: [[0, 1, 0], ...],
+     *   difficulty: 'medium',
+     *   width: 15,
+     *   height: 15,
+     * });
+     * ```
+     */
+    evaluateFunFactor(data: {
+        grid_data: number[][];
+        difficulty: 'easy' | 'medium' | 'hard' | 'expert';
+        width: number;
+        height: number;
+    }): Promise<ResponseWithRateLimit<FunFactorResult>>;
+    /**
+     * Filter a word from a wordsearch puzzle
+     *
+     * Adds the word to the tenant's filtered word list and removes it from
+     * the specified puzzle. The word will not appear in future puzzle generations
+     * and is immediately removed from the current puzzle for all users.
+     *
+     * @param puzzleId - ID of the wordsearch puzzle
+     * @param data - Word to filter and optional audit metadata
+     * @returns Updated puzzle data with the word removed
+     *
+     * @example
+     * ```typescript
+     * const result = await client.admin.filterWordFromPuzzle('puzzle-id', {
+     *   word: 'offensive',
+     *   reason: 'Inappropriate content',
+     *   addedByName: 'Admin User',
+     *   addedByEmail: 'admin@example.com',
+     * });
+     * ```
+     */
+    filterWordFromPuzzle(puzzleId: string, data: FilterWordRequest): Promise<ResponseWithRateLimit<FilterWordResult>>;
+}
+
+/**
+ * Puzzle Section Client
+ *
+ * Main client class for interacting with the Puzzle Section API.
+ */
+
+/**
+ * Client configuration options
+ */
+interface ClientConfig {
+    /**
+     * Your API key (required)
+     * Format: ps_live_xxxx or ps_sandbox_xxxx
+     */
+    apiKey: string;
+    /**
+     * API base URL
+     * @default 'https://api.puzzlesection.app'
+     */
+    baseUrl?: string;
+    /**
+     * Request timeout in milliseconds
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Number of retry attempts for failed requests
+     * @default 3
+     */
+    retryCount?: number;
+    /**
+     * End-user session token for user-specific operations
+     */
+    userToken?: string;
+    /**
+     * Custom fetch implementation (for testing or special environments)
+     */
+    fetch?: typeof fetch;
+}
+/**
+ * Internal request options
+ */
+interface RequestOptions {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined>;
+    headers?: Record<string, string>;
+}
+/**
+ * Response with rate limit info
+ */
+interface ResponseWithRateLimit<T> {
+    data: T;
+    rateLimit: RateLimitInfo;
+}
+/**
+ * Puzzle Section API Client
+ *
+ * @example
+ * ```typescript
+ * const client = new PuzzleSectionClient({
+ *   apiKey: 'ps_live_xxxxxxxxxxxx',
+ * });
+ *
+ * const puzzles = await client.puzzles.getDaily();
+ * ```
+ */
+declare class PuzzleSectionClient {
+    private readonly config;
+    /**
+     * Puzzles API
+     */
+    readonly puzzles: PuzzlesApi;
+    /**
+     * Users API
+     */
+    readonly users: UsersApi;
+    /**
+     * Progress API
+     */
+    readonly progress: ProgressApi;
+    /**
+     * Health API
+     */
+    readonly health: HealthApi;
+    /**
+     * Admin API
+     */
+    readonly admin: AdminApi;
+    constructor(config: ClientConfig);
+    /**
+     * Set the user token for user-specific operations
+     */
+    setUserToken(token: string | undefined): void;
+    /**
+     * Make an API request
+     */
+    request<T>(options: RequestOptions): Promise<ResponseWithRateLimit<T>>;
+    /**
+     * Execute a single request
+     */
+    private executeRequest;
+    /**
+     * Sleep for a given duration
+     */
+    private sleep;
+}
+
+/**
+ * SDK Error Classes
+ *
+ * Provides typed error handling for API responses.
+ */
+/**
+ * Base error class for all API errors
+ */
+declare class ApiError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly details?: unknown;
+    constructor(message: string, code: string, statusCode: number, details?: unknown);
+}
+/**
+ * Authentication error (401)
+ * Thrown when API key is invalid or missing
+ */
+declare class AuthenticationError extends ApiError {
+    constructor(message?: string);
+}
+/**
+ * Rate limit error (429)
+ * Thrown when rate limit is exceeded
+ */
+declare class RateLimitError extends ApiError {
+    readonly retryAfter: number;
+    readonly limit: number;
+    readonly remaining: number;
+    readonly reset: number;
+    constructor(message: string, retryAfter: number, limit: number, remaining: number, reset: number);
+}
+/**
+ * Not found error (404)
+ * Thrown when requested resource doesn't exist
+ */
+declare class NotFoundError extends ApiError {
+    readonly resourceType: string;
+    readonly resourceId: string;
+    constructor(resourceType: string, resourceId: string);
+}
+/**
+ * Validation error (400)
+ * Thrown when request validation fails
+ */
+declare class ValidationError extends ApiError {
+    readonly validationErrors: Record<string, string[]>;
+    constructor(message: string, validationErrors: Record<string, string[]>);
+}
+/**
+ * Server error (500)
+ * Thrown when server encounters an error
+ */
+declare class ServerError extends ApiError {
+    constructor(message?: string);
+}
+
+export { AdminApi, type AdminPuzzle, type AdminPuzzleStatus, type AdminPuzzleType, type AdminPuzzleVariant, ApiError, AuthenticationError, type ClientConfig, type CreateAdminPuzzleRequest, type FunFactorResult, HealthApi, type HealthStatus, NotFoundError, ProgressApi, type Puzzle, type PuzzleCompletion, type PuzzleData, type PuzzleDifficulty, type PuzzleProgress, PuzzleSectionClient, type PuzzleSolution, type PuzzleType, PuzzlesApi, RateLimitError, type RateLimitInfo, ServerError, type UpdateAdminPuzzleRequest, type UpsertPuzzleVariantRequest, type User, type UserStats, UsersApi, ValidationError };