@puzzle-section/sdk-typescript 1.0.0

package/dist/index.mjs

@@ -0,0 +1,957 @@
+// src/errors.ts
+var ApiError = class extends Error {
+  code;
+  statusCode;
+  details;
+  constructor(message, code, statusCode, details) {
+    super(message);
+    this.name = "ApiError";
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+};
+var AuthenticationError = class extends ApiError {
+  constructor(message = "Invalid or missing API key") {
+    super(message, "AUTHENTICATION_ERROR", 401);
+    this.name = "AuthenticationError";
+  }
+};
+var RateLimitError = class extends ApiError {
+  retryAfter;
+  limit;
+  remaining;
+  reset;
+  constructor(message, retryAfter, limit, remaining, reset) {
+    super(message, "RATE_LIMIT_EXCEEDED", 429, {
+      retryAfter,
+      limit,
+      remaining,
+      reset
+    });
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+    this.limit = limit;
+    this.remaining = remaining;
+    this.reset = reset;
+  }
+};
+var NotFoundError = class extends ApiError {
+  resourceType;
+  resourceId;
+  constructor(resourceType, resourceId) {
+    super(
+      `${resourceType} with ID '${resourceId}' not found`,
+      "NOT_FOUND",
+      404,
+      { resourceType, resourceId }
+    );
+    this.name = "NotFoundError";
+    this.resourceType = resourceType;
+    this.resourceId = resourceId;
+  }
+};
+var ValidationError = class extends ApiError {
+  validationErrors;
+  constructor(message, validationErrors) {
+    super(message, "VALIDATION_ERROR", 400, { validationErrors });
+    this.name = "ValidationError";
+    this.validationErrors = validationErrors;
+  }
+};
+var ServerError = class extends ApiError {
+  constructor(message = "An unexpected server error occurred") {
+    super(message, "SERVER_ERROR", 500);
+    this.name = "ServerError";
+  }
+};
+function createErrorFromResponse(statusCode, body, headers) {
+  const errorBody = body.error || { code: "UNKNOWN", message: "Unknown error" };
+  switch (statusCode) {
+    case 401:
+      return new AuthenticationError(errorBody.message);
+    case 404:
+      return new NotFoundError(
+        errorBody.details?.resourceType || "Resource",
+        errorBody.details?.resourceId || "unknown"
+      );
+    case 429: {
+      const retryAfter = parseInt(headers?.get("Retry-After") || "60", 10);
+      const limit = parseInt(headers?.get("X-RateLimit-Limit") || "0", 10);
+      const remaining = parseInt(
+        headers?.get("X-RateLimit-Remaining") || "0",
+        10
+      );
+      const reset = parseInt(headers?.get("X-RateLimit-Reset") || "0", 10);
+      return new RateLimitError(
+        errorBody.message,
+        retryAfter,
+        limit,
+        remaining,
+        reset
+      );
+    }
+    case 400:
+      return new ValidationError(
+        errorBody.message,
+        errorBody.details || {}
+      );
+    case 500:
+    case 502:
+    case 503:
+    case 504:
+      return new ServerError(errorBody.message);
+    default:
+      return new ApiError(
+        errorBody.message,
+        errorBody.code,
+        statusCode,
+        errorBody.details
+      );
+  }
+}
+
+// src/api/puzzles.ts
+var PuzzlesApi = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /**
+   * 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' });
+   * ```
+   */
+  async getDaily(params) {
+    return this.request({
+      method: "GET",
+      path: "/puzzles/daily",
+      query: {
+        date: params?.date,
+        types: params?.types?.join(","),
+        difficulties: params?.difficulties?.join(",")
+      }
+    });
+  }
+  /**
+   * Get a specific puzzle by ID
+   *
+   * @param id - Puzzle ID
+   * @returns Puzzle details
+   *
+   * @example
+   * ```typescript
+   * const puzzle = await client.puzzles.getById('puzzle-id');
+   * ```
+   */
+  async getById(id) {
+    return this.request({
+      method: "GET",
+      path: `/puzzles/${id}`
+    });
+  }
+  /**
+   * 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,
+   * });
+   * ```
+   */
+  async getByType(type, params) {
+    return this.request({
+      method: "GET",
+      path: `/puzzles/type/${type}`,
+      query: {
+        difficulty: params?.difficulty,
+        limit: params?.limit,
+        page: params?.page
+      }
+    });
+  }
+  /**
+   * Get available puzzle types
+   *
+   * @returns List of available puzzle types
+   */
+  async getTypes() {
+    return this.request({
+      method: "GET",
+      path: "/puzzles/types"
+    });
+  }
+  /**
+   * 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
+   */
+  async getByDate(date, type, difficulty) {
+    return this.request({
+      method: "GET",
+      path: `/puzzles/date/${date}/${type}`,
+      query: { difficulty }
+    });
+  }
+  /**
+   * Validate puzzle solution
+   *
+   * @param id - Puzzle ID
+   * @param solution - User's solution
+   * @returns Validation result
+   */
+  async validateSolution(id, solution) {
+    return this.request({
+      method: "POST",
+      path: `/puzzles/${id}/validate`,
+      body: { solution }
+    });
+  }
+};
+
+// src/api/users.ts
+var UsersApi = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /**
+   * 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();
+   * ```
+   */
+  async getCurrent() {
+    return this.request({
+      method: "GET",
+      path: "/users/me"
+    });
+  }
+  /**
+   * Get user statistics
+   *
+   * Requires a user token to be set.
+   *
+   * @returns User statistics
+   */
+  async getStats() {
+    return this.request({
+      method: "GET",
+      path: "/users/me/stats"
+    });
+  }
+  /**
+   * Get user by ID
+   *
+   * @param id - User ID
+   * @returns User profile (public fields only)
+   */
+  async getById(id) {
+    return this.request({
+      method: "GET",
+      path: `/users/${id}`
+    });
+  }
+  /**
+   * Update current user profile
+   *
+   * Requires a user token to be set.
+   *
+   * @param updates - Profile updates
+   * @returns Updated user profile
+   */
+  async update(updates) {
+    return this.request({
+      method: "PATCH",
+      path: "/users/me",
+      body: updates
+    });
+  }
+  /**
+   * Get user achievements
+   *
+   * Requires a user token to be set.
+   *
+   * @returns List of user achievements
+   */
+  async getAchievements() {
+    return this.request({
+      method: "GET",
+      path: "/users/me/achievements"
+    });
+  }
+};
+
+// src/api/progress.ts
+var ProgressApi = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /**
+   * 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`);
+   * }
+   * ```
+   */
+  async get(puzzleId) {
+    return this.request({
+      method: "GET",
+      path: `/progress/${puzzleId}`
+    });
+  }
+  /**
+   * 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]],
+   *   },
+   * });
+   * ```
+   */
+  async save(input) {
+    return this.request({
+      method: "POST",
+      path: `/progress/${input.puzzleId}`,
+      body: {
+        elapsed_time: input.elapsedTime,
+        state_data: input.state,
+        is_paused: input.isPaused ?? false
+      }
+    });
+  }
+  /**
+   * 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}`);
+   * ```
+   */
+  async complete(input) {
+    return this.request({
+      method: "POST",
+      path: `/progress/${input.puzzleId}/complete`,
+      body: {
+        elapsed_time: input.elapsedTime,
+        hints_used: input.hintsUsed ?? 0
+      }
+    });
+  }
+  /**
+   * Delete saved progress
+   *
+   * @param puzzleId - Puzzle ID
+   */
+  async delete(puzzleId) {
+    return this.request({
+      method: "DELETE",
+      path: `/progress/${puzzleId}`
+    });
+  }
+  /**
+   * Get all active progress for current user
+   *
+   * @returns List of in-progress puzzles
+   */
+  async getAll() {
+    return this.request({
+      method: "GET",
+      path: "/progress"
+    });
+  }
+  /**
+   * Get completion history for current user
+   *
+   * @param params - Optional pagination params
+   * @returns List of completed puzzles
+   */
+  async getCompletions(params) {
+    return this.request({
+      method: "GET",
+      path: "/progress/completions",
+      query: params
+    });
+  }
+};
+
+// src/api/health.ts
+var HealthApi = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /**
+   * Check API health
+   *
+   * @returns Health status
+   *
+   * @example
+   * ```typescript
+   * const health = await client.health.check();
+   * console.log(health.data.status); // 'healthy'
+   * ```
+   */
+  async check() {
+    return this.request({
+      method: "GET",
+      path: "/health"
+    });
+  }
+  /**
+   * Simple ping check
+   *
+   * @returns Ping response
+   */
+  async ping() {
+    return this.request({
+      method: "GET",
+      path: "/health/ping"
+    });
+  }
+};
+
+// src/api/admin.ts
+var AdminApi = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /**
+   * 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,
+   * });
+   * ```
+   */
+  async listPuzzles(params) {
+    return this.request({
+      method: "GET",
+      path: "/admin/puzzles",
+      query: {
+        type: params?.type,
+        status: params?.status,
+        search: params?.search,
+        page: params?.page,
+        pageSize: params?.pageSize
+      }
+    });
+  }
+  /**
+   * 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();
+   * ```
+   */
+  async listDeletedPuzzles(params) {
+    return this.request({
+      method: "GET",
+      path: "/admin/puzzles/deleted",
+      query: {
+        type: params?.type,
+        search: params?.search,
+        page: params?.page,
+        pageSize: params?.pageSize
+      }
+    });
+  }
+  /**
+   * 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');
+   * ```
+   */
+  async getPuzzle(id) {
+    return this.request({
+      method: "GET",
+      path: `/admin/puzzles/${id}`
+    });
+  }
+  /**
+   * 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',
+   * });
+   * ```
+   */
+  async createPuzzle(data) {
+    return this.request({
+      method: "POST",
+      path: "/admin/puzzles",
+      body: data
+    });
+  }
+  /**
+   * 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',
+   * });
+   * ```
+   */
+  async updatePuzzle(id, data) {
+    return this.request({
+      method: "PUT",
+      path: `/admin/puzzles/${id}`,
+      body: data
+    });
+  }
+  /**
+   * Soft delete an admin puzzle (move to recycle bin)
+   *
+   * @param id - Puzzle ID
+   * @returns Success message
+   *
+   * @example
+   * ```typescript
+   * await client.admin.deletePuzzle('puzzle-id');
+   * ```
+   */
+  async deletePuzzle(id) {
+    return this.request({
+      method: "DELETE",
+      path: `/admin/puzzles/${id}`
+    });
+  }
+  /**
+   * 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`);
+   * ```
+   */
+  async removeFromLibrary(id) {
+    return this.request({
+      method: "POST",
+      path: `/admin/puzzles/${id}/remove-from-library`
+    });
+  }
+  /**
+   * 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');
+   * ```
+   */
+  async restorePuzzle(id) {
+    return this.request({
+      method: "POST",
+      path: `/admin/puzzles/${id}/restore`
+    });
+  }
+  /**
+   * Permanently delete a puzzle (cannot be undone)
+   *
+   * @param id - Puzzle ID
+   * @returns Success message
+   *
+   * @example
+   * ```typescript
+   * await client.admin.permanentlyDeletePuzzle('puzzle-id');
+   * ```
+   */
+  async permanentlyDeletePuzzle(id) {
+    return this.request({
+      method: "DELETE",
+      path: `/admin/puzzles/${id}/permanent`
+    });
+  }
+  /**
+   * Publish an admin puzzle
+   *
+   * @param id - Puzzle ID
+   * @returns Published puzzle
+   *
+   * @example
+   * ```typescript
+   * const puzzle = await client.admin.publishPuzzle('puzzle-id');
+   * ```
+   */
+  async publishPuzzle(id) {
+    return this.request({
+      method: "POST",
+      path: `/admin/puzzles/${id}/publish`
+    });
+  }
+  /**
+   * Unpublish an admin puzzle
+   *
+   * @param id - Puzzle ID
+   * @returns Unpublished puzzle
+   *
+   * @example
+   * ```typescript
+   * const puzzle = await client.admin.unpublishPuzzle('puzzle-id');
+   * ```
+   */
+  async unpublishPuzzle(id) {
+    return this.request({
+      method: "POST",
+      path: `/admin/puzzles/${id}/unpublish`
+    });
+  }
+  /**
+   * 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], ...],
+   * });
+   * ```
+   */
+  async upsertVariant(puzzleId, data) {
+    return this.request({
+      method: "PUT",
+      path: `/admin/puzzles/${puzzleId}/variants`,
+      body: data
+    });
+  }
+  /**
+   * 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');
+   * ```
+   */
+  async deleteVariant(puzzleId, variantId) {
+    return this.request({
+      method: "DELETE",
+      path: `/admin/puzzles/${puzzleId}/variants/${variantId}`
+    });
+  }
+  /**
+   * 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,
+   * });
+   * ```
+   */
+  async evaluateFunFactor(data) {
+    return this.request({
+      method: "POST",
+      path: "/admin/puzzles/evaluate-fun-factor",
+      body: data
+    });
+  }
+  /**
+   * 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',
+   * });
+   * ```
+   */
+  async filterWordFromPuzzle(puzzleId, data) {
+    return this.request({
+      method: "POST",
+      path: `/v1/puzzles/${puzzleId}/filter-word`,
+      body: data
+    });
+  }
+};
+
+// src/client.ts
+var PuzzleSectionClient = class {
+  config;
+  /**
+   * Puzzles API
+   */
+  puzzles;
+  /**
+   * Users API
+   */
+  users;
+  /**
+   * Progress API
+   */
+  progress;
+  /**
+   * Health API
+   */
+  health;
+  /**
+   * Admin API
+   */
+  admin;
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new Error("API key is required");
+    }
+    this.config = {
+      apiKey: config.apiKey,
+      baseUrl: config.baseUrl || "https://api.puzzlesection.app",
+      timeout: config.timeout || 3e4,
+      retryCount: config.retryCount || 3,
+      userToken: config.userToken,
+      fetch: config.fetch || globalThis.fetch.bind(globalThis)
+    };
+    this.puzzles = new PuzzlesApi(this.request.bind(this));
+    this.users = new UsersApi(this.request.bind(this));
+    this.progress = new ProgressApi(this.request.bind(this));
+    this.health = new HealthApi(this.request.bind(this));
+    this.admin = new AdminApi(this.request.bind(this));
+  }
+  /**
+   * Set the user token for user-specific operations
+   */
+  setUserToken(token) {
+    this.config.userToken = token;
+  }
+  /**
+   * Make an API request
+   */
+  async request(options) {
+    const { method, path, body, query, headers = {} } = options;
+    const url = new URL(`${this.config.baseUrl}/api/v1${path}`);
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (value !== void 0) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    const requestHeaders = {
+      "Content-Type": "application/json",
+      "X-API-Key": this.config.apiKey,
+      ...headers
+    };
+    if (this.config.userToken) {
+      requestHeaders["X-User-Token"] = this.config.userToken;
+    }
+    const requestInit = {
+      method,
+      headers: requestHeaders
+    };
+    if (body && method !== "GET") {
+      requestInit.body = JSON.stringify(body);
+    }
+    let lastError;
+    for (let attempt = 0; attempt <= this.config.retryCount; attempt++) {
+      try {
+        const response = await this.executeRequest(url.toString(), requestInit);
+        return response;
+      } catch (error) {
+        lastError = error;
+        if (error instanceof ApiError) {
+          if (error.statusCode >= 400 && error.statusCode < 500 && error.statusCode !== 429) {
+            throw error;
+          }
+          if (error.statusCode === 429 && attempt < this.config.retryCount) {
+            const retryAfter = error.retryAfter || Math.pow(2, attempt);
+            await this.sleep(retryAfter * 1e3);
+            continue;
+          }
+        }
+        if (attempt < this.config.retryCount) {
+          await this.sleep(Math.pow(2, attempt) * 1e3);
+        }
+      }
+    }
+    throw lastError;
+  }
+  /**
+   * Execute a single request
+   */
+  async executeRequest(url, init) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+    try {
+      const response = await this.config.fetch(url, {
+        ...init,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      const rateLimit = {
+        limit: parseInt(response.headers.get("X-RateLimit-Limit") || "0", 10),
+        remaining: parseInt(response.headers.get("X-RateLimit-Remaining") || "0", 10),
+        reset: parseInt(response.headers.get("X-RateLimit-Reset") || "0", 10)
+      };
+      let body;
+      const contentType = response.headers.get("content-type") || "";
+      if (contentType && !contentType.includes("application/json")) {
+        throw new ApiError(
+          `Server returned non-JSON response (HTTP ${response.status})`,
+          "INVALID_RESPONSE",
+          response.status
+        );
+      }
+      try {
+        body = await response.json();
+      } catch {
+        throw new ApiError(
+          `Failed to parse server response (HTTP ${response.status})`,
+          "INVALID_RESPONSE",
+          response.status
+        );
+      }
+      if (!response.ok || !body.success) {
+        throw createErrorFromResponse(
+          response.status,
+          body,
+          response.headers
+        );
+      }
+      return {
+        data: body.data,
+        rateLimit
+      };
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof ApiError) {
+        throw error;
+      }
+      if (error.name === "AbortError") {
+        throw new ApiError("Request timed out", "TIMEOUT", 408);
+      }
+      throw new ApiError(
+        `Network error: ${error.message}`,
+        "NETWORK_ERROR",
+        0
+      );
+    }
+  }
+  /**
+   * Sleep for a given duration
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+export {
+  ApiError,
+  AuthenticationError,
+  NotFoundError,
+  PuzzleSectionClient,
+  RateLimitError,
+  ServerError,
+  ValidationError
+};