@shobdo/js

@shobdo/js

The official JavaScript and TypeScript client for the Shobdo API.

Search across 30+ multilingual dictionaries, retrieve rich definitions, and stream pronunciation audio.

Installation

npm install @shobdo/js
# or
yarn add @shobdo/js
# or
pnpm add @shobdo/js

Initialization

Import the ShobdoClient and initialize it with your API key. You can generate an API key from the Shobdo Console.

import { ShobdoClient } from '@shobdo/js';

const client = new ShobdoClient({ 
  apiKey: process.env.SHOBDO_API_KEY,
  
  // Optional: Configure retry behavior for rate limits and server errors
  maxRetries: 3, // default: 2
  
  // Optional: Set a request timeout in milliseconds
  timeout: 5000, // default: 10000
});

Note: In Node.js 18+ and modern browsers, the native fetch API is used automatically. If you are using an older environment without a global fetch, you must provide a polyfill via the fetch configuration option.

Usage

1. Search Dictionaries

Search across all dictionaries, or filter by specific languages and sources.

const response = await client.search("hello", {
  lang: "en",             // Filter by ISO 639-1 language code
  limit: 10,              // Pagination limit (max 100)
  offset: 0,              // Pagination offset
  matchType: "prefix",    // "exact" | "prefix" | "contains"
});

console.log(`Found ${response.meta.total} results`);

response.data.forEach(result => {
  console.log(`${result.word} - ${result.preview}`);
});

2. Retrieve Entry by Word

Look up a full dictionary entry directly by the word string. The SDK automatically handles URL-encoding for non-Latin scripts (e.g., Arabic, Bengali, Japanese).

// Look up a Bengali word in the English-Bengali dictionary
const bengalEntry = await client.getEntryByWord("shobdo_bi_en_us_bn_bd_665k", "ধন্যবাদ");

console.log(bengalEntry.data.htmlContent);
console.log(bengalEntry.data.phonetic);

3. Retrieve Entry by ID

If you have an entry ID from a previous search result, you can fetch the full entry details:

const entry = await client.getEntryById("dictionary_id_here", "entry_id_here");

if (entry.data.hasAudio) {
  console.log("Audio is available for this entry.");
}

4. Audio URLs

Pronunciation audio is served via a CDN redirect. The SDK provides a helper to construct the correct audio URL for use in <audio> tags or custom players.

const audioUrl = client.getAudioUrl("dictionary_id_here", "entry_id_here");

// In the browser:
const audio = new Audio(audioUrl);
audio.play();

Error Handling

The SDK exposes custom error classes to help you gracefully handle API failures.

import { RateLimitError, AuthenticationError, NotFoundError } from '@shobdo/js';

try {
  await client.search("hello");
} catch (error) {
  if (error instanceof RateLimitError) {
    console.error("Monthly request quota exceeded. Please upgrade your plan.");
  } else if (error instanceof AuthenticationError) {
    console.error("Invalid or missing API key.");
  } else if (error instanceof NotFoundError) {
    console.error("The requested dictionary or entry does not exist.");
  } else {
    console.error("An unexpected error occurred:", error.message);
  }
}

TypeScript

The SDK is written in TypeScript and exports all API response interfaces.

import type { 
  SearchResult, 
  FullEntry, 
  SearchOptions, 
  ApiResponse 
} from '@shobdo/js';

License

Apache-2.0