shamela 1.3.3 → 1.3.5

package/README.md

@@ -1,3 +1,11 @@
+https://dev.shamela.ws/updates/win/87_64.zip
+https://dev.shamela.ws/versions/win.php
+https://dev.shamela.ws/api/v1/patches/master?api_key=7b9524-8fc30c-e6241o-a0167e-a6d013&version=0
+https://dev.shamela.ws/api/v1/patches/master-download/master-0-1209.zip?api_key=7b9524-8fc30c-e6241o-a0167e-a6d013
+https://dev.shamela.ws/covers/3.jpg?1
+https://dev.shamela.ws/api/v1/patches/book-updates/1681?api_key=7b9524-8fc30c-e6241o-a0167e-a6d013&major_release=0&minor_release=0
+https://ready.shamela.ws/ready/1681-6-1.zip
+
 # shamela
 
 [![wakatime](https://wakatime.com/badge/user/a0b906ce-b8e7-4463-8bce-383238df6d4b/project/faef70ab-efdb-448b-ab83-0fc66c95888e.svg)](https://wakatime.com/badge/user/a0b906ce-b8e7-4463-8bce-383238df6d4b/project/faef70ab-efdb-448b-ab83-0fc66c95888e)
@@ -30,7 +38,8 @@ A universal TypeScript library for accessing and downloading Maktabah Shamela v4
 - [Quick Start](#quick-start)
   - [Standard Node.js](#standard-nodejs)
   - [Next.js / Bundled Environments](#nextjs--bundled-environments)
-  - [Browser](#browser)
+  - [Browser (Full API)](#browser-full-api)
+  - [Browser (Content Utilities Only)](#browser-content-utilities-only)
 - [API Reference](#api-reference)
   - [Configuration](#configuration)
     - [configure](#configure)
@@ -93,8 +102,9 @@ import { configure, getBook } from 'shamela';
 // Configure API credentials
 configure({
   apiKey: process.env.SHAMELA_API_KEY,
-  booksEndpoint: process.env.SHAMELA_BOOKS_ENDPOINT,
-  masterPatchEndpoint: process.env.SHAMELA_MASTER_ENDPOINT,
+  // Configure only the endpoints you need:
+  booksEndpoint: process.env.SHAMELA_BOOKS_ENDPOINT,     // Required for book APIs
+  masterPatchEndpoint: process.env.SHAMELA_MASTER_ENDPOINT, // Required for master APIs
   // sqlJsWasmUrl is auto-detected in standard Node.js
 });
 
@@ -155,7 +165,7 @@ export async function downloadBookAction(bookId: number) {
 
 **Important:** Only import `shamela` in server-side code (Server Actions, API Routes, or Server Components). Never import in client components or `layout.tsx`.
 
-### Browser
+### Browser (Full API)
 
 In browsers, the library automatically uses a CDN-hosted WASM file:
 
@@ -172,6 +182,54 @@ configure({
 const book = await getBook(26592);
 ```
 
+### Browser (Content Utilities Only)
+
+If you only need the content processing utilities (sanitization, parsing, etc.) without the database functionality, use the lightweight `shamela/content` export:
+
+```typescript
+import {
+  sanitizePageContent,
+  splitPageBodyFromFooter,
+  removeTagsExceptSpan,
+  parseContentRobust,
+} from 'shamela/content';
+
+// Process content without loading sql.js (~1.5KB gzipped vs ~900KB)
+const clean = removeTagsExceptSpan(sanitizePageContent(rawContent));
+const [body, footnotes] = splitPageBodyFromFooter(clean);
+```
+
+This is ideal for:
+- Client-side React/Next.js components
+- Bundled environments where you want to avoid sql.js WASM
+- Processing pre-downloaded book data
+
+**Available exports from `shamela/content`:**
+- `parseContentRobust` - Parse HTML into structured lines
+- `mapPageCharacterContent` - Normalize Arabic text with mapping rules
+- `splitPageBodyFromFooter` - Separate body from footnotes
+- `removeArabicNumericPageMarkers` - Remove page markers
+- `removeTagsExceptSpan` - Strip HTML except spans
+- `htmlToMarkdown` - Convert Shamela HTML to Markdown
+- `normalizeHtml` - Normalize hadeeth tags to standard spans
+
+### Extending Content Processing Rules
+
+You can import `DEFAULT_MAPPING_RULES` from `shamela/constants` to extend or customize the character mapping used by `mapPageCharacterContent`:
+
+```typescript
+import { mapPageCharacterContent } from 'shamela/content';
+import { DEFAULT_MAPPING_RULES } from 'shamela/constants';
+
+// Extend default rules with custom mappings
+const customRules = {
+  ...DEFAULT_MAPPING_RULES,
+  'customPattern': 'replacement',
+};
+
+const processed = mapPageCharacterContent(rawContent, customRules);
+```
+
 ## API Reference
 
 ### Configuration
@@ -633,6 +691,40 @@ bun run format            # Format code
 bun run lint              # Lint code
 ```
 
+## Scripts Folder
+
+The `scripts/` directory contains standalone reverse-engineering tools for extracting and decoding data from Shamela's desktop application databases. These are **development tools**, not part of the published npm package.
+
+### Available Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `shamela-decoder.ts` | Core decoder for Shamela's custom character encoding |
+| `export-narrators.ts` | Exports 18,989 narrator biographies from S1.db |
+| `export-roots.ts` | Exports 3.2M Arabic word→root morphological mappings from S2.db |
+
+### Running Scripts
+
+```bash
+# Export narrators to JSON
+bun run scripts/export-narrators.ts
+
+# Export Arabic roots
+bun run scripts/export-roots.ts
+
+# Run script tests
+bun test scripts/
+```
+
+### Script Documentation
+
+- `scripts/README.md` – Quick start guide and reverse-engineering methodology
+- `scripts/AGENTS.md` – Comprehensive documentation including:
+  - Database schema discoveries
+  - Character encoding algorithm (substitution cipher)
+  - Validation approaches and coverage statistics
+  - Common patterns and debugging techniques
+
 ## License
 
 MIT License - see LICENSE file for details.

package/dist/constants-CSNUBkui.js

@@ -0,0 +1,2 @@
+const e=0,t=`99999`,n={"<img[^>]*>>":``,舄:``,"﵀":`رَحِمَهُ ٱللَّٰهُ`,"﵁":`رضي الله عنه`,"﵂":`رَضِيَ ٱللَّٰهُ عَنْهَا`,"﵃":`رَضِيَ اللَّهُ عَنْهُمْ`,"﵄":`رَضِيَ ٱللَّٰهُ عَنْهُمَا`,"﵅":`رَضِيَ اللَّهُ عَنْهُنَّ`,"﵇":`عَلَيْهِ ٱلسَّلَٰمُ`,"﵈":`عَلَيْهِمُ السَّلامُ`,"﵊":`عليه الصلاة والسلام`,"﵌":`صلى الله عليه وآله وسلم`,"﵍":`عَلَيْهِ ٱلسَّلَٰمُ`,"﵎":`تبارك وتعالى`,"﵏":`رَحِمَهُمُ ٱللَّٰهُ`,"﷽":`بِسْمِ اللَّهِ الرَّحْمَنِ الرَّحِيمِ`,"﷿":`عَزَّ وَجَلَّ`};export{e as n,t as r,n as t};
+//# sourceMappingURL=constants-CSNUBkui.js.map

package/dist/constants-CSNUBkui.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants-CSNUBkui.js","names":["DEFAULT_MAPPING_RULES: Record<string, string>"],"sources":["../src/utils/constants.ts"],"sourcesContent":["/**\n * The default version number for master metadata.\n * @constant {number}\n */\nexport const DEFAULT_MASTER_METADATA_VERSION = 0;\n\n/**\n * Placeholder value used to represent unknown or missing data.\n * @constant {string}\n */\nexport const UNKNOWN_VALUE_PLACEHOLDER = '99999';\n\n/**\n * Default rules to map characters from page content.\n */\nexport const DEFAULT_MAPPING_RULES: Record<string, string> = {\n    '<img[^>]*>>': '',\n    舄: '',\n    '﵀': 'رَحِمَهُ ٱللَّٰهُ',\n    '﵁': 'رضي الله عنه',\n    '﵂': 'رَضِيَ ٱللَّٰهُ عَنْهَا',\n    '﵃': 'رَضِيَ اللَّهُ عَنْهُمْ',\n    '﵄': 'رَضِيَ ٱللَّٰهُ عَنْهُمَا',\n    '﵅': 'رَضِيَ اللَّهُ عَنْهُنَّ',\n    '﵇': 'عَلَيْهِ ٱلسَّلَٰمُ',\n    '﵈': 'عَلَيْهِمُ السَّلامُ',\n    '﵊': 'عليه الصلاة والسلام',\n    '﵌': 'صلى الله عليه وآله وسلم',\n    '﵍': 'عَلَيْهِ ٱلسَّلَٰمُ',\n    '﵎': 'تبارك وتعالى',\n    '﵏': 'رَحِمَهُمُ ٱللَّٰهُ',\n    '﷽': 'بِسْمِ اللَّهِ الرَّحْمَنِ الرَّحِيمِ',\n    '﷿': 'عَزَّ وَجَلَّ',\n};\n"],"mappings":"AAIA,MAAa,EAAkC,EAMlC,EAA4B,QAK5BA,EAAgD,CACzD,cAAe,GACf,EAAG,GACH,IAAK,oBACL,IAAK,eACL,IAAK,0BACL,IAAK,0BACL,IAAK,4BACL,IAAK,2BACL,IAAK,sBACL,IAAK,uBACL,IAAK,sBACL,IAAK,0BACL,IAAK,sBACL,IAAK,eACL,IAAK,sBACL,IAAK,wCACL,IAAK,gBACR"}

package/dist/content-BCABDXRO.d.ts

@@ -0,0 +1,70 @@
+//#region src/content.d.ts
+type Line = {
+  id?: string;
+  text: string;
+};
+/**
+ * Parses Shamela HTML content into structured lines while preserving headings.
+ *
+ * @param content - The raw HTML markup representing a page
+ * @returns An array of {@link Line} objects containing text and optional IDs
+ */
+declare const parseContentRobust: (content: string) => Line[];
+/**
+ * Sanitises page content by applying regex replacement rules.
+ *
+ * @param text - The text to clean
+ * @param rules - Optional custom replacements, defaults to {@link DEFAULT_MAPPING_RULES}
+ * @returns The sanitised content
+ */
+declare const mapPageCharacterContent: (text: string, rules?: Record<string, string>) => string;
+/**
+ * Splits a page body from its trailing footnotes using a marker string.
+ *
+ * @param content - Combined body and footnote text
+ * @param footnoteMarker - Marker indicating the start of footnotes
+ * @returns A tuple containing the page body followed by the footnote section
+ */
+declare const splitPageBodyFromFooter: (content: string, footnoteMarker?: string) => readonly [string, string];
+/**
+ * Removes Arabic numeral page markers enclosed in turtle ⦗ ⦘ brackets.
+ * Replaces the marker along with up to two preceding whitespace characters
+ * (space or carriage return) and up to one following whitespace character
+ * with a single space.
+ *
+ * @param text - Text potentially containing page markers
+ * @returns The text with numeric markers replaced by a single space
+ */
+declare const removeArabicNumericPageMarkers: (text: string) => string;
+/**
+ * Removes anchor and hadeeth tags from the content while preserving spans.
+ *
+ * @param content - HTML string containing various tags
+ * @returns The content with only span tags retained
+ */
+declare const removeTagsExceptSpan: (content: string) => string;
+/**
+ * Normalizes Shamela HTML for CSS styling:
+ * - Converts <hadeeth-N> to <span class="hadeeth">
+ * - Converts </hadeeth> or standalone <hadeeth> to </span>
+ */
+declare const normalizeHtml: (html: string) => string;
+/**
+ * Convert Shamela HTML to Markdown format for easier pattern matching.
+ *
+ * Transformations:
+ * - `<span data-type="title">text</span>` → `## text`
+ * - `<a href="inr://...">text</a>` → `text` (strip narrator links)
+ * - All other HTML tags → stripped
+ *
+ * Note: Content typically already has proper line breaks before title spans,
+ * so we don't add extra newlines around the ## header.
+ * Line ending normalization is handled by segmentPages.
+ *
+ * @param html - HTML content from Shamela
+ * @returns Markdown-formatted content
+ */
+declare const htmlToMarkdown: (html: string) => string;
+//#endregion
+export { parseContentRobust as a, splitPageBodyFromFooter as c, normalizeHtml as i, htmlToMarkdown as n, removeArabicNumericPageMarkers as o, mapPageCharacterContent as r, removeTagsExceptSpan as s, Line as t };
+//# sourceMappingURL=content-BCABDXRO.d.ts.map

package/dist/content-DlA9y7g5.js

@@ -0,0 +1,8 @@
+import{t as e}from"./constants-CSNUBkui.js";const t=/^[)\]\u00BB"”'’.,?!:\u061B\u060C\u061F\u06D4\u2026]+$/,n=e=>{let n=[];for(let r of e){let e=n[n.length-1];e&&t.test(r.text)?e.text+=r.text:n.push(r)}return n},r=e=>e.replace(/\r\n/g,`
+`).replace(/\r/g,`
+`).split(`
+`).map(e=>e.trim()).filter(Boolean),i=e=>r(e).map(e=>({text:e})),a=(e,t)=>{let n=RegExp(`${t}\\s*=\\s*("([^"]*)"|'([^']*)'|([^s>]+))`,`i`),r=e.match(n);if(r)return r[2]??r[3]??r[4]},o=e=>{let t=[],n=/<[^>]+>/g,r=0,i;for(i=n.exec(e);i;){i.index>r&&t.push({type:`text`,value:e.slice(r,i.index)});let o=i[0],s=/^<\//.test(o),c=o.match(/^<\/?\s*([a-zA-Z0-9:-]+)/),l=c?c[1].toLowerCase():``;if(s)t.push({name:l,type:`end`});else{let e={};e.id=a(o,`id`),e[`data-type`]=a(o,`data-type`),t.push({attributes:e,name:l,type:`start`})}r=n.lastIndex,i=n.exec(e)}return r<e.length&&t.push({type:`text`,value:e.slice(r)}),t},s=(e,t)=>{let n=e.trim();return n?t?{id:t,text:n}:{text:n}:null},c=e=>{for(let t=e.length-1;t>=0;t--){let n=e[t];if(n.isTitle&&n.id)return n.id}},l=(e,t)=>{if(!e)return;let n=e.split(`
+`);for(let e=0;e<n.length;e++){if(e>0){let e=s(t.currentText,t.currentId);e&&t.result.push(e),t.currentText=``,t.currentId=c(t.spanStack)||void 0}n[e]&&(t.currentText+=n[e])}},u=(e,t)=>{let n=e.attributes[`data-type`]===`title`,r;n&&(r=(e.attributes.id??``).replace(/^toc-/,``)),t.spanStack.push({id:r,isTitle:n}),n&&r&&!t.currentId&&(t.currentId=r)},d=e=>{if(e=e.replace(/\r\n/g,`
+`).replace(/\r/g,`
+`),!/<span[^>]*>/i.test(e))return n(i(e));let t=o(`<root>${e}</root>`),r={currentId:void 0,currentText:``,result:[],spanStack:[]};for(let e of t)e.type===`text`?l(e.value,r):e.type===`start`&&e.name===`span`?u(e,r):e.type===`end`&&e.name===`span`&&r.spanStack.pop();let a=s(r.currentText,r.currentId);return a&&r.result.push(a),n(r.result).filter(e=>e.text.length>0)},f=Object.entries(e).map(([e,t])=>({regex:new RegExp(e,`g`),replacement:t})),p=t=>{if(t===e)return f;let n=[];for(let e in t)n.push({regex:new RegExp(e,`g`),replacement:t[e]});return n},m=(t,n=e)=>{let r=p(n),i=t;for(let e=0;e<r.length;e++){let{regex:t,replacement:n}=r[e];i=i.replace(t,n)}return i},h=(e,t=`_________`)=>{let n=``,r=e.indexOf(t);return r>=0&&(n=e.slice(r+t.length),e=e.slice(0,r)),[e,n]},g=e=>e.replace(/(?: |\r){0,2}⦗[\u0660-\u0669]+⦘(?: |\r)?/g,` `),_=e=>(e=e.replace(/<a[^>]*>(.*?)<\/a>/gs,`$1`),e=e.replace(/<hadeeth[^>]*>|<\/hadeeth>|<hadeeth-\d+>/gs,``),e),v=e=>e.replace(/<hadeeth-\d+>/gi,`<span class="hadeeth">`).replace(/<\s*\/?\s*hadeeth\s*>/gi,`</span>`),y=e=>e.replace(/<span[^>]*data-type=["']title["'][^>]*>(.*?)<\/span>/gi,`## $1`).replace(/<a[^>]*href=["']inr:\/\/[^"']*["'][^>]*>(.*?)<\/a>/gi,`$1`).replace(/<[^>]*>/g,``);export{g as a,d as i,m as n,_ as o,v as r,h as s,y as t};
+//# sourceMappingURL=content-DlA9y7g5.js.map

package/dist/content-DlA9y7g5.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-DlA9y7g5.js","names":["out: Line[]","tokens: Token[]","match: RegExpExecArray | null","attributes: Record<string, string | undefined>","id: string | undefined"],"sources":["../src/content.ts"],"sourcesContent":["import { DEFAULT_MAPPING_RULES } from './utils/constants';\n\nexport type Line = {\n    id?: string;\n    text: string;\n};\n\nconst PUNCT_ONLY = /^[)\\]\\u00BB\"”'’.,?!:\\u061B\\u060C\\u061F\\u06D4\\u2026]+$/;\n\n/**\n * Merges punctuation-only lines into the preceding title when appropriate.\n *\n * @param lines - The processed line candidates to normalise\n * @returns A new array where dangling punctuation fragments are appended to titles\n */\nconst mergeDanglingPunctuation = (lines: Line[]): Line[] => {\n    const out: Line[] = [];\n    for (const item of lines) {\n        const last = out[out.length - 1];\n        if (last && PUNCT_ONLY.test(item.text)) {\n            last.text += item.text;\n        } else {\n            out.push(item);\n        }\n    }\n    return out;\n};\n\n/**\n * Normalises raw text into discrete line entries.\n *\n * @param text - Raw book content potentially containing inconsistent breaks\n * @returns An array of trimmed line strings with empty entries removed\n */\nconst splitIntoLines = (text: string) => {\n    const normalized = text.replace(/\\r\\n/g, '\\n').replace(/\\r/g, '\\n');\n\n    return normalized\n        .split('\\n')\n        .map((line) => line.trim())\n        .filter(Boolean);\n};\n\n/**\n * Converts plain text content into {@link Line} objects without title metadata.\n *\n * @param content - The text content to split into line structures\n * @returns A {@link Line} array wrapping each detected sentence fragment\n */\nconst processTextContent = (content: string): Line[] => {\n    return splitIntoLines(content).map((line) => ({ text: line }));\n};\n\n/**\n * Extracts an attribute value from the provided HTML tag string.\n *\n * @param tag - Raw HTML tag source\n * @param name - Attribute name to locate\n * @returns The attribute value when found; otherwise undefined\n */\nconst extractAttribute = (tag: string, name: string): string | undefined => {\n    const pattern = new RegExp(`${name}\\\\s*=\\\\s*(\"([^\"]*)\"|'([^']*)'|([^s>]+))`, 'i');\n    const match = tag.match(pattern);\n    if (!match) {\n        return undefined;\n    }\n    return match[2] ?? match[3] ?? match[4];\n};\n\ntype Token =\n    | { type: 'text'; value: string }\n    | { type: 'start'; name: string; attributes: Record<string, string | undefined> }\n    | { type: 'end'; name: string };\n\n/**\n * Breaks the provided HTML fragment into structural tokens.\n *\n * @param html - HTML fragment containing book content markup\n * @returns A token stream describing text and span boundaries\n */\nconst tokenize = (html: string): Token[] => {\n    const tokens: Token[] = [];\n    const tagRegex = /<[^>]+>/g;\n    let lastIndex = 0;\n    let match: RegExpExecArray | null;\n    match = tagRegex.exec(html);\n\n    while (match) {\n        if (match.index > lastIndex) {\n            tokens.push({ type: 'text', value: html.slice(lastIndex, match.index) });\n        }\n\n        const raw = match[0];\n        const isEnd = /^<\\//.test(raw);\n        const nameMatch = raw.match(/^<\\/?\\s*([a-zA-Z0-9:-]+)/);\n        const name = nameMatch ? nameMatch[1].toLowerCase() : '';\n\n        if (isEnd) {\n            tokens.push({ name, type: 'end' });\n        } else {\n            const attributes: Record<string, string | undefined> = {};\n            attributes.id = extractAttribute(raw, 'id');\n            attributes['data-type'] = extractAttribute(raw, 'data-type');\n            tokens.push({ attributes, name, type: 'start' });\n        }\n\n        lastIndex = tagRegex.lastIndex;\n        match = tagRegex.exec(html);\n    }\n\n    if (lastIndex < html.length) {\n        tokens.push({ type: 'text', value: html.slice(lastIndex) });\n    }\n\n    return tokens;\n};\n\n/**\n * Pushes the accumulated text as a new line to the result array.\n */\nconst createLine = (text: string, id?: string): Line | null => {\n    const trimmed = text.trim();\n    if (!trimmed) {\n        return null;\n    }\n    return id ? { id, text: trimmed } : { text: trimmed };\n};\n\n/**\n * Finds the active title ID from the span stack.\n */\nconst getActiveTitleId = (spanStack: Array<{ isTitle: boolean; id?: string }>): string | undefined => {\n    for (let i = spanStack.length - 1; i >= 0; i--) {\n        const entry = spanStack[i];\n        if (entry.isTitle && entry.id) {\n            return entry.id;\n        }\n    }\n};\n\n/**\n * Processes text content by handling line breaks and maintaining title context.\n */\nconst processTextWithLineBreaks = (\n    raw: string,\n    state: {\n        currentText: string;\n        currentId?: string;\n        result: Line[];\n        spanStack: Array<{ isTitle: boolean; id?: string }>;\n    },\n) => {\n    if (!raw) {\n        return;\n    }\n\n    const parts = raw.split('\\n');\n\n    for (let i = 0; i < parts.length; i++) {\n        // Push previous line when crossing a line break\n        if (i > 0) {\n            const line = createLine(state.currentText, state.currentId);\n            if (line) {\n                state.result.push(line);\n            }\n            state.currentText = '';\n\n            // Preserve title ID if still inside a title span\n            const activeTitleId = getActiveTitleId(state.spanStack);\n            state.currentId = activeTitleId || undefined;\n        }\n\n        // Append the text part\n        if (parts[i]) {\n            state.currentText += parts[i];\n        }\n    }\n};\n\n/**\n * Handles the start of a span tag, updating the stack and current ID.\n */\nconst handleSpanStart = (\n    token: { attributes: Record<string, string | undefined> },\n    state: {\n        currentId?: string;\n        spanStack: Array<{ isTitle: boolean; id?: string }>;\n    },\n) => {\n    const dataType = token.attributes['data-type'];\n    const isTitle = dataType === 'title';\n\n    let id: string | undefined;\n    if (isTitle) {\n        const rawId = token.attributes.id ?? '';\n        id = rawId.replace(/^toc-/, '');\n    }\n\n    state.spanStack.push({ id, isTitle });\n\n    // First title span on the current physical line wins\n    if (isTitle && id && !state.currentId) {\n        state.currentId = id;\n    }\n};\n\n/**\n * Parses Shamela HTML content into structured lines while preserving headings.\n *\n * @param content - The raw HTML markup representing a page\n * @returns An array of {@link Line} objects containing text and optional IDs\n */\nexport const parseContentRobust = (content: string): Line[] => {\n    // Normalize line endings first\n    content = content.replace(/\\r\\n/g, '\\n').replace(/\\r/g, '\\n');\n\n    // Fast path when there are no span tags at all\n    if (!/<span[^>]*>/i.test(content)) {\n        return mergeDanglingPunctuation(processTextContent(content));\n    }\n\n    const tokens = tokenize(`<root>${content}</root>`);\n    const state = {\n        currentId: undefined as string | undefined,\n        currentText: '',\n        result: [] as Line[],\n        spanStack: [] as Array<{ isTitle: boolean; id?: string }>,\n    };\n\n    // Process all tokens\n    for (const token of tokens) {\n        if (token.type === 'text') {\n            processTextWithLineBreaks(token.value, state);\n        } else if (token.type === 'start' && token.name === 'span') {\n            handleSpanStart(token, state);\n        } else if (token.type === 'end' && token.name === 'span') {\n            // Closing a span does NOT end the line; trailing text stays on the same line\n            state.spanStack.pop();\n        }\n    }\n\n    // Flush any trailing text\n    const finalLine = createLine(state.currentText, state.currentId);\n    if (finalLine) {\n        state.result.push(finalLine);\n    }\n\n    // Merge punctuation-only lines and drop empties\n    return mergeDanglingPunctuation(state.result).filter((line) => line.text.length > 0);\n};\n\nconst DEFAULT_COMPILED_RULES = Object.entries(DEFAULT_MAPPING_RULES).map(([pattern, replacement]) => ({\n    regex: new RegExp(pattern, 'g'),\n    replacement,\n}));\n\n/**\n * Compiles sanitisation rules into RegExp objects for reuse.\n *\n * @param rules - Key/value replacements used during sanitisation\n * @returns A list of compiled regular expression rules\n */\nconst getCompiledRules = (rules: Record<string, string>) => {\n    if (rules === DEFAULT_MAPPING_RULES) {\n        return DEFAULT_COMPILED_RULES;\n    }\n\n    const compiled = [];\n    for (const pattern in rules) {\n        compiled.push({\n            regex: new RegExp(pattern, 'g'),\n            replacement: rules[pattern],\n        });\n    }\n    return compiled;\n};\n\n/**\n * Sanitises page content by applying regex replacement rules.\n *\n * @param text - The text to clean\n * @param rules - Optional custom replacements, defaults to {@link DEFAULT_MAPPING_RULES}\n * @returns The sanitised content\n */\nexport const mapPageCharacterContent = (\n    text: string,\n    rules: Record<string, string> = DEFAULT_MAPPING_RULES,\n): string => {\n    const compiledRules = getCompiledRules(rules);\n\n    let content = text;\n    for (let i = 0; i < compiledRules.length; i++) {\n        const { regex, replacement } = compiledRules[i];\n        content = content.replace(regex, replacement);\n    }\n    return content;\n};\n\n/**\n * Splits a page body from its trailing footnotes using a marker string.\n *\n * @param content - Combined body and footnote text\n * @param footnoteMarker - Marker indicating the start of footnotes\n * @returns A tuple containing the page body followed by the footnote section\n */\nexport const splitPageBodyFromFooter = (content: string, footnoteMarker = '_________') => {\n    let footnote = '';\n    const indexOfFootnote = content.indexOf(footnoteMarker);\n\n    if (indexOfFootnote >= 0) {\n        footnote = content.slice(indexOfFootnote + footnoteMarker.length);\n        content = content.slice(0, indexOfFootnote);\n    }\n\n    return [content, footnote] as const;\n};\n\n/**\n * Removes Arabic numeral page markers enclosed in turtle ⦗ ⦘ brackets.\n * Replaces the marker along with up to two preceding whitespace characters\n * (space or carriage return) and up to one following whitespace character\n * with a single space.\n *\n * @param text - Text potentially containing page markers\n * @returns The text with numeric markers replaced by a single space\n */\nexport const removeArabicNumericPageMarkers = (text: string) => {\n    return text.replace(/(?: |\\r){0,2}⦗[\\u0660-\\u0669]+⦘(?: |\\r)?/g, ' ');\n};\n\n/**\n * Removes anchor and hadeeth tags from the content while preserving spans.\n *\n * @param content - HTML string containing various tags\n * @returns The content with only span tags retained\n */\nexport const removeTagsExceptSpan = (content: string) => {\n    // Remove <a> tags and their content, keeping only the text inside\n    content = content.replace(/<a[^>]*>(.*?)<\\/a>/gs, '$1');\n\n    // Remove <hadeeth> tags (both self-closing, with content, and numbered)\n    content = content.replace(/<hadeeth[^>]*>|<\\/hadeeth>|<hadeeth-\\d+>/gs, '');\n\n    return content;\n};\n\n/**\n * Normalizes Shamela HTML for CSS styling:\n * - Converts <hadeeth-N> to <span class=\"hadeeth\">\n * - Converts </hadeeth> or standalone <hadeeth> to </span>\n */\nexport const normalizeHtml = (html: string): string => {\n    return html.replace(/<hadeeth-\\d+>/gi, '<span class=\"hadeeth\">').replace(/<\\s*\\/?\\s*hadeeth\\s*>/gi, '</span>');\n};\n\n/**\n * Convert Shamela HTML to Markdown format for easier pattern matching.\n *\n * Transformations:\n * - `<span data-type=\"title\">text</span>` → `## text`\n * - `<a href=\"inr://...\">text</a>` → `text` (strip narrator links)\n * - All other HTML tags → stripped\n *\n * Note: Content typically already has proper line breaks before title spans,\n * so we don't add extra newlines around the ## header.\n * Line ending normalization is handled by segmentPages.\n *\n * @param html - HTML content from Shamela\n * @returns Markdown-formatted content\n */\nexport const htmlToMarkdown = (html: string): string => {\n    return (\n        html\n            // Convert title spans to markdown headers (no extra newlines - content already has them)\n            .replace(/<span[^>]*data-type=[\"']title[\"'][^>]*>(.*?)<\\/span>/gi, '## $1')\n            // Strip narrator links but keep text\n            .replace(/<a[^>]*href=[\"']inr:\\/\\/[^\"']*[\"'][^>]*>(.*?)<\\/a>/gi, '$1')\n            // Strip all remaining HTML tags\n            .replace(/<[^>]*>/g, '')\n    );\n};\n"],"mappings":"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"}

package/dist/content.d.ts

@@ -0,0 +1,2 @@
+import { a as parseContentRobust, c as splitPageBodyFromFooter, i as normalizeHtml, n as htmlToMarkdown, o as removeArabicNumericPageMarkers, r as mapPageCharacterContent, s as removeTagsExceptSpan, t as Line } from "./content-BCABDXRO.js";
+export { Line, htmlToMarkdown, mapPageCharacterContent, normalizeHtml, parseContentRobust, removeArabicNumericPageMarkers, removeTagsExceptSpan, splitPageBodyFromFooter };

package/dist/content.js

@@ -0,0 +1 @@
+import{a as e,i as t,n,o as r,r as i,s as a,t as o}from"./content-DlA9y7g5.js";export{o as htmlToMarkdown,n as mapPageCharacterContent,i as normalizeHtml,t as parseContentRobust,e as removeArabicNumericPageMarkers,r as removeTagsExceptSpan,a as splitPageBodyFromFooter};

package/dist/index.d.ts

@@ -1,228 +1,8 @@
-//#region src/db/types.d.ts
+import { a as parseContentRobust, c as splitPageBodyFromFooter, i as normalizeHtml, n as htmlToMarkdown, o as removeArabicNumericPageMarkers, r as mapPageCharacterContent, s as removeTagsExceptSpan, t as Line } from "./content-BCABDXRO.js";
+import { a as DownloadBookOptions, c as GetBookMetadataResponsePayload, d as OutputOptions, f as Page, h as Title, i as Category, l as GetMasterMetadataResponsePayload, m as ShamelaConfigKey, n as Book, o as DownloadMasterOptions, p as ShamelaConfig, r as BookData, s as GetBookMetadataOptions, t as Author, u as MasterData } from "./types-BRXOrgNv.js";
 
-/**
- * A record that can be deleted by patches.
- */
-type Deletable = {
-  /** Indicates if it was deleted in the patch if it is set to '1 */
-  is_deleted?: string;
-};
-type Unique = {
-  /** Unique identifier */
-  id: number;
-};
-/**
- * Database row structure for the author table.
- */
-type AuthorRow = Deletable & Unique & {
-  /** Author biography */
-  biography: string;
-  /** Death year */
-  death_number: string;
-  /** The death year as a text */
-  death_text: string;
-  /** Author name */
-  name: string;
-};
-/**
- * Database row structure for the book table.
- */
-type BookRow = Deletable & Unique & {
-  /** Serialized author ID(s) "2747, 3147" or "513" */
-  author: string;
-  /** Bibliography information */
-  bibliography: string;
-  /** Category ID */
-  category: string;
-  /** Publication date (or 99999 for unavailable) */
-  date: string;
-  /** Hint or description */
-  hint: string;
-  /** Major version */
-  major_release: string;
-  /** Serialized metadata */
-  metadata: string;
-  /** Minor version */
-  minor_release: string;
-  /** Book name */
-  name: string;
-  /** Serialized PDF links */
-  pdf_links: string;
-  /** Printed flag */
-  printed: string;
-  /** Book type */
-  type: string;
-};
-/**
- * Database row structure for the category table.
- */
-type CategoryRow = Deletable & Unique & {
-  /** Category name */
-  name: string;
-  /** Category order in the list to show. */
-  order: string;
-};
-/**
- * Database row structure for the page table.
- */
-type PageRow = Deletable & Unique & {
-  /** Page content */
-  content: string;
-  /** Page number */
-  number: string | null;
-  /** Page reference */
-  page: string | null;
-  /** Part number */
-  part: string | null;
-  /** Additional metadata */
-  services: string | null;
-};
-/**
- * Database row structure for the title table.
- */
-type TitleRow = Deletable & Unique & {
-  /** Title content */
-  content: string;
-  /** Page number */
-  page: string;
-  /** Parent title ID */
-  parent: string | null;
-};
-//#endregion
-//#region src/types.d.ts
-/**
- * Represents an author entity.
- */
-type Author = AuthorRow;
-/**
- * Represents a book entity.
- */
-type Book = BookRow;
-/**
- * A category for a book.
- */
-type Category = CategoryRow;
-/**
- * A page in a book.
- */
-type Page = Pick<PageRow, 'id' | 'content'> & {
-  page?: number;
-  part?: string;
-  number?: string;
-};
-/**
- * A title heading in a book.
- */
-type Title = Pick<TitleRow, 'id' | 'content'> & {
-  page: number;
-  parent?: number;
-};
-/**
- * Represents book content data.
- */
-type BookData = {
-  /** Array of pages in the book */
-  pages: Page[];
-  /** Array of titles/chapters */
-  titles: Title[];
-};
-/**
- * Master data structure containing all core entities.
- */
-type MasterData = {
-  /** Array of all authors */
-  authors: Author[];
-  /** Array of all books */
-  books: Book[];
-  /** Array of all categories */
-  categories: Category[];
-  /** Version number for the downloaded master database */
-  version: number;
-};
-/**
- * Options for downloading a book.
- */
-type DownloadBookOptions = {
-  /** Optional book metadata */
-  bookMetadata?: GetBookMetadataResponsePayload;
-  /** Output file configuration */
-  outputFile: OutputOptions;
-};
-/**
- * Options for downloading master data.
- */
-type DownloadMasterOptions = {
-  /** Optional master metadata */
-  masterMetadata?: GetMasterMetadataResponsePayload;
-  /** Output file configuration */
-  outputFile: OutputOptions;
-};
-/**
- * Options for getting book metadata.
- */
-type GetBookMetadataOptions = {
-  /** Major version number */
-  majorVersion: number;
-  /** Minor version number */
-  minorVersion: number;
-};
-/**
- * Response payload for book metadata requests.
- */
-type GetBookMetadataResponsePayload = {
-  /** Major release version */
-  majorRelease: number;
-  /** URL for major release download */
-  majorReleaseUrl: string;
-  /** Optional minor release version */
-  minorRelease?: number;
-  /** Optional URL for minor release download */
-  minorReleaseUrl?: string;
-};
-/**
- * Response payload for master metadata requests.
- */
-type GetMasterMetadataResponsePayload = {
-  /** Download URL */
-  url: string;
-  /** Version number */
-  version: number;
-};
-type NodeJSOutput = {
-  /** Output file path (Node.js only) */
-  path: string;
-  writer?: never;
-};
-type CustomOutput = {
-  /** Custom writer used when path is not provided */
-  writer: (payload: string | Uint8Array) => Promise<void> | void;
-  path?: undefined;
-};
-/**
- * Output file options.
- */
-type OutputOptions = NodeJSOutput | CustomOutput;
-/**
- * Runtime configuration for the library.
- */
-type ShamelaConfig = {
-  /** API key used to authenticate against Shamela services */
-  apiKey?: string;
-  /** Endpoint used for book metadata */
-  booksEndpoint?: string;
-  /** Endpoint used for master metadata */
-  masterPatchEndpoint?: string;
-  /** Optional override for the sql.js wasm asset location */
-  sqlJsWasmUrl?: string;
-  /** Optional custom fetch implementation for environments without a global fetch */
-  fetchImplementation?: typeof fetch;
-};
-/**
- * Valid configuration keys.
- */
-type ShamelaConfigKey = keyof ShamelaConfig;
-//#endregion
 //#region src/api.d.ts
+
 /**
  * Retrieves metadata for a specific book from the Shamela API.
  *
@@ -399,51 +179,5 @@ declare const configure: (config: ConfigureOptions) => void;
  */
 declare const resetConfig: () => void;
 //#endregion
-//#region src/content.d.ts
-type Line = {
-  id?: string;
-  text: string;
-};
-/**
- * Parses Shamela HTML content into structured lines while preserving headings.
- *
- * @param content - The raw HTML markup representing a page
- * @returns An array of {@link Line} objects containing text and optional IDs
- */
-declare const parseContentRobust: (content: string) => Line[];
-/**
- * Sanitises page content by applying regex replacement rules.
- *
- * @param text - The text to clean
- * @param rules - Optional custom replacements, defaults to {@link DEFAULT_SANITIZATION_RULES}
- * @returns The sanitised content
- */
-declare const sanitizePageContent: (text: string, rules?: Record<string, string>) => string;
-/**
- * Splits a page body from its trailing footnotes using a marker string.
- *
- * @param content - Combined body and footnote text
- * @param footnoteMarker - Marker indicating the start of footnotes
- * @returns A tuple containing the page body followed by the footnote section
- */
-declare const splitPageBodyFromFooter: (content: string, footnoteMarker?: string) => readonly [string, string];
-/**
- * Removes Arabic numeral page markers enclosed in turtle ⦗ ⦘ brackets.
- * Replaces the marker along with up to two preceding whitespace characters
- * (space or carriage return) and up to one following whitespace character
- * with a single space.
- *
- * @param text - Text potentially containing page markers
- * @returns The text with numeric markers replaced by a single space
- */
-declare const removeArabicNumericPageMarkers: (text: string) => string;
-/**
- * Removes anchor and hadeeth tags from the content while preserving spans.
- *
- * @param content - HTML string containing various tags
- * @returns The content with only span tags retained
- */
-declare const removeTagsExceptSpan: (content: string) => string;
-//#endregion
-export { Author, Book, BookData, Category, type ConfigureOptions, DownloadBookOptions, DownloadMasterOptions, GetBookMetadataOptions, GetBookMetadataResponsePayload, GetMasterMetadataResponsePayload, Line, type Logger, MasterData, OutputOptions, Page, ShamelaConfig, ShamelaConfigKey, Title, configure, downloadBook, downloadMasterDatabase, getBook, getBookMetadata, getCoverUrl, getMaster, getMasterMetadata, parseContentRobust, removeArabicNumericPageMarkers, removeTagsExceptSpan, resetConfig, sanitizePageContent, splitPageBodyFromFooter };
+export { Author, Book, BookData, Category, type ConfigureOptions, DownloadBookOptions, DownloadMasterOptions, GetBookMetadataOptions, GetBookMetadataResponsePayload, GetMasterMetadataResponsePayload, Line, type Logger, MasterData, OutputOptions, Page, ShamelaConfig, ShamelaConfigKey, Title, configure, downloadBook, downloadMasterDatabase, getBook, getBookMetadata, getCoverUrl, getMaster, getMasterMetadata, htmlToMarkdown, mapPageCharacterContent, normalizeHtml, parseContentRobust, removeArabicNumericPageMarkers, removeTagsExceptSpan, resetConfig, splitPageBodyFromFooter };
 //# sourceMappingURL=index.d.ts.map