TypeScript SDK

The official TypeScript client is the recommended way to integrate The Puzzle Section into your application. It provides full type definitions, automatic retries with exponential backoff, and typed error classes.

Use the SDK over raw HTTP

The SDK handles authentication headers, retry logic, rate-limit backoff, timeout management, and response parsing. It wraps every endpoint the v1 API exposes and keeps your integration code minimal and type-safe.

Features

Full Type Safety

Every request and response is strongly typed. Catch errors at compile time, not in production.

Automatic Retries

Transient 5xx errors and 429 rate-limit responses are retried automatically with exponential backoff. Configurable retry count.

Typed Error Classes

Errors are mapped to typed classes (AuthenticationError, RateLimitError, NotFoundError, etc.) for precise error handling.

Rate Limit Awareness

Every response includes rate-limit metadata. The SDK surfaces this alongside the response data via ResponseWithRateLimit<T>.

API Modules

The SDK exposes three modules, each mapping to a group of API endpoints:

Module	Property	Description
Puzzles	`client.puzzles`	Fetch daily puzzles, query by type/date/ID, list types, validate solutions
Health	`client.health`	Service health checks and ping
Admin	`client.admin`	Puzzle CRUD, publishing, variants, fun-factor evaluation (tenant-scoped)

Quick Example

TypeScript

1import { PuzzleSectionClient } from '@puzzle-section/sdk';
2
3const client = new PuzzleSectionClient({
4  apiKey: process.env.PUZZLE_SECTION_API_KEY!,
5});
6
7// Fetch today's puzzles
8const { data: puzzles, rateLimit } = await client.puzzles.getDaily();
9
10// Fetch a specific puzzle
11const { data: puzzle } = await client.puzzles.getById('550e8400-...');
12
13// Check service health
14const { data: health } = await client.health.check();
15console.log(health.status); // 'healthy' | 'degraded' | 'unhealthy'

Using a Different Language?

If you need to integrate with a language we do not have an official SDK for, you can generate a client from our OpenAPI specification:

https://api.puzzlesection.app/api/v1/openapi.json

Compatible with OpenAPI Generator and similar tools. You can also refer to the REST API reference for endpoint details.