nusus 0.4.0 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +31 -14
- package/package.json +5 -3
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Nusus
|
|
2
2
|
|
|
3
|
-
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.
|
|
3
|
+
TypeScript SDK **and agent CLI** 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. The `nusus` binary ships in the same npm package as the SDK.
|
|
4
4
|
|
|
5
5
|
```bash
|
|
6
6
|
npm install nusus
|
|
@@ -48,24 +48,39 @@ All requests support `AbortSignal`; failures use the exported `NususError` codes
|
|
|
48
48
|
|
|
49
49
|
## Agent CLI
|
|
50
50
|
|
|
51
|
+
The package installs a `nusus` binary (`scripts/search.mjs`) that wraps the SDK as explicit research tools. Prefer the CLI from agents; use the SDK from application code.
|
|
52
|
+
|
|
51
53
|
```bash
|
|
52
|
-
npx nusus
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
54
|
+
npm install -g nusus # or: npx nusus …
|
|
55
|
+
nusus --help
|
|
56
|
+
nusus --version
|
|
57
|
+
|
|
58
|
+
# Discover (offline bundled catalog)
|
|
59
|
+
nusus find-books "الأربعون النووية" --limit 5
|
|
60
|
+
nusus find-books --author-id 44 --limit 10
|
|
61
|
+
nusus find-authors "النووي" --limit 5
|
|
62
|
+
nusus list-categories
|
|
63
|
+
nusus catalog
|
|
64
|
+
|
|
65
|
+
# Search / retrieve (live Turath)
|
|
66
|
+
nusus search "إنما الأعمال بالنيات" --book-id 147927
|
|
67
|
+
nusus retrieve "النية" --max-passages 3 --max-chars 2000
|
|
68
|
+
|
|
69
|
+
# Page / metadata (live)
|
|
70
|
+
nusus get-page --book-id 147927 --page-id 5
|
|
71
|
+
nusus get-context --book-id 147927 --page-id 5 --pages-before 1 --pages-after 1
|
|
72
|
+
nusus get-book 147927
|
|
73
|
+
nusus get-author 44
|
|
65
74
|
```
|
|
66
75
|
|
|
67
76
|
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.
|
|
68
77
|
|
|
78
|
+
| Record `type` | Commands |
|
|
79
|
+
| --- | --- |
|
|
80
|
+
| `meta` | First line of `find-books`, `find-authors`, `search`, `retrieve` |
|
|
81
|
+
| `book` / `author` / `category` / `catalog` | Discovery + `get-book` / `get-author` |
|
|
82
|
+
| `passage` | `search`, `retrieve`, `get-page`, `get-context` |
|
|
83
|
+
|
|
69
84
|
| Exit | Meaning |
|
|
70
85
|
| --- | --- |
|
|
71
86
|
| 0 | Success (including zero hits; find/search/retrieve emit a `meta` line; offline finders report `returned`, live search/retrieve report `totalMatches`) |
|
|
@@ -75,6 +90,8 @@ Default stdout is **JSONL** (one object per line, camelCase, every line has `typ
|
|
|
75
90
|
|
|
76
91
|
`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.
|
|
77
92
|
|
|
93
|
+
Repo layout and module boundaries: [`docs/CODEBASE_MAP.md`](docs/CODEBASE_MAP.md). Agent skill copy: [`docs/turath-research-SKILL.md`](docs/turath-research-SKILL.md).
|
|
94
|
+
|
|
78
95
|
## Known limitations
|
|
79
96
|
|
|
80
97
|
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.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "nusus",
|
|
3
|
-
"version": "0.4.
|
|
4
|
-
"description": "TypeScript SDK for searching and citing classical Islamic and Arabic texts via Turath
|
|
3
|
+
"version": "0.4.1",
|
|
4
|
+
"description": "TypeScript SDK and agent CLI for searching and citing classical Islamic and Arabic texts via Turath",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"turath",
|
|
7
7
|
"shamela",
|
|
@@ -11,7 +11,9 @@
|
|
|
11
11
|
"hadith",
|
|
12
12
|
"fiqh",
|
|
13
13
|
"typescript",
|
|
14
|
-
"sdk"
|
|
14
|
+
"sdk",
|
|
15
|
+
"cli",
|
|
16
|
+
"jsonl"
|
|
15
17
|
],
|
|
16
18
|
"repository": {
|
|
17
19
|
"type": "git",
|