TypeScript SDK
عميل مُنمَّط بالكامل لـ Node.js وDeno وBun وبيئات edge.
التثبيت
npm install kalimalabتهيئة العميل
import KalimaLab from 'kalimalab'const client = new KalimaLab({ apiKey: process.env.KALIMALAB_API_KEY,})الطرق
client.words.searchابحث في الكلمات العربية بنص استعلام مع فلاتر اختيارية.
client.words.search(params: { q: string limit?: number offset?: number root?: string pattern?: string pos?: string letters?: number}): Promise<SearchResult>| Param | Type | Req | Description |
|---|---|---|---|
q | string | Yes | استعلام البحث — نص عربي أو حروف لاتينية |
limit | number | No | 1-100 نتيجة في الصفحة. الافتراضي: 20. |
offset | number | No | إزاحة الترقيم. الافتراضي: 0. |
root | string | No | فلتر بجذر عربي (مثل كتب) |
pattern | string | No | فلتر بوزن صرفي |
pos | string | No | تصنيف الكلام: اسم، فعل، صفة، ظرف |
letters | number | No | فلتر بعدد أحرف محدد |
Returns: Promise<SearchResult> — { data: Word[], total: number, offset: number, limit: number }
const result = await client.words.search({ q: 'كتب', limit: 10 })console.log(result.total) // 47console.log(result.data[0]) // { id, word, meaning_en, root, ... }client.words.getجلب التفاصيل اللغوية الكاملة لكلمة واحدة بواسطة slug الخاص بها.
client.words.get(slug: string): Promise<Word>| Param | Type | Req | Description |
|---|---|---|---|
slug | string | Yes | slug الكلمة أو معرّفها (من نتائج البحث) |
Returns: Promise<Word>
const word = await client.words.get('كتب')console.log(word.meaning_en) // 'to write'console.log(word.root) // 'كتب'client.words.dailyاحصل على كلمة اليوم.
client.words.daily(): Promise<Word>Returns: Promise<Word>
const word = await client.words.daily()console.log(word.word) // 'الأَمَل'console.log(word.meaning_en) // 'hope'client.words.randomاحصل على كلمات عربية مختارة عشوائياً.
client.words.random(params?: { count?: number }): Promise<Word[]>| Param | Type | Req | Description |
|---|---|---|---|
count | number | No | 1-20 كلمة. الافتراضي: 1. |
Returns: Promise<Word[]>
const words = await client.words.random({ count: 5 })words.forEach(w => console.log(w.word))client.words.validateتحقق من وجود سلاسل عربية في قاعدة بيانات كلمات.
client.words.validate(words: string[]): Promise<ValidationResult>| Param | Type | Req | Description |
|---|---|---|---|
words | string[] | Yes | حتى 100 كلمة عربية للتحقق منها |
Returns: Promise<{ valid: string[], invalid: string[], count: { valid: number, invalid: number } }>
const result = await client.words.validate(['كتب', 'xyz123', 'مدرسة'])console.log(result.valid) // ['كتب', 'مدرسة']console.log(result.invalid) // ['xyz123']client.text.analyzeحلّل مقطعاً من النص العربي.
client.text.analyze(text: string): Promise<TextAnalysis>| Param | Type | Req | Description |
|---|---|---|---|
text | string | Yes | نص عربي للتحليل (حد أقصى 5,000 حرف) |
Returns: Promise<TextAnalysis> — { wordCount, letterCount, uniqueWords, frequency }
const analysis = await client.text.analyze('بسم الله الرحمن الرحيم')console.log(analysis.wordCount) // 4client.stats.getأعد إحصاءات قاعدة البيانات.
client.stats.get(): Promise<Stats>Returns: Promise<{ totalWords: number, totalRoots: number, totalPatterns: number }>
const stats = await client.stats.get()console.log(stats.totalWords) // 477000معالجة الأخطاء
import KalimaLab, { KalimaLabError } from 'kalimalab'try { const result = await client.words.search({ q: 'كتب' })} catch (err) { if (err instanceof KalimaLabError) { console.error(err.status) // 401, 429, 500 console.error(err.code) // 'unauthorized' | 'rate_limited' | ... console.error(err.message) }}أنواع TypeScript
import type { Word, SearchResult, TextAnalysis, ValidationResult, Stats, KalimaLabError,} from 'kalimalab'