nusus 0.2.1 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # Nusus
 
-TypeScript SDK for searching and citing classical Islamic and Arabic texts through [Turath](https://app.turath.io/), 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.
+TypeScript SDK for searching and citing classical Islamic and Arabic texts through [Turath](https://app.turath.io/), a Shamela-style digital library. Use Nusus to retrieve source text, metadata, citations, locators, and direct links from Arabic heritage books for research tools and AI agents.
 
 ```bash
 npm install nusus
@@ -13,7 +13,9 @@ import { createTurathClient } from "nusus/turath";
 
 const turath = createTurathClient({ timeout: 10_000 });
 const books = turath.findBooks("الأربعون النووية");
+const authors = turath.findAuthors("النووي");
 const categories = turath.listCategories();
+const catalog = turath.getCatalogMetadata();
 const results = await turath.search("إنما الأعمال بالنيات", {
   bookIds: [147927],
 });
@@ -21,43 +23,78 @@ const context = await turath.getContext(results.items[0]);
 
 console.log(context.text);
 console.log(context.citation);
+console.log(context.locator);
 console.log(context.url);
 ```
 
-Agent-ready retrieval is one call:
+Agent-ready retrieval is one call. By default each hit is a single page with a match-centered excerpt; adjacent pages are opt-in:
 
 ```ts
 const context = await turath.retrieve("النية", {
   maxPassages: 5,
   maxCharsPerPassage: 2_000,
+  // pagesBefore: 1,
+  // pagesAfter: 1,
 });
+
+for (const passage of context.passages) {
+  console.log(passage.citation); // includes تراث bookId + صفحة تراث
+  console.log(passage.locator); // { bookId, internalPage, url, ... }
+  console.log(passage.provenance); // rank, truncation, scope, ...
+}
 ```
 
-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.
+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. The core SDK is retrieval-only: no madhhab ranking, fatwa logic, or hadith grading.
 
 ## Agent CLI
 
 ```bash
-npx nusus "إنما الأعمال بالنيات" 3
-npx nusus --book-id 147927 "النية" 3
-npx nusus --page 147927 5
-
-# Bun
-bunx nusus "إنما الأعمال بالنيات" 3
+npx nusus --help
+npx nusus --version
+npx nusus find-books "الأربعون النووية" --limit 5
+npx nusus find-books --author-id 44 --limit 10
+npx nusus find-authors "النووي" --limit 5
+npx nusus search "إنما الأعمال بالنيات" --book-id 147927
+npx nusus retrieve "النية" --max-passages 3 --max-chars 2000
+npx nusus get-page --book-id 147927 --page-id 5
+npx nusus get-context --book-id 147927 --page-id 5
+npx nusus get-book 147927
+npx nusus get-author 44
+npx nusus list-categories
+npx nusus catalog
 ```
 
-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"`.
+Default stdout is **JSONL** (one object per line, camelCase, every line has `type`). Use `--format text` for compact human lines. Diagnostics are JSON on **stderr** only. Unknown or command-inapplicable flags are rejected.
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | Success (including zero hits; find/search/retrieve emit a `meta` line; offline finders report `returned`, live search/retrieve report `totalMatches`) |
+| 1 | Usage / invalid argument |
+| 2 | Not found |
+| 3 | Rate limit / HTTP / invalid response / timeout (`ABORTED`) / internal |
+
+`page-id` is Turath’s internal page (`location.internalPage`), not the printed page. `search`/`retrieve` accept at most one `--book-id`, one `--author-id`, and one `--category-id` (filters may be combined). Offline `find-books` accepts repeated `--author-id`/`--category-id` and may omit the title query when those filters are set. `--timeout 0` disables the request timeout (max `600000`). There is no madhhab ranking or multi-book fanout in the CLI.
 
 ## 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.
+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.
+
+Offline author discovery uses an ID→name map verified via official `GET /author` only (no fabricated names), plus live `getAuthor()` for full metadata. `getCatalogMetadata()` reports known book/author ID counts, resolved offline names, and unresolved author IDs. Re-hydrate or resume with `bun scripts/refresh-catalog.mjs authors` (resumable, rate-limit aware). Book listing refresh is fail-closed: `bun scripts/refresh-catalog.mjs books` refuses unofficial sources.
+
+Browser support is not claimed because the checked API responses do not advertise CORS support.
 
 ## Development
 
 ```bash
 bun install
+bun run build   # CLI bin loads dist/; also auto-built by CLI tests if missing
 bun test
 bun run typecheck
-bun run build
-```
 
+# optional live contract (also scheduled via GitHub Actions)
+bun run test:live
+
+# official-API catalog tooling
+bun scripts/refresh-catalog.mjs authors --limit 10
+bun scripts/refresh-catalog.mjs books   # fails closed on purpose
+```

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { NususError } from "./errors.js";
 export type { NususErrorCode } from "./errors.js";
-export type { Author, AuthorSummary, Book, BookSummary, Category, CategorySummary, Passage, RetrievedContext, SearchPage, SourceLocation, TurathId, } from "./models.js";
+export type { Author, AuthorSummary, Book, BookSummary, BookTocEntry, CatalogMetadata, Category, CategorySummary, Passage, PassageProvenance, RetrievedContext, RetrieveScope, SearchPage, SourceLocation, SourceLocator, TurathId, } from "./models.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,YAAY,EACV,MAAM,EACN,aAAa,EACb,IAAI,EACJ,WAAW,EACX,QAAQ,EACR,eAAe,EACf,OAAO,EACP,gBAAgB,EAChB,UAAU,EACV,cAAc,EACd,QAAQ,GACT,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,YAAY,EACV,MAAM,EACN,aAAa,EACb,IAAI,EACJ,WAAW,EACX,YAAY,EACZ,eAAe,EACf,QAAQ,EACR,eAAe,EACf,OAAO,EACP,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,cAAc,EACd,aAAa,EACb,QAAQ,GACT,MAAM,aAAa,CAAC"}

package/dist/models.d.ts

@@ -16,6 +16,11 @@ export type BookSummary = {
     id: string;
     title: string;
 };
+export type BookTocEntry = {
+    title: string;
+    level?: number;
+    page?: number;
+};
 export type Author = AuthorSummary & {
     provider: "turath";
     id: string;
@@ -29,6 +34,10 @@ export type Book = BookSummary & {
     category?: CategorySummary;
     description?: string;
     hasPdf?: boolean;
+    /** Normalized TOC from Turath book indexes when present. */
+    toc?: BookTocEntry[];
+    /** Volume labels from Turath book indexes when present. */
+    volumes?: string[];
     raw?: unknown;
 };
 export type SourceLocation = {
@@ -36,6 +45,31 @@ export type SourceLocation = {
     printedPage?: number;
     volume?: string;
 };
+export type SourceLocator = {
+    bookId: string;
+    internalPage?: number;
+    printedPage?: number;
+    volume?: string;
+    url: string;
+};
+export type RetrieveScope = {
+    bookIds?: TurathId[];
+    authorIds?: TurathId[];
+    categoryIds?: TurathId[];
+};
+export type PassageProvenance = {
+    query: string;
+    scope?: RetrieveScope;
+    rank: number;
+    totalMatches: number;
+    truncated: boolean;
+    truncation?: "prefix" | "match-window";
+    contextPages: {
+        before: number;
+        after: number;
+    };
+    retrievedVia: "page" | "search-hit";
+};
 export type Passage = {
     provider: "turath";
     book: BookSummary;
@@ -47,6 +81,8 @@ export type Passage = {
     headings: string[];
     url: string;
     citation: string;
+    locator?: SourceLocator;
+    provenance?: PassageProvenance;
     raw?: unknown;
 };
 export type SearchPage = {
@@ -59,4 +95,15 @@ export type RetrievedContext = {
     totalMatches: number;
     query: string;
 };
+export type CatalogMetadata = {
+    scannedAt: string;
+    bookCount: number;
+    categoryCount: number;
+    /** Distinct author IDs referenced by the bundled book catalog. */
+    authorIdCount: number;
+    /** Bundled offline author names verified via official GET /author. */
+    authorNameCount: number;
+    /** Known catalog author IDs with no verified offline name (missing/empty upstream or not yet hydrated). */
+    unresolvedAuthorIdCount: number;
+};
 //# sourceMappingURL=models.d.ts.map

package/dist/models.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,eAAe,GAAG;IACvC,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,MAAM,GAAG,aAAa,GAAG;IACnC,QAAQ,EAAE,QAAQ,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,IAAI,GAAG,WAAW,GAAG;IAC/B,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG;IACpB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,QAAQ,EAAE,cAAc,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC"}
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"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"}

package/dist/turath/catalog-authors.d.ts

@@ -0,0 +1,2 @@
+export declare const CATALOG_AUTHORS: readonly [number, string][];
+//# sourceMappingURL=catalog-authors.d.ts.map

package/dist/turath/catalog-authors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-authors.d.ts","sourceRoot":"","sources":["../../src/turath/catalog-authors.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,eAAe,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EA89FtD,CAAC"}