nusus 0.2.1 → 0.3.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,19 +23,28 @@ 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
 
@@ -50,7 +61,11 @@ The CLI emits JSON Lines with passage text, source metadata, citations, and dire
 
 ## 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
 
@@ -59,5 +74,11 @@ bun install
 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, 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,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

@@ -36,6 +36,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 +72,8 @@ export type Passage = {
     headings: string[];
     url: string;
     citation: string;
+    locator?: SourceLocator;
+    provenance?: PassageProvenance;
     raw?: unknown;
 };
 export type SearchPage = {
@@ -59,4 +86,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"}