@isahaq/kosh-server 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Isahaq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,22 @@
-# Temporary Holding Version
+# @isahaq/kosh-server
 
-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.
+Fastify app, module loader, REST/OpenAPI generator, auth, Shutro environment per request (RFC 0002)
+
+Part of [Kosh](https://github.com/isahaq1/kosh), a modern ERP framework on TypeScript, PostgreSQL and the
+[Shutro](https://github.com/isahaq1/shutro) ORM.
+
+```sh
+pnpm add @isahaq/kosh-server
+```
+
+Documentation: [docs/server.md](https://github.com/isahaq1/kosh/blob/main/docs/server.md) · design: [RFCs](https://github.com/isahaq1/kosh/tree/main/docs/rfcs)
+
+Node.js 24 or later; ESM only.
+
+## Contact
+
+Isahaq · hmisahaq01@gmail.com · +8801852376598
+
+## License
+
+MIT

package/dist/api/client.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The typed client generator (RFC 0002 §6.4, `kosh generate client`): turns the OpenAPI document of an installed
+ * module set into one self-contained TypeScript module, with no imports, that browsers and Node both run:
+ *
+ * - an interface per model (read, create, update) and per shared schema (Problem, Money, AggregateQuery, ...);
+ * - `Models`, the map from model name to those types and its transitions;
+ * - `createClient()`: typed calls for every generated route and the auth routes, sessions by cookie (with the
+ *   CSRF header) or Bearer token, `KoshApiError` carrying the RFC 9457 problem.
+ *
+ * Generated code is deterministic (sorted), so regenerating without changes gives the same file.
+ */
+type Schema = Readonly<Record<string, unknown>>;
+/** The TypeScript type of a JSON Schema (the subset `openApiDocument` emits). */
+export declare function typeOf(schema: Schema, indent?: string): string;
+/** Generates the client module for an OpenAPI document produced by `openApiDocument`. */
+export declare function generateClient(document: Schema): string;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/api/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,KAAK,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAgBhD,iFAAiF;AACjF,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,SAAK,GAAG,MAAM,CAgC1D;AAyCD,yFAAyF;AACzF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA8CvD"}

package/dist/api/client.js

@@ -0,0 +1,380 @@
+/**
+ * The typed client generator (RFC 0002 §6.4, `kosh generate client`): turns the OpenAPI document of an installed
+ * module set into one self-contained TypeScript module, with no imports, that browsers and Node both run:
+ *
+ * - an interface per model (read, create, update) and per shared schema (Problem, Money, AggregateQuery, ...);
+ * - `Models`, the map from model name to those types and its transitions;
+ * - `createClient()`: typed calls for every generated route and the auth routes, sessions by cookie (with the
+ *   CSRF header) or Bearer token, `KoshApiError` carrying the RFC 9457 problem.
+ *
+ * Generated code is deterministic (sorted), so regenerating without changes gives the same file.
+ */
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+function propertyName(key) {
+    return IDENTIFIER.test(key) ? key : JSON.stringify(key);
+}
+function refName(ref) {
+    return ref.replace(/^#\/components\/schemas\//, '');
+}
+function asSchema(value) {
+    return typeof value === 'object' && value !== null ? value : {};
+}
+/** The TypeScript type of a JSON Schema (the subset `openApiDocument` emits). */
+export function typeOf(schema, indent = '') {
+    if (typeof schema['$ref'] === 'string')
+        return refName(schema['$ref']);
+    if (Array.isArray(schema['oneOf']))
+        return schema['oneOf'].map((s) => typeOf(asSchema(s), indent)).join(' | ');
+    if (Array.isArray(schema['enum']))
+        return schema['enum'].map((v) => JSON.stringify(v)).join(' | ');
+    const types = Array.isArray(schema['type']) ? schema['type'] : [schema['type']];
+    return types
+        .map((type) => {
+        switch (type) {
+            case 'string':
+                return 'string';
+            case 'integer':
+            case 'number':
+                return 'number';
+            case 'boolean':
+                return 'boolean';
+            case 'null':
+                return 'null';
+            case 'array': {
+                const item = typeOf(asSchema(schema['items']), indent);
+                return /^[\w.]+$/.test(item) ? `${item}[]` : `(${item})[]`;
+            }
+            case 'object':
+                return schema['properties'] === undefined
+                    ? 'Record<string, unknown>'
+                    : objectType(schema, indent);
+            default:
+                return 'unknown';
+        }
+    })
+        .join(' | ');
+}
+function doc(schema, indent) {
+    const parts = [schema['title'], schema['description']].filter((p) => typeof p === 'string' && p !== '');
+    return parts.length === 0 ? '' : `${indent}/** ${parts.join(': ').replaceAll('*/', '* /')} */\n`;
+}
+function objectType(schema, indent) {
+    const properties = asSchema(schema['properties']);
+    const required = new Set(Array.isArray(schema['required']) ? schema['required'] : []);
+    const inner = `${indent}  `;
+    const lines = Object.entries(properties).map(([key, value]) => {
+        const s = asSchema(value);
+        const optional = required.has(key) ? '' : '?';
+        return `${doc(s, inner)}${inner}${propertyName(key)}${optional}: ${typeOf(s, inner)};`;
+    });
+    return lines.length === 0 ? 'Record<string, never>' : `{\n${lines.join('\n')}\n${indent}}`;
+}
+/** Model name → schema name and transitions, read back from the generated paths. */
+function modelsOf(paths) {
+    const models = new Map();
+    for (const [path, item] of Object.entries(paths)) {
+        const list = /^\/api\/v1\/models\/([^/{}]+)$/.exec(path);
+        const operation = asSchema(asSchema(item)['get'])['operationId'];
+        if (list?.[1] !== undefined && typeof operation === 'string' && operation.startsWith('list'))
+            models.set(list[1], { name: list[1], schema: operation.slice(4), transitions: [] });
+    }
+    for (const path of Object.keys(paths)) {
+        const t = /^\/api\/v1\/models\/([^/{}]+)\/\{id\}\/transitions\/([^/{}]+)$/.exec(path);
+        if (t?.[1] !== undefined && t[2] !== undefined)
+            models.get(t[1])?.transitions.push(t[2]);
+    }
+    return [...models.values()]
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((m) => ({ ...m, transitions: m.transitions.sort() }));
+}
+/** Generates the client module for an OpenAPI document produced by `openApiDocument`. */
+export function generateClient(document) {
+    const info = asSchema(document['info']);
+    const schemas = asSchema(asSchema(document['components'])['schemas']);
+    const models = modelsOf(asSchema(document['paths']));
+    const out = [];
+    out.push(`// Generated by \`kosh generate client\` from ${JSON.stringify(String(info['title'] ?? 'Kosh API'))} ${String(info['version'] ?? '')}. Do not edit: regenerate.`, '', '// ------------------------------------------------------------------------------------------------- schemas', '');
+    for (const name of Object.keys(schemas).sort()) {
+        const schema = asSchema(schemas[name]);
+        const body = typeOf(schema);
+        const declaration = body.startsWith('{')
+            ? `export interface ${name} ${body}`
+            : `export type ${name} = ${body};`;
+        out.push(`${doc(schema, '')}${declaration}`, '');
+    }
+    out.push('// -------------------------------------------------------------------------------------------------- models', '', '/** Every model this API serves: its read, create and update shapes, and its state transitions. */', 'export interface Models {');
+    for (const m of models)
+        out.push(`  ${JSON.stringify(m.name)}: {`, `    record: ${m.schema};`, `    create: ${m.schema}Create;`, `    update: ${m.schema}Update;`, `    transitions: ${m.transitions.length === 0 ? 'never' : m.transitions.map((t) => JSON.stringify(t)).join(' | ')};`, '  };');
+    out.push('}', '', '/** The model names, at runtime. */', `export const MODEL_NAMES: readonly ModelName[] = ${JSON.stringify(models.map((m) => m.name))};`, '', RUNTIME);
+    return `${out
+        .filter((line, i, all) => !(line === '' && all[i - 1] === ''))
+        .join('\n')
+        .trimEnd()}\n`;
+}
+/** The runtime part of the generated module (plain TypeScript, erasable syntax only). */
+const RUNTIME = `// ------------------------------------------------------------------------------------------------- runtime
+
+export type ModelName = keyof Models;
+export type RecordOf<M extends ModelName> = Models[M]['record'];
+export type CreateOf<M extends ModelName> = Models[M]['create'];
+export type UpdateOf<M extends ModelName> = Models[M]['update'];
+export type TransitionOf<M extends ModelName> = Models[M]['transitions'];
+
+/** The fields a list returns: all default fields, or \`id\` plus the requested ones. */
+export type Selected<R, K extends keyof R> = [K] extends [never] ? R : Pick<R, K | ('id' & keyof R)>;
+
+/** Search parameters. \`filter\` is a Shutro domain, e.g. \`{ name: { ilike: 'acme%' } }\`. */
+export interface ListQuery<R, K extends keyof R> {
+  readonly filter?: Readonly<Record<string, unknown>>;
+  readonly order?: string | readonly string[];
+  readonly fields?: readonly K[];
+  readonly limit?: number;
+  readonly offset?: number;
+  readonly count?: boolean;
+}
+
+export interface ListResult<T> {
+  readonly items: T[];
+  /** With \`count: true\`. */
+  readonly count?: number;
+}
+
+/** A record with its ETag, to send back as \`ifMatch\` (412 when it changed since). */
+export interface Versioned<T> {
+  readonly record: T;
+  readonly etag: string | null;
+}
+
+export interface WriteOptions {
+  /** A retried request with the same key returns the first response. */
+  readonly idempotencyKey?: string;
+  /** The ETag read with the record. */
+  readonly ifMatch?: string;
+}
+
+/** The caller's view of a model (\`GET /api/v1/meta/{model}\`). */
+export interface ModelMeta {
+  readonly name: string;
+  readonly label: string;
+  readonly operations: Readonly<Record<'read' | 'write' | 'create' | 'unlink' | 'export' | 'import', boolean>>;
+  readonly transitions: readonly string[];
+  readonly onchange: readonly string[];
+  readonly fields: readonly {
+    readonly key: string;
+    readonly kind: string;
+    readonly label: string;
+    readonly required: boolean;
+    readonly readonly: boolean;
+    readonly target?: string;
+    readonly options?: readonly { readonly value: string; readonly label: string }[];
+  }[];
+}
+
+/** Typed calls on one model. */
+export interface ModelClient<M extends ModelName> {
+  list<K extends keyof RecordOf<M> & string = never>(
+    query?: ListQuery<RecordOf<M>, K>,
+  ): Promise<ListResult<Selected<RecordOf<M>, K>>>;
+  get(id: number): Promise<Versioned<RecordOf<M>>>;
+  create(values: CreateOf<M>, options?: WriteOptions): Promise<Versioned<RecordOf<M>>>;
+  update(id: number, values: UpdateOf<M>, options?: WriteOptions): Promise<Versioned<RecordOf<M>>>;
+  delete(id: number, options?: WriteOptions): Promise<void>;
+  transition(id: number, name: TransitionOf<M>, options?: WriteOptions): Promise<Versioned<RecordOf<M>>>;
+  aggregate(query: AggregateQuery): Promise<Record<string, unknown>[]>;
+  onchange(input: OnchangeInput): Promise<OnchangeResult>;
+  meta(): Promise<ModelMeta>;
+}
+
+export interface SignIn {
+  readonly token: string;
+  readonly csrfToken: string;
+  readonly twoFactorRequired: boolean;
+}
+
+export interface CurrentUser {
+  readonly id: number;
+  readonly login: string;
+  readonly name: string;
+  readonly company: number | null;
+  readonly companies: readonly number[];
+  readonly twoFactorEnabled: boolean;
+}
+
+/** The auth routes; sign-in keeps the session (token or CSRF token) in the client. */
+export interface AuthClient {
+  login(login: string, password: string): Promise<SignIn>;
+  verifyTwoFactor(code: string): Promise<void>;
+  logout(): Promise<void>;
+  me(): Promise<CurrentUser>;
+  setupTwoFactor(): Promise<{ readonly secret: string; readonly otpauthUri: string }>;
+  enableTwoFactor(code: string): Promise<{ readonly recoveryCodes: readonly string[] }>;
+  disableTwoFactor(password: string, code: string): Promise<void>;
+  changePassword(current: string, next: string): Promise<void>;
+}
+
+export interface KoshClient {
+  model<M extends ModelName>(name: M): ModelClient<M>;
+  readonly auth: AuthClient;
+  /** The company of later requests (\`X-Company\`); \`undefined\`: the user's default. */
+  setCompany(company: number | undefined): void;
+}
+
+export interface ClientOptions {
+  /** Default: same origin. */
+  readonly baseUrl?: string;
+  /** \`cookie\` (browsers: the session cookie plus the CSRF header) or \`bearer\` (scripts, servers). Default: cookie. */
+  readonly session?: 'cookie' | 'bearer';
+  /** An existing session token (bearer) or CSRF token (cookie). */
+  readonly token?: string;
+  readonly csrfToken?: string;
+  readonly company?: number;
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly fetch?: typeof fetch;
+}
+
+/** A refused request: the RFC 9457 problem the server returned. */
+export class KoshApiError extends Error {
+  readonly status: number;
+  readonly problem: Problem;
+  constructor(problem: Problem) {
+    super(problem.hint === undefined ? problem.detail : \`\${problem.detail} \${problem.hint}\`);
+    this.name = 'KoshApiError';
+    this.status = problem.status;
+    this.problem = problem;
+  }
+}
+
+interface Call {
+  readonly query?: Readonly<Record<string, string | undefined>>;
+  readonly body?: unknown;
+  readonly headers?: Readonly<Record<string, string | undefined>>;
+}
+
+/** Creates a client. */
+export function createClient(options: ClientOptions = {}): KoshClient {
+  const base = (options.baseUrl ?? '').replace(/\\/$/, '');
+  const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+  const mode = options.session ?? 'cookie';
+  let token = options.token;
+  let csrf = options.csrfToken;
+  let company = options.company;
+
+  async function call<T>(method: string, path: string, c: Call = {}): Promise<{ body: T; headers: Headers }> {
+    const params = new URLSearchParams();
+    for (const [k, v] of Object.entries(c.query ?? {})) if (v !== undefined) params.set(k, v);
+    const headers: Record<string, string> = { accept: 'application/json', ...options.headers };
+    for (const [k, v] of Object.entries(c.headers ?? {})) if (v !== undefined) headers[k] = v;
+    if (c.body !== undefined) headers['content-type'] = 'application/json';
+    if (company !== undefined) headers['x-company'] = String(company);
+    if (mode === 'bearer' && token !== undefined) headers['authorization'] = \`Bearer \${token}\`;
+    if (mode === 'cookie' && csrf !== undefined && method !== 'GET') headers['x-csrf-token'] = csrf;
+    const search = params.size === 0 ? '' : \`?\${params.toString()}\`;
+    const response = await doFetch(\`\${base}\${path}\${search}\`, {
+      method,
+      headers,
+      ...(c.body === undefined ? {} : { body: JSON.stringify(c.body) }),
+      ...(mode === 'cookie' ? { credentials: 'include' as const } : {}),
+    });
+    const text = await response.text();
+    let body: unknown = null;
+    try {
+      body = text === '' ? null : JSON.parse(text);
+    } catch {
+      body = null;
+    }
+    if (!response.ok) {
+      const p = typeof body === 'object' && body !== null && 'type' in body ? (body as Problem) : undefined;
+      throw new KoshApiError(
+        p ?? { type: 'about:blank', title: response.statusText, status: response.status, detail: text.slice(0, 500) },
+      );
+    }
+    return { body: body as T, headers: response.headers };
+  }
+
+  const versioned = async <T>(pending: Promise<{ body: T; headers: Headers }>): Promise<Versioned<T>> => {
+    const { body, headers } = await pending;
+    return { record: body, etag: headers.get('etag') };
+  };
+  const writeHeaders = (o: WriteOptions = {}): Record<string, string | undefined> => ({
+    'idempotency-key': o.idempotencyKey,
+    'if-match': o.ifMatch,
+  });
+
+  function model<M extends ModelName>(name: M): ModelClient<M> {
+    const root = \`/api/v1/models/\${encodeURIComponent(name)}\`;
+    return {
+      async list(query = {}) {
+        const order = typeof query.order === 'string' ? query.order : query.order?.join(',');
+        const { body } = await call<ListResult<never>>('GET', root, {
+          query: {
+            filter: query.filter === undefined ? undefined : JSON.stringify(query.filter),
+            order,
+            fields: query.fields?.join(','),
+            limit: query.limit === undefined ? undefined : String(query.limit),
+            offset: query.offset === undefined ? undefined : String(query.offset),
+            count: query.count === true ? 'true' : undefined,
+          },
+        });
+        return body;
+      },
+      get: (id) => versioned(call('GET', \`\${root}/\${id}\`)),
+      create: (values, o) => versioned(call('POST', root, { body: values, headers: writeHeaders(o) })),
+      update: (id, values, o) => versioned(call('PATCH', \`\${root}/\${id}\`, { body: values, headers: writeHeaders(o) })),
+      async delete(id, o) {
+        await call('DELETE', \`\${root}/\${id}\`, { headers: writeHeaders(o) });
+      },
+      transition: (id, t, o) =>
+        versioned(call('POST', \`\${root}/\${id}/transitions/\${encodeURIComponent(t)}\`, { headers: writeHeaders(o) })),
+      async aggregate(query) {
+        return (await call<{ rows: Record<string, unknown>[] }>('POST', \`\${root}/aggregate\`, { body: query })).body.rows;
+      },
+      async onchange(input) {
+        return (await call<OnchangeResult>('POST', \`\${root}/onchange\`, { body: input })).body;
+      },
+      async meta() {
+        return (await call<ModelMeta>('GET', \`/api/v1/meta/\${encodeURIComponent(name)}\`)).body;
+      },
+    };
+  }
+
+  const auth: AuthClient = {
+    async login(login, password) {
+      const { body } = await call<SignIn>('POST', '/api/v1/auth/login', { body: { login, password } });
+      if (mode === 'bearer') token = body.token;
+      else csrf = body.csrfToken;
+      return body;
+    },
+    async verifyTwoFactor(code) {
+      await call('POST', '/api/v1/auth/2fa/verify', { body: { code } });
+    },
+    async logout() {
+      await call('POST', '/api/v1/auth/logout');
+      token = undefined;
+      csrf = undefined;
+    },
+    async me() {
+      return (await call<CurrentUser>('GET', '/api/v1/auth/me')).body;
+    },
+    async setupTwoFactor() {
+      return (await call<{ secret: string; otpauthUri: string }>('POST', '/api/v1/auth/2fa/setup')).body;
+    },
+    async enableTwoFactor(code) {
+      return (await call<{ recoveryCodes: string[] }>('POST', '/api/v1/auth/2fa/enable', { body: { code } })).body;
+    },
+    async disableTwoFactor(password, code) {
+      await call('POST', '/api/v1/auth/2fa/disable', { body: { password, code } });
+    },
+    async changePassword(current, next) {
+      await call('POST', '/api/v1/auth/password', { body: { current, next } });
+    },
+  };
+
+  return {
+    model,
+    auth,
+    setCompany(next) {
+      company = next;
+    },
+  };
+}`;
+//# sourceMappingURL=client.js.map

package/dist/api/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"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"}

package/dist/api/idempotency.d.ts

@@ -0,0 +1,23 @@
+import type { FastifyRequest } from 'fastify';
+import type { Driver, Env } from '../orm.js';
+export declare const IDEMPOTENCY_TABLE = "kosh_idempotency";
+/** Statements creating the idempotency table (run at server start). */
+export declare function idempotencyTableStatements(): readonly {
+    readonly text: string;
+    readonly params: readonly [];
+}[];
+/** A handler's result: status and JSON body. */
+export interface Outcome {
+    readonly status: number;
+    readonly body: unknown;
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Set when the stored response of an earlier request is replayed. */
+    readonly replayed?: boolean;
+}
+/**
+ * Runs `compute` at most once per idempotency key (in the request's transaction `env`). Without a key it just runs.
+ * @throws {HttpProblem} 400 for a malformed key, 409 while the first request with the key is still running,
+ * 422 when the key was used for a different request.
+ */
+export declare function idempotent(request: FastifyRequest, env: Env, driver: Driver, compute: () => Promise<Outcome>): Promise<Outcome>;
+//# sourceMappingURL=idempotency.d.ts.map

package/dist/api/idempotency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../../src/api/idempotency.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,OAAO,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAE7C,eAAO,MAAM,iBAAiB,qBAAqB,CAAC;AAEpD,uEAAuE;AACvE,wBAAgB,0BAA0B,IAAI,SAAS;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC;CAC9B,EAAE,CAOF;AAED,gDAAgD;AAChD,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAID;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,cAAc,EACvB,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAC9B,OAAO,CAAC,OAAO,CAAC,CAkDlB"}

package/dist/api/idempotency.js

@@ -0,0 +1,52 @@
+/**
+ * Idempotency keys (RFC 0002 §6.4, CLAUDE.md robustness): an `Idempotency-Key` header on an unsafe request stores the
+ * key and, in the same transaction, the response. A retry with the same key replays the stored response instead of
+ * acting twice; the same key with a different request is refused; a failed request stores nothing (the transaction
+ * rolls back), so its retry runs again. Keys are per user.
+ */
+import { createHash } from 'node:crypto';
+import { HttpProblem } from '../errors.js';
+export const IDEMPOTENCY_TABLE = 'kosh_idempotency';
+/** Statements creating the idempotency table (run at server start). */
+export function idempotencyTableStatements() {
+    return [
+        {
+            text: `CREATE TABLE IF NOT EXISTS ${IDEMPOTENCY_TABLE} ("user_id" bigint NOT NULL, "key" text NOT NULL, "fingerprint" text NOT NULL, "status" integer, "response" jsonb, "created_at" timestamp with time zone NOT NULL DEFAULT now(), PRIMARY KEY ("user_id", "key"))`,
+            params: [],
+        },
+    ];
+}
+const KEY = /^[\w.:-]{1,128}$/;
+/**
+ * Runs `compute` at most once per idempotency key (in the request's transaction `env`). Without a key it just runs.
+ * @throws {HttpProblem} 400 for a malformed key, 409 while the first request with the key is still running,
+ * 422 when the key was used for a different request.
+ */
+export async function idempotent(request, env, driver, compute) {
+    const header = request.headers['idempotency-key'];
+    if (header === undefined)
+        return compute();
+    const key = Array.isArray(header) ? header[0] : header;
+    if (key === undefined || !KEY.test(key))
+        throw new HttpProblem(400, 'invalid-idempotency-key', 'Invalid idempotency key', 'Idempotency-Key must be 1–128 characters of letters, digits, _ . : -.');
+    const fingerprint = createHash('sha256')
+        .update(`${request.method} ${request.url.split('?')[0] ?? ''} ${JSON.stringify(request.body ?? null)}`)
+        .digest('hex');
+    const claimed = await env.sql `INSERT INTO kosh_idempotency (user_id, key, fingerprint) VALUES (${env.uid}, ${key}, ${fingerprint}) ON CONFLICT DO NOTHING RETURNING key`;
+    if (claimed.length === 0) {
+        // Another request with this key committed (this one waited on it): read it with a fresh snapshot.
+        const [row] = await driver.query({
+            text: 'SELECT fingerprint, status, response FROM kosh_idempotency WHERE user_id = $1 AND key = $2',
+            params: [env.uid, key],
+        });
+        if (row === undefined || row.status === null)
+            throw new HttpProblem(409, 'idempotency-in-progress', 'Request in progress', `A request with Idempotency-Key ${key} is still running.`, 'Retry shortly.');
+        if (row.fingerprint !== fingerprint)
+            throw new HttpProblem(422, 'idempotency-key-reused', 'Idempotency key reused', `Idempotency-Key ${key} was used for a different request.`, 'Use a new key for each distinct request.');
+        return { status: row.status, body: row.response, replayed: true };
+    }
+    const outcome = await compute();
+    await env.sql `UPDATE kosh_idempotency SET status = ${outcome.status}, response = (${JSON.stringify(outcome.body ?? null)})::jsonb WHERE user_id = ${env.uid} AND key = ${key}`;
+    return outcome;
+}
+//# sourceMappingURL=idempotency.js.map

package/dist/api/idempotency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.js","sourceRoot":"","sources":["../../src/api/idempotency.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAG3C,MAAM,CAAC,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAEpD,uEAAuE;AACvE,MAAM,UAAU,0BAA0B;IAIxC,OAAO;QACL;YACE,IAAI,EAAE,8BAA8B,iBAAiB,kNAAkN;YACvQ,MAAM,EAAE,EAAE;SACX;KACF,CAAC;AACJ,CAAC;AAWD,MAAM,GAAG,GAAG,kBAAkB,CAAC;AAE/B;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,OAAuB,EACvB,GAAQ,EACR,MAAc,EACd,OAA+B;IAE/B,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAClD,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,OAAO,EAAE,CAAC;IAC3C,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACvD,IAAI,GAAG,KAAK,SAAS,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC;QACrC,MAAM,IAAI,WAAW,CACnB,GAAG,EACH,yBAAyB,EACzB,yBAAyB,EACzB,uEAAuE,CACxE,CAAC;IACJ,MAAM,WAAW,GAAG,UAAU,CAAC,QAAQ,CAAC;SACrC,MAAM,CACL,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,EAAE,CAC/F;SACA,MAAM,CAAC,KAAK,CAAC,CAAC;IACjB,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,GAAG,CAE3B,oEAAoE,GAAG,CAAC,GAAG,KAAK,GAAG,KAAK,WAAW,wCAAwC,CAAC;IAC9I,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,kGAAkG;QAClG,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,MAAM,CAAC,KAAK,CAI7B;YACD,IAAI,EAAE,4FAA4F;YAClG,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC;SACvB,CAAC,CAAC;QACH,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,MAAM,KAAK,IAAI;YAC1C,MAAM,IAAI,WAAW,CACnB,GAAG,EACH,yBAAyB,EACzB,qBAAqB,EACrB,kCAAkC,GAAG,oBAAoB,EACzD,gBAAgB,CACjB,CAAC;QACJ,IAAI,GAAG,CAAC,WAAW,KAAK,WAAW;YACjC,MAAM,IAAI,WAAW,CACnB,GAAG,EACH,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,GAAG,oCAAoC,EAC1D,0CAA0C,CAC3C,CAAC;QACJ,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACpE,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,OAAO,EAAE,CAAC;IAChC,MAAM,GAAG,CAAC,GAAG,CAAA,wCAAwC,OAAO,CAAC,MAAM,iBAAiB,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,4BAA4B,GAAG,CAAC,GAAG,cAAc,GAAG,EAAE,CAAC;IAC/K,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/api/metadata.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Model metadata for the generated API (RFC 0002 §6.3–6.4), read from Shutro's registry: `registry.describe()` plus
+ * the field descriptors for what `describe()` does not normalize yet (selection values, state transitions;
+ * docs/shutro-requests.md #1). Computed once per registry; per-user views are filtered at request time.
+ */
+import type { Registry } from '../orm.js';
+/** One field as the API exposes it. */
+export interface ApiField {
+    readonly key: string;
+    readonly kind: string;
+    readonly label: string;
+    readonly required: boolean;
+    /** Not writable through the API (readonly, computed without inverse, implicit). */
+    readonly readonly: boolean;
+    /** Has a column: listable, filterable, sortable. */
+    readonly stored: boolean;
+    /** Required when creating (required, no default, not computed). */
+    readonly requiredOnCreate: boolean;
+    readonly target: string | null;
+    /** `[value, label]` for selection and state fields with a static list. */
+    readonly options: readonly (readonly [string, string])[] | null;
+    readonly translate: boolean;
+}
+/** A state transition. */
+export interface TransitionSpec {
+    readonly name: string;
+    readonly field: string;
+    readonly from: readonly string[];
+    readonly to: string;
+    /** A feature permission the user needs (`definePermission`), or `null`. */
+    readonly requires: string | null;
+}
+/** One model as the API exposes it. */
+export interface ApiModel {
+    readonly name: string;
+    readonly label: string;
+    /** `res.partner` → `ResPartner` (OpenAPI component names). */
+    readonly schemaName: string;
+    readonly fields: readonly ApiField[];
+    readonly byKey: ReadonlyMap<string, ApiField>;
+    /** Transition names (state fields). */
+    readonly transitions: readonly string[];
+    /** The transitions in detail: their state field, source and target states, and required permission. */
+    readonly transitionSpecs: readonly TransitionSpec[];
+    /** Fields with onchange handlers. */
+    readonly onchange: readonly string[];
+    /** The stored field names are searched by (`name` by default), or `null`. */
+    readonly recName: string | null;
+}
+/** `res.partner` → `ResPartner`. */
+export declare function schemaName(model: string): string;
+/** The API metadata of every model of the registry. */
+export declare function apiModels(registry: Registry): ReadonlyMap<string, ApiModel>;
+/** Fields listed by default: stored, not binary, not x2many. */
+export declare function defaultFields(model: ApiModel): readonly ApiField[];
+/** The models the generated API serves: every installed model except the modules' `privateModels`. */
+export declare function publicApiModels(registry: {
+    readonly loaded: {
+        readonly modules: readonly {
+            readonly privateModels?: readonly string[];
+        }[];
+    };
+    readonly registry: Registry;
+}): ReadonlyMap<string, ApiModel>;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/api/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/api/metadata.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1C,uCAAuC;AACvC,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,mEAAmE;IACnE,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC;IAChE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,0BAA0B;AAC1B,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,uCAAuC;AACvC,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,QAAQ,EAAE,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC9C,uCAAuC;IACvC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,uGAAuG;IACvG,QAAQ,CAAC,eAAe,EAAE,SAAS,cAAc,EAAE,CAAC;IACpD,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAWD,oCAAoC;AACpC,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKhD;AAED,uDAAuD;AACvD,wBAAgB,SAAS,CAAC,QAAQ,EAAE,QAAQ,GAAG,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CA6D3E;AASD,gEAAgE;AAChE,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,QAAQ,EAAE,CAIlE;AAED,sGAAsG;AACtG,wBAAgB,eAAe,CAAC,QAAQ,EAAE;IACxC,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,SAAS;YAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;SAAE,EAAE,CAAA;KAAE,CAAC;IACjG,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;CAC7B,GAAG,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAGhC"}