shutro-erp 0.3.6 → 0.3.7

package/dist/sales/module.js

@@ -5,12 +5,15 @@
  */
 import { contactsShutro } from '../contacts/index.js';
 import { messagingShutro } from '../messaging/index.js';
-import { computeTaxes, productShutro, taxRule } from '../product/index.js';
+import { computeTaxes, priceFor, productShutro, taxRule } from '../product/index.js';
 import { orm } from '../server/orm.js';
-import { check, compute, defineModel, defineModule, extendModel, f, onchange, records, } from './.kosh/bindings.js';
+import { check, compute, defineModel, defineModule, extendModel, f, method, onchange, records, } from './.kosh/bindings.js';
 /** A line's taxes through the engine (RFC 0016): its amount after discount, its taxes in order. */
 function taxesOf(l) {
-    const amount = l.quantity.times(l.priceUnit).times(orm.toDecimal(100).minus(l.discount)).div(100);
+    const amount = l.quantity
+        .times(l.priceUnit ?? orm.toDecimal('0'))
+        .times(orm.toDecimal(100).minus(l.discount))
+        .div(100);
     return computeTaxes(amount, l.quantity, [...l.taxes].map(taxRule));
 }
 /** A monetary value's amount (a Money object or a plain Decimal), or null. */
@@ -63,20 +66,64 @@ export const SaleOrder = defineModel('sale.order', {
             label: 'Salesperson',
         }),
         partner: f.many2one('res.partner', { required: true, checkCompany: true, label: 'Customer' }),
+        /** Where the invoice goes and where the goods go (RFC 0028 §3.2); empty: the customer's own address. */
+        partnerInvoice: f.many2one('res.partner', {
+            checkCompany: true,
+            label: 'Invoice to',
+            help: 'The contact the invoice is addressed to; empty: the customer.',
+        }),
+        partnerShipping: f.many2one('res.partner', {
+            checkCompany: true,
+            label: 'Deliver to',
+            help: 'Where the goods go; empty: the customer’s address.',
+        }),
+        /** The price list its lines are priced by (RFC 0028 §3.1); from the customer, else none (list prices). */
+        pricelist: f.many2one('product.pricelist', {
+            ondelete: 'restrict',
+            label: 'Price list',
+            help: 'Lines without a price typed in are priced by this list; each line says why.',
+        }),
         currency: f.many2one('res.currency', { required: true }),
         dateOrder: f.date({ required: true, default: (env) => env.today(), label: 'Order date' }),
         validityDate: f.date({ label: 'Valid until' }),
         clientReference: f.char({ label: 'Customer reference' }),
         note: f.text({ label: 'Terms and conditions' }),
         lines: f.one2many('sale.order.line', 'order'),
-        amountUntaxed: f.monetary({ currency: 'currency', store: true, label: 'Untaxed', ...amounts }),
-        amountTax: f.monetary({ currency: 'currency', store: true, label: 'Taxes', ...amounts }),
-        amountTotal: f.monetary({ currency: 'currency', store: true, label: 'Total', ...amounts }),
+        /** The quotation template it started from (RFC 0028 §3.5). */
+        template: f.many2one('sale.order.template', {
+            ondelete: 'set null',
+            label: 'Quotation template',
+            help: '“Fill from template” fills the quotation’s lines, options, validity and terms from it.',
+        }),
+        /** Optional products offered with the quotation; added as lines when the customer wants them. */
+        options: f.one2many('sale.order.option', 'order', { label: 'Optional products' }),
+        amountUntaxed: f.monetary({
+            currency: 'currency',
+            store: true,
+            label: 'Untaxed',
+            help: 'The sum of the lines’ amounts before taxes.',
+            ...amounts,
+        }),
+        amountTax: f.monetary({
+            currency: 'currency',
+            store: true,
+            label: 'Taxes',
+            help: 'The sum of the taxes on the lines.',
+            ...amounts,
+        }),
+        amountTotal: f.monetary({
+            currency: 'currency',
+            store: true,
+            label: 'Total',
+            help: 'What the customer pays: the untaxed amount plus the taxes.',
+            ...amounts,
+        }),
         /** RFC 0022 step 2: what the order earns — the lines' untaxed amounts less their products' cost. */
         margin: f.monetary({
             currency: 'currency',
             store: true,
             label: 'Margin',
+            help: 'What the order earns: its lines’ untaxed amounts less their products’ cost.',
             ...compute('sale.order', 'margin', ['lines.margin', 'currency'], (orders) => {
                 for (const o of orders)
                     o.margin = o.currency === null ? null : o.lines.sum('margin', o.currency);
@@ -86,6 +133,7 @@ export const SaleOrder = defineModel('sale.order', {
             scale: 1,
             store: true,
             label: 'Margin (%)',
+            help: 'The margin as a percentage of the untaxed amount.',
             ...compute('sale.order', 'marginPercent', ['margin', 'amountUntaxed'], (orders) => {
                 for (const o of orders) {
                     const untaxed = amountOf(o.amountUntaxed);
@@ -98,6 +146,7 @@ export const SaleOrder = defineModel('sale.order', {
             }),
         }),
         state: f.state({
+            help: 'A quotation until it is confirmed as a sales order, which can then be locked or cancelled.',
             states: {
                 draft: 'Quotation',
                 sent: 'Quotation sent',
@@ -108,6 +157,54 @@ export const SaleOrder = defineModel('sale.order', {
             initial: 'draft',
             transitions: {
                 send: { from: ['draft'], to: 'sent' },
+                // A quotation filled from its template (RFC 0028 §3.5): lines, options, validity, terms.
+                fill: {
+                    from: ['draft'],
+                    to: 'draft',
+                    guard: records('sale.order', async (orders) => (await orders.load({ template: true })).filter((o) => o.template === null)),
+                    message: 'Choose a quotation template first.',
+                    after: records('sale.order', async (orders) => {
+                        const env = orders.env;
+                        for (const o of await orders.load({ template: { lines: { product: true } } })) {
+                            const t = o.template;
+                            if (t === null)
+                                continue;
+                            const rows = [...t.lines].sort((a, b) => (a.sequence ?? 10) - (b.sequence ?? 10));
+                            const lines = rows.filter((r) => r.optional !== true);
+                            const options = rows.filter((r) => r.optional === true);
+                            if (lines.length > 0)
+                                await env.model('sale.order.line').create(lines.map((r) => ({
+                                    order: o.id,
+                                    product: r.product.id,
+                                    name: r.name,
+                                    quantity: r.quantity,
+                                })));
+                            if (options.length > 0)
+                                await env.model('sale.order.option').create(options.map((r) => ({
+                                    order: o.id,
+                                    product: r.product.id,
+                                    name: r.name,
+                                    quantity: r.quantity,
+                                })));
+                            const days = t.validityDays ?? 0;
+                            const date = String(o.dateOrder).slice(0, 10);
+                            const [y, m, day] = date.split('-').map(Number);
+                            await env
+                                .model('sale.order')
+                                .browse([o.id])
+                                .write({
+                                ...(days > 0
+                                    ? {
+                                        validityDate: new Date(Date.UTC(y, m - 1, day + days))
+                                            .toISOString()
+                                            .slice(0, 10),
+                                    }
+                                    : {}),
+                                ...(t.note !== null && t.note !== '' ? { note: t.note } : {}),
+                            });
+                        }
+                    }),
+                },
                 confirm: {
                     from: ['draft', 'sent'],
                     to: 'sale',
@@ -116,6 +213,11 @@ export const SaleOrder = defineModel('sale.order', {
                         return loaded.filter((o) => o.lines.length === 0);
                     }),
                     message: 'Add at least one line before confirming the order.',
+                    // Other apps check the order first (sale_account: the customer's credit).
+                    before: records('sale.order', async (orders) => {
+                        const env = orders.env;
+                        await env.model('sale.order').browse(orders.ids).confirming();
+                    }),
                     // Other apps act on a confirmation through the outbox (sale_project creates the tasks).
                     after: records('sale.order', async (orders) => {
                         for (const o of await orders.load({}))
@@ -124,17 +226,40 @@ export const SaleOrder = defineModel('sale.order', {
                 },
                 lock: { from: ['sale'], to: 'done' },
                 unlock: { from: ['done'], to: 'sale' },
-                cancel: { from: ['draft', 'sent', 'sale'], to: 'cancel' },
+                cancel: {
+                    from: ['draft', 'sent', 'sale'],
+                    to: 'cancel',
+                    // Other apps follow a cancellation through the outbox (sale_crm: a deal with every quotation cancelled).
+                    after: records('sale.order', async (orders) => {
+                        for (const o of await orders.load({}))
+                            await orders.env.emit('sale.order.cancelled', { id: o.id });
+                    }),
+                },
                 redraft: { from: ['cancel'], to: 'draft' },
             },
             extensible: true, // Accounting adds invoicing states through its bridge
         }),
     },
+    methods: {
+        /** Before a confirmation: nothing here; sale_account checks the customer's credit (RFC 0028 §3.2). */
+        confirming: method('sale.order', async () => undefined),
+    },
     onchange: {
         // The customer's currency, else the company's; an empty validity and terms from the company's settings.
         partner: onchange('sale.order', async (d, env) => {
             await quotationDefaults(d, env);
             const p = await d.record('partner');
+            const [priced] = p === null
+                ? []
+                : await env
+                    .model('res.partner')
+                    .browse([p.id])
+                    .load({ pricelist: { currency: true } });
+            d.set('pricelist', priced?.pricelist?.id ?? null);
+            if (priced?.pricelist?.currency) {
+                d.set('currency', priced.pricelist.currency.id);
+                return;
+            }
             if (p?.currency) {
                 d.set('currency', p.currency.id);
                 return;
@@ -146,6 +271,12 @@ export const SaleOrder = defineModel('sale.order', {
             if (company !== undefined)
                 d.set('currency', company.currency.id);
         }),
+        // A price list in another currency puts the order in it.
+        pricelist: onchange('sale.order', async (d) => {
+            const list = await d.record('pricelist');
+            if (list?.currency)
+                d.set('currency', list.currency.id);
+        }),
         // A new order date moves the validity with it.
         dateOrder: onchange('sale.order', async (d, env) => {
             d.set('validityDate', null);
@@ -173,6 +304,16 @@ async function quotationDefaults(d, env) {
     if ((d.get('note') ?? '') === '' && typeof terms === 'string' && terms !== '')
         d.set('note', terms);
 }
+/** A line's price and why (RFC 0028 §3.1): typed in, else its order's price list, else the list price. */
+async function linePrice(l) {
+    if (l.manualPrice !== null)
+        return { price: l.manualPrice, reason: 'Typed in.' };
+    if (l.product === null)
+        return { price: orm.toDecimal('0'), reason: null };
+    const env = l.env;
+    const found = await priceFor(l.env, l.order?.pricelist?.id ?? null, l.product.id, l.quantity, String(l.order?.dateOrder ?? env.today()).slice(0, 10));
+    return { price: found.price, reason: found.explanation };
+}
 export const SaleOrderLine = defineModel('sale.order.line', {
     label: 'Order line',
     access: {
@@ -185,7 +326,43 @@ export const SaleOrderLine = defineModel('sale.order.line', {
         name: f.char({ required: true, label: 'Description' }),
         quantity: f.decimal({ scale: 3, required: true, default: '1' }),
         uom: f.many2one('uom.uom', { label: 'Unit' }),
-        priceUnit: f.decimal({ scale: 2, required: true, default: '0', label: 'Unit price' }),
+        /**
+         * The unit price: the one typed in, else the order's price list's (RFC 0028 §3.1). Typing a price keeps it
+         * (`manualPrice`); changing the product, the quantity or the list reprices the lines without one.
+         */
+        priceUnit: f.decimal({
+            scale: 2,
+            store: true,
+            label: 'Unit price',
+            help: 'The price typed in, else the order’s price list’s (see why on the line), else the product’s list price.',
+            ...compute('sale.order.line', 'priceUnit', ['product', 'quantity', 'manualPrice', 'order.pricelist', 'order.dateOrder'], async (lines) => {
+                for (const l of lines)
+                    l.priceUnit = (await linePrice(l)).price;
+            }),
+            inverse: async (records) => {
+                const lines = records;
+                const env = records.env;
+                // Who may set prices by hand (RFC 0028 §3.1): the server decides.
+                if (!env.su && !env.access.has('sales.price_override'))
+                    throw new orm.ValidationError('sale.order.line', ['priceUnit'], 'You may not change prices.', 'Prices come from the price list; ask a Sales manager.');
+                for (const l of lines)
+                    await env
+                        .model('sale.order.line')
+                        .browse([l.id])
+                        .write({ manualPrice: l.priceUnit });
+            },
+        }),
+        /** The price typed in, kept when the product, the quantity or the list changes (empty: the list's price). */
+        manualPrice: f.decimal({ scale: 2, label: 'Price typed in' }),
+        /** Why the line has its price: the list and rule, or "typed in". */
+        priceReason: f.char({
+            store: true,
+            label: 'Why this price',
+            ...compute('sale.order.line', 'priceReason', ['product', 'quantity', 'manualPrice', 'order.pricelist', 'order.dateOrder'], async (lines) => {
+                for (const l of lines)
+                    l.priceReason = (await linePrice(l)).reason;
+            }),
+        }),
         /** Percent off the unit price (0–100). */
         discount: f.decimal({ scale: 2, required: true, default: '0', label: 'Discount %' }),
         /** The line's taxes, applied in order (RFC 0016). */
@@ -203,6 +380,7 @@ export const SaleOrderLine = defineModel('sale.order.line', {
         subtotal: f.monetary({
             currency: 'currency',
             store: true,
+            help: 'The line’s amount before taxes: the quantity times the unit price, less the discount and any tax included in the price.',
             ...compute('sale.order.line', 'subtotal', [
                 'quantity',
                 'priceUnit',
@@ -224,6 +402,7 @@ export const SaleOrderLine = defineModel('sale.order.line', {
             currency: 'currency',
             store: true,
             label: 'Margin',
+            help: 'What the line earns: its untaxed amount less its product’s cost for the quantity.',
             ...compute('sale.order.line', 'margin', ['subtotal', 'quantity', 'product.standardPrice'], (lines) => {
                 for (const l of lines) {
                     const untaxed = amountOf(l.subtotal);
@@ -238,6 +417,7 @@ export const SaleOrderLine = defineModel('sale.order.line', {
             currency: 'currency',
             store: true,
             label: 'Tax',
+            help: 'The taxes on this line, computed from its amount and its taxes.',
             ...compute('sale.order.line', 'taxAmount', [
                 'quantity',
                 'priceUnit',
@@ -279,10 +459,118 @@ export const SaleOrderLine = defineModel('sale.order.line', {
         },
     },
 });
+/** A quotation template (RFC 0028 §3.5): lines and optional products, validity and terms. */
+export const SaleOrderTemplate = defineModel('sale.order.template', {
+    label: 'Quotation template',
+    archivable: true,
+    order: ['name asc'],
+    access: {
+        'sales.user': ['read'],
+        'sales.manager': ['read', 'write', 'create', 'unlink', 'export', 'import'],
+    },
+    fields: {
+        name: f.char({ required: true, translate: true }),
+        validityDays: f.integer({
+            default: 0,
+            label: 'Valid for (days)',
+            help: 'The quotation is valid until its date plus these days; 0 keeps the quotation’s own.',
+        }),
+        note: f.text({ label: 'Terms and conditions' }),
+        lines: f.one2many('sale.order.template.line', 'template', { label: 'Lines' }),
+    },
+});
+export const SaleOrderTemplateLine = defineModel('sale.order.template.line', {
+    label: 'Template line',
+    order: ['template asc', 'sequence asc', 'id asc'],
+    access: {
+        'sales.user': ['read'],
+        'sales.manager': ['read', 'write', 'create', 'unlink'],
+    },
+    fields: {
+        template: f.many2one('sale.order.template', { required: true, ondelete: 'cascade' }),
+        sequence: f.integer({ default: 10 }),
+        product: f.many2one('product.product', { required: true }),
+        name: f.char({ required: true, label: 'Description' }),
+        quantity: f.decimal({ scale: 3, required: true, default: '1' }),
+        optional: f.boolean({
+            default: false,
+            label: 'Optional',
+            help: 'Offered with the quotation; the customer adds it, or not.',
+        }),
+    },
+});
+/** An optional product offered with a quotation (RFC 0028 §3.5); added, it becomes a line, once. */
+export const SaleOrderOption = defineModel('sale.order.option', {
+    label: 'Optional product',
+    order: ['order asc', 'id asc'],
+    access: {
+        'sales.user': ['read', 'write', 'create', 'unlink'],
+        'sales.manager': ['read', 'write', 'create', 'unlink'],
+    },
+    fields: {
+        order: f.many2one('sale.order', { required: true, ondelete: 'cascade' }),
+        product: f.many2one('product.product', { required: true }),
+        name: f.char({ required: true, label: 'Description' }),
+        quantity: f.decimal({ scale: 3, required: true, default: '1' }),
+        /** Empty: the order's price list prices the line. */
+        priceUnit: f.decimal({ scale: 2, label: 'Unit price' }),
+        line: f.many2one('sale.order.line', { ondelete: 'set null', label: 'Added as' }),
+        state: f.state({
+            help: 'Offered until it is added to the quotation as a line.',
+            states: { offered: 'Offered', added: 'Added' },
+            initial: 'offered',
+            transitions: {
+                // Added while the quotation is open: a line, priced by the list unless the option has a price.
+                add: {
+                    from: ['offered'],
+                    to: 'added',
+                    guard: records('sale.order.option', async (options) => (await options.load({ order: true })).filter((o) => o.order.state !== 'draft' && o.order.state !== 'sent')),
+                    message: 'Options are added while the quotation is open.',
+                    after: records('sale.order.option', async (options) => {
+                        const env = options.env;
+                        for (const o of await options.load({})) {
+                            const made = await env.asSuperuser({ reason: 'option added' }, (su) => su.model('sale.order.line').create([
+                                {
+                                    order: o.order.id,
+                                    product: o.product.id,
+                                    name: o.name,
+                                    quantity: o.quantity,
+                                    ...(o.priceUnit === null ? {} : { priceUnit: o.priceUnit }),
+                                },
+                            ]));
+                            await env
+                                .model('sale.order.option')
+                                .browse([o.id])
+                                .write({ line: made.ids[0] });
+                        }
+                    }),
+                },
+            },
+        }),
+    },
+});
+/** The customer's price list (RFC 0028 §3.1): their orders start on it. */
+export const PartnerPricelist = extendModel('res.partner', {
+    fields: {
+        pricelist: f.many2one('product.pricelist', {
+            ondelete: 'set null',
+            label: 'Price list',
+            help: 'Orders for this customer start on this price list.',
+        }),
+    },
+});
 export const salesShutro = defineModule({
     name: 'sales',
-    version: '0.3.0',
+    version: '0.5.0',
     migrations: [
+        {
+            version: '0.4.0',
+            description: 'Price lists: existing lines keep the price they have, as typed in (no order is repriced)',
+            up: async (ctx) => {
+                await ctx.sql `UPDATE sale_order_line SET manual_price = price_unit WHERE manual_price IS NULL`;
+                await ctx.sql `UPDATE sale_order_line SET price_reason = 'Typed in.' WHERE price_reason IS NULL`;
+            },
+        },
         {
             version: '0.2.0',
             description: 'Several taxes per line: the single tax of each line becomes its first',
@@ -301,9 +589,16 @@ export const salesShutro = defineModule({
         }),
         orm.defineGroup({ code: 'sales.manager', label: 'Sales manager', implies: ['sales.user'] }),
     ],
+    permissions: [
+        orm.definePermission({
+            code: 'sales.price_override',
+            label: 'Type in prices on order lines (instead of the price list)',
+            groups: ['sales.user'],
+        }),
+    ],
     sequences: [
         orm.defineSequence({ code: 'sale.order', prefix: 'SO/{year}/', padding: 5, reset: 'yearly' }),
     ],
-    models: [SaleOrder, SaleOrderLine],
-    extensions: [CompanySales],
+    models: [SaleOrder, SaleOrderLine, SaleOrderTemplate, SaleOrderTemplateLine, SaleOrderOption],
+    extensions: [CompanySales, PartnerPricelist],
 });

package/dist/server/api/duplicate.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Duplicate (RFC 0023 R1, §3.2): a copy of a record made **as the user** (ACL, record rules and field groups decide)
+ * from the model's metadata — Shutro has no `copy()` yet (docs/shutro-requests.md #32):
+ * - stored, writable fields are copied; many2one kept, many2many as the same set;
+ * - states, sequences and computed fields start again (they are read-only, so not copied);
+ * - a field in a unique constraint (beside the company) is left out, or for a required text gets " (copy)";
+ * - one2many lines are copied with the record, each line by the same rules, without the link back.
+ */
+import type { Env } from '../orm.js';
+import type { ApiModel } from './metadata.js';
+type Row = Record<string, unknown>;
+/** The record's copy (as the API takes values), with its lines. */
+export declare function duplicateValues(env: Env, models: ReadonlyMap<string, ApiModel>, model: ApiModel, id: number): Promise<Row>;
+export {};

package/dist/server/api/duplicate.js

@@ -0,0 +1,75 @@
+const ref = (env, name) => env.model(name);
+/** Whether a field's value is copied as such. */
+const copied = (env, model, f) => f.stored &&
+    !f.readonly &&
+    f.kind !== 'one2many' &&
+    f.kind !== 'binary' &&
+    env.access.canField(model.name, f.key, 'read') &&
+    env.access.canField(model.name, f.key, 'write');
+/** The fields of the model's unique constraints, the company aside. */
+const uniqueKeys = (model) => new Set(model.unique.flat().filter((k) => k !== 'company'));
+async function valuesOf(env, model, id, skip, rename) {
+    const fields = model.fields.filter((f) => copied(env, model, f) && f.key !== skip);
+    const scalar = fields.filter((f) => f.kind !== 'many2many').map((f) => f.key);
+    const sets = fields.filter((f) => f.kind === 'many2many').map((f) => f.key);
+    let loaded = await ref(env, model.name)
+        .browse([id])
+        .load(['id', ...scalar]);
+    if (sets.length > 0)
+        loaded = await loaded.load(Object.fromEntries(sets.map((k) => [k, true])));
+    const [row] = loaded.read(['id', ...fields.map((f) => f.key)]);
+    if (row === undefined)
+        return {};
+    const unique = uniqueKeys(model);
+    const out = {};
+    for (const f of fields) {
+        const value = row[f.key];
+        if (value === null || value === undefined)
+            continue;
+        if (unique.has(f.key)) {
+            if (rename &&
+                f.required &&
+                (f.kind === 'char' || f.kind === 'text') &&
+                typeof value === 'string')
+                out[f.key] = `${value} (copy)`;
+            continue;
+        }
+        if (f.kind === 'many2one')
+            out[f.key] = typeof value === 'object' ? value.id : value;
+        else if (f.kind === 'many2many')
+            out[f.key] = {
+                set: value.map((v) => typeof v === 'object' && v !== null ? v.id : v),
+            };
+        else
+            out[f.key] = value;
+    }
+    return out;
+}
+/** The record's copy (as the API takes values), with its lines. */
+export async function duplicateValues(env, models, model, id) {
+    const values = await valuesOf(env, model, id, null, true);
+    for (const f of model.fields) {
+        if (f.kind !== 'one2many' || f.readonly || f.target === null)
+            continue;
+        if (!env.access.canField(model.name, f.key, 'write'))
+            continue;
+        const lines = models.get(f.target);
+        if (lines === undefined || !env.access.can(f.target, 'create'))
+            continue;
+        // The lines' link back: their many2one to this model that is required.
+        const back = lines.fields.find((x) => x.kind === 'many2one' && x.target === model.name && x.required);
+        if (back === undefined)
+            continue;
+        const [parent] = (await ref(env, model.name)
+            .browse([id])
+            .load({ [f.key]: true })).read([f.key]);
+        const lineIds = (parent?.[f.key] ?? []).map((v) => typeof v === 'object' && v !== null ? Number(v.id) : Number(v));
+        if (lineIds.length === 0)
+            continue;
+        const create = [];
+        for (const lineId of lineIds)
+            create.push(await valuesOf(env, lines, lineId, back.key, false));
+        values[f.key] = { create };
+    }
+    return values;
+}

package/dist/server/api/explain.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Explain (RFC 0031 §3.1): what a model, its fields and its buttons are, for developers and administrators — the
+ * facts behind the dark popovers of Developer mode. Where each field comes from (the module that defined the model,
+ * or the one that extended it), what it points to (and, for a one-to-many, through which field), whether it is
+ * stored or computed and from what, its default, its rules; each transition's states and guard; and every relation
+ * into the model from the other served models.
+ *
+ * - `GET /api/v1/meta/explain/:model`   administrators and `base.developer` only
+ */
+import type { FastifyInstance } from 'fastify';
+import type { KoshRegistry } from '../registry.js';
+import type { ApiModel } from './metadata.js';
+/** One field, explained. */
+export interface ExplainedField {
+    readonly key: string;
+    readonly label: string;
+    readonly kind: string;
+    readonly help: string | null;
+    readonly target: string | null;
+    /** For a one-to-many: the field of the target that points back. */
+    readonly inverse: string | null;
+    readonly required: boolean;
+    readonly readonly: boolean;
+    readonly stored: boolean;
+    readonly computed: boolean;
+    /** What a computed field is computed from. */
+    readonly depends: readonly string[];
+    readonly hasDefault: boolean;
+    readonly default: string | null;
+    readonly ondelete: string | null;
+    readonly translate: boolean;
+    readonly index: boolean;
+    readonly options: readonly (readonly [string, string])[] | null;
+    /** The module whose model or extension declares it. */
+    readonly module: string | null;
+}
+/** One transition, explained. */
+export interface ExplainedTransition {
+    readonly name: string;
+    readonly field: string;
+    readonly from: readonly string[];
+    readonly to: string;
+    readonly guarded: boolean;
+    readonly message: string | null;
+    readonly requires: string | null;
+}
+/** A model, explained. */
+export interface Explained {
+    readonly model: string;
+    readonly label: string;
+    readonly module: string | null;
+    readonly extendedBy: readonly string[];
+    readonly fields: readonly ExplainedField[];
+    readonly transitions: readonly ExplainedTransition[];
+    /** The relations of other models into this one. */
+    readonly incoming: readonly {
+        readonly model: string;
+        readonly field: string;
+        readonly label: string;
+        readonly kind: string;
+    }[];
+}
+/** A model explained, from the registry and the API metadata. */
+export declare function explainModel(registry: KoshRegistry, models: ReadonlyMap<string, ApiModel>, name: string): Explained | null;
+/** The group that may read explanations besides administrators. */
+export declare const DEVELOPER_GROUP = "base.developer";
+export declare function registerExplain(app: FastifyInstance, options: {
+    readonly registry: KoshRegistry;
+    readonly models: ReadonlyMap<string, ApiModel>;
+}): void;