nusus 0.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Nusus contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+# Nusus
+
+TypeScript SDK for retrieving citable context from classical Islamic and Arabic texts. The first provider is [Turath](https://app.turath.io/).
+
+```bash
+npm install nusus
+# or
+bun add nusus
+```
+
+```ts
+import { createTurathClient } from "nusus/turath";
+
+const turath = createTurathClient({ timeout: 10_000 });
+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:
+
+```ts
+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
+
+```bash
+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
+
+Turath does not expose verified catalog-discovery endpoints, so book, author, and category filters require numeric IDs. Browser support is not claimed because the checked API responses do not advertise CORS support.
+
+## Development
+
+```bash
+bun install
+bun test
+bun run typecheck
+bun run build
+```
+

package/dist/errors.d.ts

@@ -0,0 +1,14 @@
+export type NususErrorCode = "INVALID_ARGUMENT" | "NOT_FOUND" | "RATE_LIMITED" | "HTTP_ERROR" | "INVALID_RESPONSE" | "ABORTED";
+export declare class NususError extends Error {
+    readonly code: NususErrorCode;
+    readonly status?: number;
+    readonly url?: string;
+    readonly retryAfter?: number;
+    constructor(code: NususErrorCode, message: string, options?: {
+        status?: number;
+        url?: string;
+        retryAfter?: number;
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GACtB,kBAAkB,GAClB,WAAW,GACX,cAAc,GACd,YAAY,GACZ,kBAAkB,GAClB,SAAS,CAAC;AAEd,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;gBAG3B,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QACP,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,KAAK,CAAC,EAAE,OAAO,CAAC;KACZ;CAST"}

package/dist/errors.js

@@ -0,0 +1,15 @@
+export class NususError extends Error {
+    code;
+    status;
+    url;
+    retryAfter;
+    constructor(code, message, options = {}) {
+        super(message, { cause: options.cause });
+        this.name = "NususError";
+        this.code = code;
+        this.status = options.status;
+        this.url = options.url;
+        this.retryAfter = options.retryAfter;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAQA,MAAM,OAAO,UAAW,SAAQ,KAAK;IAC1B,IAAI,CAAiB;IACrB,MAAM,CAAU;IAChB,GAAG,CAAU;IACb,UAAU,CAAU;IAE7B,YACE,IAAoB,EACpB,OAAe,EACf,UAKI,EAAE;QAEN,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;QACvB,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IACvC,CAAC;CACF"}

package/dist/index.d.ts

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

package/dist/index.d.ts.map

@@ -0,0 +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,eAAe,EACf,OAAO,EACP,gBAAgB,EAChB,UAAU,EACV,cAAc,EACd,QAAQ,GACT,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { NususError } from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}

package/dist/models.d.ts

@@ -0,0 +1,57 @@
+export type TurathId = number | string;
+export type AuthorSummary = {
+    id?: string;
+    name?: string;
+};
+export type CategorySummary = {
+    id: string;
+    title?: string;
+};
+export type BookSummary = {
+    id: string;
+    title: string;
+};
+export type Author = AuthorSummary & {
+    provider: "turath";
+    id: string;
+    biography?: string;
+    deathYear?: string;
+    raw?: unknown;
+};
+export type Book = BookSummary & {
+    provider: "turath";
+    author?: AuthorSummary;
+    category?: CategorySummary;
+    description?: string;
+    hasPdf?: boolean;
+    raw?: unknown;
+};
+export type SourceLocation = {
+    internalPage?: number;
+    printedPage?: number;
+    volume?: string;
+};
+export type Passage = {
+    provider: "turath";
+    book: BookSummary;
+    author?: AuthorSummary;
+    category?: CategorySummary;
+    location: SourceLocation;
+    text: string;
+    snippet?: string;
+    headings: string[];
+    url: string;
+    citation: string;
+    raw?: unknown;
+};
+export type SearchPage = {
+    items: Passage[];
+    totalMatches: number;
+    page: number;
+};
+export type RetrievedContext = {
+    passages: Passage[];
+    totalMatches: number;
+    query: string;
+};
+//# sourceMappingURL=models.d.ts.map

package/dist/models.d.ts.map

@@ -0,0 +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,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"}

package/dist/models.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=models.js.map

package/dist/models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":""}

package/dist/transport.d.ts

@@ -0,0 +1,8 @@
+export type FetchLike = typeof fetch;
+export type TransportOptions = {
+    baseUrl?: string;
+    fetch?: FetchLike;
+    timeout?: number;
+};
+export declare const createTransport: ({ baseUrl, fetch: fetcher, timeout, }?: TransportOptions) => <T>(path: string, params: Record<string, string | number | undefined>, signal?: AbortSignal) => Promise<T>;
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,SAAS,GAAG,OAAO,KAAK,CAAC;AAErC,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAUF,eAAO,MAAM,eAAe,GAAI,wCAI7B,gBAAqB,MAQR,CAAC,EAAE,MAAM,MAAM,EAAE,QAAQ,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,EAAE,SAAS,WAAW,KAAG,OAAO,CAAC,CAAC,CA6CrH,CAAC"}

package/dist/transport.js

@@ -0,0 +1,70 @@
+import { NususError } from "./errors.js";
+const retryAfterSeconds = (value) => {
+    if (!value)
+        return undefined;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds))
+        return Math.max(0, seconds);
+    const date = Date.parse(value);
+    return Number.isNaN(date) ? undefined : Math.max(0, Math.ceil((date - Date.now()) / 1000));
+};
+export const createTransport = ({ baseUrl = "https://api.turath.io/", fetch: fetcher = globalThis.fetch, timeout = 10_000, } = {}) => {
+    if (typeof fetcher !== "function") {
+        throw new NususError("INVALID_ARGUMENT", "A fetch implementation is required");
+    }
+    if (!Number.isFinite(timeout) || timeout < 0) {
+        throw new NususError("INVALID_ARGUMENT", "timeout must be a non-negative number");
+    }
+    return async (path, params, signal) => {
+        const url = new URL(path, baseUrl);
+        for (const [key, value] of Object.entries(params)) {
+            if (value !== undefined)
+                url.searchParams.set(key, String(value));
+        }
+        const controller = new AbortController();
+        const abort = () => controller.abort(signal?.reason);
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted)
+            abort();
+        const timer = timeout ? setTimeout(() => controller.abort(new Error("Request timed out")), timeout) : undefined;
+        try {
+            if (controller.signal.aborted)
+                throw controller.signal.reason;
+            const response = await fetcher(url, {
+                headers: { accept: "application/json" },
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const code = response.status === 404 ? "NOT_FOUND" : response.status === 429 ? "RATE_LIMITED" : "HTTP_ERROR";
+                throw new NususError(code, `Turath request failed with HTTP ${response.status}`, {
+                    status: response.status,
+                    url: url.href,
+                    retryAfter: retryAfterSeconds(response.headers.get("retry-after")),
+                });
+            }
+            try {
+                return (await response.json());
+            }
+            catch (cause) {
+                throw new NususError("INVALID_RESPONSE", "Turath returned invalid JSON", { url: url.href, cause });
+            }
+        }
+        catch (cause) {
+            if (cause instanceof NususError)
+                throw cause;
+            if (controller.signal.aborted) {
+                throw new NususError("ABORTED", signal?.aborted ? "Request aborted" : "Request timed out", {
+                    url: url.href,
+                    cause,
+                });
+            }
+            throw new NususError("HTTP_ERROR", "Turath request failed", { url: url.href, cause });
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            signal?.removeEventListener("abort", abort);
+        }
+    };
+};
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"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"}

package/dist/turath/citations.d.ts

@@ -0,0 +1,5 @@
+import type { Passage } from "../models.js";
+export type CitationSource = Pick<Passage, "author" | "book" | "location">;
+export declare const getSourceUrl: (source: CitationSource) => string;
+export declare const formatCitation: (source: CitationSource) => string;
+//# sourceMappingURL=citations.d.ts.map

package/dist/turath/citations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citations.d.ts","sourceRoot":"","sources":["../../src/turath/citations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,EAAE,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC,CAAC;AAE3E,eAAO,MAAM,YAAY,GAAI,QAAQ,cAAc,KAAG,MAMrD,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,QAAQ,cAAc,KAAG,MAMvD,CAAC"}

package/dist/turath/citations.js

@@ -0,0 +1,18 @@
+export const getSourceUrl = (source) => {
+    const url = new URL(`https://app.turath.io/book/${source.book.id}`);
+    if (source.location.internalPage !== undefined) {
+        url.searchParams.set("page", String(source.location.internalPage));
+    }
+    return url.href;
+};
+export const formatCitation = (source) => {
+    const parts = [source.author?.name, source.book.title].filter(Boolean);
+    if (source.location.volume)
+        parts.push(`ج ${source.location.volume}`);
+    if (source.location.printedPage !== undefined)
+        parts.push(`ص ${source.location.printedPage}`);
+    else if (source.location.internalPage !== undefined)
+        parts.push(`صفحة تراث ${source.location.internalPage}`);
+    return parts.join("، ");
+};
+//# sourceMappingURL=citations.js.map

package/dist/turath/citations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"citations.js","sourceRoot":"","sources":["../../src/turath/citations.ts"],"names":[],"mappings":"AAIA,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,MAAsB,EAAU,EAAE;IAC7D,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,8BAA8B,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;IACpE,IAAI,MAAM,CAAC,QAAQ,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/C,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,GAAG,CAAC,IAAI,CAAC;AAClB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,MAAsB,EAAU,EAAE;IAC/D,MAAM,KAAK,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAa,CAAC;IACnF,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM;QAAE,KAAK,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACtE,IAAI,MAAM,CAAC,QAAQ,CAAC,WAAW,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;SACzF,IAAI,MAAM,CAAC,QAAQ,CAAC,YAAY,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,aAAa,MAAM,CAAC,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAC;IAC7G,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC,CAAC"}

package/dist/turath/client.d.ts

@@ -0,0 +1,44 @@
+import type { Book, Passage, RetrievedContext, SearchPage, TurathId } from "../models.js";
+import { type TransportOptions } from "../transport.js";
+import { type CitationSource } from "./citations.js";
+export type RequestOptions = {
+    signal?: AbortSignal;
+};
+export type TurathSearchOptions = RequestOptions & {
+    authorIds?: TurathId[];
+    bookIds?: TurathId[];
+    categoryIds?: TurathId[];
+    page?: number;
+    sort?: "relevance" | "page";
+};
+export type ContextOptions = RequestOptions & {
+    pagesBefore?: number;
+    pagesAfter?: number;
+};
+export type RetrieveOptions = RequestOptions & {
+    maxPassages?: number;
+    maxCharsPerPassage?: number;
+    scope?: {
+        bookIds?: TurathId[];
+        authorIds?: TurathId[];
+        categoryIds?: TurathId[];
+    };
+};
+export type TurathClientOptions = TransportOptions;
+export declare const createTurathClient: (options?: TurathClientOptions) => {
+    getAuthor: (authorId: TurathId, { signal }?: RequestOptions) => Promise<import("../models.js").Author>;
+    getBook: (bookId: TurathId, { signal }?: RequestOptions) => Promise<Book>;
+    getPage: (bookId: TurathId, pageId: TurathId, { signal }?: RequestOptions) => Promise<Passage>;
+    getPages: (bookId: TurathId, range: {
+        from: number;
+        to: number;
+    }, { signal }?: RequestOptions) => Promise<Passage[]>;
+    search: (query: string, options?: TurathSearchOptions) => Promise<SearchPage>;
+    searchAll: (query: string, options?: Omit<TurathSearchOptions, "page">) => AsyncGenerator<Passage>;
+    getContext: (source: Passage, options?: ContextOptions) => Promise<Passage>;
+    retrieve: (query: string, options?: RetrieveOptions) => Promise<RetrievedContext>;
+    formatCitation: (source: CitationSource) => string;
+    getSourceUrl: (source: CitationSource) => string;
+};
+export type TurathClient = ReturnType<typeof createTurathClient>;
+//# sourceMappingURL=client.d.ts.map

package/dist/turath/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/turath/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC1F,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACzE,OAAO,EAAgC,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAInF,MAAM,MAAM,cAAc,GAAG;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,CAAC;AAEtD,MAAM,MAAM,mBAAmB,GAAG,cAAc,GAAG;IACjD,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC;IACrB,WAAW,CAAC,EAAE,QAAQ,EAAE,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,KAAK,CAAC,EAAE;QACN,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC;QACrB,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;QACvB,WAAW,CAAC,EAAE,QAAQ,EAAE,CAAC;KAC1B,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,CAAC;AAgCnD,eAAO,MAAM,kBAAkB,GAAI,UAAS,mBAAwB;0BAG/B,QAAQ,eAAc,cAAc;sBAOxC,QAAQ,eAAc,cAAc,KAAQ,OAAO,CAAC,IAAI,CAAC;sBAKzD,QAAQ,UAAU,QAAQ,eAAc,cAAc,KAAQ,OAAO,CAAC,OAAO,CAAC;uBASnG,QAAQ,SACT;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,eACvB,cAAc,KACzB,OAAO,CAAC,OAAO,EAAE,CAAC;oBAWQ,MAAM,YAAW,mBAAmB,KAAQ,OAAO,CAAC,UAAU,CAAC;uBA2BlD,MAAM,YAAW,IAAI,CAAC,mBAAmB,EAAE,MAAM,CAAC,KAAQ,cAAc,CAAC,OAAO,CAAC;yBAgBzF,OAAO,YAAW,cAAc,KAAQ,OAAO,CAAC,OAAO,CAAC;sBAmB3D,MAAM,YAAW,eAAe,KAAQ,OAAO,CAAC,gBAAgB,CAAC;6BAgCrE,cAAc;2BAChB,cAAc;CAExC,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/turath/client.js

@@ -0,0 +1,156 @@
+import { NususError } from "../errors.js";
+import { createTransport } from "../transport.js";
+import { formatCitation, getSourceUrl } from "./citations.js";
+import { normalizeAuthor, normalizeBook, normalizePage, normalizeSearchHit } from "./normalize.js";
+const id = (value, name = "id") => {
+    const result = String(value);
+    if (!/^[1-9]\d*$/.test(result))
+        throw new NususError("INVALID_ARGUMENT", `${name} must be a positive integer`);
+    return result;
+};
+const integer = (value, name, minimum = 0) => {
+    if (!Number.isInteger(value) || value < minimum) {
+        throw new NususError("INVALID_ARGUMENT", `${name} must be an integer of at least ${minimum}`);
+    }
+    return value;
+};
+const only = (values, name) => {
+    if (!values?.length)
+        return undefined;
+    if (values.length > 1) {
+        throw new NususError("INVALID_ARGUMENT", `Turath currently supports only one ${name} filter per search`);
+    }
+    return id(values[0], name);
+};
+const truncate = (text, maxChars) => {
+    const cut = text.slice(0, maxChars);
+    // avoid ending on a lone high surrogate (split code point)
+    return /[\uD800-\uDBFF]$/.test(cut) ? cut.slice(0, -1) : cut;
+};
+const emptyObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && Object.keys(value).length === 0;
+export const createTurathClient = (options = {}) => {
+    const request = createTransport(options);
+    const getAuthor = async (authorId, { signal } = {}) => {
+        const author = id(authorId, "author id");
+        const raw = await request("author", { id: author, ver: 3 }, signal);
+        if (emptyObject(raw))
+            throw new NususError("NOT_FOUND", `Author ${author} not found`);
+        return normalizeAuthor(raw);
+    };
+    const getBook = async (bookId, { signal } = {}) => {
+        const book = id(bookId, "book id");
+        return normalizeBook(await request("book", { id: book, include: "indexes", ver: 3 }, signal));
+    };
+    const getPage = async (bookId, pageId, { signal } = {}) => {
+        const book = id(bookId, "book id");
+        const page = id(pageId, "page id");
+        const raw = await request("page", { book_id: book, pg: page, ver: 3 }, signal);
+        if (emptyObject(raw))
+            throw new NususError("NOT_FOUND", `Book ${book}, page ${page} not found`);
+        return normalizePage(raw, book);
+    };
+    const getPages = async (bookId, range, { signal } = {}) => {
+        integer(range.from, "from", 1);
+        integer(range.to, "to", range.from);
+        // ponytail: sequential page fetches; add bounded concurrency if large ranges get slow (Phase 3)
+        const pages = [];
+        for (let page = range.from; page <= range.to; page += 1) {
+            pages.push(await getPage(bookId, page, { signal }));
+        }
+        return pages;
+    };
+    const search = async (query, options = {}) => {
+        if (!query.trim())
+            throw new NususError("INVALID_ARGUMENT", "query must not be empty");
+        const page = integer(options.page ?? 1, "page", 1);
+        const raw = await request("search", {
+            q: query,
+            ver: 3,
+            page,
+            author: only(options.authorIds, "author"),
+            book: only(options.bookIds, "book"),
+            cat_id: only(options.categoryIds, "category"),
+            sort: options.sort === "page" ? "page_id" : undefined,
+        }, options.signal);
+        if (typeof raw !== "object" || raw === null ||
+            typeof raw.count !== "number" ||
+            !Array.isArray(raw.data)) {
+            throw new NususError("INVALID_RESPONSE", "Turath returned an invalid search response");
+        }
+        const response = raw;
+        return { items: response.data.map(normalizeSearchHit), totalMatches: response.count, page };
+    };
+    const searchAll = async function* (query, options = {}) {
+        let page = 1;
+        let yielded = 0;
+        while (true) {
+            const result = await search(query, { ...options, page });
+            if (!result.items.length)
+                return;
+            for (const item of result.items) {
+                yield item;
+                yielded += 1;
+                if (yielded >= result.totalMatches)
+                    return;
+            }
+            if (yielded >= result.totalMatches)
+                return;
+            page += 1;
+        }
+    };
+    const getContext = async (source, options = {}) => {
+        const center = source.location.internalPage;
+        if (center === undefined)
+            throw new NususError("INVALID_ARGUMENT", "passage has no internal page");
+        integer(center, "internal page", 1);
+        const before = integer(options.pagesBefore ?? 1, "pagesBefore");
+        const after = integer(options.pagesAfter ?? 1, "pagesAfter");
+        const pages = [];
+        for (let page = Math.max(1, center - before); page <= center + after; page += 1) {
+            try {
+                pages.push(await getPage(source.book.id, page, { signal: options.signal }));
+            }
+            catch (error) {
+                if (!(error instanceof NususError) || error.code !== "NOT_FOUND" || page === center)
+                    throw error;
+            }
+        }
+        const headings = [...new Set(pages.flatMap((page) => page.headings))];
+        const result = { ...source, text: pages.map((page) => page.text).join("\n\n"), headings, raw: pages.map((page) => page.raw) };
+        return { ...result, citation: formatCitation(result), url: getSourceUrl(result) };
+    };
+    const retrieve = async (query, options = {}) => {
+        const maxPassages = integer(options.maxPassages ?? 5, "maxPassages", 1);
+        const maxChars = integer(options.maxCharsPerPassage ?? 4_000, "maxCharsPerPassage", 1);
+        const searchOptions = { ...options.scope, signal: options.signal };
+        const first = await search(query, searchOptions);
+        const hits = first.items.slice(0, maxPassages);
+        for (let page = 2; hits.length < Math.min(maxPassages, first.totalMatches); page += 1) {
+            const next = await search(query, { ...searchOptions, page });
+            if (!next.items.length)
+                break;
+            hits.push(...next.items.slice(0, maxPassages - hits.length));
+        }
+        const passages = await Promise.all(hits.map(async (hit) => {
+            const page = hit.location.internalPage === undefined
+                ? hit
+                : await getPage(hit.book.id, hit.location.internalPage, { signal: options.signal });
+            const bounded = { ...page, snippet: hit.snippet, text: truncate(page.text, maxChars) };
+            return { ...bounded, citation: formatCitation(bounded), url: getSourceUrl(bounded) };
+        }));
+        return { passages, totalMatches: first.totalMatches, query };
+    };
+    return {
+        getAuthor,
+        getBook,
+        getPage,
+        getPages,
+        search,
+        searchAll,
+        getContext,
+        retrieve,
+        formatCitation: (source) => formatCitation(source),
+        getSourceUrl: (source) => getSourceUrl(source),
+    };
+};
+//# sourceMappingURL=client.js.map

package/dist/turath/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/turath/client.ts"],"names":[],"mappings":"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"}

package/dist/turath/index.d.ts

@@ -0,0 +1,5 @@
+export { createTurathClient } from "./client.js";
+export type { ContextOptions, RequestOptions, RetrieveOptions, TurathClient, TurathClientOptions, TurathSearchOptions, } from "./client.js";
+export { formatCitation, getSourceUrl } from "./citations.js";
+export type { CitationSource } from "./citations.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/turath/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/turath/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,YAAY,EACV,cAAc,EACd,cAAc,EACd,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9D,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/turath/index.js

@@ -0,0 +1,3 @@
+export { createTurathClient } from "./client.js";
+export { formatCitation, getSourceUrl } from "./citations.js";
+//# sourceMappingURL=index.js.map

package/dist/turath/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/turath/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AASjD,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/turath/normalize.d.ts

@@ -0,0 +1,6 @@
+import type { Author, Book, Passage } from "../models.js";
+export declare const normalizeAuthor: (raw: unknown) => Author;
+export declare const normalizeBook: (raw: unknown) => Book;
+export declare const normalizePage: (raw: unknown, bookId: string) => Passage;
+export declare const normalizeSearchHit: (raw: unknown) => Passage;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/turath/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/turath/normalize.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AA2B1D,eAAO,MAAM,eAAe,GAAI,KAAK,OAAO,KAAG,MAa9C,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,KAAK,OAAO,KAAG,IAe5C,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,KAAK,OAAO,EAAE,QAAQ,MAAM,KAAG,OAoB5D,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,KAAK,OAAO,KAAG,OAsBjD,CAAC"}

package/dist/turath/normalize.js

@@ -0,0 +1,102 @@
+import { NususError } from "../errors.js";
+import { formatCitation, getSourceUrl } from "./citations.js";
+const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const invalid = (message, cause) => {
+    throw new NususError("INVALID_RESPONSE", message, { cause });
+};
+const parseMeta = (value) => {
+    if (typeof value !== "string")
+        return invalid("Turath metadata is not encoded JSON");
+    try {
+        const parsed = JSON.parse(value);
+        if (!record(parsed))
+            return invalid("Turath metadata is not an object");
+        return parsed;
+    }
+    catch (cause) {
+        if (cause instanceof NususError)
+            throw cause;
+        return invalid("Turath metadata contains invalid JSON", cause);
+    }
+};
+const passage = (input) => {
+    const source = { author: input.author, book: input.book, location: input.location };
+    return { ...input, url: getSourceUrl(source), citation: formatCitation(source) };
+};
+export const normalizeAuthor = (raw) => {
+    if (!record(raw) || typeof raw.id !== "number" || typeof raw.name !== "string") {
+        return invalid("Turath returned an invalid author");
+    }
+    const author = raw;
+    return {
+        provider: "turath",
+        id: String(author.id),
+        name: author.name,
+        ...(typeof author.biography === "string" && { biography: author.biography }),
+        ...(typeof author.death === "string" && { deathYear: author.death }),
+        raw,
+    };
+};
+export const normalizeBook = (raw) => {
+    if (!record(raw) || !record(raw.meta) || typeof raw.meta.id !== "number" || typeof raw.meta.name !== "string") {
+        return invalid("Turath returned an invalid book");
+    }
+    const book = raw;
+    return {
+        provider: "turath",
+        id: String(book.meta.id),
+        title: book.meta.name,
+        ...(typeof book.meta.author_id === "number" && { author: { id: String(book.meta.author_id) } }),
+        ...(typeof book.meta.cat_id === "number" && { category: { id: String(book.meta.cat_id) } }),
+        ...(typeof book.meta.info === "string" && { description: book.meta.info }),
+        ...(Boolean(book.meta.pdf_links) && { hasPdf: true }),
+        raw,
+    };
+};
+export const normalizePage = (raw, bookId) => {
+    if (!record(raw) || typeof raw.meta !== "string" || typeof raw.text !== "string") {
+        return invalid("Turath returned an invalid page");
+    }
+    const page = raw;
+    const meta = parseMeta(page.meta);
+    if (typeof meta.book_name !== "string")
+        return invalid("Turath page is missing its book name");
+    return passage({
+        provider: "turath",
+        book: { id: bookId, title: meta.book_name },
+        ...(meta.author_name && { author: { name: meta.author_name } }),
+        location: {
+            ...(typeof meta.page_id === "number" && { internalPage: meta.page_id }),
+            ...(typeof meta.page === "number" && { printedPage: meta.page }),
+            ...(typeof meta.vol === "string" && { volume: meta.vol }),
+        },
+        text: page.text,
+        headings: Array.isArray(meta.headings) && meta.headings.every((item) => typeof item === "string") ? meta.headings : [],
+        raw,
+    });
+};
+export const normalizeSearchHit = (raw) => {
+    if (!record(raw) || typeof raw.book_id !== "number" || typeof raw.meta !== "string" || typeof raw.text !== "string") {
+        return invalid("Turath returned an invalid search result");
+    }
+    const hit = raw;
+    const meta = parseMeta(hit.meta);
+    if (typeof meta.book_name !== "string")
+        return invalid("Turath search result is missing its book name");
+    return passage({
+        provider: "turath",
+        book: { id: String(hit.book_id), title: meta.book_name },
+        ...(typeof hit.author_id === "number" && { author: { id: String(hit.author_id), ...(meta.author_name && { name: meta.author_name }) } }),
+        ...(typeof hit.cat_id === "number" && { category: { id: String(hit.cat_id) } }),
+        location: {
+            ...(typeof meta.page_id === "number" && { internalPage: meta.page_id }),
+            ...(typeof meta.page === "number" && { printedPage: meta.page }),
+            ...(typeof meta.vol === "string" && { volume: meta.vol }),
+        },
+        text: hit.text,
+        ...(typeof hit.snip === "string" && { snippet: hit.snip }),
+        headings: Array.isArray(meta.headings) && meta.headings.every((item) => typeof item === "string") ? meta.headings : [],
+        raw,
+    });
+};
+//# sourceMappingURL=normalize.js.map

package/dist/turath/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../src/turath/normalize.ts"],"names":[],"mappings":"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"}

package/dist/turath/raw-types.d.ts

@@ -0,0 +1,44 @@
+export type RawAuthor = {
+    id: number;
+    name: string;
+    biography?: string;
+    death?: string;
+    [key: string]: unknown;
+};
+export type RawBook = {
+    meta: {
+        id: number;
+        name: string;
+        author_id?: number;
+        cat_id?: number;
+        info?: string;
+        pdf_links?: unknown;
+        [key: string]: unknown;
+    };
+    indexes?: Record<string, unknown>;
+};
+export type RawPageMeta = {
+    headings?: string[];
+    page_id?: number;
+    page?: number;
+    vol?: string;
+    book_name?: string;
+    author_name?: string;
+};
+export type RawPage = {
+    meta: string;
+    text: string;
+};
+export type RawSearchHit = {
+    author_id?: number;
+    book_id: number;
+    cat_id?: number;
+    meta: string;
+    snip?: string;
+    text: string;
+};
+export type RawSearch = {
+    count: number;
+    data: RawSearchHit[];
+};
+//# sourceMappingURL=raw-types.d.ts.map

package/dist/turath/raw-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw-types.d.ts","sourceRoot":"","sources":["../../src/turath/raw-types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG;IACpB,IAAI,EAAE;QACJ,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD,MAAM,MAAM,YAAY,GAAG;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,YAAY,EAAE,CAAA;CAAE,CAAC"}

package/dist/turath/raw-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=raw-types.js.map

package/dist/turath/raw-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw-types.js","sourceRoot":"","sources":["../../src/turath/raw-types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "nusus",
+  "version": "0.1.0",
+  "description": "Citable context from classical Islamic and Arabic texts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mwijanarko1/nusus.git"
+  },
+  "homepage": "https://github.com/mwijanarko1/nusus#readme",
+  "bugs": "https://github.com/mwijanarko1/nusus/issues",
+  "type": "module",
+  "files": [
+    "dist",
+    "scripts/search.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "nusus": "scripts/search.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./turath": {
+      "types": "./dist/turath/index.d.ts",
+      "import": "./dist/turath/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "bun test",
+    "test:live": "NUSUS_LIVE=1 bun test ./tests/live.test.ts"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT"
+}

package/scripts/search.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+// Agent-facing Turath search CLI built on nusus.
+// Drop-in replacement for the old turath-sdk search.mjs.
+//
+// Usage:
+//   node search.mjs "<Arabic query>" [max_results]
+//   node search.mjs --madhhab hanafi|maliki|shafii|hanbali "<topic>" [max_results]
+//   node search.mjs --books "بدائع الصنائع,الهداية" "<query>" [max_results]
+//   node search.mjs --book-id 147927 "<query>" [max_results]
+//   node search.mjs --page <book_id> <page_id>          # fetch one page + context
+//
+// Output: JSON per line — book_id, title, author, volume, page_id, printed_page,
+// headings, citation, url, text (bounded), prev/next context.
+
+import { createTurathClient } from "../dist/turath/index.js";
+
+const MADHHAB_BOOKS = {
+  hanafi: ["رد المحتار ابن عابدين", "الهداية المرغيناني", "فتح القدير ابن الهمام", "بدائع الصنائع الكاساني", "المبسوط السرخسي"],
+  maliki: ["مختصر خليل", "المدونة الكبرى سحنون", "التوضيح شرح مختصر ابن الحاجب خليل", "الشرح الكبير الدردير حاشية الدسوقي", "مواهب الجليل الحطاب"],
+  shafii: ["منهاج الطالبين النووي", "تحفة المحتاج ابن حجر الهيتمي", "نهاية المحتاج الرملي", "مغني المحتاج الشربيني", "المجموع شرح المهذب النووي"],
+  hanbali: ["منتهى الإرادات ابن النجار", "الإقناع الحجاوي", "كشاف القناع البهوتي", "شرح منتهى الإرادات البهوتي", "المغني ابن قدامة"],
+};
+
+const MADHHAB_LABELS = {
+  hanafi: { name: "الحنفية", at: "عند الحنفية", fi: "في مذهب الحنفية" },
+  maliki: { name: "المالكية", at: "عند المالكية", fi: "في المذهب المالكي" },
+  shafii: { name: "الشافعية", at: "عند الشافعية", fi: "في مذهب الشافعية" },
+  hanbali: { name: "الحنابلة", at: "عند الحنابلة", fi: "في المذهب الحنبلي" },
+};
+
+// === arg parsing ===
+const args = process.argv.slice(2);
+let madhhab = null;
+let books = null;
+let bookId = null;
+let pageMode = false;
+let query = null;
+let maxResults = 5;
+
+for (let i = 0; i < args.length; i++) {
+  const a = args[i];
+  if (a === "--madhhab") {
+    madhhab = args[++i]?.toLowerCase();
+    if (!MADHHAB_BOOKS[madhhab]) fail(`Invalid madhhab. Use: ${Object.keys(MADHHAB_BOOKS).join(", ")}`);
+  } else if (a === "--books") books = args[++i]?.split(",").map((s) => s.trim()).filter(Boolean);
+  else if (a === "--book-id") bookId = args[++i];
+  else if (a === "--page") pageMode = true;
+  else if (a === "--topic") query = args[++i];
+  else if (!a.startsWith("--") && query === null && isNaN(Number(a))) query = a;
+}
+// last numeric non-flag arg = max results (or page args in --page mode)
+const numbers = args.filter((a) => !a.startsWith("--") && /^\d+$/.test(a));
+if (numbers.length && !pageMode) maxResults = parseInt(numbers[numbers.length - 1], 10);
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+const turath = createTurathClient({ timeout: 15_000 });
+
+const emit = (item) => console.log(JSON.stringify(item));
+
+const passageToJson = (p, extra = {}) => ({
+  book_id: Number(p.book.id),
+  title: p.book.title,
+  author: p.author?.name,
+  volume: p.location.volume,
+  page_id: p.location.internalPage,
+  printed_page: p.location.printedPage,
+  headings: p.headings.join(" > "),
+  citation: p.citation,
+  url: p.url,
+  ...extra,
+});
+
+// === page mode: node search.mjs --page <book_id> <page_id> ===
+if (pageMode) {
+  const [pBook, pPage] = numbers;
+  if (!pBook || !pPage) fail("Usage: node search.mjs --page <book_id> <page_id>");
+  const page = await turath.getPage(pBook, pPage);
+  const context = await turath.getContext(page, { pagesBefore: 1, pagesAfter: 1 });
+  emit(passageToJson(page, { text: page.text, context_text: context.text }));
+  process.exit(0);
+}
+
+if (!query) fail('Usage: node search.mjs [--madhhab hanafi|maliki|shafii|hanbali] [--books "t1,t2"] [--book-id N] "<query>" [max_results]');
+
+// === build tiered queries ===
+const searchQueries = [];
+if (madhhab) {
+  const label = MADHHAB_LABELS[madhhab];
+  searchQueries.push({ q: `${query} ${label.at}`, tier: 1, source_type: `madhhab:${madhhab}` });
+  searchQueries.push({ q: `${query} ${label.fi}`, tier: 1, source_type: `madhhab:${madhhab}` });
+  searchQueries.push({ q: `${query} ${label.name}`, tier: 2, source_type: `madhhab:${madhhab}` });
+  for (const book of MADHHAB_BOOKS[madhhab]) {
+    searchQueries.push({ q: `${query} ${book}`, tier: 3, source_type: `book:${madhhab}` });
+  }
+} else if (books) {
+  for (const b of books) searchQueries.push({ q: `${query} ${b}`, tier: 3, source_type: "targeted" });
+}
+searchQueries.push({ q: query, tier: 4, source_type: "broad" });
+
+// === execute ===
+const seen = new Set();
+const collected = [];
+const scope = bookId ? { bookIds: [bookId] } : undefined;
+
+for (const sq of searchQueries) {
+  if (collected.length >= maxResults * 3) break;
+  try {
+    const result = await turath.search(sq.q, scope ? { ...scope } : {});
+    for (const hit of result.items) {
+      const key = `${hit.book.id}:${hit.location.internalPage ?? ""}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      collected.push({ hit, tier: sq.tier, source_type: sq.source_type, matched_term: sq.q.replace(query, "").trim() });
+    }
+  } catch {
+    // skip failed tier queries; broad fallback still runs
+  }
+}
+
+collected.sort((a, b) => a.tier - b.tier);
+const top = collected.slice(0, maxResults);
+
+for (const { hit, tier, source_type, matched_term } of top) {
+  let text = hit.text;
+  let prevTail = "";
+  let nextHead = "";
+  if (hit.location.internalPage !== undefined) {
+    try {
+      const page = await turath.getPage(hit.book.id, hit.location.internalPage);
+      text = page.text;
+      const pg = hit.location.internalPage;
+      if (pg > 1) {
+        try { prevTail = (await turath.getPage(hit.book.id, pg - 1)).text.slice(-300); } catch {}
+      }
+      try { nextHead = (await turath.getPage(hit.book.id, pg + 1)).text.slice(0, 300); } catch {}
+    } catch {}
+  }
+  emit(passageToJson(hit, {
+    source_type,
+    tier,
+    matched_term,
+    snippet: hit.snippet,
+    prev_text_tail: prevTail,
+    text: text.slice(0, 1500),
+    next_text_head: nextHead,
+  }));
+}
+
+if (top.length === 0) emit({ error: "No results", query, madhhab });