altalandi 0.6.2 → 0.6.4

package/client.mjs

@@ -1,258 +1,288 @@
-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")
+      && (it.part === undefined || typeof it.part === "string"))) {
+    throw new AltalandiError("Altalandi refineBatch requires a non-empty list of { id?, text, part? } items.", {
+      code: "INVALID_INPUT",
+    });
+  }
+  const body = {
+    items: items.map((it) => ({
+      ...(it.id === undefined ? {} : { id: it.id }),
+      text: it.text,
+      ...(it.part === undefined ? {} : { part: it.part }),
+    })),
+  };
+  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"));
+}
+
+/**
+ * Create or name a job ("verk") and have the engine classify it from a sample
+ * (POST /v1/jobs): the kind of text and its specialist fields. Free, not
+ * billed. `sample` is a string or a list of strings, at most 12,000 characters
+ * together (about 3,000 is plenty). An existing job keeps its classification
+ * unless `reclassify` is true. An engine without jobs answers 404.
+ */
+export async function createJob(job, options = {}) {
+  if (!job || typeof job.id !== "string" || !job.id
+    || !(typeof job.sample === "string" || (Array.isArray(job.sample) && job.sample.every((s) => typeof s === "string")))) {
+    throw new AltalandiError("Altalandi createJob requires { id, sample } (sample: a string or a list of strings).", {
+      code: "INVALID_INPUT",
+    });
+  }
+  const body = { id: job.id, sample: job.sample };
+  for (const field of ["title", "sourceLang", "reclassify"]) {
+    if (job[field] !== undefined) body[field] = job[field];
+  }
+  return post("/v1/jobs", body, options, (p) => typeof p.id === "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.4",
   "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";
 }
@@ -362,6 +365,18 @@ const count = (n) => formatInt(n || 0);
 /** The one summary of a folder or site run: every file, every changed passage
  *  (before and after, with the meaning verdict) and, under their own heading,
  *  the passages that keep the original text because a check did not pass. */
+/** A job's classification (POST /v1/jobs) as one line: "Vefsíða · Bókhald",
+ *  the kind and the field names. null when it is not known: uncertain, a
+ *  fallback, or nothing named. */
+export function jobTypeText(classification) {
+  const c = classification;
+  if (!c || typeof c !== "object" || c.uncertain || c.source === "fallback") return null;
+  const name = (x) => String(x?.name || x?.label || x?.code || "").replace(/\s+/g, " ").trim();
+  const kind = c.kind ? name(c.kind) : "";
+  const fields = (Array.isArray(c.fields) ? c.fields : []).map(name).filter(Boolean).join(", ");
+  return [kind, fields].filter(Boolean).join(" · ") || null;
+}
+
 export function batchReportMarkdown(summary) {
   const t = summary?.totals || {};
   const files = Array.isArray(summary?.files) ? summary.files : [];
@@ -386,8 +401,12 @@ export function batchReportMarkdown(summary) {
     `| Stafir sendir | ${count(t.characters)} |`,
     ...(Number.isFinite(t.billedCharacters)
       ? [`| Stafir rukkaðir | ${t.billedCharactersApprox ? "um " : ""}${count(t.billedCharacters)} |`] : []),
+    // The job's kind and fields, as the engine classified them (when it knows).
+    ...(jobTypeText(summary?.classification) ? [`| Tegund verks | ${cell(jobTypeText(summary.classification))} |`] : []),
     `| 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) {