@tollwyn/baukasten 0.0.2 → 1.2.2

package/dist/server/log.js

@@ -0,0 +1,61 @@
+// The operations log of a product: one JSON object per line, time, level and message first. A field
+// that is an Error becomes `{ name, message, code }`, never its other properties, which may carry
+// data of a customer. What a field holds is the caller's choice; the baukasten never logs a client
+// address, an email address, a password or a key.
+const LEVELS = ['debug', 'info', 'warn', 'error', 'silent'];
+/** An error as the log shows it; an AggregateError (pg tries every address) lists its messages. */
+export function describeError(error) {
+    if (!(error instanceof Error))
+        return { name: typeof error, message: String(error) };
+    const described = { name: error.name, message: error.message };
+    const code = Reflect.get(error, 'code');
+    if (typeof code === 'string' || typeof code === 'number')
+        described.code = code;
+    if (error instanceof AggregateError) {
+        described.errors = error.errors.map((inner) => describeError(inner).message);
+    }
+    return described;
+}
+const isLevel = (name) => LEVELS.some((level) => level === name);
+export function createLog(options) {
+    const { write, now } = options;
+    const name = options.level ?? 'info';
+    const threshold = LEVELS.indexOf(isLevel(name) ? name : 'info');
+    function line(level, msg, fields) {
+        if (LEVELS.indexOf(level) < threshold)
+            return;
+        const entry = { time: now().toISOString(), level, msg };
+        for (const [key, value] of Object.entries(fields)) {
+            entry[key] = value instanceof Error ? describeError(value) : value;
+        }
+        write(serialize(entry, Object.keys(fields)) + '\n');
+    }
+    if (!isLevel(name)) {
+        line('warn', 'LOG_LEVEL is not a level, logging at info', { levels: [...LEVELS] });
+    }
+    return {
+        debug: (msg, fields = {}) => line('debug', msg, fields),
+        info: (msg, fields = {}) => line('info', msg, fields),
+        warn: (msg, fields = {}) => line('warn', msg, fields),
+        error: (msg, fields = {}) => line('error', msg, fields)
+    };
+}
+/** A field JSON cannot write (a cycle, a BigInt) is named instead of losing the whole line. */
+function serialize(entry, fields) {
+    try {
+        return JSON.stringify(entry);
+    }
+    catch {
+        const unserializable = fields.filter((key) => {
+            try {
+                JSON.stringify(entry[key]);
+                return false;
+            }
+            catch {
+                return true;
+            }
+        });
+        const kept = Object.entries(entry).filter(([key]) => !unserializable.includes(key));
+        return JSON.stringify({ ...Object.fromEntries(kept), unserializable });
+    }
+}

package/dist/server/machine.d.ts

@@ -0,0 +1,4 @@
+import type { RequestEvent } from '@sveltejs/kit';
+import type { Services } from './services.js';
+/** The answer of a machine endpoint of the baukasten, or null for any other path. */
+export declare function serveMachine(s: Services, event: RequestEvent): Promise<Response> | null;

package/dist/server/machine.js

@@ -0,0 +1,57 @@
+import { ApiError, respond } from './api.js';
+import { productNumbers, SALES_PATH, salesNumbers, bearerFits } from './sales.js';
+import { WEBHOOK_PATH } from './stripe.js';
+function only(s, event, method) {
+    if (event.request.method !== method) {
+        throw new ApiError(405, 'method_not_allowed', s.messages.api.methodNotAllowed, {
+            headers: { allow: method }
+        });
+    }
+}
+/**
+ * Applies an event of Stripe once. A wrong signature is a 400; an event that fails is a 500, so that
+ * Stripe sends it again later.
+ */
+async function webhook(s, event) {
+    only(s, event, 'POST');
+    if (s.config.stripe.kind === 'none') {
+        s.log.warn('stripe: a webhook without Stripe configured');
+        throw new ApiError(503, 'not_configured', s.messages.stripe.notConfigured);
+    }
+    const payload = await event.request.text();
+    const received = await s.billing.receive(payload, event.request.headers.get('stripe-signature'));
+    switch (received.kind) {
+        case 'invalid':
+            s.log.warn('stripe: a webhook with a wrong signature');
+            throw new ApiError(400, 'invalid_signature', s.messages.stripe.signature);
+        case 'applied':
+        case 'repeated':
+            return Response.json({ received: true });
+    }
+}
+async function sales(s, event) {
+    only(s, event, 'GET');
+    if (!bearerFits(event.request.headers.get('authorization'), s.config.salesToken)) {
+        throw new ApiError(401, 'unauthorized', s.messages.sales.unauthorized);
+    }
+    const own = productNumbers(await s.salesNumbers(s.db));
+    const numbers = await salesNumbers(s.db, {
+        currency: s.product.catalog.currency,
+        now: s.now(),
+        own,
+        count: s.config.stripe.kind === 'stripe' && s.config.stripe.mode === 'live' ? 'live' : 'all',
+        log: s.log
+    });
+    return Response.json(numbers, { headers: { 'cache-control': 'no-store' } });
+}
+/** The answer of a machine endpoint of the baukasten, or null for any other path. */
+export function serveMachine(s, event) {
+    switch (event.url.pathname) {
+        case WEBHOOK_PATH:
+            return respond(s.log, s.messages, () => webhook(s, event));
+        case SALES_PATH:
+            return respond(s.log, s.messages, () => sales(s, event));
+        default:
+            return null;
+    }
+}

package/dist/server/mail.d.ts

@@ -0,0 +1,20 @@
+import type { Log } from './log.js';
+import type { Mail, Mailer } from './ports.js';
+/**
+ * A mail the relay did not take. Only what SMTP calls the failure is kept; the reply of a server can
+ * quote the address of the recipient.
+ */
+export declare class MailFailed extends Error {
+    name: string;
+    readonly code: string;
+    constructor(details: {
+        code: string;
+        responseCode?: number;
+        command?: string;
+    });
+}
+/** Sends a mail of the accounts: true when it went out; a failure is logged with its kind. */
+export declare function deliver(mailer: Mailer, log: Log, mail: Mail, about: {
+    kind: string;
+    account: string;
+}): Promise<boolean>;

package/dist/server/mail.js

@@ -0,0 +1,29 @@
+/**
+ * A mail the relay did not take. Only what SMTP calls the failure is kept; the reply of a server can
+ * quote the address of the recipient.
+ */
+export class MailFailed extends Error {
+    name = 'MailFailed';
+    code;
+    constructor(details) {
+        const parts = [
+            details.code,
+            ...(details.responseCode === undefined ? [] : [`reply ${details.responseCode}`]),
+            ...(details.command === undefined ? [] : [`at ${details.command}`])
+        ];
+        super(`the mail was not sent: ${parts.join(', ')}`);
+        this.code = details.code;
+    }
+}
+/** Sends a mail of the accounts: true when it went out; a failure is logged with its kind. */
+export async function deliver(mailer, log, mail, about) {
+    try {
+        await mailer.send(mail);
+        log.info('mail sent', about);
+        return true;
+    }
+    catch (error) {
+        log.error('mail failed', { ...about, error });
+        return false;
+    }
+}

package/dist/server/messages.d.ts

@@ -0,0 +1,105 @@
+import type { Language } from '../product.js';
+export interface MailText {
+    subject: string;
+    text: string;
+}
+/** A link in a mail and what it is about: the product, its address and how long the link holds. */
+interface LinkMail {
+    name: string;
+    origin: string;
+    link: string;
+    hours: number;
+}
+export interface Messages {
+    tooMany: (seconds: number) => string;
+    crossSite: string;
+    email: {
+        invalid: string;
+        tooLong: string;
+    };
+    password: {
+        tooShort: string;
+        tooLong: string;
+    };
+    signup: {
+        acceptTerms: string;
+        confirmBusiness: string;
+        taken: string;
+    };
+    login: {
+        wrong: string;
+    };
+    link: {
+        invalid: string;
+    };
+    mailFailed: string;
+    account: {
+        sameEmail: string;
+        wrongPassword: string;
+        wrongCurrent: string;
+        taken: string;
+        confirmDelete: string;
+        keyName: string;
+        confirmFirst: string;
+    };
+    api: {
+        unauthorized: (example: string) => string;
+        rateLimited: (seconds: number) => string;
+        invalidJson: string;
+        notAnObject: string;
+        invalidRequest: string;
+        emailTaken: string;
+        notFound: string;
+        methodNotAllowed: string;
+        payloadTooLarge: string;
+        failed: string;
+        forbidden: string;
+        internal: string;
+        acceptTerms: (terms: string) => string;
+        actingForBusiness: string;
+        via: string;
+        firstKey: string;
+        price: string;
+        quantity: (max: number) => string;
+        subscribed: string;
+        noCustomer: string;
+    };
+    stripe: {
+        /** By the box for the terms in Checkout, in Markdown with their link. */
+        terms: (name: string, url: string) => string;
+        signature: string;
+        notConfigured: string;
+    };
+    sales: {
+        unauthorized: string;
+    };
+    mails: {
+        verify: (mail: LinkMail) => MailText;
+        reset: (mail: LinkMail) => MailText;
+        change: (mail: LinkMail) => MailText;
+        changed: (mail: {
+            name: string;
+            origin: string;
+            newEmail: string;
+        }) => MailText;
+    };
+    openApi: {
+        signup: string;
+        signupCreated: string;
+        account: string;
+        email: string;
+        acceptTerms: string;
+        actingForBusiness: string;
+        via: string;
+        apiKey: string;
+        checkout: string;
+        checkoutBody: string;
+        portal: string;
+        url: string;
+        price: string;
+        quantity: string;
+        errors: Record<'invalidJson' | 'invalidRequest' | 'emailTaken' | 'unauthorized' | 'rateLimited' | 'forbidden' | 'subscribed' | 'noCustomer' | 'notConfigured', string>;
+    };
+}
+export declare const MESSAGES: Record<Language, Messages>;
+export {};

package/dist/server/messages.js

@@ -0,0 +1,232 @@
+const signature = (name, origin) => `\n\n— ${name}\n${origin}`;
+const en = {
+    tooMany: (seconds) => {
+        const minutes = Math.max(1, Math.ceil(seconds / 60));
+        return `Too many tries. Try again in ${minutes} minute${minutes === 1 ? '' : 's'}.`;
+    },
+    crossSite: 'Cross-site form submissions are forbidden.',
+    email: {
+        invalid: 'Enter a valid email address.',
+        tooLong: 'The email address is too long.'
+    },
+    password: {
+        tooShort: 'Use at least 10 characters for the password.',
+        tooLong: 'Use at most 200 characters for the password.'
+    },
+    signup: {
+        acceptTerms: 'Please accept the terms to sign up.',
+        confirmBusiness: 'Please confirm that you sign up for your business: we serve businesses only.',
+        taken: 'An account with this email address already exists.'
+    },
+    login: { wrong: 'Email or password is wrong.' },
+    link: { invalid: 'This link is invalid, used or expired.' },
+    mailFailed: 'We could not send the email. Please try again in a moment.',
+    account: {
+        sameEmail: 'This is your address already.',
+        wrongPassword: 'The password is wrong.',
+        wrongCurrent: 'The current password is wrong.',
+        taken: 'Another account uses this address.',
+        confirmDelete: 'Type your email address to confirm.',
+        keyName: 'API key',
+        confirmFirst: 'Confirm your email address first; then you can create keys.'
+    },
+    api: {
+        unauthorized: (example) => `Send a valid API key as "Authorization: Bearer ${example}".`,
+        rateLimited: (seconds) => `Too many requests. Try again in ${seconds} seconds.`,
+        invalidJson: 'The request body must be JSON.',
+        notAnObject: 'The request body must be a JSON object.',
+        invalidRequest: 'The request body is not valid.',
+        emailTaken: 'An account with this email address already exists.',
+        notFound: 'There is no such API endpoint.',
+        methodNotAllowed: 'This endpoint does not support the method.',
+        payloadTooLarge: 'The request body is too large.',
+        failed: 'The request failed.',
+        forbidden: 'Cross-site form submissions are forbidden. Send JSON with "Content-Type: application/json".',
+        internal: 'Something went wrong on our side.',
+        acceptTerms: (terms) => `Send "accept_terms": true to accept the terms (${terms}) on behalf of your business.`,
+        actingForBusiness: 'Send "acting_for_business": true to state that you sign up for your business: we serve businesses only.',
+        via: 'via is the referral tag of the link you came by: small letters and digits, joined by single hyphens, at most 32 characters.',
+        firstKey: 'Created at sign-up',
+        price: 'price must be the lookup key of a price of the product.',
+        quantity: (max) => `quantity must be a whole number from 1 to ${max}.`,
+        subscribed: 'The account has a running subscription; change it in the customer portal (POST /api/v1/billing/portal).',
+        noCustomer: 'The account has paid for nothing yet, so it has no customer portal.'
+    },
+    stripe: {
+        terms: (name, url) => `I accept the [terms of ${name}](${url}) on behalf of my business.`,
+        signature: 'The signature of the webhook does not fit.',
+        notConfigured: 'Stripe is not configured.'
+    },
+    sales: { unauthorized: 'Send the token for the sales numbers as "Authorization: Bearer …".' },
+    mails: {
+        verify: ({ name, origin, link, hours }) => ({
+            subject: `Confirm your email address for ${name}`,
+            text: `Please confirm your email address for your account at ${name}:\n\n${link}\n\n` +
+                `The link is valid for ${hours} hours. If you did not create this account, ignore this email.` +
+                signature(name, origin)
+        }),
+        reset: ({ name, origin, link, hours }) => ({
+            subject: `Set a new password for ${name}`,
+            text: `Set a new password for your account at ${name}:\n\n${link}\n\n` +
+                `The link is valid for ${hours === 1 ? 'one hour' : `${hours} hours`} and works once. If you did not ask for it, ` +
+                'ignore this email; your password stays as it is.' +
+                signature(name, origin)
+        }),
+        change: ({ name, origin, link, hours }) => ({
+            subject: `Confirm your new email address for ${name}`,
+            text: `Confirm that this address becomes the login address of your account at ${name}:\n\n` +
+                `${link}\n\nThe link is valid for ${hours} hours. If you did not ask for it, ignore this email.` +
+                signature(name, origin)
+        }),
+        changed: ({ name, origin, newEmail }) => ({
+            subject: `Your email address for ${name} was changed`,
+            text: `The login address of your account at ${name} is now ${newEmail}.\n\n` +
+                'If you did not do this, reply to this email right away.' +
+                signature(name, origin)
+        })
+    },
+    openApi: {
+        signup: 'Create an account and get its first API key at once',
+        signupCreated: 'The account and its first API key, shown only here. A link to confirm the email address goes to it.',
+        account: 'The account of the API key',
+        email: 'The email address of the account.',
+        acceptTerms: 'Accepts the terms on behalf of the business that signs up.',
+        actingForBusiness: 'States that the account is for a business, not a consumer.',
+        via: 'The referral tag of the link the business came by, if any (?via=…).',
+        apiKey: 'An API key of the account as a bearer token.',
+        checkout: 'A Checkout page at Stripe for a price of the product',
+        checkoutBody: 'A subscription or a purchase; whoever pays accepts the terms there on behalf of the business. Back to /account.',
+        portal: 'The customer portal of the account at Stripe: payment method, invoices, subscription',
+        url: 'The address to open in a browser; it holds for a short while.',
+        price: 'The lookup key of a price of the product.',
+        quantity: 'For a subscription that counts a quantity, like seats; 1 without.',
+        errors: {
+            invalidJson: 'The body is not JSON (invalid_json).',
+            invalidRequest: 'The body is not valid (invalid_request); details name each problem.',
+            emailTaken: 'An account with this email address exists (email_taken).',
+            unauthorized: 'No valid API key (unauthorized).',
+            rateLimited: 'Too many requests (rate_limited); see the header Retry-After.',
+            forbidden: 'A form from another site (forbidden).',
+            subscribed: 'The account has a running subscription (subscribed).',
+            noCustomer: 'The account has paid for nothing yet (no_customer).',
+            notConfigured: 'Stripe is not configured (not_configured).'
+        }
+    }
+};
+const de = {
+    tooMany: (seconds) => {
+        const minutes = Math.max(1, Math.ceil(seconds / 60));
+        return `Zu viele Versuche. Versuchen Sie es in ${minutes} Minute${minutes === 1 ? '' : 'n'} wieder.`;
+    },
+    crossSite: 'Formulare von anderen Seiten sind nicht erlaubt.',
+    email: {
+        invalid: 'Geben Sie eine gültige E-Mail-Adresse ein.',
+        tooLong: 'Die E-Mail-Adresse ist zu lang.'
+    },
+    password: {
+        tooShort: 'Das Passwort braucht mindestens 10 Zeichen.',
+        tooLong: 'Das Passwort darf höchstens 200 Zeichen haben.'
+    },
+    signup: {
+        acceptTerms: 'Bitte akzeptieren Sie die Bedingungen, um sich zu registrieren.',
+        confirmBusiness: 'Bitte bestätigen Sie, dass Sie sich für Ihr Unternehmen registrieren: wir bedienen nur Unternehmen.',
+        taken: 'Zu dieser E-Mail-Adresse besteht schon ein Konto.'
+    },
+    login: { wrong: 'E-Mail-Adresse oder Passwort ist falsch.' },
+    link: { invalid: 'Dieser Link ist ungültig, schon benutzt oder abgelaufen.' },
+    mailFailed: 'Wir konnten die E-Mail nicht senden. Bitte versuchen Sie es gleich nochmals.',
+    account: {
+        sameEmail: 'Das ist schon Ihre Adresse.',
+        wrongPassword: 'Das Passwort ist falsch.',
+        wrongCurrent: 'Das aktuelle Passwort ist falsch.',
+        taken: 'Ein anderes Konto benutzt diese Adresse.',
+        confirmDelete: 'Geben Sie zur Bestätigung Ihre E-Mail-Adresse ein.',
+        keyName: 'API-Schlüssel',
+        confirmFirst: 'Bestätigen Sie zuerst Ihre E-Mail-Adresse; dann können Sie Schlüssel anlegen.'
+    },
+    api: {
+        unauthorized: (example) => `Senden Sie einen gültigen API-Schlüssel als "Authorization: Bearer ${example}".`,
+        rateLimited: (seconds) => `Zu viele Anfragen. Versuchen Sie es in ${seconds} Sekunden wieder.`,
+        invalidJson: 'Der Inhalt der Anfrage muss JSON sein.',
+        notAnObject: 'Der Inhalt der Anfrage muss ein JSON-Objekt sein.',
+        invalidRequest: 'Der Inhalt der Anfrage ist nicht gültig.',
+        emailTaken: 'Zu dieser E-Mail-Adresse besteht schon ein Konto.',
+        notFound: 'Diesen API-Endpunkt gibt es nicht.',
+        methodNotAllowed: 'Dieser Endpunkt kennt die Methode nicht.',
+        payloadTooLarge: 'Der Inhalt der Anfrage ist zu gross.',
+        failed: 'Die Anfrage ist fehlgeschlagen.',
+        forbidden: 'Formulare von anderen Seiten sind nicht erlaubt. Senden Sie JSON mit "Content-Type: application/json".',
+        internal: 'Bei uns ist etwas schiefgegangen.',
+        acceptTerms: (terms) => `Senden Sie "accept_terms": true, um die Bedingungen (${terms}) für Ihr Unternehmen zu akzeptieren.`,
+        actingForBusiness: 'Senden Sie "acting_for_business": true, um zu bestätigen, dass Sie sich für Ihr Unternehmen registrieren: wir bedienen nur Unternehmen.',
+        via: 'via ist die Kennung des Links, über den Sie kamen: kleine Buchstaben und Ziffern, mit einzelnen Bindestrichen verbunden, höchstens 32 Zeichen.',
+        firstKey: 'Bei der Registrierung angelegt',
+        price: 'price muss der lookup_key eines Preises des Produkts sein.',
+        quantity: (max) => `quantity muss eine ganze Zahl von 1 bis ${max} sein.`,
+        subscribed: 'Das Konto hat ein laufendes Abo; ändern Sie es im Kundenportal (POST /api/v1/billing/portal).',
+        noCustomer: 'Das Konto hat noch nichts bezahlt und darum kein Kundenportal.'
+    },
+    stripe: {
+        terms: (name, url) => `Ich akzeptiere die [Bedingungen von ${name}](${url}) im Namen meines Unternehmens.`,
+        signature: 'Die Signatur des Webhooks passt nicht.',
+        notConfigured: 'Stripe ist nicht eingerichtet.'
+    },
+    sales: {
+        unauthorized: 'Senden Sie das Token für die Zahlen des Vertriebs als "Authorization: Bearer …".'
+    },
+    mails: {
+        verify: ({ name, origin, link, hours }) => ({
+            subject: `Bestätigen Sie Ihre E-Mail-Adresse für ${name}`,
+            text: `Bitte bestätigen Sie Ihre E-Mail-Adresse für Ihr Konto bei ${name}:\n\n${link}\n\n` +
+                `Der Link gilt ${hours} Stunden. Falls Sie dieses Konto nicht eröffnet haben, ignorieren Sie diese E-Mail.` +
+                signature(name, origin)
+        }),
+        reset: ({ name, origin, link, hours }) => ({
+            subject: `Neues Passwort für ${name}`,
+            text: `Setzen Sie ein neues Passwort für Ihr Konto bei ${name}:\n\n${link}\n\n` +
+                `Der Link gilt ${hours === 1 ? 'eine Stunde' : `${hours} Stunden`} und funktioniert einmal. Falls Sie ihn nicht ` +
+                'angefordert haben, ignorieren Sie diese E-Mail; Ihr Passwort bleibt, wie es ist.' +
+                signature(name, origin)
+        }),
+        change: ({ name, origin, link, hours }) => ({
+            subject: `Bestätigen Sie Ihre neue E-Mail-Adresse für ${name}`,
+            text: `Bestätigen Sie, dass diese Adresse die Anmeldeadresse Ihres Kontos bei ${name} wird:\n\n` +
+                `${link}\n\nDer Link gilt ${hours} Stunden. Falls Sie ihn nicht angefordert haben, ignorieren Sie diese E-Mail.` +
+                signature(name, origin)
+        }),
+        changed: ({ name, origin, newEmail }) => ({
+            subject: `Ihre E-Mail-Adresse für ${name} wurde geändert`,
+            text: `Die Anmeldeadresse Ihres Kontos bei ${name} ist jetzt ${newEmail}.\n\n` +
+                'Falls Sie das nicht waren, antworten Sie sofort auf diese E-Mail.' +
+                signature(name, origin)
+        })
+    },
+    openApi: {
+        signup: 'Ein Konto eröffnen und gleich seinen ersten API-Schlüssel erhalten',
+        signupCreated: 'Das Konto und sein erster API-Schlüssel, der nur hier erscheint. Ein Link zur Bestätigung der E-Mail-Adresse geht an sie.',
+        account: 'Das Konto des API-Schlüssels',
+        email: 'Die E-Mail-Adresse des Kontos.',
+        acceptTerms: 'Akzeptiert die Bedingungen für das Unternehmen, das sich registriert.',
+        actingForBusiness: 'Bestätigt, dass das Konto einem Unternehmen gehört, nicht einem Konsumenten.',
+        via: 'Die Kennung des Links, über den das Unternehmen kam, falls es eine gibt (?via=…).',
+        apiKey: 'Ein API-Schlüssel des Kontos als Bearer-Token.',
+        checkout: 'Eine Checkout-Seite bei Stripe für einen Preis des Produkts',
+        checkoutBody: 'Ein Abo oder ein Einmalkauf; wer zahlt, akzeptiert dort die Bedingungen für das Unternehmen. Zurück nach /account.',
+        portal: 'Das Kundenportal des Kontos bei Stripe: Zahlungsmittel, Rechnungen, Abo',
+        url: 'Die Adresse zum Öffnen im Browser; sie gilt eine kurze Weile.',
+        price: 'Der lookup_key eines Preises des Produkts.',
+        quantity: 'Für ein Abo mit einer Menge, etwa Plätzen; ohne 1.',
+        errors: {
+            invalidJson: 'Der Inhalt ist kein JSON (invalid_json).',
+            invalidRequest: 'Der Inhalt ist nicht gültig (invalid_request); details nennt jedes Problem.',
+            emailTaken: 'Zu dieser E-Mail-Adresse besteht ein Konto (email_taken).',
+            unauthorized: 'Kein gültiger API-Schlüssel (unauthorized).',
+            rateLimited: 'Zu viele Anfragen (rate_limited); siehe die Kopfzeile Retry-After.',
+            forbidden: 'Ein Formular von einer anderen Seite (forbidden).',
+            subscribed: 'Das Konto hat ein laufendes Abo (subscribed).',
+            noCustomer: 'Das Konto hat noch nichts bezahlt (no_customer).',
+            notConfigured: 'Stripe ist nicht eingerichtet (not_configured).'
+        }
+    }
+};
+export const MESSAGES = { en, de };

package/dist/server/migrations.d.ts

@@ -0,0 +1,28 @@
+export type Layer = 'baukasten' | 'product';
+export interface MigrationFile {
+    name: string;
+    sql: string;
+    checksum: string;
+}
+export interface AppliedMigration {
+    name: string;
+    checksum: string;
+}
+export interface Plan {
+    pending: MigrationFile[];
+    /** Applied migrations of a newer version, all after the files of this one. */
+    ahead: string[];
+    problems: string[];
+}
+/** What a database still needs of this version, as `layer/name`, and why it must not be migrated. */
+export interface MigrationStatus {
+    pending: string[];
+    problems: string[];
+}
+/** The migrations among the files of a folder, in order; other files are no concern of theirs. */
+export declare function migrationFiles(layer: Layer, entries: readonly {
+    name: string;
+    sql: string;
+}[]): MigrationFile[];
+/** What to apply, what the database has ahead, and the problems that forbid applying anything. */
+export declare function plan(layer: Layer, files: readonly MigrationFile[], applied: readonly AppliedMigration[]): Plan;

package/dist/server/migrations.js

@@ -0,0 +1,59 @@
+// Forward-only SQL migrations in two layers: first that of the baukasten (schema `baukasten`), then
+// that of the product (its `migrations/`, schema `public`). A file changed after it was applied
+// stops the run, and so does a gap. A database ahead of this version, with later migrations of a
+// newer one, is fine: the delivery service falls back to the previous version when a newer one
+// starts unhealthy, so a migration only adds, and the previous version runs against the newer
+// schema.
+import { createHash } from 'node:crypto';
+const NAME = /^(\d{3})_[a-z0-9_]+\.sql$/;
+/** The migrations among the files of a folder, in order; other files are no concern of theirs. */
+export function migrationFiles(layer, entries) {
+    const numbers = new Set();
+    const files = entries
+        .filter((entry) => entry.name.endsWith('.sql'))
+        .map((entry) => {
+        const number = NAME.exec(entry.name)?.[1];
+        if (number === undefined) {
+            throw new Error(`${layer} migrations are named like 001_name.sql: ${entry.name}`);
+        }
+        if (numbers.has(number))
+            throw new Error(`two ${layer} migrations share the number ${number}`);
+        numbers.add(number);
+        return {
+            name: entry.name,
+            sql: entry.sql,
+            checksum: createHash('sha256').update(entry.sql).digest('hex')
+        };
+    });
+    return files.sort((a, b) => (a.name < b.name ? -1 : 1));
+}
+/** What to apply, what the database has ahead, and the problems that forbid applying anything. */
+export function plan(layer, files, applied) {
+    const done = new Map(applied.map((row) => [row.name, row.checksum]));
+    const known = new Set(files.map((file) => file.name));
+    const names = applied.map((row) => row.name).sort();
+    const changed = files
+        .filter((file) => done.has(file.name) && done.get(file.name) !== file.checksum)
+        .map((file) => `${layer} migration ${file.name} was changed after it was applied`);
+    const pending = files.filter((file) => !done.has(file.name));
+    const gaps = pending.flatMap((file) => {
+        const later = names.find((name) => name > file.name);
+        if (later === undefined)
+            return [];
+        return [`${layer} migration ${file.name} is not applied, but the later ${later} is`];
+    });
+    const unknown = names.filter((name) => !known.has(name));
+    const diverged = unknown.flatMap((name) => {
+        const own = files.find((file) => file.name > name);
+        if (own === undefined)
+            return [];
+        return [
+            `the database carries the ${layer} migration ${name}, which this version does not know, before ${own.name}, which it does`
+        ];
+    });
+    return {
+        pending,
+        ahead: unknown.filter((name) => files.every((file) => file.name < name)),
+        problems: [...changed, ...gaps, ...diverged]
+    };
+}

package/dist/server/openapi.d.ts

@@ -0,0 +1,24 @@
+import type { Messages } from './messages.js';
+export interface OpenApiPart {
+    paths: Record<string, unknown>;
+    components: {
+        schemas: Record<string, unknown>;
+        securitySchemes: Record<string, unknown>;
+    };
+}
+/** An OpenAPI document as far as the merge reads it; the rest is the product's. */
+export interface OpenApiDocument {
+    paths?: Record<string, unknown>;
+    components?: {
+        schemas?: Record<string, unknown>;
+        securitySchemes?: Record<string, unknown>;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+export declare function openApiPart(origin: string, messages: Messages): OpenApiPart;
+/**
+ * `document` with the part of the baukasten. The product's own paths use its security scheme
+ * `apiKey` and its schema `Error`; a name both define is an error, not an override.
+ */
+export declare function mergeOpenApi(document: OpenApiDocument, part: OpenApiPart): OpenApiDocument;