@rekhu/core 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 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`.

package/README.md

@@ -54,6 +54,42 @@ It fixes:
 - 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rekhu/core",
-  "version": "0.1.0",
+  "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",

package/src/index.js

@@ -6,10 +6,23 @@
 //     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.1.0';
+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 {
@@ -104,9 +117,9 @@ export function createRekhu(options = {}) {
         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 && action !== 'models') 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 (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 (action !== 'models') await checkLimits(tenant, who, knower);
+        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();
@@ -121,7 +134,8 @@ export function createRekhu(options = {}) {
         }
         if (!response.ok) throw await failed(response);
         const answer = await response.json();
-        if (action === 'models') return answer;
+        // 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,
@@ -163,17 +177,40 @@ export function createRekhu(options = {}) {
         };
     };
 
-    /** Seshat: a print file against the order it is for; fix, preview, download. */
+    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 (file, { name, order = {}, explain = false } = {}) => {
-                if (!name) throw new RekhuError('Give the file\'s name: check(bytes, { name: \'flyer.pdf\', order }).', 0, 'invalid_request_error');
-                const bytes = file instanceof Uint8Array ? file : file instanceof ArrayBuffer ? new Uint8Array(file) : typeof file?.arrayBuffer === 'function' ? new Uint8Array(await file.arrayBuffer()) : null;
-                if (!bytes) throw new RekhuError('The file is a Buffer, Uint8Array, ArrayBuffer or Blob.', 0, 'invalid_request_error');
-                return k.call('check', { order, ...(explain ? { explain: true } : {}) }, { file: { name, bytes } });
+            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),