altalandi 0.6.2 → 0.6.3

package/client.mjs

@@ -1,258 +1,260 @@
-const DEFAULT_BASE_URL = "https://altalandi.is/api";
-const DEFAULT_TIMEOUT_MS = 300_000;
-const REQUEST_FIELDS = [
-  "sourceLang",
-  "domain",
-  "register",
-  "preserveMeaning",
-  "scoreNativeness",
-  "onlyImprove",
-  "polishPass",
-  "writer",
-  "scoring",
-  "glossary",
-  "returnDiffs",
-  "contribute",
-];
-// /v1/refine/batch takes fewer options: no writer/scoring tiers, polish or diffs switch.
-const BATCH_REQUEST_FIELDS = [
-  "sourceLang",
-  "domain",
-  "register",
-  "preserveMeaning",
-  "scoreNativeness",
-  "onlyImprove",
-  "glossary",
-  "autoTerminology",
-  "contribute",
-];
-
-export class AltalandiError extends Error {
-  constructor(message, { code = "ALTALANDI_ERROR", status, retryAfterMs } = {}) {
-    super(message);
-    this.name = "AltalandiError";
-    this.code = code;
-    if (Number.isInteger(status)) this.status = status;
-    if (Number.isFinite(retryAfterMs)) this.retryAfterMs = retryAfterMs;
-  }
-}
-
-/** Retry-After as milliseconds: delay-seconds or an HTTP date. */
-function retryAfterMs(response) {
-  const value = response?.headers?.get?.("retry-after");
-  if (!value) return undefined;
-  if (/^\s*\d+\s*$/.test(value)) return Number(value) * 1000;
-  const at = Date.parse(value);
-  return Number.isFinite(at) ? Math.max(0, at - Date.now()) : undefined;
-}
-
-export class MeaningVerificationError extends AltalandiError {
-  constructor(verdict) {
-    const changed = verdict === false;
-    super(
-      changed
-        ? "Altalandi could not preserve the input meaning."
-        : "Altalandi did not return a verified meaning verdict.",
-      { code: changed ? "MEANING_NOT_PRESERVED" : "MEANING_UNVERIFIED" },
-    );
-    this.name = "MeaningVerificationError";
-    this.verdict = verdict === false ? false : null;
-  }
-}
-
-function env(name) {
-  if (typeof process === "undefined" || !process.env) return undefined;
-  return process.env[name];
-}
-
-function cleanText(value, secret = "") {
-  if (typeof value !== "string") return "";
-  let cleaned = value.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim();
-  if (secret) cleaned = cleaned.split(secret).join("[redacted]");
-  return cleaned.slice(0, 300);
-}
-
-function errorDetail(payload) {
-  const detail = payload?.detail;
-  if (typeof detail === "string") return detail;
-  if (Array.isArray(detail)) {
-    return detail
-      .map((entry) => (typeof entry?.msg === "string" ? entry.msg : ""))
-      .filter(Boolean)
-      .join("; ");
-  }
-  return "";
-}
-
-function requestBody(text, options) {
-  const body = { text };
-  for (const field of REQUEST_FIELDS) {
-    if (options[field] !== undefined) body[field] = options[field];
-  }
-  return body;
-}
-
-/** POST a JSON body to `${baseUrl}${route}` with the key, base URL, timeout and
- *  error handling every call shares. Returns the payload when `validShape`
- *  accepts it; throws an AltalandiError (with status and Retry-After) otherwise. */
-async function post(route, body, options, validShape) {
-  const explicitKey = options.apiKey;
-  const selectedKey = explicitKey === undefined ? env("ALTALANDI_API_KEY") : explicitKey;
-  if (selectedKey !== undefined && typeof selectedKey !== "string") {
-    throw new AltalandiError("Altalandi apiKey must be a string.", { code: "INVALID_CONFIG" });
-  }
-  const apiKey = selectedKey?.trim();
-  if (!apiKey) {
-    throw new AltalandiError(
-      "No Altalandi API key. Set ALTALANDI_API_KEY or pass apiKey explicitly.",
-      { code: "MISSING_API_KEY" },
-    );
-  }
-
-  const selectedBaseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
-  if (typeof selectedBaseUrl !== "string") {
-    throw new AltalandiError("Altalandi baseUrl must be a string.", { code: "INVALID_CONFIG" });
-  }
-  const baseUrl = selectedBaseUrl.trim().replace(/\/+$/, "");
-  if (!baseUrl) {
-    throw new AltalandiError("Altalandi baseUrl must not be empty.", { code: "INVALID_CONFIG" });
-  }
-
-  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
-    throw new AltalandiError("Altalandi timeoutMs must be a positive number.", {
-      code: "INVALID_CONFIG",
-    });
-  }
-
-  const fetchImpl = options.fetch ?? globalThis.fetch;
-  if (typeof fetchImpl !== "function") {
-    throw new AltalandiError("This runtime does not provide fetch.", { code: "INVALID_CONFIG" });
-  }
-
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    let response;
-    try {
-      response = await fetchImpl(`${baseUrl}${route}`, {
-        method: "POST",
-        headers: {
-          "content-type": "application/json",
-          authorization: `Bearer ${apiKey}`,
-        },
-        body: JSON.stringify(body),
-        signal: controller.signal,
-      });
-    } catch {
-      if (controller.signal.aborted) {
-        throw new AltalandiError(`Altalandi timed out after ${timeoutMs} ms.`, {
-          code: "TIMEOUT",
-        });
-      }
-      throw new AltalandiError("Altalandi could not reach the API.", { code: "NETWORK_ERROR" });
-    }
-
-    let raw = "";
-    try {
-      raw = await response.text();
-    } catch {
-      if (controller.signal.aborted) {
-        throw new AltalandiError(`Altalandi timed out after ${timeoutMs} ms.`, {
-          code: "TIMEOUT",
-        });
-      }
-      if (response.ok) {
-        throw new AltalandiError("Altalandi could not read the API response.", {
-          code: "INVALID_RESPONSE",
-          status: response.status,
-        });
-      }
-      // The HTTP status remains useful when an error response has no readable body.
-    }
-
-    let payload;
-    if (raw) {
-      try {
-        payload = JSON.parse(raw);
-      } catch {
-        if (response.ok) {
-          throw new AltalandiError("Altalandi returned an invalid JSON response.", {
-            code: "INVALID_RESPONSE",
-            status: response.status,
-          });
-        }
-      }
-    }
-
-    if (!response.ok) {
-      const status = Number.isInteger(response.status) ? response.status : 0;
-      const statusText = cleanText(response.statusText);
-      const detail = cleanText(errorDetail(payload), apiKey);
-      const suffix = detail || statusText;
-      throw new AltalandiError(
-        `Altalandi API request failed (${status || "unknown status"})${suffix ? `: ${suffix}` : "."}`,
-        { code: "API_ERROR", status, retryAfterMs: retryAfterMs(response) },
-      );
-    }
-
-    if (!payload || typeof payload !== "object" || Array.isArray(payload) || !validShape(payload)) {
-      throw new AltalandiError("Altalandi returned an invalid response shape.", {
-        code: "INVALID_RESPONSE",
-        status: response.status,
-      });
-    }
-
-    return payload;
-  } finally {
-    clearTimeout(timeout);
-  }
-}
-
-/**
- * Refine English or Icelandic text through the hosted Altalandi API.
- * Client settings (`apiKey`, `baseUrl`, `timeoutMs`, `fetch`) are never sent in
- * the JSON body. The full API result is returned without weakening its verdict.
- */
-export async function refine(text, options = {}) {
-  if (typeof text !== "string" || !text.trim()) {
-    throw new AltalandiError("Altalandi requires non-empty text.", { code: "INVALID_INPUT" });
-  }
-  return post("/v1/refine", requestBody(text, options), options, (p) => typeof p.output === "string");
-}
-
-/**
- * Refine many short strings in one call (POST /v1/refine/batch): at most 500
- * items of at most 2,000 characters each, 20,000 characters together. Each item
- * comes back with its own output and meaning verdict; an item with `error` came
- * back unchanged and was not billed. Same key, limits and errors as refine().
- */
-export async function refineBatch(items, options = {}) {
-  if (!Array.isArray(items) || !items.length
-    || !items.every((it) => it && typeof it.text === "string" && (it.id === undefined || typeof it.id === "string"))) {
-    throw new AltalandiError("Altalandi refineBatch requires a non-empty list of { id?, text } items.", {
-      code: "INVALID_INPUT",
-    });
-  }
-  const body = { items: items.map((it) => (it.id === undefined ? { text: it.text } : { id: it.id, text: it.text })) };
-  for (const field of BATCH_REQUEST_FIELDS) {
-    if (options[field] !== undefined) body[field] = options[field];
-  }
-  return post("/v1/refine/batch", body, options, (p) => Array.isArray(p.items)
-    && p.items.every((it) => it && typeof it === "object" && typeof it.output === "string"));
-}
-
-/** Assert that an existing result carries a completed, positive meaning check. */
-export function assertMeaningVerified(result) {
-  if (result?.meaningPreserved !== true) {
-    throw new MeaningVerificationError(result?.meaningPreserved);
-  }
-  return result;
-}
-
-/** Request meaning verification and reject unless the API returns strict true. */
-export async function refineVerified(text, options = {}) {
-  const result = await refine(text, { ...options, preserveMeaning: true });
-  assertMeaningVerified(result);
-  return result;
-}
+const DEFAULT_BASE_URL = "https://altalandi.is/api";
+const DEFAULT_TIMEOUT_MS = 300_000;
+const REQUEST_FIELDS = [
+  "sourceLang",
+  "domain",
+  "register",
+  "preserveMeaning",
+  "scoreNativeness",
+  "onlyImprove",
+  "polishPass",
+  "writer",
+  "scoring",
+  "glossary",
+  "returnDiffs",
+  "contribute",
+  "job",
+];
+// /v1/refine/batch takes fewer options: no writer/scoring tiers, polish or diffs switch.
+const BATCH_REQUEST_FIELDS = [
+  "sourceLang",
+  "domain",
+  "register",
+  "preserveMeaning",
+  "scoreNativeness",
+  "onlyImprove",
+  "glossary",
+  "autoTerminology",
+  "contribute",
+  "job",
+];
+
+export class AltalandiError extends Error {
+  constructor(message, { code = "ALTALANDI_ERROR", status, retryAfterMs } = {}) {
+    super(message);
+    this.name = "AltalandiError";
+    this.code = code;
+    if (Number.isInteger(status)) this.status = status;
+    if (Number.isFinite(retryAfterMs)) this.retryAfterMs = retryAfterMs;
+  }
+}
+
+/** Retry-After as milliseconds: delay-seconds or an HTTP date. */
+function retryAfterMs(response) {
+  const value = response?.headers?.get?.("retry-after");
+  if (!value) return undefined;
+  if (/^\s*\d+\s*$/.test(value)) return Number(value) * 1000;
+  const at = Date.parse(value);
+  return Number.isFinite(at) ? Math.max(0, at - Date.now()) : undefined;
+}
+
+export class MeaningVerificationError extends AltalandiError {
+  constructor(verdict) {
+    const changed = verdict === false;
+    super(
+      changed
+        ? "Altalandi could not preserve the input meaning."
+        : "Altalandi did not return a verified meaning verdict.",
+      { code: changed ? "MEANING_NOT_PRESERVED" : "MEANING_UNVERIFIED" },
+    );
+    this.name = "MeaningVerificationError";
+    this.verdict = verdict === false ? false : null;
+  }
+}
+
+function env(name) {
+  if (typeof process === "undefined" || !process.env) return undefined;
+  return process.env[name];
+}
+
+function cleanText(value, secret = "") {
+  if (typeof value !== "string") return "";
+  let cleaned = value.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim();
+  if (secret) cleaned = cleaned.split(secret).join("[redacted]");
+  return cleaned.slice(0, 300);
+}
+
+function errorDetail(payload) {
+  const detail = payload?.detail;
+  if (typeof detail === "string") return detail;
+  if (Array.isArray(detail)) {
+    return detail
+      .map((entry) => (typeof entry?.msg === "string" ? entry.msg : ""))
+      .filter(Boolean)
+      .join("; ");
+  }
+  return "";
+}
+
+function requestBody(text, options) {
+  const body = { text };
+  for (const field of REQUEST_FIELDS) {
+    if (options[field] !== undefined) body[field] = options[field];
+  }
+  return body;
+}
+
+/** POST a JSON body to `${baseUrl}${route}` with the key, base URL, timeout and
+ *  error handling every call shares. Returns the payload when `validShape`
+ *  accepts it; throws an AltalandiError (with status and Retry-After) otherwise. */
+async function post(route, body, options, validShape) {
+  const explicitKey = options.apiKey;
+  const selectedKey = explicitKey === undefined ? env("ALTALANDI_API_KEY") : explicitKey;
+  if (selectedKey !== undefined && typeof selectedKey !== "string") {
+    throw new AltalandiError("Altalandi apiKey must be a string.", { code: "INVALID_CONFIG" });
+  }
+  const apiKey = selectedKey?.trim();
+  if (!apiKey) {
+    throw new AltalandiError(
+      "No Altalandi API key. Set ALTALANDI_API_KEY or pass apiKey explicitly.",
+      { code: "MISSING_API_KEY" },
+    );
+  }
+
+  const selectedBaseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+  if (typeof selectedBaseUrl !== "string") {
+    throw new AltalandiError("Altalandi baseUrl must be a string.", { code: "INVALID_CONFIG" });
+  }
+  const baseUrl = selectedBaseUrl.trim().replace(/\/+$/, "");
+  if (!baseUrl) {
+    throw new AltalandiError("Altalandi baseUrl must not be empty.", { code: "INVALID_CONFIG" });
+  }
+
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new AltalandiError("Altalandi timeoutMs must be a positive number.", {
+      code: "INVALID_CONFIG",
+    });
+  }
+
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new AltalandiError("This runtime does not provide fetch.", { code: "INVALID_CONFIG" });
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    let response;
+    try {
+      response = await fetchImpl(`${baseUrl}${route}`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+    } catch {
+      if (controller.signal.aborted) {
+        throw new AltalandiError(`Altalandi timed out after ${timeoutMs} ms.`, {
+          code: "TIMEOUT",
+        });
+      }
+      throw new AltalandiError("Altalandi could not reach the API.", { code: "NETWORK_ERROR" });
+    }
+
+    let raw = "";
+    try {
+      raw = await response.text();
+    } catch {
+      if (controller.signal.aborted) {
+        throw new AltalandiError(`Altalandi timed out after ${timeoutMs} ms.`, {
+          code: "TIMEOUT",
+        });
+      }
+      if (response.ok) {
+        throw new AltalandiError("Altalandi could not read the API response.", {
+          code: "INVALID_RESPONSE",
+          status: response.status,
+        });
+      }
+      // The HTTP status remains useful when an error response has no readable body.
+    }
+
+    let payload;
+    if (raw) {
+      try {
+        payload = JSON.parse(raw);
+      } catch {
+        if (response.ok) {
+          throw new AltalandiError("Altalandi returned an invalid JSON response.", {
+            code: "INVALID_RESPONSE",
+            status: response.status,
+          });
+        }
+      }
+    }
+
+    if (!response.ok) {
+      const status = Number.isInteger(response.status) ? response.status : 0;
+      const statusText = cleanText(response.statusText);
+      const detail = cleanText(errorDetail(payload), apiKey);
+      const suffix = detail || statusText;
+      throw new AltalandiError(
+        `Altalandi API request failed (${status || "unknown status"})${suffix ? `: ${suffix}` : "."}`,
+        { code: "API_ERROR", status, retryAfterMs: retryAfterMs(response) },
+      );
+    }
+
+    if (!payload || typeof payload !== "object" || Array.isArray(payload) || !validShape(payload)) {
+      throw new AltalandiError("Altalandi returned an invalid response shape.", {
+        code: "INVALID_RESPONSE",
+        status: response.status,
+      });
+    }
+
+    return payload;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+/**
+ * Refine English or Icelandic text through the hosted Altalandi API.
+ * Client settings (`apiKey`, `baseUrl`, `timeoutMs`, `fetch`) are never sent in
+ * the JSON body. The full API result is returned without weakening its verdict.
+ */
+export async function refine(text, options = {}) {
+  if (typeof text !== "string" || !text.trim()) {
+    throw new AltalandiError("Altalandi requires non-empty text.", { code: "INVALID_INPUT" });
+  }
+  return post("/v1/refine", requestBody(text, options), options, (p) => typeof p.output === "string");
+}
+
+/**
+ * Refine many short strings in one call (POST /v1/refine/batch): at most 500
+ * items of at most 2,000 characters each, 20,000 characters together. Each item
+ * comes back with its own output and meaning verdict; an item with `error` came
+ * back unchanged and was not billed. Same key, limits and errors as refine().
+ */
+export async function refineBatch(items, options = {}) {
+  if (!Array.isArray(items) || !items.length
+    || !items.every((it) => it && typeof it.text === "string" && (it.id === undefined || typeof it.id === "string"))) {
+    throw new AltalandiError("Altalandi refineBatch requires a non-empty list of { id?, text } items.", {
+      code: "INVALID_INPUT",
+    });
+  }
+  const body = { items: items.map((it) => (it.id === undefined ? { text: it.text } : { id: it.id, text: it.text })) };
+  for (const field of BATCH_REQUEST_FIELDS) {
+    if (options[field] !== undefined) body[field] = options[field];
+  }
+  return post("/v1/refine/batch", body, options, (p) => Array.isArray(p.items)
+    && p.items.every((it) => it && typeof it === "object" && typeof it.output === "string"));
+}
+
+/** Assert that an existing result carries a completed, positive meaning check. */
+export function assertMeaningVerified(result) {
+  if (result?.meaningPreserved !== true) {
+    throw new MeaningVerificationError(result?.meaningPreserved);
+  }
+  return result;
+}
+
+/** Request meaning verification and reject unless the API returns strict true. */
+export async function refineVerified(text, options = {}) {
+  const result = await refine(text, { ...options, preserveMeaning: true });
+  assertMeaningVerified(result);
+  return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "altalandi",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "Native-sounding Icelandic from your terminal or AI agent: one-time login, a Claude Code skill, and meaning verification.",
   "type": "module",
   "main": "./client.mjs",

package/report.mjs

@@ -89,6 +89,7 @@ export function reportMarkdown(input, data, options = {}) {
     `| Innfæddni | ${q.nativenessScore ?? "n/a"}/100 |`,
     `| Ritill | ${tier.writer || "standard"} / ${tier.scoring || "?"} |`,
     `| Auðkenni | ${data?.runUrl ? `[${data.id}](${data.runUrl})` : data?.id || "?"} |`,
+    ...(data?.jobUrl ? [`| Verkið | ${data.jobUrl} |`] : []),
     "",
     "## Fyrir", "", fence(input), "",
     "## Eftir", "", fence(data?.output), "",
@@ -335,7 +336,9 @@ export function reviewMarkdown(input, data, { before = null, after = null, maxCh
 
   out.push("**Kostnaður**", ...costLines(data, before, after));
   // The run's own page: the text sent, the result, the checks and the review.
-  if (data?.runUrl) out.push(`- Verkið: ${data.runUrl}`);
+  // A call sent as part of a job (--job) links the job first, then this part.
+  if (data?.jobUrl) out.push(`- Verkið: ${data.jobUrl}`);
+  if (data?.runUrl) out.push(`- ${data?.jobUrl ? "Hlutinn" : "Verkið"}: ${data.runUrl}`);
   else if (data?.id) out.push(`- Auðkenni: \`${data.id}\``);
   return out.join("\n") + "\n";
 }
@@ -388,6 +391,8 @@ export function batchReportMarkdown(summary) {
       ? [`| Stafir rukkaðir | ${t.billedCharactersApprox ? "um " : ""}${count(t.billedCharacters)} |`] : []),
     `| Tegund texta | ${cell(summary?.domain || "general")} |`,
     `| Málsnið | ${cell(summary?.register || "neutral")} |`,
+    // The run's one job page (an engine that knows jobs); never one link per call.
+    ...(summary?.jobUrl ? [`| Verkið | ${summary.jobUrl} |`] : []),
   ];
 
   if (summary?.stopped) {

package/skill/SKILL.md

@@ -27,7 +27,7 @@ yourself or summarise the result in your own words.
   line, below. It waits up to 5 minutes per call and handles long texts.
 - **No shell, only the Altalandi tools** (`refine_icelandic`,
   `proofread_icelandic`, `get_refinement_status`, for example in claude.ai or
-  ChatGPT): use the tools, and follow "Long texts through the tools" below. The
+  ChatGPT): use the tools, and follow "Long texts in parts" below. The
   tools cannot wait as long as the command line, so long texts go in parts.
 
 How long a call takes: a few seconds for a sentence, 10–30 seconds for a
@@ -73,21 +73,30 @@ A document of several sections (more than about 3,000 characters) goes better
 through the folder run below: it refines and checks each passage on its own,
 and a passage that fails keeps its original without holding up the rest. Save
 the text as a `.md` file in an empty temporary folder and run the folder steps.
+To send it in parts instead, follow "Long texts in parts".
 
-## Long texts through the tools
+## Long texts in parts
 
 1. **Split the text into parts** at paragraph breaks, never inside a sentence:
    at most **1,000 characters** a part for English, **1,500** for Icelandic.
    Keep a heading with the paragraph under it. A list or a table stays in one
    part when it fits.
-2. **Call the tool once per part,** at most 3 at a time, in order. Give every
-   part its own new `operationId` (a fresh UUID). Keep a note of which ID
+2. **Command line: make one job id** for the whole text: `j_`, today's date
+   (yyyymmdd) and 6 random letters or digits, e.g. `j_20261013k4x9qa`. Run the
+   procedure once per part, in order, each with its own in and out files, and
+   add `--job <id> --part "Hluti N af M"` every time; on the first part add
+   `--job-title "<short name of the document>"` too. All parts are then one
+   verk on the site.
+3. **Tools: call the tool once per part,** at most 3 at a time, in order. Give
+   every part its own new `operationId` (a fresh UUID). Keep a note of which ID
    belongs to which part.
-3. **Join the results in the original order** and give the user the whole text,
-   then each part's verdict and changes, as the tool returns them.
-4. **A part that is refused or unverified keeps its original text.** Say which
+4. **Join the results in the original order** and give the user the whole text,
+   then each part's verdict and changes, as the command or the tool returns
+   them. With a job, end with its link once: `Verkið: <link>`, as the blocks
+   print it.
+5. **A part that is refused or unverified keeps its original text.** Say which
    part, and why (the tool says why). Never rewrite it yourself.
-5. **Terms must match across parts.** If two parts translate the same term
+6. **Terms must match across parts.** If two parts translate the same term
    differently, point it out and ask which to keep; do not quietly change one.
 
 ## If a call times out

package/update.mjs

@@ -142,6 +142,7 @@ export const SHIPPED_SKILLS = new Set([
   "aeb88010599539fd", // 0.6.0
   "ebfc4ef17a614973", // 0.6.1
   "9def55ecc6b30785", // 0.6.2
+  "2168eaa25a5c561c", // after 0.6.2 (3c73702: stafir and krónur)
 ]);
 
 export function skillFingerprint(text) {