@rekhu/core 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to `@rekhu/core`. Versions follow [semantic versioning](https://semver.org).
+
+## 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`.
+- **ai_enhance:** `seshat().enhance(picture, modes, options, extra)` improves one picture without a check:
+  - the modes are upscale to a print size, extend, denoise, sharpen, restore, remove_background, replace_background, remove_object, vectorize and colour_correct;
+  - large pictures run as a job: `poll(jobId)`, or a webhook checked with `verifyWebhook()`;
+  - `enhancePreview(fileId)` gives a before / after picture, and `upload()` keeps a mask or background picture.
+
+## 0.1.0 · 6 November 2026
+
+- **Rekhu Core for Node.js.** Rekhu's knowers in a Node.js back end, with the app's own tenants (`tenant`), languages (`locale`), limits a day per tenant and user (`limits`, `limitsFor`), its own price per call (`price`) and every call kept in a ledger (`memoryLedger`, `fileLedger`, or the app's own) and passed to `onUsage`.
+- **Seshat**: check a print file against its order, fix it, preview a page, download the fixed file.
+- **Rekhu Machines**: identify, profile, check, choose, explain; feedback on an answer.
+- `npx rekhu-core usage` for a file ledger, per tenant and month, with CSV. Cloud or private deployment.

package/LICENSE.txt

@@ -0,0 +1,18 @@
+Rekhu Core for Node.js (@rekhu/core), by Rekhu (Charisma Design, the Netherlands)
+
+This software is licensed, not sold. It is provided to holders of a Rekhu account under the
+Rekhu Terms of Service at https://rekhu.com/terms, which grant a limited, revocable,
+non-exclusive, non-transferable licence to install and run the package in applications
+linked to that account by a valid site key, solely to use the Rekhu services under the account's plan.
+
+The package is a client of the Rekhu platform: it functions only with a valid site key issued by the
+platform, verifies that key with the platform, and performs work only on instructions received through
+the platform. A revoked key stops the package in that application.
+
+You may not copy, modify, distribute, sublicense, host for third parties, reverse engineer, or use the
+package with any server, service, model or backend other than the Rekhu platform, nor remove or
+circumvent the key check, licence verification, metering or security measures, except where mandatory
+law expressly allows. Code, migrations and tests that the agent writes in your application are your own,
+as the Terms describe.
+
+All rights reserved. hello@rekhu.com

package/README.md

@@ -1,3 +1,139 @@
-# Temporary Holding Version
+# Rekhu Core for Node.js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Rekhu's **knowers** in your Node.js back end. A knower is a specialist that knows one part of a trade the way its best expert does: it understands what is asked, decides, explains in your user's language and learns from what your users accept or correct. The first two know print: **Seshat** knows print files, **Rekhu Machines** knows printing and finishing machines.
+
+Your tenants, users, limits and prices stay yours: every call is kept in your ledger, next to what Rekhu charged you, so you can charge your customers per call or per plan. Express, Next.js, Nuxt, Hono, Bun and Deno.
+
+```bash
+npm install @rekhu/core
+```
+
+```js
+import { createRekhu } from '@rekhu/core';
+
+const rekhu = createRekhu({
+    key: process.env.REKHU_APP_KEY,                       // the app key from your Rekhu account
+    knowers: ['seshat', 'machines'],
+    tenant: (user) => ({ id: user.teamId, name: user.teamName }),   // multi-tenant: the customer a user belongs to
+    locales: ['en', 'nl', 'ar'],
+    locale: (user) => user.language,
+    limits: { seshat: { perDayPerTenant: 500 } },
+    price: (tenant, knower, action, meta) => 0.02,         // what you charge your customer for a call
+    onUsage: (row) => db.rekhuUsage.insert(row),           // or ledger: { record, count } in your own database
+});
+```
+
+No Rekhu account yet? [Create one](https://rekhu.com/register?ref=core-node): it starts with $10 credit, no card needed.
+
+## Seshat: print files
+
+Seshat checks a print file **against the order it is for**. Each finding comes with Seshat's decision: `fix`, `ask` (the customer chooses), `refuse` or `note`.
+
+```js
+const seshat = rekhu.seshat({ user });
+const order = { width_mm: 148, height_mm: 210, bleed_mm: 3, pages: 2, colour: 'cmyk' };
+
+const check = await seshat.check(fileBuffer, { name: 'flyer.pdf', order, explain: true });
+const fixed = await seshat.fix(check.file_id, 'auto', order);       // or [{ fix: 'scale_to_size', option: 'fit' }, { fix: 'add_bleed' }]
+const pdf = await seshat.download(fixed.file_id);                    // a Buffer
+const proof = await seshat.preview(fixed.file_id);                   // { image: 'data:image/png;base64,…' }
+```
+
+It checks:
+- size against the order, and the trim and bleed;
+- the resolution of every picture as placed;
+- RGB and spot colours, fonts and total ink;
+- the pages, small text and thin lines;
+- white set to overprint, and text near the cut;
+- pictures, EPS files and zips.
+
+It fixes:
+- the bleed, by mirroring the edges;
+- the size: scale, fit or fill;
+- the trim box;
+- CMYK colours and embedded fonts;
+- pictures, made into print PDFs.
+
+## 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.
+
+| Mode | What it does | Options |
+|---|---|---|
+| `upscale` | More pixels, up to 4×: to a resolution at a print size | `ppi`, `width_mm`, `height_mm`, or `factor` |
+| `extend` | Grows the picture beyond its edges (bleed); a little per side on CPU | `all_mm`, or `top_mm` `right_mm` `bottom_mm` `left_mm` (or `_px`) |
+| `denoise`, `sharpen` | Cleans JPEG artefacts and noise; crisper edges | `strength`, `amount` |
+| `restore` | An old or scanned photo: scratches filled, noise and faded colour corrected | |
+| `remove_background` | Transparent PNG, or a solid colour | `background: '#ffffff'` |
+| `replace_background` | A new background from a picture you send | `background_file_id` (from `upload`) |
+| `remove_object` | Fills an object or blemish from its surroundings | `region: {x, y, w, h}`, or `mask_file_id` |
+| `vectorize` | A logo or line drawing as SVG. A photo is refused (`not_vectorizable`) | |
+| `colour_correct` | Exposure and white balance | |
+
+Every answer says what it invented in `warnings` (an edge, a filled area, a reconstructed detail), with a `confidence` from 0 to 1. RGB stays RGB, and CMYK stays CMYK unless the mode needs otherwise. Files are kept a day and never used for training. A large picture runs as a job: poll it, or give a webhook URL. The webhook is signed `x-rekhu-signature: t=…,v1=…` with the `webhook_secret` the call answered. Each mode is priced on its own, and `meta.usage` says per item what it cost.
+
+Limits:
+- at most 40 megapixels in and 120 megapixels out;
+- upscaling at most 4×;
+- extending at most 12 % of a side on CPU;
+- removing at most a quarter of the picture.
+
+```js
+const s = rekhu.seshat({ tenant: { id: tenant.uuid, name: tenant.name } });
+await s.modules();                    // { modules: { preflight: false, ai_enhance: true }, modes: [...] }
+const r = await s.enhance(photoBuffer, ['denoise', 'upscale'], { ppi: 300, width_mm: 100, height_mm: 70 }, { name: 'photo.png', webhookUrl: 'https://shop.example.com/hooks/rekhu' });
+const { image } = await s.enhancePreview(r.file_id);          // before | after, a data: URL
+const png = await s.download(r.file_id);                       // a Buffer
+await s.poll('j_…');                                           // for a job
+
+import { verifyWebhook } from '@rekhu/core';
+if (!verifyWebhook(rawBody, req.headers['x-rekhu-signature'], storedSecret)) return res.status(401).end();
+```
+
+## Rekhu Machines
+
+```js
+const machines = rekhu.machines({ user });
+await machines.identify('Heidelberg Speedmaster SM 74-4 with coater, 2009');
+await machines.profile('heidelberg-sm-74', { colour_units: 4 });
+await machines.check(machineProfile, { model: 'heidelberg-sm-74', explain: true });
+await machines.choose({ width_mm: 85, height_mm: 55, quantity: 5000, colours_front: 4, colours_back: 4, gsm: 350 }, shopMachines);
+await machines.explain('Can I print 400 g/m² board on it?', { model: 'heidelberg-sm-74' });
+```
+
+The machine profile:
+
+| Field | |
+|---|---|
+| `type` | printing, cutting, … |
+| `method` | offset, digital_toner, digital_liquid, inkjet_sheet, large_format, guillotine |
+| `sheet_max_mm`, `sheet_min_mm` | `[w, h]` |
+| `gsm` | `[min, max]` |
+| `colour_units`, `perfecting` | |
+| `speed`, `speed_unit` | |
+| `makeready_minutes`, `makeready_waste_sheets` | |
+| `gripper_mm` | |
+
+Every answer has a `ref`; `machines.feedback(ref, 'corrected', { speed: 12000 })` is what the knower learns from.
+
+## Usage per tenant
+
+The default ledger is in memory. For a single server, `fileLedger('storage/rekhu-usage.jsonl')` keeps it in a file:
+
+```bash
+npx rekhu-core usage --ledger storage/rekhu-usage.jsonl --month 2026-11 --csv usage-2026-11.csv
+```
+
+Calls, model calls, what Rekhu charged and your own price, per tenant, knower and action. With several servers, give `ledger: { record(row), count(filter) }` backed by your own database.
+
+## Where Rekhu runs
+
+- `REKHU_DEPLOYMENT=cloud` (the default) uses Rekhu's platform.
+- `private` uses Rekhu inside your network: set `REKHU_PLATFORM` to its address.
+
+The knowers and this package are the same in both.
+
+## Errors
+
+- `RekhuError` carries `status` and `type`.
+- `LimitReached` (429) carries `scope: 'tenant' | 'user'`; nothing is sent to Rekhu.

package/bin/rekhu-core.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// npx rekhu-core usage --ledger storage/rekhu-usage.jsonl [--month 2026-11] [--tenant shop-42] [--csv usage.csv]
+// The usage of Rekhu's knowers per tenant in a month, from a file ledger (fileLedger).
+
+import { writeFile } from 'node:fs/promises';
+import { fileLedger, usage } from '../src/ledger.js';
+
+const args = process.argv.slice(2);
+const option = (name) => { const i = args.indexOf(`--${name}`); return i >= 0 ? args[i + 1] : undefined; };
+if (args[0] !== 'usage' || !option('ledger')) {
+    console.log('npx rekhu-core usage --ledger <file> [--month YYYY-MM] [--tenant <id>] [--csv <file>]');
+    process.exit(args[0] ? 1 : 0);
+}
+try {
+    const rows = await usage(fileLedger(option('ledger')), { month: option('month'), tenant: option('tenant') });
+    if (!rows.length) { console.log('No usage in that month.'); process.exit(0); }
+    console.table(rows.map((r) => ({ tenant: r.tenant, name: r.name, knower: r.knower, action: r.action, calls: r.calls, 'model calls': r.model_calls, 'Rekhu cost (USD)': r.cost_usd.toFixed(4), 'your price': r.price === null ? '' : r.price.toFixed(2) })));
+    if (option('csv')) {
+        const quote = (v) => (/[",\n]/.test(String(v)) ? `"${String(v).replace(/"/g, '""')}"` : String(v ?? ''));
+        const lines = [['tenant', 'name', 'knower', 'action', 'calls', 'model calls', 'Rekhu cost (USD)', 'your price'], ...rows.map((r) => [r.tenant, r.name, r.knower, r.action, r.calls, r.model_calls, r.cost_usd.toFixed(4), r.price === null ? '' : r.price.toFixed(2)])];
+        await writeFile(option('csv'), lines.map((l) => l.map(quote).join(',')).join('\n') + '\n');
+        console.log(`Written to ${option('csv')}.`);
+    }
+} catch (error) {
+    console.error(error.message);
+    process.exit(1);
+}

package/index.d.ts

@@ -0,0 +1,73 @@
+export const VERSION: string;
+
+export interface Tenant { id: string; name: string; [key: string]: unknown }
+export interface UsageRow {
+    tenant_id: string | null; tenant_name: string | null; user_id: string | null; knower: string; action: string; ref: string | null;
+    ok: boolean; model_calls: number; cost_usd: number; price: number | null; ms: number; created_at: string;
+}
+export interface Ledger {
+    record(row: UsageRow): Promise<void> | void;
+    count(filter: { knower?: string; tenant?: string; user?: string; since?: string; until?: string }): Promise<number> | number;
+    rows?(filter?: { knower?: string; tenant?: string; user?: string; since?: string; until?: string }): Promise<UsageRow[]>;
+}
+export interface Limits { perDayPerTenant?: number | null; perDayPerUser?: number | null }
+
+export interface RekhuOptions<User = any> {
+    key?: string;
+    platform?: string;
+    deployment?: 'cloud' | 'private';
+    tenancy?: 'single' | 'multi';
+    appId?: string;
+    appName?: string;
+    knowers?: string[];
+    locales?: string[];
+    tenant?: (user: User) => Tenant | string | null | Promise<Tenant | string | null>;
+    userId?: (user: User) => string | number;
+    locale?: (user: User) => string | null | Promise<string | null>;
+    limits?: Record<string, Limits>;
+    limitsFor?: (tenant: Tenant | null, knower: string) => Limits | Promise<Limits>;
+    price?: (tenant: Tenant | null, knower: string, action: string, meta: Record<string, unknown>) => number | null | Promise<number | null>;
+    onUsage?: (row: UsageRow & { tenant: Tenant | null; user: User | null }) => void | Promise<void>;
+    ledger?: Ledger | false;
+    timeout?: number;
+    fetch?: typeof fetch;
+}
+
+export interface Who<User = any> { user?: User | null; userId?: string | number; tenant?: { id: string; name?: string } }
+export type Answer = Record<string, any> & { ref?: string; meta?: { model_calls: number; cost_usd: number; ms: number } };
+
+export interface Machines {
+    models(): Promise<Array<{ id: string; maker: string; model: string; type: string; method: string; format: string | null }>>;
+    identify(text: string): Promise<Answer>;
+    profile(model: string, known?: Record<string, unknown>): Promise<Answer>;
+    check(machine: Record<string, unknown>, options?: { model?: string; explain?: boolean }): Promise<Answer>;
+    choose(job: { width_mm: number; height_mm: number; quantity: number; bleed_mm?: number; colours_front?: number; colours_back?: number; gsm?: number }, machines: Array<Record<string, unknown>>): Promise<Answer>;
+    explain(question: string, options?: { machine?: Record<string, unknown>; model?: string }): Promise<Answer>;
+    feedback(ref: string, outcome: 'accepted' | 'corrected' | 'rejected', correction?: Record<string, unknown>): Promise<Answer>;
+}
+
+export interface Order { width_mm?: number; height_mm?: number; bleed_mm?: number; pages?: number; colour?: 'cmyk' | 'any'; min_ppi?: number; safe_mm?: number; max_ink?: number; spot_colours_allowed?: boolean }
+export interface Seshat {
+    check(file: Uint8Array | ArrayBuffer | Blob, options: { name: string; order?: Order; explain?: boolean }): Promise<Answer>;
+    fix(fileId: string, fixes?: 'auto' | Array<{ fix: string; option?: string }>, order?: Order): Promise<Answer>;
+    preview(fileId: string, options?: { page?: number; longest?: number }): Promise<Answer>;
+    download(fileId: string): Promise<Buffer>;
+    feedback(ref: string, outcome: 'accepted' | 'corrected' | 'rejected', correction?: Record<string, unknown>): Promise<Answer>;
+}
+
+export interface Rekhu<User = any> {
+    config: Record<string, unknown>;
+    machines(who?: Who<User>): Machines;
+    seshat(who?: Who<User>): Seshat;
+    knower(name: string): (who?: Who<User>) => { call(action: string, input?: Record<string, unknown>): Promise<Answer>; feedback(ref: string, outcome: string, correction?: Record<string, unknown>): Promise<Answer> };
+    installed(name: string): boolean;
+    usage(filter?: { month?: string; tenant?: string }): Promise<Array<{ tenant: string; name: string; knower: string; action: string; calls: number; model_calls: number; cost_usd: number; price: number | null }>>;
+}
+
+export function createRekhu<User = any>(options?: RekhuOptions<User>): Rekhu<User>;
+export function memoryLedger(): Ledger;
+export function fileLedger(path: string): Ledger;
+export function usage(ledger: Ledger, filter?: { month?: string; tenant?: string }): Promise<unknown[]>;
+export function parseKey(key: string): { key: string; customer: string; agent: string } | null;
+export class RekhuError extends Error { status: number; type: string }
+export class LimitReached extends RekhuError { scope: 'tenant' | 'user' }

package/package.json

@@ -1,6 +1,17 @@
 {
   "name": "@rekhu/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.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",
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "author": "Rekhu <hello@rekhu.com> (https://rekhu.com)",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./index.d.ts",
+  "bin": { "rekhu-core": "bin/rekhu-core.js" },
+  "exports": { ".": { "types": "./index.d.ts", "import": "./src/index.js" } },
+  "engines": { "node": ">=20" },
+  "files": ["src", "bin", "index.d.ts", "README.md", "CHANGELOG.md", "LICENSE.txt"],
+  "scripts": { "test": "node --test test/*.test.js" }
+}

package/src/index.js

@@ -0,0 +1,221 @@
+// Rekhu Core for Node.js: Rekhu's knowers in the app's own back end. A knower knows one part of a trade the way its
+// best expert does; Seshat knows print files, Rekhu Machines knows printing and finishing machines. The app keeps its
+// tenants, languages, limits and prices: every call is kept in its ledger, with what Rekhu charged and its own price.
+//
+//     const rekhu = createRekhu({ tenant: (user) => ({ id: user.teamId, name: user.teamName }), knowers: ['seshat', 'machines'] });
+//     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 { memoryLedger, fileLedger, usage } from './ledger.js';
+
+export { memoryLedger, fileLedger, usage };
+export const VERSION = '0.2.0';
+
+/**
+ * Whether a webhook Rekhu sent is genuine: the x-rekhu-signature header (t=…,v1=…) over the raw body, with the
+ * webhook_secret the call answered, and not older than `tolerance` seconds.
+ */
+export function verifyWebhook(body, signature, secret, tolerance = 300) {
+    const m = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(String(signature || ''));
+    if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > tolerance) return false;
+    const expected = createHmac('sha256', secret).update(`${m[1]}.${body}`).digest();
+    const given = Buffer.from(m[2], 'hex');
+    return given.length === expected.length && timingSafeEqual(given, expected);
+}
+
+/** A knower could not answer: Rekhu's status (0 when the call was not made) and its error type. */
+export class RekhuError extends Error {
+    constructor(message, status = 0, type = 'api_error') {
+        super(message);
+        this.name = 'RekhuError';
+        this.status = status;
+        this.type = type;
+    }
+}
+
+/** 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) {
+        super(message, 429, 'limit_reached');
+        this.name = 'LimitReached';
+        this.scope = scope;
+    }
+}
+
+/** The key's parts: agk_<customer>_<agent>_<secret>, or null when it is not a Rekhu app key. */
+export function parseKey(key) {
+    const m = /^agk_([a-z0-9-]+)_([a-z0-9-]+)_[A-Za-z0-9_-]+$/.exec(String(key || ''));
+    return m ? { key: m[0], customer: m[1], agent: m[2] } : null;
+}
+
+export function createRekhu(options = {}) {
+    const env = (name) => (typeof process !== 'undefined' ? process.env[name] : undefined);
+    const config = {
+        key: options.key ?? env('REKHU_APP_KEY') ?? env('REKHU_SECRET_KEY'),
+        deployment: options.deployment || env('REKHU_DEPLOYMENT') || 'cloud',
+        platform: String(options.platform || env('REKHU_PLATFORM') || 'https://api.rekhu.ai').replace(/\/$/, ''),
+        tenancy: options.tenancy || (options.tenant ? 'multi' : 'single'),
+        appId: options.appId || 'app',
+        appName: options.appName || 'the application',
+        locales: (options.locales || String(env('REKHU_LOCALES') || 'en').split(',')).map((l) => String(l).trim().toLowerCase()).filter(Boolean),
+        knowers: options.knowers || String(env('REKHU_KNOWERS') || '').split(',').map((k) => k.trim()).filter(Boolean),
+        limits: options.limits || {},
+        ledger: options.ledger === false ? null : options.ledger || memoryLedger(),
+        timeout: options.timeout || 180000,
+        fetch: options.fetch || globalThis.fetch,
+    };
+    const resolvers = { tenant: options.tenant || null, locale: options.locale || null, limits: options.limitsFor || null, price: options.price || null, onUsage: options.onUsage || null };
+
+    function platform() {
+        if (config.deployment === 'private' && (!config.platform || config.platform === 'https://api.rekhu.ai')) {
+            throw new RekhuError('REKHU_DEPLOYMENT is private: set REKHU_PLATFORM to the address of Rekhu inside your network.', 0, 'configuration_error');
+        }
+        if (!['cloud', 'private'].includes(config.deployment)) throw new RekhuError(`REKHU_DEPLOYMENT ${config.deployment} is not available; use cloud or private.`, 0, 'configuration_error');
+        return config.platform;
+    }
+
+    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');
+        return k;
+    }
+
+    async function tenantOf(user, named) {
+        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 !== null && t !== undefined && t !== '' && typeof t !== 'object') return { id: String(t), name: String(t) };
+        return null;
+    }
+
+    async function localeOf(user) {
+        const asked = String((resolvers.locale && user ? await resolvers.locale(user) : null) || config.locales[0] || 'en').slice(0, 2).toLowerCase();
+        return config.locales.includes(asked) ? asked : config.locales[0] || 'en';
+    }
+
+    async function checkLimits(tenant, userId, knower) {
+        if (!config.ledger) return;
+        const limits = { ...(config.limits[knower] || {}), ...((resolvers.limits && (await resolvers.limits(tenant, knower))) || {}) };
+        const since = new Date(new Date().toISOString().slice(0, 10) + 'T00:00:00.000Z').toISOString();
+        if (limits.perDayPerTenant != null && tenant && (await config.ledger.count({ knower, tenant: tenant.id, since })) >= limits.perDayPerTenant) {
+            throw new LimitReached(`${tenant.name} has used today's ${limits.perDayPerTenant} calls to ${knower}.`, 'tenant');
+        }
+        if (limits.perDayPerUser != null && userId != null && (await config.ledger.count({ knower, user: String(userId), since })) >= limits.perDayPerUser) {
+            throw new LimitReached(`Today's ${limits.perDayPerUser} calls to ${knower} are used up.`, 'user');
+        }
+    }
+
+    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');
+    }
+
+    /** 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 } = {}) {
+        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);
+        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) } : {}) };
+        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 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;
+        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,
+            ok: true, model_calls: Number(meta.model_calls || 0), cost_usd: Number(meta.cost_usd || 0),
+            price: resolvers.price ? (await resolvers.price(tenant, knower, action, meta)) ?? null : null, ms: Date.now() - started, created_at: new Date().toISOString(),
+        };
+        if (config.ledger) await config.ledger.record(row);
+        if (resolvers.onUsage) await resolvers.onUsage({ ...row, tenant, user });
+        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);
+        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());
+    }
+
+    const knowerFor = (name) => (who = {}) => ({ call: (action, input, extra = {}) => call(name, action, input, { ...who, ...extra }), feedback: (ref, outcome, correction) => feedback(name, ref, outcome, correction) });
+
+    /** Rekhu Machines: printing and finishing machines, sent as a Rekhu machine profile (see the README). */
+    const machines = (who = {}) => {
+        const k = knowerFor('machines')(who);
+        return {
+            ...k,
+            models: async () => (await k.call('models', {})).models || [],
+            identify: (text) => k.call('identify', { text }),
+            profile: (model, known = {}) => k.call('profile', { model, known }),
+            check: (machine, { model = null, explain = false } = {}) => k.call('check', { machine, ...(model ? { model } : {}), ...(explain ? { explain: true } : {}) }),
+            choose: (job, list) => k.call('choose', { job, machines: list }),
+            explain: (question, { machine = null, model = null } = {}) => k.call('explain', { question, ...(machine ? { machine } : {}), ...(model ? { model } : {}) }),
+        };
+    };
+
+    const bytesOf = async (file) => (file instanceof Uint8Array ? file : file instanceof ArrayBuffer ? new Uint8Array(file) : typeof file?.arrayBuffer === 'function' ? new Uint8Array(await file.arrayBuffer()) : null);
+
+    /** Seshat: a print file against the order it is for; fix, preview, download. With ai_enhance: one picture improved. */
+    const seshat = (who = {}) => {
+        const k = knowerFor('seshat')(who);
+        const file = async (f, name, what) => {
+            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');
+            return { name, bytes };
+        };
+        return {
+            ...k,
+            check: async (f, { name, order = {}, explain = false } = {}) => k.call('check', { order, ...(explain ? { explain: true } : {}) }, { file: await file(f, name, 'check') }),
+            /** Which modules this application may use (preflight, ai_enhance) and the modes. Not charged. */
+            modules: () => k.call('modules', {}),
+            /** A file kept for a day (a mask, a background picture): its file_id. Not charged. */
+            upload: async (f, { name } = {}) => k.call('upload', {}, { file: await file(f, name, 'upload') }),
+            /**
+             * ai_enhance: one picture (bytes with a name, or a file_id) through the modes, in order. options: ppi, width_mm,
+             * height_mm, factor, all_mm…, background, region; extra: async, webhookUrl, maskFileId, backgroundFileId.
+             * A large picture answers { status: 'queued', job_id }: poll() it, or verify the webhook with verifyWebhook().
+             */
+            enhance: async (picture, modes, options = {}, extra = {}) => {
+                const input = {
+                    mode: [].concat(modes), options,
+                    ...(extra.async ? { async: true } : {}), ...(extra.webhookUrl ? { webhook_url: extra.webhookUrl } : {}),
+                    ...(extra.maskFileId ? { mask_file_id: extra.maskFileId } : {}), ...(extra.backgroundFileId ? { background_file_id: extra.backgroundFileId } : {}),
+                };
+                if (typeof picture === 'string' && /^f_[a-z0-9]{24}$/.test(picture)) return k.call('enhance', { ...input, file_id: picture });
+                return k.call('enhance', input, { file: await file(picture, extra.name, 'enhance') });
+            },
+            enhancePreview: (fileId, { longest = 900 } = {}) => k.call('enhance_preview', { file_id: fileId, longest }),
+            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),
+        };
+    };
+
+    return { config, machines, seshat, knower: knowerFor, installed: (name) => config.knowers.includes(name), usage: (filter) => usage(config.ledger, filter) };
+}

package/src/ledger.js

@@ -0,0 +1,60 @@
+// Where every call to a knower is kept: who (tenant, user), which knower and action, what Rekhu charged and the app's
+// own price. The app's limits a day are counted from it. Any object with record(row) and count(filter) works: a table
+// in the app's own database is the usual choice; these two are for one process, and for a single server.
+
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+const matches = (row, { knower, tenant, user, since, until }) =>
+    (!knower || row.knower === knower)
+    && (tenant === undefined || row.tenant_id === tenant)
+    && (user === undefined || row.user_id === user)
+    && (!since || row.created_at >= since)
+    && (!until || row.created_at < until);
+
+/** In memory, for one process: development, tests, or a server that may forget its usage on a restart. */
+export function memoryLedger() {
+    const rows = [];
+    return {
+        async record(row) { rows.push(row); },
+        async count(filter) { return rows.filter((r) => matches(r, filter)).length; },
+        async rows(filter = {}) { return rows.filter((r) => matches(r, filter)); },
+    };
+}
+
+/** One JSON line per call in a file: for a single server, read by `npx rekhu-core usage --ledger <file>`. */
+export function fileLedger(path) {
+    const all = async () => {
+        const text = await readFile(path, 'utf8').catch((error) => (error.code === 'ENOENT' ? '' : Promise.reject(error)));
+        return text.split('\n').filter(Boolean).map((line) => { try { return JSON.parse(line); } catch { return null; } }).filter(Boolean);
+    };
+    return {
+        async record(row) {
+            await mkdir(dirname(path), { recursive: true });
+            await appendFile(path, JSON.stringify(row) + '\n');
+        },
+        async count(filter) { return (await all()).filter((r) => matches(r, filter)).length; },
+        async rows(filter = {}) { return (await all()).filter((r) => matches(r, filter)); },
+    };
+}
+
+/** The usage of a month per tenant, knower and action: calls, model calls, Rekhu's cost and the app's price. */
+export async function usage(ledger, { month, tenant } = {}) {
+    if (typeof ledger.rows !== 'function') throw new Error('this ledger cannot list its rows; read the usage from your own table');
+    const m = month || new Date().toISOString().slice(0, 7);
+    if (!/^\d{4}-\d{2}$/.test(m)) throw new Error('the month is YYYY-MM');
+    const since = `${m}-01T00:00:00.000Z`;
+    const [y, mo] = m.split('-').map(Number);
+    const until = new Date(Date.UTC(mo === 12 ? y + 1 : y, mo === 12 ? 0 : mo, 1)).toISOString();
+    const groups = new Map();
+    for (const r of await ledger.rows({ since, until, ...(tenant !== undefined ? { tenant } : {}) })) {
+        const key = [r.tenant_id, r.knower, r.action].join('|');
+        const g = groups.get(key) || { tenant: r.tenant_id, name: r.tenant_name, knower: r.knower, action: r.action, calls: 0, model_calls: 0, cost_usd: 0, price: null };
+        g.calls += 1;
+        g.model_calls += Number(r.model_calls || 0);
+        g.cost_usd = Math.round((g.cost_usd + Number(r.cost_usd || 0)) * 1e6) / 1e6;
+        if (r.price !== null && r.price !== undefined) g.price = Math.round(((g.price || 0) + Number(r.price)) * 100) / 100;
+        groups.set(key, g);
+    }
+    return [...groups.values()].sort((a, b) => `${a.tenant}${a.knower}${a.action}`.localeCompare(`${b.tenant}${b.knower}${b.action}`));
+}