dicta-nakdan 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moshe Malka
+
+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,46 @@
+# dicta-nakdan
+
+Typed, zero-dependency client for **[Dicta](https://dicta.org.il/)'s free Nakdan API** — automatic Hebrew **vocalization** (adding niqqud / nikud to unpointed text), with per-word alternatives and confidence.
+
+```
+npm install dicta-nakdan
+```
+
+## Why
+
+Adding niqqud (vowel points) to Hebrew text is genuinely hard — it's a context-dependent NLP problem, not a lookup. Dicta, a nonprofit, offers a remarkably good vocalizer for free, but its raw API returns a terse word-array format with no types and no documented contract. This wraps it in a clean, typed TypeScript API and normalizes the response — so you can add nikud in one call.
+
+```ts
+import { vocalize, nakdan } from "dicta-nakdan";
+
+await vocalize("שלום עולם");  // "שָׁלוֹם עוֹלָם"
+
+const r = await nakdan("בראשית ברא אלהים", { genre: "rabbinic" });
+r.text;                        // the fully pointed string
+r.words[0].vocalized;          // "בְּרֵאשִׁית"
+r.words[0].options;            // alternative vocalizations Dicta considered
+r.words[0].confident;          // whether Dicta was sure
+```
+
+## API
+
+- **`vocalize(text, opts?)`** → the pointed string (the common case).
+- **`nakdan(text, opts?)`** → `{ text, words }`, where each word is `{ word, vocalized, isSeparator, options, confident }` — separators (spaces, punctuation) are preserved in order so you can reconstruct or re-render the text.
+
+**`opts`**: `genre` (`"modern"` default, `"rabbinic"`, or `"poetry"`), `fetch` (inject for tests/proxies), `endpoint` (override the pinned API URL), `timeoutMs` (default 30000). Empty or non-Hebrew input, HTTP failures, timeouts, and unexpected responses all throw `NakdanError`.
+
+The mocked test suite runs offline against a captured real response; `npm run smoke` calls the live API.
+
+## A note on the upstream service
+
+Dicta is a nonprofit and the Nakdan API is offered free with no formal published contract; its endpoints are version-numbered. This package pins a working endpoint and lets you override it via `opts.endpoint` if Dicta rolls a new version. Please use the service considerately.
+
+## Related
+
+By the same author: [`mispar`](https://github.com/moshejs/mispar) (Hebrew gematria, 13 classical methods) and [Gamatria](https://gamatria.vercel.app), a gematria search engine over the Tanakh and Mishnah.
+
+## Author
+
+Built by **[Moshe Malka](https://moshemalka.com)** — engineering leader in New York City. Studio work at [Quentin.Code](https://www.quentin.software/).
+
+MIT © Moshe Malka

package/dist/index.cjs

@@ -0,0 +1,101 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  NakdanError: () => NakdanError,
+  nakdan: () => nakdan,
+  vocalize: () => vocalize
+});
+module.exports = __toCommonJS(index_exports);
+var NakdanError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.name = "NakdanError";
+    this.status = status;
+  }
+};
+var DEFAULT_ENDPOINT = "https://nakdan-2-0.loadbalancer.dicta.org.il/api";
+function normalize(raw) {
+  const words = raw.map((r) => {
+    const isSeparator = r.sep === true;
+    const options = Array.isArray(r.options) ? r.options : [];
+    const vocalized = isSeparator ? r.word : options[0] ?? r.word;
+    return {
+      word: r.word,
+      vocalized,
+      isSeparator,
+      options,
+      confident: r.fconfident === true
+    };
+  });
+  return { text: words.map((w) => w.vocalized).join(""), words };
+}
+var HEBREW_RE = /[֐-׿]/;
+async function nakdan(text, opts = {}) {
+  if (typeof text !== "string" || text.trim() === "") {
+    throw new NakdanError("nakdan requires non-empty text");
+  }
+  if (!HEBREW_RE.test(text)) {
+    throw new NakdanError("nakdan requires Hebrew text (no Hebrew characters found)");
+  }
+  const doFetch = opts.fetch ?? globalThis.fetch;
+  const endpoint = opts.endpoint ?? DEFAULT_ENDPOINT;
+  const genre = opts.genre ?? "modern";
+  const timeoutMs = opts.timeoutMs ?? 3e4;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let res;
+  try {
+    res = await doFetch(endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json" },
+      body: JSON.stringify({ task: "nakdan", genre, data: text, addmorph: false, keepqq: false }),
+      signal: controller.signal
+    });
+  } catch (err) {
+    if (err instanceof Error && err.name === "AbortError") {
+      throw new NakdanError(`Nakdan request timed out after ${timeoutMs}ms`);
+    }
+    throw new NakdanError(`Nakdan request failed: ${err.message}`);
+  } finally {
+    clearTimeout(timer);
+  }
+  if (!res.ok) throw new NakdanError(`Nakdan request failed with HTTP ${res.status}`, res.status);
+  let raw;
+  try {
+    raw = await res.json();
+  } catch {
+    throw new NakdanError("Nakdan returned a non-JSON response");
+  }
+  if (!Array.isArray(raw)) {
+    throw new NakdanError("Unexpected Nakdan response shape (expected an array of words)");
+  }
+  return normalize(raw);
+}
+async function vocalize(text, opts = {}) {
+  return (await nakdan(text, opts)).text;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  NakdanError,
+  nakdan,
+  vocalize
+});

package/dist/index.d.cts

@@ -0,0 +1,70 @@
+/**
+ * dicta-nakdan — typed, zero-dependency client for Dicta's free Nakdan
+ * (automatic Hebrew vocalization / niqqud) API.
+ *
+ * Send unpointed Hebrew text, get it back with niqqud, plus per-word
+ * alternatives and a confidence flag — normalized from Dicta's raw
+ * word-array format into a clean TypeScript shape.
+ *
+ * Dicta (dicta.org.il) is a nonprofit; the tools are free. There is no formal
+ * published API contract, and the service's endpoints are version-numbered,
+ * so a drift-resistant default endpoint is pinned and overridable.
+ */
+/** Text genre — Dicta tunes vocalization to the register. */
+type Genre = "modern" | "rabbinic" | "poetry";
+interface NakdanOptions {
+    /** Custom fetch implementation (testing, proxies). Defaults to global fetch. */
+    fetch?: typeof globalThis.fetch;
+    /** Override the API endpoint (defaults to the pinned Nakdan endpoint). */
+    endpoint?: string;
+    /** Text genre. Default "modern". */
+    genre?: Genre;
+    /** Request timeout in milliseconds. Default 30000. */
+    timeoutMs?: number;
+}
+/** One token in the Nakdan result. */
+interface NakdanWord {
+    /** The token text. For separators this is the whitespace/punctuation itself. */
+    word: string;
+    /** The vocalized (pointed) form — Dicta's top choice. Equals `word` for separators. */
+    vocalized: string;
+    /** True for whitespace/punctuation between words. */
+    isSeparator: boolean;
+    /** Alternative vocalizations Dicta considered (most likely first), if any. */
+    options: string[];
+    /** Dicta's confidence in the chosen vocalization (word tokens only). */
+    confident: boolean;
+}
+interface NakdanResult {
+    /** The fully vocalized text (all tokens' top choices concatenated). */
+    text: string;
+    /** Per-token detail, including separators, in order. */
+    words: NakdanWord[];
+}
+declare class NakdanError extends Error {
+    readonly status?: number;
+    constructor(message: string, status?: number);
+}
+/**
+ * Vocalize Hebrew text, returning the full result (text + per-word detail).
+ *
+ * ```ts
+ * const r = await nakdan("שלום עולם");
+ * r.text;              // "שָׁלוֹם עוֹלָם"
+ * r.words[0].options;  // alternative vocalizations of the first word
+ * ```
+ *
+ * @throws {NakdanError} on empty/non-Hebrew input, network failure, timeout,
+ *   or an unexpected response shape.
+ */
+declare function nakdan(text: string, opts?: NakdanOptions): Promise<NakdanResult>;
+/**
+ * Vocalize Hebrew text and return just the pointed string — the common case.
+ *
+ * ```ts
+ * await vocalize("שלום עולם"); // "שָׁלוֹם עוֹלָם"
+ * ```
+ */
+declare function vocalize(text: string, opts?: NakdanOptions): Promise<string>;
+
+export { type Genre, NakdanError, type NakdanOptions, type NakdanResult, type NakdanWord, nakdan, vocalize };

package/dist/index.d.ts

@@ -0,0 +1,70 @@
+/**
+ * dicta-nakdan — typed, zero-dependency client for Dicta's free Nakdan
+ * (automatic Hebrew vocalization / niqqud) API.
+ *
+ * Send unpointed Hebrew text, get it back with niqqud, plus per-word
+ * alternatives and a confidence flag — normalized from Dicta's raw
+ * word-array format into a clean TypeScript shape.
+ *
+ * Dicta (dicta.org.il) is a nonprofit; the tools are free. There is no formal
+ * published API contract, and the service's endpoints are version-numbered,
+ * so a drift-resistant default endpoint is pinned and overridable.
+ */
+/** Text genre — Dicta tunes vocalization to the register. */
+type Genre = "modern" | "rabbinic" | "poetry";
+interface NakdanOptions {
+    /** Custom fetch implementation (testing, proxies). Defaults to global fetch. */
+    fetch?: typeof globalThis.fetch;
+    /** Override the API endpoint (defaults to the pinned Nakdan endpoint). */
+    endpoint?: string;
+    /** Text genre. Default "modern". */
+    genre?: Genre;
+    /** Request timeout in milliseconds. Default 30000. */
+    timeoutMs?: number;
+}
+/** One token in the Nakdan result. */
+interface NakdanWord {
+    /** The token text. For separators this is the whitespace/punctuation itself. */
+    word: string;
+    /** The vocalized (pointed) form — Dicta's top choice. Equals `word` for separators. */
+    vocalized: string;
+    /** True for whitespace/punctuation between words. */
+    isSeparator: boolean;
+    /** Alternative vocalizations Dicta considered (most likely first), if any. */
+    options: string[];
+    /** Dicta's confidence in the chosen vocalization (word tokens only). */
+    confident: boolean;
+}
+interface NakdanResult {
+    /** The fully vocalized text (all tokens' top choices concatenated). */
+    text: string;
+    /** Per-token detail, including separators, in order. */
+    words: NakdanWord[];
+}
+declare class NakdanError extends Error {
+    readonly status?: number;
+    constructor(message: string, status?: number);
+}
+/**
+ * Vocalize Hebrew text, returning the full result (text + per-word detail).
+ *
+ * ```ts
+ * const r = await nakdan("שלום עולם");
+ * r.text;              // "שָׁלוֹם עוֹלָם"
+ * r.words[0].options;  // alternative vocalizations of the first word
+ * ```
+ *
+ * @throws {NakdanError} on empty/non-Hebrew input, network failure, timeout,
+ *   or an unexpected response shape.
+ */
+declare function nakdan(text: string, opts?: NakdanOptions): Promise<NakdanResult>;
+/**
+ * Vocalize Hebrew text and return just the pointed string — the common case.
+ *
+ * ```ts
+ * await vocalize("שלום עולם"); // "שָׁלוֹם עוֹלָם"
+ * ```
+ */
+declare function vocalize(text: string, opts?: NakdanOptions): Promise<string>;
+
+export { type Genre, NakdanError, type NakdanOptions, type NakdanResult, type NakdanWord, nakdan, vocalize };

package/dist/index.js

@@ -0,0 +1,74 @@
+// src/index.ts
+var NakdanError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.name = "NakdanError";
+    this.status = status;
+  }
+};
+var DEFAULT_ENDPOINT = "https://nakdan-2-0.loadbalancer.dicta.org.il/api";
+function normalize(raw) {
+  const words = raw.map((r) => {
+    const isSeparator = r.sep === true;
+    const options = Array.isArray(r.options) ? r.options : [];
+    const vocalized = isSeparator ? r.word : options[0] ?? r.word;
+    return {
+      word: r.word,
+      vocalized,
+      isSeparator,
+      options,
+      confident: r.fconfident === true
+    };
+  });
+  return { text: words.map((w) => w.vocalized).join(""), words };
+}
+var HEBREW_RE = /[֐-׿]/;
+async function nakdan(text, opts = {}) {
+  if (typeof text !== "string" || text.trim() === "") {
+    throw new NakdanError("nakdan requires non-empty text");
+  }
+  if (!HEBREW_RE.test(text)) {
+    throw new NakdanError("nakdan requires Hebrew text (no Hebrew characters found)");
+  }
+  const doFetch = opts.fetch ?? globalThis.fetch;
+  const endpoint = opts.endpoint ?? DEFAULT_ENDPOINT;
+  const genre = opts.genre ?? "modern";
+  const timeoutMs = opts.timeoutMs ?? 3e4;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let res;
+  try {
+    res = await doFetch(endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json" },
+      body: JSON.stringify({ task: "nakdan", genre, data: text, addmorph: false, keepqq: false }),
+      signal: controller.signal
+    });
+  } catch (err) {
+    if (err instanceof Error && err.name === "AbortError") {
+      throw new NakdanError(`Nakdan request timed out after ${timeoutMs}ms`);
+    }
+    throw new NakdanError(`Nakdan request failed: ${err.message}`);
+  } finally {
+    clearTimeout(timer);
+  }
+  if (!res.ok) throw new NakdanError(`Nakdan request failed with HTTP ${res.status}`, res.status);
+  let raw;
+  try {
+    raw = await res.json();
+  } catch {
+    throw new NakdanError("Nakdan returned a non-JSON response");
+  }
+  if (!Array.isArray(raw)) {
+    throw new NakdanError("Unexpected Nakdan response shape (expected an array of words)");
+  }
+  return normalize(raw);
+}
+async function vocalize(text, opts = {}) {
+  return (await nakdan(text, opts)).text;
+}
+export {
+  NakdanError,
+  nakdan,
+  vocalize
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "dicta-nakdan",
+  "version": "1.0.0",
+  "description": "Typed, zero-dependency client for Dicta's free Nakdan API — automatic Hebrew vocalization (niqqud) with per-word alternatives. Add nikud to unpointed Hebrew text.",
+  "keywords": [
+    "hebrew",
+    "nakdan",
+    "niqqud",
+    "nikud",
+    "vocalization",
+    "diacritics",
+    "dicta",
+    "hebrew-nlp",
+    "judaica",
+    "torah",
+    "api-client"
+  ],
+  "homepage": "https://moshemalka.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moshejs/dicta-nakdan.git"
+  },
+  "bugs": "https://github.com/moshejs/dicta-nakdan/issues",
+  "author": "Moshe Malka <hello@moshemalka.com> (https://moshemalka.com)",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "smoke": "node scripts/smoke.mjs",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.2.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}