@rekhu/core 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to `@rekhu/core`. Versions follow [semantic versioning](https://semver.org).
 
+
+## 0.3.0 · 9 November 2026
+
+In parity with rekhu/core 0.3.0 for Laravel:
+
+- **Typed errors** under `RekhuError`: `InvalidKey`, `ModuleNotEnabled`, `RegionUnavailable`, `CreditExhausted`, `AppPaused`, `FileNotFound`, `InvalidRequest`, `RateLimited`, `Unavailable`, and `errorFor()`.
+- **Retries without double charges:** a dropped connection, 429, 502 or 503 is tried again up to three times; charged calls carry an `idempotency-key`, and a replayed answer is not kept in the ledger twice.
+- **Large files streamed** from a path; `downloadTo(fileId, path)`; `remove(fileId)`.
+- **File names in any language** arrive whole.
+- **Seshat:** `codes()`, structured `options` on `ask` findings, unknown fixes refused and not charged, side effects in `applied`, `resolved`.
+- `download()` and `feedback()` send the tenant and user; `knowers` is optional; no account offer in error messages.
 ## 0.2.0 · 6 November 2026
 
 - **Seshat in modules:** `seshat().modules()` says which modules this application may use (`preflight`, `ai_enhance`); a call to a module that is off is refused with `module_not_enabled`.

package/README.md

@@ -54,6 +54,14 @@ It fixes:
 - CMYK colours and embedded fonts;
 - pictures, made into print PDFs.
 
+**Every code, decision and fix in one list:** `await seshat.codes()` (free) answers the versioned list to map your own tool's names against. Every `ask` finding carries `options` (`upload_new`, `print_as_is`, `fix:<fix>[:<option>]`), so you can offer the choice without `explain`.
+
+**Fixes only, your own check:** `upload()` the file (free), then `fix(fileId, [{ fix: 'add_bleed' }, { fix: 'convert_cmyk' }], order)`. An unknown fix or option is refused (`InvalidRequest`) and not charged. `applied` lists every change, side effects too (`side_effect_of`), and `resolved` the codes the file no longer has.
+
+**Large files:** pass a path instead of a Buffer and the file is streamed; `downloadTo(fileId, path)` writes the result straight to disk; `remove(fileId)` deletes a kept file at once. File names keep every character.
+
+**What it costs:** `meta.usage` has one line per charged item: the check (`seshat`) and the explanation (`seshat_explain`). A refused call, or a fix with nothing to do, costs nothing.
+
 ## Seshat AI: one picture improved (ai_enhance)
 
 For a platform with its own preflight that only wants Seshat's image work, or next to the preflight. The module is switched on per application by Rekhu; `modules()` tells which ones this key may use.
@@ -135,5 +143,7 @@ The knowers and this package are the same in both.
 
 ## Errors
 
-- `RekhuError` carries `status` and `type`.
+- Every refusal is a `RekhuError` with `status` and `type`, and its own class: `InvalidKey` (401, also a key from another Rekhu platform), `ModuleNotEnabled` and `RegionUnavailable` (403), `CreditExhausted` and `AppPaused` (402), `FileNotFound` (404), `InvalidRequest` (422, not charged), `RateLimited` and `Unavailable` (after retries).
+- A dropped connection, 429, 502 or 503 is tried again up to three times. Charged calls carry an `idempotency-key`, so a retry is never charged twice (`meta.replayed`).
+- `knowers` (or `REKHU_KNOWERS`) is optional: empty means every knower the key allows.
 - `LimitReached` (429) carries `scope: 'tenant' | 'user'`; nothing is sent to Rekhu.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rekhu/core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Rekhu Core for Node.js: Rekhu's knowers in your app (Seshat for print files, Rekhu Machines for printing machines), with your own tenants, languages, limits and a usage ledger per customer.",
   "keywords": ["ai", "print", "printing", "preflight", "pdf", "machines", "multi-tenant", "rekhu"],
   "homepage": "https://rekhu.com",

package/src/index.js

@@ -6,11 +6,14 @@
 //     await rekhu.machines({ user }).identify('Heidelberg Speedmaster SM 74-4 with coater');
 //     await rekhu.seshat({ user }).check(pdfBuffer, { name: 'flyer.pdf', order: { width_mm: 148, height_mm: 210 } });
 
-import { createHmac, timingSafeEqual } from 'node:crypto';
+import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto';
+import { createWriteStream, existsSync, openAsBlob } from 'node:fs';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
 import { memoryLedger, fileLedger, usage } from './ledger.js';
 
 export { memoryLedger, fileLedger, usage };
-export const VERSION = '0.2.0';
+export const VERSION = '0.3.0';
 
 /**
  * Whether a webhook Rekhu sent is genuine: the x-rekhu-signature header (t=…,v1=…) over the raw body, with the
@@ -34,6 +37,39 @@ export class RekhuError extends Error {
     }
 }
 
+/** The key is missing, revoked, or belongs to another Rekhu platform (401). */
+export class InvalidKey extends RekhuError {}
+/** The knower's module is not switched on for this application (403 module_not_enabled). */
+export class ModuleNotEnabled extends RekhuError {}
+/** The account processes data in Europe only and this call has no engine in the EU (403 region_unavailable). */
+export class RegionUnavailable extends RekhuError {}
+/** The Rekhu account's credit is used up (402). */
+export class CreditExhausted extends RekhuError {}
+/** The application is paused or at its monthly limit in the Rekhu account (402 app_limit). */
+export class AppPaused extends RekhuError {}
+/** A kept file is past its day, removed, or of another account (404). */
+export class FileNotFound extends RekhuError {}
+/** Refused before anything ran, with what was wrong (422); nothing was charged. */
+export class InvalidRequest extends RekhuError {}
+/** Too many calls at once, after the client tried again (429). */
+export class RateLimited extends RekhuError {}
+/** Rekhu or a service behind it could not answer, after the client tried again (502, 503, 529). */
+export class Unavailable extends RekhuError {}
+
+/** The typed error for an answer from Rekhu: catch the class you handle, or RekhuError for all of them. */
+export function errorFor(status, type, message) {
+    const Type = status === 401 ? InvalidKey : type === 'module_not_enabled' ? ModuleNotEnabled : type === 'region_unavailable' ? RegionUnavailable
+        : type === 'app_limit' ? AppPaused : status === 402 ? CreditExhausted : status === 404 ? FileNotFound : status === 422 || status === 400 ? InvalidRequest
+            : status === 429 ? RateLimited : status >= 500 ? Unavailable : RekhuError;
+    const error = new Type(message, status, type);
+    error.name = Type.name;
+    return error;
+}
+
+const FREE = ['models', 'modules', 'codes', 'upload', 'poll', 'enhance_preview'];
+const RETRY = [429, 502, 503, 529];
+const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
 /** One of the app's own limits a day is reached (scope: tenant or user); nothing was sent to Rekhu. */
 export class LimitReached extends RekhuError {
     constructor(message, scope) {
@@ -77,7 +113,7 @@ export function createRekhu(options = {}) {
 
     function key() {
         const k = parseKey(config.key);
-        if (!k) throw new RekhuError('REKHU_APP_KEY is missing or not a Rekhu app key (agk_…). No Rekhu account yet? Create one at https://rekhu.com/register?ref=core-node: it starts with $10 credit, no card needed.', 0, 'configuration_error');
+        if (!k) throw new InvalidKey('REKHU_APP_KEY is missing or not a Rekhu app key (agk_…): put the app key from your Rekhu account (Projects → the app → Connection) in the environment.', 0, 'configuration_error');
         return k;
     }
 
@@ -85,7 +121,7 @@ export function createRekhu(options = {}) {
         if (named) return { id: String(named.id), name: String(named.name ?? named.id) };
         if (config.tenancy !== 'multi') return { id: config.appId, name: config.appName };
         const t = resolvers.tenant && user ? await resolvers.tenant(user) : null;
-        if (t && typeof t === 'object' && t.id !== undefined && t.id !== null && t.id !== '') return { id: String(t.id), name: String(t.name ?? t.id), ...t, id: String(t.id) };
+        if (t && typeof t === 'object' && t.id !== undefined && t.id !== null && t.id !== '') return { ...t, id: String(t.id), name: String(t.name ?? t.id) };
         if (t !== null && t !== undefined && t !== '' && typeof t !== 'object') return { id: String(t), name: String(t) };
         return null;
     }
@@ -109,33 +145,55 @@ export function createRekhu(options = {}) {
 
     async function failed(response) {
         const error = await response.json().catch(() => ({}));
-        return new RekhuError(error?.error?.message || `Rekhu answered ${response.status}`, response.status, error?.error?.type || 'api_error');
+        return errorFor(response.status, error?.error?.type || 'api_error', error?.error?.message || `Rekhu answered ${response.status}`);
     }
 
-    /** One call to a knower for a user (or a named tenant): the app's limits, the call, the ledger and onUsage. */
-    async function call(knower, action, input = {}, { user = null, userId = null, tenant: named = null, file = null } = {}) {
+    /**
+     * One request, tried again on a dropped connection or a 429, 502, 503 or 529, waiting a little longer each time (and
+     * as long as retry-after asks, up to 5 seconds); any other failure is the typed error for it.
+     */
+    async function send(make) {
+        for (let attempt = 1; ; attempt++) {
+            let response;
+            try {
+                response = await make();
+            } catch (error) {
+                if (error instanceof RekhuError) throw error;
+                if (attempt >= 3) throw new Unavailable('Rekhu could not be reached; try again in a moment.', 503, 'connection_error');
+                await pause(250 * 2 ** attempt);
+                continue;
+            }
+            if (response.ok) return response;
+            if (attempt < 3 && RETRY.includes(response.status)) {
+                await pause(Math.min(5000, Number(response.headers?.get?.('retry-after')) * 1000 || 250 * 2 ** attempt));
+                continue;
+            }
+            throw await failed(response);
+        }
+    }
+
+    async function headersFor(user, userId, named) {
         const k = key();
-        if (!config.knowers.includes(knower)) throw new RekhuError(`The knower ${knower} is not installed in this app: add it to knowers (or REKHU_KNOWERS).`, 0, 'configuration_error');
         const tenant = await tenantOf(user, named);
-        if (config.tenancy === 'multi' && !tenant && !['models', 'modules'].includes(action)) throw new RekhuError('This app is multi-tenant, and no tenant was found for the user: give createRekhu a tenant function, or pass a tenant.', 0, 'configuration_error');
         const who = userId ?? (user ? (options.userId ? options.userId(user) : user.id) : null);
-        if (!['models', 'modules', 'upload', 'poll', 'enhance_preview'].includes(action)) await checkLimits(tenant, who, knower);
+        return { tenant, who, headers: { accept: 'application/json', 'x-api-key': k.key, 'x-agent': k.agent, 'x-tenant': String(tenant?.id ?? config.appId), 'x-tenant-name': String(tenant?.name ?? config.appName), ...(who != null ? { 'x-user': String(who) } : {}) } };
+    }
+
+    /** One call to a knower for a user (or a named tenant): the app's limits, the call, the ledger and onUsage. */
+    async function call(knower, action, input = {}, { user = null, userId = null, tenant: named = null, file = null } = {}) {
+        if (config.knowers.length && !config.knowers.includes(knower)) throw new RekhuError(`The knower ${knower} is not in this app's knowers (REKHU_KNOWERS): add it, or leave the list empty to use every knower the key allows.`, 0, 'configuration_error');
+        const { tenant, who, headers } = await headersFor(user, userId, named);
+        if (config.tenancy === 'multi' && !tenant && !FREE.includes(action)) throw new RekhuError('This app is multi-tenant, and no tenant was found for the user: give createRekhu a tenant function, or pass a tenant.', 0, 'configuration_error');
+        if (!FREE.includes(action)) await checkLimits(tenant, who, knower);
         const body = ['check', 'explain'].includes(action) && input.language === undefined ? { ...input, language: await localeOf(user) } : input;
-        const headers = { accept: 'application/json', 'x-api-key': k.key, 'x-agent': k.agent, 'x-tenant': String(tenant?.id ?? config.appId), 'x-tenant-name': String(tenant?.name ?? config.appName), ...(who != null ? { 'x-user': String(who) } : {}) };
+        if (!FREE.includes(action)) headers['idempotency-key'] = randomUUID();
         const started = Date.now();
-        let response;
-        try {
-            response = file
-                ? await config.fetch(`${platform()}/v1/knowers/${knower}/${action}`, { method: 'POST', headers: { ...headers, 'content-type': 'application/octet-stream', 'x-file-name': file.name, 'x-knower-input': JSON.stringify(body) }, body: file.bytes, signal: AbortSignal.timeout(config.timeout) })
-                : await config.fetch(`${platform()}/v1/knowers/${knower}/${action}`, { method: 'POST', headers: { ...headers, 'content-type': 'application/json' }, body: JSON.stringify(body), signal: AbortSignal.timeout(config.timeout) });
-        } catch (error) {
-            if (error instanceof RekhuError) throw error;
-            throw new RekhuError('Rekhu could not be reached; try again in a moment.', 503, 'connection_error');
-        }
-        if (!response.ok) throw await failed(response);
+        const url = `${platform()}/v1/knowers/${knower}/${action}`;
+        const response = await send(async () => (file
+            ? config.fetch(url, { method: 'POST', headers: { ...headers, 'content-type': 'application/octet-stream', 'x-file-name': encodeURIComponent(file.name), 'x-knower-input': JSON.stringify({ ...body, name: file.name }) }, body: file.path ? await openAsBlob(file.path) : file.bytes, signal: AbortSignal.timeout(config.timeout) })
+            : config.fetch(url, { method: 'POST', headers: { ...headers, 'content-type': 'application/json' }, body: JSON.stringify(body), signal: AbortSignal.timeout(config.timeout) })));
         const answer = await response.json();
-        // what is not charged is not kept in the ledger
-        if (['models', 'modules', 'upload', 'poll', 'enhance_preview'].includes(action)) return answer;
+        if (FREE.includes(action) || answer.meta?.replayed) return answer;
         const meta = answer.meta || {};
         const row = {
             tenant_id: tenant?.id ?? null, tenant_name: tenant?.name ?? null, user_id: who != null ? String(who) : null, knower, action, ref: answer.ref ?? null,
@@ -147,21 +205,33 @@ export function createRekhu(options = {}) {
         return answer;
     }
 
-    async function feedback(knower, ref, outcome, correction = null) {
-        const k = key();
-        const response = await config.fetch(`${platform()}/v1/knowers/${knower}/feedback`, { method: 'POST', headers: { 'content-type': 'application/json', accept: 'application/json', 'x-api-key': k.key, 'x-agent': k.agent }, body: JSON.stringify({ ref, outcome, ...(correction ? { correction } : {}) }) });
-        if (!response.ok) throw await failed(response);
+    async function feedback(knower, ref, outcome, correction = null, who = {}) {
+        const { headers } = await headersFor(who.user ?? null, who.userId ?? null, who.tenant ?? null);
+        const response = await send(() => config.fetch(`${platform()}/v1/knowers/${knower}/feedback`, { method: 'POST', headers: { ...headers, 'content-type': 'application/json' }, body: JSON.stringify({ ref, outcome, ...(correction ? { correction } : {}) }) }));
         return response.json();
     }
 
-    async function download(knower, fileId) {
-        const k = key();
-        const response = await config.fetch(`${platform()}/v1/knowers/${knower}/files/${encodeURIComponent(fileId)}`, { headers: { 'x-api-key': k.key, 'x-agent': k.agent } });
-        if (!response.ok) throw await failed(response);
-        return Buffer.from(await response.arrayBuffer());
+    async function fileRequest(knower, fileId, method, who = {}) {
+        const { headers } = await headersFor(who.user ?? null, who.userId ?? null, who.tenant ?? null);
+        return send(() => config.fetch(`${platform()}/v1/knowers/${knower}/files/${encodeURIComponent(fileId)}`, { method, headers, signal: AbortSignal.timeout(config.timeout) }));
+    }
+
+    async function download(knower, fileId, who = {}) {
+        return Buffer.from(await (await fileRequest(knower, fileId, 'GET', who)).arrayBuffer());
+    }
+
+    /** A result written straight to a path, without holding a large file in memory. */
+    async function downloadTo(knower, fileId, path, who = {}) {
+        const response = await fileRequest(knower, fileId, 'GET', who);
+        await pipeline(Readable.fromWeb(response.body), createWriteStream(path));
+        return path;
+    }
+
+    async function remove(knower, fileId, who = {}) {
+        await fileRequest(knower, fileId, 'DELETE', who);
     }
 
-    const knowerFor = (name) => (who = {}) => ({ call: (action, input, extra = {}) => call(name, action, input, { ...who, ...extra }), feedback: (ref, outcome, correction) => feedback(name, ref, outcome, correction) });
+    const knowerFor = (name) => (who = {}) => ({ call: (action, input, extra = {}) => call(name, action, input, { ...who, ...extra }), feedback: (ref, outcome, correction) => feedback(name, ref, outcome, correction, who) });
 
     /** Rekhu Machines: printing and finishing machines, sent as a Rekhu machine profile (see the README). */
     const machines = (who = {}) => {
@@ -183,6 +253,7 @@ export function createRekhu(options = {}) {
     const seshat = (who = {}) => {
         const k = knowerFor('seshat')(who);
         const file = async (f, name, what) => {
+            if (typeof f === 'string' && existsSync(f)) return { name: name || f.split(/[\\/]/).pop(), path: f };
             if (!name) throw new RekhuError(`Give the file's name: ${what}(bytes, { name: 'flyer.pdf' }).`, 0, 'invalid_request_error');
             const bytes = await bytesOf(f);
             if (!bytes) throw new RekhuError('The file is a Buffer, Uint8Array, ArrayBuffer or Blob.', 0, 'invalid_request_error');
@@ -213,7 +284,13 @@ export function createRekhu(options = {}) {
             poll: (jobId) => k.call('poll', { job_id: jobId }),
             fix: (fileId, fixes = 'auto', order = {}) => k.call('fix', { file_id: fileId, fixes, order }),
             preview: (fileId, { page = 1, longest = 1200 } = {}) => k.call('preview', { file_id: fileId, page, longest }),
-            download: (fileId) => download('seshat', fileId),
+            download: (fileId) => download('seshat', fileId, who),
+            /** The same, written straight to a path: for large print files. */
+            downloadTo: (fileId, path) => downloadTo('seshat', fileId, path, who),
+            /** A kept file removed at once: a customer took it out of their order. */
+            remove: (fileId) => remove('seshat', fileId, who),
+            /** Every finding code, decision and fix with its options, versioned: the list to map against. Not charged. */
+            codes: () => k.call('codes', {}),
         };
     };