@vocab-bloom-hub/client

Typed client for the public read-only API of a Vocab Bloom Hub instance — an English dictionary with IPA, CEFR levels, sense-level definitions, examples, translations (Russian, Spanish, French, German, Portuguese, Chinese, Arabic) and inflected forms, served under /api/v1.

Documentation, the API reference and a playground: vocab-bloom-hub.com.

• One method per endpoint, typed from the server's OpenAPI document — the types cannot drift from the API.
• Node.js ≥ 20 and browsers; fetch only, no dependencies; ESM and CommonJS.
• Errors are thrown as typed exceptions; AbortSignal on every call; optional ETag cache for repeated reads; opt-in retry on 429 / 5xx honouring Retry-After; a versioned User-Agent.

Install

npm install @vocab-bloom-hub/client

Stable releases publish under latest. A prerelease publishes under its channel dist-tag (alpha, beta) and never takes latest, so it has to be named: npm install @vocab-bloom-hub/client@beta.

Quick start

import { VocabBloomClient, NotFoundError } from '@vocab-bloom-hub/client';

const client = new VocabBloomClient({ baseUrl: 'https://dict.example.com' });

// search: relevance tiers, typo tolerance
const { data, meta } = await client.search({ search: 'definately' });
console.log(meta.fuzzy, data[0].word); // true "definitely"

// a headword with every part of speech, forms, meanings and translations
try {
  const run = await client.word('run');
  console.log(run.data[0].meanings[0].definition);
} catch (error) {
  if (error instanceof NotFoundError) console.log('no such word');
  else throw error;
}

// walk the whole dictionary, page after page
for await (const word of client.iterateWords({ word_level: ['A1', 'A2'], with_meanings: true })) {
  console.log(word.word, word.meanings.length);
}

API

| Method | Endpoint | Answer | | -------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | search(request) | GET /search | SearchResponse | | searchDetailed(request) | GET /search/detailed | DetailedSearchResponse | | word(headword) | GET /words/{word} | HeadwordResponse | | wordsBatch(words) | POST /words/batch | WordsBatchResponse — up to 50 headwords, one rate-limit unit; misses under meta.not_found | | wordById(id) | GET /words/id/{id} | WordResponse | | meanings(headword) | GET /words/{word}/meanings | MeaningsResponse | | translations(headword, query?) | GET /words/{word}/translations | TranslationsResponse | | forms(headword) | GET /words/{word}/forms | FormsResponse | | synonyms(headword) | GET /words/{word}/synonyms | LinksResponse — the linked headwords per meaning | | antonyms(headword) | GET /words/{word}/antonyms | LinksResponse | | words(query?) | GET /words | WordsResponse (one page) | | iterateWords(query?) | GET /words, following the cursor | AsyncGenerator<Word> | | iterateSearchDetailed(request) | GET /search/detailed, page after page | AsyncGenerator<Word> — stops at the server's page cap (DETAILED_SEARCH_MAX_PAGE, 20) | | random(filters?) | GET /random | WordResponse | | meta() | GET /meta | MetaResponse | | openapi() | GET /openapi.json | the OpenAPI 3 document | | suggest(request) | POST /suggestions | SuggestionCreatedResponse — files a reader report (or an edit proposal) into the instance's moderation queue |

Every method resolves to the { data, meta } envelope the API answers with and takes an optional last argument { signal, headers, timeoutMs }. The request and response types (Word, Meaning, SearchRequest, ListWordsQuery, …) are exported — the request types of the GET reads are their query strings, so a SearchRequest is { search, type?, limit? } — and so are the raw generated paths / components / operations for anything not aliased. The contract itself — tiers, filters, cursor pagination, caching — is documented in the server's docs/api.md.

Options

new VocabBloomClient({
  baseUrl: 'https://dict.example.com', // origin of the instance; /api/v1 is appended
  headers: { 'X-App': 'my-app' }, // sent with every request
  cache: true, // ETag revalidation (see below); or your own ResponseCache
  fetch: myFetch, // a custom fetch (instrumentation, polyfills, tests)
  timeoutMs: 10_000, // fail a hung request with NetworkError; null disables (the default is 10 s)
  retry: { attempts: 3, backoffMs: 500, maxDelayMs: 60_000 }, // opt-in: retry the GET reads on 429 / 5xx (see below)
});

timeoutMs can also be passed per call and combines with your signal — whichever fires first aborts the request.

Every request carries User-Agent: vocab-bloom-hub-npm/<version> (USER_AGENT, built from SDK_VERSION) so an operator can tell SDK traffic apart in the log; pass your own User-Agent in headers to replace it. Browsers own the header and ignore the value.

Retry

Off by default — the client documents exact request counts against the rate limit, so the loop is opt-in. With retry: {} (or explicit attempts / backoffMs) a GET answered 429 or 5xx is sent again: after Retry-After when the server sent it, otherwise after backoffMs, then twice that, and so on, up to attempts tries in total (the first one included; 3 and 500 ms by default); no single wait exceeds maxDelayMs (60 s by default), whatever Retry-After says. POST requests (the batch lookup, a suggestion), 4xx answers and network errors are never retried; an abort of your signal while waiting ends the wait with NetworkError.

Errors

Failed requests throw:

| Class | When | Fields | | ----------------- | ----------------------------------------------- | ---------------------------------------------- | | NotFoundError | 404 | status, code (word_doesnt_found), body | | RateLimitError | 429 — the public rate limit | retryAfter (seconds, from Retry-After) | | NetworkError | no answer: DNS, connection, TLS, abort, timeout | status: 0, code: 'network_error', cause | | VocabBloomError | everything else | status, code, body |

Without the retry option the client never retries on its own: a RateLimitError carries retryAfter (seconds) and backoff is the caller's decision.

code is the machine-readable error of the API (invalid_cursor, too_many_requests, …), or http_error when the answer was not JSON (a proxy page, for instance).

ETag cache

With cache: true every GET answer is kept in memory per URL together with its ETag; the next read of the same URL sends If-None-Match and, on 304 Not Modified, returns the kept body — the round trip stays, the payload does not. MemoryCache holds 500 entries (least recently used out); pass an object with get(url) / set(url, entry) for a store of your own. Off by default.

Development

yarn workspace @vocab-bloom-hub/client generate        # types from apps/server/openapi/public-v1.json
yarn workspace @vocab-bloom-hub/client generate:check  # fail when the generated types are stale (CI)
yarn workspace @vocab-bloom-hub/client build           # dist/ (ESM, CJS, d.ts)
yarn workspace @vocab-bloom-hub/client test            # unit tests + the client against the real server on SQLite
yarn workspace @vocab-bloom-hub/client pack:check      # publint + arethetypeswrong on the packed tarball (CI, release)

The package ships ESM and CommonJS with a declaration file for each (dist/index.d.ts, dist/index.d.cts); the exports map hands every consumer the pair its resolution asks for.

src/generated/openapi.ts is produced by openapi-typescript from the committed public spec and committed itself: a contract change on the server shows up as a diff here, and test/contract.spec.ts fails until every operation of the spec has a client method.

License

MIT — the dictionary data an instance serves is CC BY 4.0.