Nusus

TypeScript SDK for searching and citing classical Islamic and Arabic texts through Turath, a Shamela-style digital library. Use Nusus to retrieve source text, metadata, citations, and direct links from Arabic heritage books for research tools and AI agents.

npm install nusus
# or
bun add nusus

import { createTurathClient } from "nusus/turath";

const turath = createTurathClient({ timeout: 10_000 });
const books = turath.findBooks("الأربعون النووية");
const categories = turath.listCategories();
const results = await turath.search("إنما الأعمال بالنيات", {
  bookIds: [147927],
});
const context = await turath.getContext(results.items[0]);

console.log(context.text);
console.log(context.citation);
console.log(context.url);

Agent-ready retrieval is one call:

const context = await turath.retrieve("النية", {
  maxPassages: 5,
  maxCharsPerPassage: 2_000,
});

All requests support AbortSignal; failures use the exported NususError codes. Source text is returned unchanged. Search filters currently accept one Turath ID each because that is all the upstream API has verified.

Agent CLI

npx nusus "إنما الأعمال بالنيات" 3
npx nusus --book-id 147927 "النية" 3
npx nusus --page 147927 5

# Bun
bunx nusus "إنما الأعمال بالنيات" 3

The CLI emits JSON Lines with passage text, source metadata, citations, and direct Turath URLs. It also supports --madhhab hanafi|maliki|shafii|hanbali and --books "title one,title two".

Known limitations

Book and category discovery uses a bundled snapshot of 8,124 Turath books scanned in March 2026 because Turath does not expose verified catalog endpoints. Newly added or changed upstream records may therefore be absent until the snapshot is refreshed. Author-name discovery is not yet available; catalog books retain their author IDs. Browser support is not claimed because the checked API responses do not advertise CORS support.

Development

bun install
bun test
bun run typecheck
bun run build