wordorb

Official JavaScript/TypeScript SDK for the Word Orb vocabulary intelligence API.

• TypeScript-first with full type exports
• Zero dependencies (native fetch)
• Works without an API key (free tier)
• Auto-retry with exponential backoff on 429/503
• Optional in-memory response caching

Installation

npm install wordorb

Quick Start

import { WordOrb } from 'wordorb'

// Works without a key (free tier)
const orb = new WordOrb()

// Look up a word
const word = await orb.lookup('courage')
console.log(word.def, word.ipa, word.langs.es)

// Get a structured lesson
const lesson = await orb.lesson({ day: 47, track: 'learn' })

// Fetch quiz questions
const quiz = await orb.quiz({ day: 47 })
quiz.questions.forEach(q => console.log(q.question))

With an API Key

const orb = new WordOrb({ apiKey: 'wo_your_key_here' })

Get an API key at wordorb.ai/developer.

Constructor Options

const orb = new WordOrb({
  apiKey: 'wo_...',         // Optional. Higher rate limits.
  baseUrl: 'https://...',   // Default: 'https://wordorb.ai'
  cache: true,              // Default: false. In-memory TTL cache.
  cacheTtl: 300000,         // Default: 300000 (5 min), in ms.
  retries: 2,               // Default: 2. Retries on 429/503.
  timeout: 10000,           // Default: 10000 (10s), in ms.
})

API Reference

orb.lookup(word)

Look up a word. Returns definition, IPA, translations, etymology, and age-calibrated tones.

const result = await orb.lookup('serendipity')

Returns WordResult:

| Field | Type | Description | |------------|---------------------------|------------------------------------------| | word | string | The looked-up word | | def | string? | Definition | | ipa | string? | IPA pronunciation | | pos | string? | Part of speech | | etymology| string? | Word origin | | audio | string? | URL to audio pronunciation | | langs | Record<string, string> | Translations keyed by language code | | tones | WordTone[]? | Age-calibrated tone variants | | synonyms | string[]? | Synonyms | | antonyms | string[]? | Antonyms | | examples | string[]? | Usage examples |

orb.lesson(params)

Fetch a structured 5-phase lesson (hook, story, wonder, action, wisdom).

const lesson = await orb.lesson({
  day: 47,           // 1-365 (required)
  track: 'learn',    // 'learn' | 'grow' | 'teach' | 'trivia'
  age: 'adult',      // 'child' | 'teen' | 'adult'
  lang: 'en',        // language code
})

orb.quiz(params)

Fetch quiz questions for a given day and track.

const quiz = await orb.quiz({
  day: 47,           // 1-365 (required)
  track: 'learn',    // 'learn' | 'grow' | 'teach' | 'trivia'
  lang: 'en',        // language code
})

orb.search(params)

Search for words matching a query string.

const results = await orb.search({ q: 'brav', limit: 10 })
results.results.forEach(hit => console.log(hit.word, hit.def))

orb.graph(params)

Get knowledge graph connections for a word (synonyms, antonyms, related concepts).

const graph = await orb.graph({ word: 'courage' })
graph.edges?.forEach(e => console.log(e.source, '->', e.target, e.type))

orb.clearCache()

Manually clear all cached responses. No-op if caching is disabled.

Error Handling

All API errors throw WordOrbError:

import { WordOrb, WordOrbError } from 'wordorb'

try {
  const word = await orb.lookup('xyznotaword')
} catch (err) {
  if (err instanceof WordOrbError) {
    console.error(err.message)     // Human-readable message
    console.error(err.status)      // HTTP status (404, 429, etc.)
    console.error(err.retryable)   // true for 429/503/network errors
  }
}

Requirements

• Node.js 18+ (or any runtime with native fetch: Deno, Bun, Cloudflare Workers)

License

MIT