Docs/SDK

@katforge/api

@katforge/api is the official TypeScript SDK for the KATforge API. It runs anywhere JS does — browser, Capacitor mobile apps, Node, Bun, Deno — and handles the unglamorous parts of API integration so you don't have to:

  • Auth lifecycle: storing access tokens, refreshing them on 401, replaying the original request
  • Storage backends: in-memory, browser localStorage, or Capacitor secure storage
  • Pagination: async iteration, single-page, or collect-all helpers
  • Errors: typed exceptions per category (validation, conflict, rate limit, network…)
  • Multi-service routing: one client object that talks to api.katforge.com, api.geargoblins.com, etc.

At a glance

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

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

// Authenticate
await katforge.auth.login ('anders@example.com', 'hunter2');

// Read your profile
const me = await katforge.users.me ();

// Submit a game result
await katforge.games.lextris.submitResult ({
   type:  'daily',
   score: 1500,
   level: 5,
   wordsFound:    12,
   blocksDropped: 45,
   timeTaken:     '225.00',
   completed:     true
});

// Iterate every leaderboard entry
for await (const entry of katforge.games.lextris.leaderboard ({ mode: 'daily' })) {
   console.log (entry.display_name, entry.score);
}

Modules

The SDK is organized as a tree of namespaces:

flowchart LR
    KF[katforge]
    KF --> auth["auth<br/><small>login, logout, guest, refresh, OAuth, passport</small>"]
    KF --> users["users<br/><small>me, update, password, communication, delete</small>"]
    KF --> leads["leads<br/><small>contact form</small>"]
    KF --> games["games"]
    KF --> events["on / off<br/><small>event emitter</small>"]

    games --> lextris["lextris<br/><small>results, leaderboard</small>"]
    games --> goblins["goblins<br/><small>characters, news, state</small>"]
    games --> stumper["stumper<br/><small>categories, questions, lobbies, endless,<br/>leaderboard, favorites, preferences, state</small>"]

Each module is documented separately:

Generated reference

For every method's full type signature, see the auto-generated TypeDoc reference. It's regenerated from packages/sdk/src on every docs build, so it's always in sync with the published code.