Docs/@katforge/api

@katforge/api

The official TypeScript SDK. Wraps every API endpoint as a fluent namespace, handles JWT refresh, and types every error. Runs in browsers, Capacitor, Node, Bun, Deno.

shell

npm install @katforge/api

Instantiate

TypeScript

import { KATforge, browserStorage } from '@katforge/api';

const katforge = new KATforge ({
   baseUrl: 'https://api.katforge.com',
   storage: browserStorage,
   games:   [ 'lextris', 'goblins', 'stumper' ]
});

Namespace tree

TypeScript

katforge
   .auth           .login (id, pw)  .logout ()  .guest ()  .refresh ()
                    .upgrade (dto)  .passport ()  .oauthUrl (provider, opts)
   .users          .me ()  .create (dto)  .check (dto)  .update (dto)
                    .changePassword (dto)  .delete ()
   .games.lextris  .submitResult (dto)  .leaderboard (params)
   .games.goblins  .characters.list ()  .characters.create (dto)
                    .characters.get (id)  .characters.update (id, dto)
                    .news ()  .state (charId)
   .games.stumper  .categories ()  .generateQuestions (cat, diff, count)
                    .createLobby (dto)  .joinLobby (code, name)
                    .leaderboard (params)  .startEndless (dto)

Pagination

Every paginated endpoint returns a PaginatedResponse:

TypeScript

// Iterate all
for await (const entry of katforge.games.lextris.leaderboard ({ mode: 'daily' })) { ... }

// Single page
const page = await katforge.games.lextris.leaderboard ({ mode: 'daily' }).page ();

// Collect
const all = await katforge.games.lextris.leaderboard ({ mode: 'daily' }).all ();

Storage backends

Backend	Use case
`browserStorage`	`localStorage` (default for web)
`createMemoryStorage ()`	In-memory (tests, SSR)
`createCapacitorStorage (SecureStorage)`	iOS Keychain / Android EncryptedSharedPreferences

Errors

All extend KATforgeError. The SDK intercepts 401, refreshes the token, and replays the request once before throwing.

TypeScript

AuthenticationError   // 401
AuthorizationError    // 403
NotFoundError         // 404
ConflictError         // 409
ValidationError       // 422 (has .violations)
RateLimitError        // 429 (has .retryAfter)
NetworkError          // transport failure