shutro-erp 0.3.0 → 0.3.2

package/dist/cli/templates.d.ts

@@ -1,5 +1,5 @@
 /**
- * The starter project `kosh init` writes: an API server and the back-office app, both importing `shutro-erp`.
+ * The starter project `shutro-erp init` writes: an API server and the back-office app, both importing `shutro-erp`.
  * Server files run on Node.js directly (type stripping); the back-office is a Vite app proxying `/api` to the server.
  */
 export type AppName = 'permissions' | 'reporting' | 'messaging' | 'contacts' | 'product' | 'sales' | 'purchase' | 'accounting' | 'sale_account' | 'purchase_account' | 'project' | 'sale_project' | 'l10n_bd' | 'l10n_in';
@@ -16,7 +16,7 @@ export interface AppSpec {
     /** A localization (RFC 0016): installed, with its bridged apps, for a company in this country (ISO 3166). */
     readonly country?: string;
 }
-/** The apps `kosh init` can install (base and Settings are always there), in the order the installer lists them. */
+/** The apps `shutro-erp init` can install (base and Settings are always there), in the order the installer lists them. */
 export declare const APPS: Readonly<Record<AppName, AppSpec>>;
 export interface StarterOptions {
     readonly name: string;
@@ -27,7 +27,7 @@ export interface StarterOptions {
     readonly koshVersion: string;
     /** The database name of the Docker PostgreSQL service (compose.yaml). */
     readonly dockerDb?: string;
-    /** Attachments in a folder (KOSH_STORAGE_DIR) rather than S3. */
+    /** Attachments in a folder (SHUTRO_ERP_STORAGE_DIR) rather than S3. */
     readonly fileStorage?: boolean;
 }
 /** The project's package.json (merged into an existing one: missing scripts and dependencies are added). */

package/dist/cli/templates.js

@@ -1,8 +1,8 @@
 /**
- * The starter project `kosh init` writes: an API server and the back-office app, both importing `shutro-erp`.
+ * The starter project `shutro-erp init` writes: an API server and the back-office app, both importing `shutro-erp`.
  * Server files run on Node.js directly (type stripping); the back-office is a Vite app proxying `/api` to the server.
  */
-/** The apps `kosh init` can install (base and Settings are always there), in the order the installer lists them. */
+/** The apps `shutro-erp init` can install (base and Settings are always there), in the order the installer lists them. */
 export const APPS = {
     permissions: {
         label: 'Roles, field security and approvals',
@@ -88,6 +88,7 @@ const REACT = {
     react: '^19.1.0',
     'react-dom': '^19.1.0',
     '@tanstack/react-query': '^5.90.0',
+    '@tanstack/react-router': '^1.170.0',
     i18next: '^25.0.0 || ^26.0.0',
     'react-i18next': '^16.0.0 || ^17.0.0',
 };
@@ -105,8 +106,8 @@ export function packageJson(options, existing) {
             start: 'node --env-file=.env src/server.ts',
             web: 'vite',
             'build:web': 'vite build',
-            migrate: 'kosh migrate',
-            seed: 'kosh seed',
+            migrate: 'shutro-erp migrate',
+            seed: 'shutro-erp seed',
             'docker:up': 'docker compose up -d --build',
         }),
         engines: { node: '>=24', ...(base['engines'] ?? {}) },
@@ -130,12 +131,13 @@ export function modulesTs(_options) {
     const imports = apps.map((a) => `import { ${APPS[a].server} } from 'shutro-erp/${a}';`);
     return `/**
  * The apps this installation can install (the catalogue). The database records which are installed: Settings → Apps
- * in the back-office, or \`npx kosh apps\`, installs, disables and enables them. \`base\` (users, companies, sign-in)
+ * in the back-office, or \`npx shutro-erp apps\`, installs, disables and enables them. \`base\` (users, companies, sign-in)
  * and Settings are always installed. Add your own modules here (\`defineModule\` from \`shutro-erp/modules-sdk\`),
  * then install them from Settings → Apps.
  */
 import { base } from 'shutro-erp';
 import { automation } from 'shutro-erp/automation';
+import { integrations } from 'shutro-erp/integrations';
 import { mail } from 'shutro-erp/mail';
 import { notify } from 'shutro-erp/notify';
 import { realtime } from 'shutro-erp/realtime';
@@ -145,12 +147,12 @@ import { dataImport } from 'shutro-erp/import';
 import { studio } from 'shutro-erp/studio';
 ${imports.join('\n')}
 
-export const modules = [base, settings, realtime, notify, mail, automation, studio, dataImport, assistant${apps.map((a) => `, ${APPS[a].server}`).join('')}];
+export const modules = [base, settings, realtime, notify, mail, automation, integrations, studio, dataImport, assistant${apps.map((a) => `, ${APPS[a].server}`).join('')}];
 `;
 }
 export function serverTs() {
     return `/**
- * The Kosh API server: \`npm start\` (reads .env). It serves the installed apps of src/modules.ts, and switches to
+ * The Shutro ERP API server: \`npm start\` (reads .env). It serves the installed apps of src/modules.ts, and switches to
  * the new set without a restart when apps are installed or disabled (here or on another server).
  */
 import { createAppHost, startAppHost } from 'shutro-erp';
@@ -162,11 +164,11 @@ const host = await createAppHost({
   catalogue: modules,
   migrationsDir: 'migrations',
   ...(env['VALKEY_URL'] ? { valkeyUrl: env['VALKEY_URL'] } : {}),
-  // Secure cookies need HTTPS: on by default in production (KOSH_SECURE_COOKIES=false for plain HTTP).
-  auth: { secureCookies: (env['KOSH_SECURE_COOKIES'] ?? String(env['NODE_ENV'] === 'production')) === 'true' },
+  // Secure cookies need HTTPS: on by default in production (SHUTRO_ERP_SECURE_COOKIES=false for plain HTTP).
+  auth: { secureCookies: (env['SHUTRO_ERP_SECURE_COOKIES'] ?? env['KOSH_SECURE_COOKIES'] ?? String(env['NODE_ENV'] === 'production')) === 'true' },
 });
 const address = await startAppHost(host, { port: Number(env['PORT'] ?? 3000), host: env['HOST'] ?? '127.0.0.1' });
-process.stdout.write(\`Kosh API on \${address}\\n\`);
+process.stdout.write(\`Shutro ERP API on \${address}\\n\`);
 `;
 }
 export function viteConfig(options) {
@@ -176,7 +178,7 @@ import react from '@vitejs/plugin-react';
 import { koshPwa } from 'shutro-erp/ui/vite';
 import { defineConfig } from 'vite';
 
-const api = process.env['KOSH_API'] ?? 'http://localhost:${options.port}';
+const api = process.env['SHUTRO_ERP_API'] ?? process.env['KOSH_API'] ?? 'http://localhost:${options.port}';
 
 export default defineConfig({
   // koshPwa: the service worker (the app opens offline and gets web push)
@@ -216,6 +218,7 @@ export function mainTsx(_options) {
         { name: 'notify', fn: 'registerNotifyWeb' },
         { name: 'mail', fn: 'registerMailWeb' },
         { name: 'automation', fn: 'registerAutomationWeb' },
+        { name: 'integrations', fn: 'registerIntegrationsWeb' },
         { name: 'studio', fn: 'registerStudioWeb' },
         { name: 'assistant', fn: 'registerAssistantWeb' },
         { name: 'import', fn: 'registerImportWeb' },
@@ -263,7 +266,7 @@ export function manifest(options) {
 }
 /** The app icon (replace it with the company's). */
 export function icon() {
-    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" role="img" aria-label="Kosh">
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" role="img" aria-label="Shutro ERP">
   <rect width="512" height="512" rx="112" fill="#1d4ed8"/>
   <path d="M156 128h56v112l108-112h72L270 258l128 126h-74L220 282v102h-64z" fill="#fff"/>
 </svg>
@@ -273,7 +276,7 @@ export function indexCss() {
     return `@import "tailwindcss";
 @import "shutro-erp/ui/styles.css";
 
-/* Tailwind scans Kosh's components for the classes they use. */
+/* Tailwind scans Shutro ERP's components for the classes they use. */
 @source "../../node_modules/shutro-erp/dist";
 `;
 }
@@ -286,7 +289,7 @@ var/
 }
 /** Three images from one build: the API (migrates, then serves) and nginx with the back-office. */
 export function dockerfile() {
-    return `# Kosh images (kosh init). Built by compose.yaml: docker compose up -d --build
+    return `# Shutro ERP images (shutro-erp init). Built by compose.yaml: docker compose up -d --build
 FROM node:24-alpine AS build
 WORKDIR /app
 COPY package.json package-lock.json* ./
@@ -306,7 +309,7 @@ COPY --from=build /app/migrations ./migrations
 RUN mkdir -p /app/var/attachments && chown -R node:node /app/var
 USER node
 EXPOSE 3000
-CMD ["sh", "-c", "npx kosh migrate && node src/server.ts"]
+CMD ["sh", "-c", "npx shutro-erp migrate && node src/server.ts"]
 
 # The back-office: static files, /api proxied to the API.
 FROM nginx:1.27-alpine AS web
@@ -315,7 +318,7 @@ COPY nginx.conf /etc/nginx/conf.d/default.conf
 `;
 }
 export function nginxConf() {
-    return `# The back-office (kosh init): the built app, /api proxied to the API service.
+    return `# The back-office (shutro-erp init): the built app, /api proxied to the API service.
 server {
   listen 80;
   root /usr/share/nginx/html;
@@ -346,9 +349,9 @@ export function composeYaml(options) {
     const db = options.dockerDb ?? options.name.replace(/-/g, '_');
     /** A compose variable: `${NAME}` or `${NAME:-default}` (plain strings: nothing to escape). */
     const v = (name, fallback) => ['$', '{', name, fallback === undefined ? '' : fallback, '}'].join('');
-    const user = v('POSTGRES_USER', ':-kosh');
+    const user = v('POSTGRES_USER', ':-shutro');
     const lines = [
-        '# Kosh in Docker (kosh init).',
+        '# Shutro ERP in Docker (shutro-erp init).',
         '#   docker compose up -d db          only PostgreSQL (the API runs with npm start)',
         '#   docker compose up -d --build     everything: the back-office on http://localhost:8080',
         `name: ${options.name}`,
@@ -367,7 +370,7 @@ export function composeYaml(options) {
         '      - db:/var/lib/postgresql',
         '    healthcheck:',
         // $$ is a literal $ for compose: the shell in the container expands the variable.
-        `      test: ["CMD-SHELL", "pg_isready -U $${v('POSTGRES_USER', ':-kosh')}"]`,
+        `      test: ["CMD-SHELL", "pg_isready -U $${v('POSTGRES_USER', ':-shutro')}"]`,
         '      interval: 5s',
         '      retries: 30',
         '',
@@ -379,9 +382,11 @@ export function composeYaml(options) {
         '    env_file: .env',
         '    environment:',
         `      DATABASE_URL: ${v('DOCKER_DATABASE_URL', `:-postgres://${user}:${v('POSTGRES_PASSWORD')}@db:5432/${v('POSTGRES_DB', `:-${db}`)}`)}`,
-        ...(options.fileStorage === false ? [] : ['      KOSH_STORAGE_DIR: /app/var/attachments']),
+        ...(options.fileStorage === false
+            ? []
+            : ['      SHUTRO_ERP_STORAGE_DIR: /app/var/attachments']),
         '      # Plain HTTP on localhost; set "true" when the site is served over HTTPS.',
-        '      KOSH_SECURE_COOKIES: "false"',
+        '      SHUTRO_ERP_SECURE_COOKIES: "false"',
         '    depends_on:',
         '      db:',
         '        condition: service_healthy',
@@ -431,19 +436,19 @@ export function tsconfig() {
 export function readme(options) {
     return `# ${options.name}
 
-A [Kosh](https://www.npmjs.com/package/shutro-erp) installation, created with \`kosh init\`.
+A [Shutro ERP](https://www.npmjs.com/package/shutro-erp) installation, created with \`shutro-erp init\`.
 
 \`\`\`sh
 npm install
 npm start          # the API on http://localhost:${options.port}
 npm run web        # the back-office on http://localhost:${options.webPort ?? 5173} (sign in as the administrator)
-npx kosh migrate   # after changing modules: plan and apply database migrations, load seed data
-npx kosh seed      # load seed data again
+npx shutro-erp migrate   # after changing modules: plan and apply database migrations, load seed data
+npx shutro-erp seed      # load seed data again
 # Settings → Apps in the back-office installs, enables and disables apps (or, in the terminal:)
-npx kosh apps                   # the apps: installed, disabled, available
-npx kosh apps install <name>    # install an app (and what it needs) in one transaction
-npx kosh apps disable <name>    # switch an app off; its data stays (npx kosh apps enable <name>)
-npx kosh module create <name>   # a new module in src/modules/<name>/
+npx shutro-erp apps                   # the apps: installed, disabled, available
+npx shutro-erp apps install <name>    # install an app (and what it needs) in one transaction
+npx shutro-erp apps disable <name>    # switch an app off; its data stays (npx shutro-erp apps enable <name>)
+npx shutro-erp module create <name>   # a new module in src/modules/<name>/
 docker compose up -d --build    # everything in Docker: http://localhost:8080
 \`\`\`
 

package/dist/cli/ui.d.ts

@@ -1,10 +1,3 @@
-/**
- * The installer's look in the terminal, without dependencies: a logo, numbered steps, spinners for long work,
- * status lines (✔ ▲ ✖) and a summary card. On a Unicode terminal everything hangs on one rail down the left (│),
- * the questions of the interactive prompter included (`tui.ts`). Colour, Unicode and animation are detected from
- * the terminal (NO_COLOR, FORCE_COLOR, KOSH_ASCII=1, TERM=dumb, Windows consoles without Unicode); output that is not
- * a terminal (tests, logs, CI) gets plain lines with the same words and no escape codes.
- */
 /** What the terminal can show. */
 export interface Terminal {
     readonly color: boolean;
@@ -23,7 +16,7 @@ type Env = Readonly<Record<string, string | undefined>>;
 export declare function detectTerminal(stream: {
     readonly isTTY?: boolean;
     readonly columns?: number;
-}, env?: Env, platform?: string): Terminal;
+}, env?: Env, platform?: string, release?: string): Terminal;
 export declare const ESC = "\u001B[";
 /** The colours and weights the installer uses. */
 export type Style = 'bold' | 'dim' | 'inverse' | 'underline' | 'green' | 'yellow' | 'red' | 'cyan' | 'magenta' | 'gray';

package/dist/cli/ui.js

@@ -2,9 +2,10 @@
  * The installer's look in the terminal, without dependencies: a logo, numbered steps, spinners for long work,
  * status lines (✔ ▲ ✖) and a summary card. On a Unicode terminal everything hangs on one rail down the left (│),
  * the questions of the interactive prompter included (`tui.ts`). Colour, Unicode and animation are detected from
- * the terminal (NO_COLOR, FORCE_COLOR, KOSH_ASCII=1, TERM=dumb, Windows consoles without Unicode); output that is not
+ * the terminal (NO_COLOR, FORCE_COLOR, SHUTRO_ERP_ASCII=1, TERM=dumb, Windows consoles without Unicode); output that is not
  * a terminal (tests, logs, CI) gets plain lines with the same words and no escape codes.
  */
+import { release as osRelease } from 'node:os';
 /** Plain output: logs, tests, pipes. */
 export const PLAIN_TERMINAL = Object.freeze({
     color: false,
@@ -14,7 +15,7 @@ export const PLAIN_TERMINAL = Object.freeze({
     columns: 80,
 });
 /** Detects what `stream` (process.stdout) can show. */
-export function detectTerminal(stream, env = process.env, platform = process.platform) {
+export function detectTerminal(stream, env = process.env, platform = process.platform, release = osRelease()) {
     const tty = stream.isTTY === true && env['TERM'] !== 'dumb' && env['CI'] === undefined;
     const forced = env['FORCE_COLOR'] !== undefined && env['FORCE_COLOR'] !== '0';
     const color = env['NO_COLOR'] === undefined && (forced || tty);
@@ -24,11 +25,16 @@ export function detectTerminal(stream, env = process.env, platform = process.pla
         env['ConEmuTask'] === '{cmd::Cmder}' ||
         env['TERM'] === 'xterm-256color' ||
         env['TERM'] === 'alacritty';
-    const unicode = env['KOSH_ASCII'] !== '1' && (platform === 'win32' ? modernWindows : env['TERM'] !== 'linux');
+    // Windows 10 and later: the console host shows box drawing and colours too (UTF-8, virtual terminal); pictographs
+    // only in the modern terminals. Older Windows keeps ASCII.
+    const windows10 = Number(release.split('.')[0]) >= 10;
+    const unicode = env['KOSH_ASCII'] !== '1' &&
+        env['SHUTRO_ERP_ASCII'] !== '1' &&
+        (platform === 'win32' ? modernWindows || windows10 : env['TERM'] !== 'linux');
     return {
         color,
         unicode,
-        emoji: unicode && tty,
+        emoji: unicode && tty && (platform !== 'win32' || modernWindows),
         animate: tty,
         columns: Math.max(40, Math.min(stream.columns ?? 80, 120)),
     };
@@ -92,12 +98,12 @@ export const ICONS = {
     rocket: ['🚀', '◆'],
 };
 const LOGO = [
-    '██╗  ██╗ ██████╗ ███████╗██╗  ██╗',
-    '██║ ██╔╝██╔═══██╗██╔════╝██║  ██║',
-    '█████╔╝ ██║   ██║███████╗███████║',
-    '██╔═██╗ ██║   ██║╚════██║██╔══██║',
-    '██║  ██╗╚██████╔╝███████║██║  ██║',
-    '╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═╝',
+    '███████╗██╗  ██╗██╗   ██╗████████╗██████╗  ██████╗',
+    '██╔════╝██║  ██║██║   ██║╚══██╔══╝██╔══██╗██╔═══██╗',
+    '███████╗███████║██║   ██║   ██║   ██████╔╝██║   ██║',
+    '╚════██║██╔══██║██║   ██║   ██║   ██╔══██╗██║   ██║',
+    '███████║██║  ██║╚██████╔╝   ██║   ██║  ██║╚██████╔╝',
+    '╚══════╝╚═╝  ╚═╝ ╚═════╝    ╚═╝   ╚═╝  ╚═╝ ╚═════╝',
 ];
 /** Cyan to violet, one 256-colour step per logo line. */
 const GRADIENT = [51, 45, 39, 33, 63, 99];
@@ -141,7 +147,7 @@ export function createUi(out, terminal = PLAIN_TERMINAL, options = {}) {
         icon,
         async banner(subtitle) {
             if (!terminal.unicode) {
-                write(`\n  ${s('bold', 'K O S H')}  ${subtitle}\n`);
+                write(`\n  ${s('bold', 'S H U T R O   E R P')}  ${subtitle}\n`);
                 return;
             }
             write('\n');
@@ -245,7 +251,25 @@ export function createUi(out, terminal = PLAIN_TERMINAL, options = {}) {
         },
         card(title, rows, tone = 'green') {
             const labelWidth = Math.max(0, ...rows.map(([l]) => width(l)));
-            const body = rows.map(([l, v]) => `${s('gray', l.padEnd(labelWidth))}  ${v}`);
+            // Long values wrap at the terminal's width, aligned after their label.
+            const room = Math.max(20, Math.min(terminal.columns, 100) - labelWidth - 10);
+            const wrap = (value) => {
+                const lines = [];
+                let current = '';
+                for (const word of value.split(' ')) {
+                    const next = current === '' ? word : `${current} ${word}`;
+                    if (current !== '' && width(next) > room) {
+                        lines.push(current);
+                        current = word;
+                    }
+                    else
+                        current = next;
+                }
+                return [...lines, current];
+            };
+            const body = rows.flatMap(([l, v]) => wrap(v).map((part, i) => i === 0
+                ? `${s('gray', l.padEnd(labelWidth))}  ${part}`
+                : `${' '.repeat(labelWidth)}  ${part}`));
             const inner = Math.max(width(title), ...body.map(width)) + 2;
             const [tl, tr, bl, br, h, v] = terminal.unicode
                 ? ['╭', '╮', '╰', '╯', '─', '│']

package/dist/contacts/.kosh/bindings.js

@@ -1,4 +1,4 @@
-// GENERATED by `pnpm generate:models` (Shutro’s generator). Do not edit. definitions-hash: 07f36b4355890ebe
+// GENERATED by `pnpm generate:models` (Shutro’s generator). Do not edit. definitions-hash: 2271aaa68e1a18a5
 // Bindings of module `contacts`: import the definition API from here to get types scoped to what it can see.
 export { defineModel, defineModule, extendModel, f, replace } from '../../server/orm.js';
 import { definitions } from '../../server/orm.js';

package/dist/contacts/.kosh/schema.d.ts

@@ -1,10 +1,11 @@
-// GENERATED by `pnpm generate:models` (Shutro’s generator). Do not edit. definitions-hash: 07f36b4355890ebe
+// GENERATED by `pnpm generate:models` (Shutro’s generator). Do not edit. definitions-hash: 2271aaa68e1a18a5
 // Schema view of module `contacts` (RFC 0002 §7.7): the models it owns or depends on, with the extensions it can see.
 import type { F } from '../../server/orm.js';
 
 /** Model name → model type (RFC 0002 §7.7). */
 export interface SchemaView {
   readonly 'audit.event': AuditEvent;
+  readonly 'auth.api_key': AuthApiKey;
   readonly 'auth.credential': AuthCredential;
   readonly 'auth.session': AuthSession;
   readonly 'auth.user_grant': AuthUserGrant;
@@ -42,6 +43,34 @@ export interface AuditEvent {
 export interface AuditEventMethods extends F.Methods<typeof import('../../server/index.js').baseShutro, 'audit.event'> {
 }
 
+/** `auth.api_key` (owner: base). */
+export interface AuthApiKey {
+  readonly name: 'auth.api_key';
+  readonly fields: {
+    readonly id: F.Id<'auth.api_key'>;
+    readonly createdAt: F.Datetime<{ readonly required: true; readonly readonly: true }>;
+    readonly updatedAt: F.Datetime<{ readonly required: true; readonly readonly: true }>;
+    readonly createdBy: F.Many2one<'res.users', { readonly readonly: true }>;
+    readonly updatedBy: F.Many2one<'res.users', { readonly readonly: true }>;
+    readonly displayName: F.Char<{ readonly required: true; readonly readonly: true; readonly compute: true }>;
+    readonly name: F.Char<{ readonly required: true }>;
+    readonly user: F.Many2one<'res.users', { readonly required: true }>;
+    readonly tokenHash: F.Char<{ readonly required: true }>;
+    readonly prefix: F.Char<{ readonly required: true }>;
+    readonly scopes: F.Text<{ readonly required: true }>;
+    readonly expiresAt: F.Datetime<{ readonly required: true }>;
+    readonly lastUsedAt: F.Datetime;
+    readonly lastUsedIp: F.Char;
+    readonly revoked: F.Bool<{ readonly required: true; readonly default: true }>;
+    readonly issuedBy: F.Many2one<'res.users'>;
+  };
+  readonly methods: AuthApiKeyMethods;
+}
+
+/** Methods of `auth.api_key`: declared ones and transitions. */
+export interface AuthApiKeyMethods extends F.Methods<typeof import('../../server/index.js').baseShutro, 'auth.api_key'> {
+}
+
 /** `auth.credential` (owner: base). */
 export interface AuthCredential {
   readonly name: 'auth.credential';
@@ -260,6 +289,7 @@ export interface ResUsers {
     readonly companies: F.Many2many<'res.company', { readonly required: true }>;
     readonly lang: F.Char<{ readonly default: true }>;
     readonly tz: F.Char<{ readonly default: true }>;
+    readonly isService: F.Bool<{ readonly required: true; readonly default: true }>;
   };
   readonly methods: ResUsersMethods;
 }

package/dist/integrations/inbound.d.ts

@@ -0,0 +1,36 @@
+import type { InboundCall, InboundWebhookSpec } from '../modules-sdk/index.js';
+import type { KoshRegistry } from '../server/index.js';
+import type { Shutro } from '../server/orm.js';
+export declare const INBOUND_JOB = "webhook.inbound";
+/** The declared inbound webhooks of the loaded modules, by `<module>.<key>`. */
+export declare function inboundHooks(registry: KoshRegistry): Map<string, InboundWebhookSpec & {
+    readonly module: string;
+}>;
+/**
+ * A `verify` for providers that sign with an HMAC of the raw body: the signature in `header` (hex or base64,
+ * optionally after a prefix such as `sha256=`), compared in constant time; the event id from `eventId`.
+ */
+export declare function hmacVerifier(options: {
+    readonly header: string;
+    readonly algorithm?: 'sha256' | 'sha512' | 'sha1';
+    readonly encoding?: 'hex' | 'base64';
+    readonly prefix?: string;
+    readonly eventId: (call: InboundCall) => string | null | undefined;
+}): (call: InboundCall, secret: string) => string | null;
+export interface ReceiveResult {
+    readonly status: 202 | 200 | 401 | 404;
+    readonly body: Record<string, unknown>;
+}
+/** Receives a call on the endpoint of `token`: checked, stored, queued once per event id. */
+export declare function receive(context: {
+    readonly shutro: Shutro;
+    readonly registry: KoshRegistry;
+}, token: string, call: InboundCall): Promise<ReceiveResult>;
+/**
+ * Handles a stored call with its module's `handle`, as the system in the endpoint's company; records the outcome
+ * in its own transaction. Throws to be retried while attempts remain.
+ */
+export declare function handleInbound(context: {
+    readonly shutro: Shutro;
+    readonly registry: KoshRegistry;
+}, callId: number, company: number, last: boolean): Promise<void>;

package/dist/integrations/inbound.js

@@ -0,0 +1,171 @@
+/**
+ * Inbound webhooks (RFC 0017 §5.4). Modules declare endpoints (`inboundWebhooks` in their manifest); a company
+ * switches one on (`webhook.endpoint`: a URL token and a secret). A call to `POST /api/v1/hooks/<token>` is checked
+ * by the module's `verify` against the raw body, stored (refused calls too, for the log), and — once per event id —
+ * handled by the module in a job, as the system in the endpoint's company, retried on failure. A repeated event id
+ * is answered 200 and not handled again; a call can be handled again from the log (replay).
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { ref } from './webhooks.js';
+export const INBOUND_JOB = 'webhook.inbound';
+/** The declared inbound webhooks of the loaded modules, by `<module>.<key>`. */
+export function inboundHooks(registry) {
+    const out = new Map();
+    for (const m of registry.loaded.modules)
+        for (const hook of m.inboundWebhooks ?? [])
+            out.set(`${m.name}.${hook.key}`, { ...hook, module: m.name });
+    return out;
+}
+/**
+ * A `verify` for providers that sign with an HMAC of the raw body: the signature in `header` (hex or base64,
+ * optionally after a prefix such as `sha256=`), compared in constant time; the event id from `eventId`.
+ */
+export function hmacVerifier(options) {
+    return (call, secret) => {
+        let given = call.headers[options.header.toLowerCase()] ?? '';
+        if (options.prefix !== undefined) {
+            if (!given.startsWith(options.prefix))
+                return null;
+            given = given.slice(options.prefix.length);
+        }
+        const expected = createHmac(options.algorithm ?? 'sha256', secret)
+            .update(call.body)
+            .digest(options.encoding ?? 'hex');
+        const a = Buffer.from(given);
+        const b = Buffer.from(expected);
+        if (a.length !== b.length || !timingSafeEqual(a, b))
+            return null;
+        const id = options.eventId(call);
+        return id === null || id === undefined || id === '' ? null : String(id);
+    };
+}
+/** Headers worth keeping in the log (no cookies, no credentials). */
+const KEPT = /^(content-type|user-agent|x-[a-z0-9-]+)$/;
+function keptHeaders(headers) {
+    return Object.fromEntries(Object.entries(headers).filter((e) => e[1] !== undefined && KEPT.test(e[0]) && !/authorization|api-key|cookie/.test(e[0])));
+}
+/** Receives a call on the endpoint of `token`: checked, stored, queued once per event id. */
+export async function receive(context, token, call) {
+    const hooks = inboundHooks(context.registry);
+    // Which endpoint (and company) the token names: looked up across companies (the token is unique).
+    const found = await context.shutro.bootstrap({ reason: 'inbound webhook: endpoint' }, (env) => env.asSuperuser({ reason: 'inbound webhook: which endpoint' }, async (su) => {
+        const set = await ref(su.withFlags({ checkCompany: false }), 'webhook.endpoint').search({
+            where: { token, active: true },
+            limit: 1,
+        });
+        if (set.length === 0)
+            return null;
+        const [row] = (await set.load(['hook', 'secret', 'company'])).read([
+            'id',
+            'hook',
+            'secret',
+            'company',
+        ]);
+        return row ?? null;
+    }));
+    const hook = found === null ? undefined : hooks.get(String(found['hook']));
+    if (found === null || hook === undefined)
+        return { status: 404, body: { title: 'Not found', detail: 'No such webhook endpoint.' } };
+    const company = found['company'];
+    let eventId = null;
+    try {
+        eventId = await hook.verify(call, String(found['secret']));
+    }
+    catch {
+        eventId = null;
+    }
+    return context.shutro.bootstrap({ reason: `inbound webhook ${hook.module}.${hook.key}`, company }, async (env) => {
+        const calls = ref(env, 'webhook.inbound');
+        const base = {
+            endpoint: found['id'],
+            headers: keptHeaders(call.headers),
+            body: call.body.slice(0, 256 * 1024),
+            company,
+        };
+        if (eventId === null) {
+            await calls.create([{ ...base, verified: false, state: 'refused' }]);
+            return {
+                status: 401,
+                body: { title: 'Not verified', detail: 'The call’s signature does not match.' },
+            };
+        }
+        const seen = await calls.search({
+            where: { endpoint: found['id'], eventId, verified: true },
+            limit: 1,
+        });
+        if (seen.length > 0)
+            return { status: 200, body: { duplicate: true, eventId } };
+        const created = await calls.create([{ ...base, eventId, verified: true, state: 'received' }]);
+        const id = created.ids[0];
+        await env.enqueue(INBOUND_JOB, { call: id, company }, { attempts: 6 });
+        return { status: 202, body: { received: true, eventId } };
+    });
+}
+/**
+ * Handles a stored call with its module's `handle`, as the system in the endpoint's company; records the outcome
+ * in its own transaction. Throws to be retried while attempts remain.
+ */
+export async function handleInbound(context, callId, company, last) {
+    const hooks = inboundHooks(context.registry);
+    const system = (reason, fn) => context.shutro.bootstrap({ reason, company }, fn);
+    const found = await system('inbound webhook: the call', async (env) => {
+        const set = ref(env, 'webhook.inbound').browse([callId]);
+        const [c] = (await set.load(['endpoint', 'body', 'headers', 'state', 'attempts'])).read([
+            'endpoint',
+            'body',
+            'headers',
+            'state',
+            'attempts',
+        ]);
+        if (c === undefined)
+            return null;
+        const [e] = (await ref(env, 'webhook.endpoint')
+            .browse([c['endpoint']])
+            .load(['hook'])).read(['hook']);
+        return { row: c, hook: String(e?.['hook'] ?? '') };
+    });
+    if (found === null || found.row['state'] === 'done')
+        return;
+    const { row, hook: name } = found;
+    const hook = hooks.get(name);
+    const attempts = Number(row['attempts'] ?? 0) + 1;
+    const write = (values) => system('inbound webhook: the outcome', (env) => ref(env, 'webhook.inbound').browse([callId]).write(values));
+    if (hook === undefined) {
+        await write({
+            state: 'failed',
+            attempts,
+            error: `The endpoint ${name} is no longer installed.`,
+        });
+        return;
+    }
+    const body = String(row['body']);
+    let json = null;
+    try {
+        json = JSON.parse(body);
+    }
+    catch {
+        json = null;
+    }
+    const call = {
+        headers: (row['headers'] ?? {}),
+        query: {},
+        body,
+        json,
+    };
+    try {
+        const result = await system(`inbound webhook ${name}`, (env) => hook.handle(env, call));
+        await write({
+            state: 'done',
+            attempts,
+            result: typeof result === 'string' ? result : null,
+            error: null,
+            handledAt: new Date(),
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        await write({ state: last ? 'failed' : 'received', attempts, error: message });
+        if (!last)
+            throw error;
+    }
+}

package/dist/integrations/index.d.ts

@@ -0,0 +1,18 @@
+import { type KoshModule } from '../modules-sdk/index.js';
+import type { Worker } from '../server/orm.js';
+import { type IntegrationsContext } from './webhooks.js';
+export { handleInbound, hmacVerifier, INBOUND_JOB, inboundHooks, type ReceiveResult, receive, } from './inbound.js';
+export { integrationsShutro, newSecret, newToken } from './models.js';
+export { CHANGE_EVENTS, DELIVER_JOB, deliver, fanOut, type IntegrationsContext, PING_EVENT, signature, urlProblem, type WebhookEvent, webhookEvents, webhookHosts, } from './webhooks.js';
+/** The workers: events to deliveries (change events and the modules' events), and the delivery jobs. */
+export declare function webhookWorkers(integrations: IntegrationsContext): Worker[];
+export interface IntegrationsOptions {
+    /** The HTTP client deliveries use (tests). */
+    readonly fetch?: typeof fetch;
+    /** Start the workers (default: unless `SHUTRO_ERP_SCHEDULES=off`). */
+    readonly workers?: boolean;
+}
+/** The Integrations app with explicit options (tests, installations wiring their own). */
+export declare function integrationsModule(options?: IntegrationsOptions): KoshModule;
+/** The Integrations app (providers and workers from the environment). */
+export declare const integrations: KoshModule;