@tollwyn/baukasten 0.0.2 → 1.2.2

package/dist/testing/smtp.d.ts

@@ -0,0 +1,38 @@
+export interface ReceivedMail {
+    /** The recipients of the envelope, in small letters. */
+    to: string[];
+    /** The From header, decoded: name and address. */
+    from: string;
+    subject: string;
+    /** The text with line feeds. */
+    text: string;
+}
+export interface SmtpDouble {
+    host: string;
+    port: number;
+    /** Every mail it took, in order. */
+    mails: ReceivedMail[];
+    /**
+     * The next mail to `to` (whose subject matches) that no earlier call took, as soon as it is here;
+     * it fails after `timeoutMs`.
+     */
+    next(to: string, options?: {
+        subject?: RegExp;
+        timeoutMs?: number;
+    }): Promise<ReceivedMail>;
+    /** Refuses mail to `to` from now on, as a relay does with an address it cannot deliver. */
+    refuse(to: string): void;
+    /** Takes mail to `to` again. */
+    accept(to: string): void;
+    stop(): Promise<void>;
+}
+/** Words like `=?UTF-8?Q?Gr=C3=BCezi?=` in a header; the space between two words goes with them. */
+export declare function decodeWords(value: string): string;
+/** The headers and the text of a plain-text message as SMTP carries it. */
+export declare function parseMessage(raw: Buffer): {
+    headers: Map<string, string>;
+    text: string;
+};
+/** The first link in a text that starts with `prefix`. */
+export declare function linkIn(text: string, prefix: string): string;
+export declare function startSmtp(): Promise<SmtpDouble>;

package/dist/testing/smtp.js

@@ -0,0 +1,165 @@
+// An SMTP server on a free local port that keeps every mail it takes, like the relay of the fleet:
+// plain SMTP, without a login and without STARTTLS. The baukasten sends plain-text mails only, and
+// the double reads exactly those: headers in RFC 2047 words, a body in 7bit, 8bit, quoted-printable
+// or base64. Its server comes from smtp-server, which a product takes as a dev dependency: no image
+// carries it.
+import { EventEmitter } from 'node:events';
+/** Words like `=?UTF-8?Q?Gr=C3=BCezi?=` in a header; the space between two words goes with them. */
+export function decodeWords(value) {
+    return value
+        .replace(/(=\?[^?]+\?[QqBb]\?[^?]*\?=)\s+(?==\?)/g, '$1')
+        .replace(/=\?([^?]+)\?([QqBb])\?([^?]*)\?=/g, (_, charset, kind, text) => {
+        const bytes = kind.toUpperCase() === 'B'
+            ? Buffer.from(text, 'base64')
+            : quotedPrintable(text.replaceAll('_', ' '));
+        return new TextDecoder(charset).decode(bytes);
+    });
+}
+function quotedPrintable(text) {
+    const bytes = [];
+    const soft = text.replace(/=\r?\n/g, '');
+    for (let i = 0; i < soft.length; i++) {
+        const hex = soft.slice(i + 1, i + 3);
+        if (soft[i] === '=' && /^[0-9A-Fa-f]{2}$/.test(hex)) {
+            bytes.push(parseInt(hex, 16));
+            i += 2;
+        }
+        else {
+            bytes.push(...Buffer.from(soft.charAt(i), 'latin1'));
+        }
+    }
+    return Buffer.from(bytes);
+}
+/** The headers and the text of a plain-text message as SMTP carries it. */
+export function parseMessage(raw) {
+    const source = raw.toString('latin1');
+    const end = source.indexOf('\r\n\r\n');
+    if (end < 0)
+        throw new Error('the message has no end of its headers');
+    const headers = new Map();
+    for (const line of source
+        .slice(0, end)
+        .replace(/\r\n[ \t]+/g, ' ')
+        .split('\r\n')) {
+        const colon = line.indexOf(':');
+        if (colon > 0)
+            headers.set(line.slice(0, colon).trim().toLowerCase(), line.slice(colon + 1).trim());
+    }
+    const type = headers.get('content-type') ?? 'text/plain';
+    if (!type.toLowerCase().startsWith('text/plain')) {
+        throw new Error(`the double reads plain-text mails only, not ${type}`);
+    }
+    const charset = /charset="?([^";]+)"?/i.exec(type)?.[1] ?? 'utf-8';
+    const body = source.slice(end + 4);
+    const encoding = (headers.get('content-transfer-encoding') ?? '7bit').toLowerCase();
+    const bytes = encoding === 'base64'
+        ? Buffer.from(body.replace(/\s+/g, ''), 'base64')
+        : encoding === 'quoted-printable'
+            ? quotedPrintable(body)
+            : Buffer.from(body, 'latin1');
+    // SMTP ends every message with a line break, which the text did not have.
+    const text = new TextDecoder(charset).decode(bytes).replace(/\r\n/g, '\n').replace(/\n$/, '');
+    return {
+        headers: new Map([...headers].map(([name, value]) => [name, decodeWords(value)])),
+        text
+    };
+}
+/** The first link in a text that starts with `prefix`. */
+export function linkIn(text, prefix) {
+    const match = new RegExp(`${prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\S+`).exec(text);
+    if (match === null)
+        throw new Error(`no link starting with ${prefix} in: ${text}`);
+    return match[0];
+}
+/** smtp-server, or a clear word on what is missing. */
+async function smtpServer() {
+    try {
+        return (await import('smtp-server')).SMTPServer;
+    }
+    catch (error) {
+        if (error instanceof Error && Reflect.get(error, 'code') === 'ERR_MODULE_NOT_FOUND') {
+            throw new Error('the SMTP double needs smtp-server among the devDependencies of the product: npm install --save-dev smtp-server', { cause: error });
+        }
+        throw error;
+    }
+}
+export async function startSmtp() {
+    const Server = await smtpServer();
+    const mails = [];
+    const arrived = new EventEmitter();
+    const refused = new Set();
+    const taken = new Set();
+    const server = new Server({
+        authOptional: true,
+        disabledCommands: ['AUTH', 'STARTTLS'],
+        logger: false,
+        onRcptTo(address, _session, callback) {
+            if (refused.has(address.address.toLowerCase())) {
+                callback(new Error(`mailbox ${address.address} unavailable`));
+            }
+            else
+                callback();
+        },
+        onData(stream, session, callback) {
+            const chunks = [];
+            stream.on('data', (chunk) => chunks.push(chunk));
+            stream.on('end', () => {
+                try {
+                    const { headers, text } = parseMessage(Buffer.concat(chunks));
+                    const mail = {
+                        to: session.envelope.rcptTo.map((rcpt) => rcpt.address.toLowerCase()),
+                        from: headers.get('from') ?? '',
+                        subject: headers.get('subject') ?? '',
+                        text
+                    };
+                    mails.push(mail);
+                    arrived.emit('mail', mail);
+                    callback();
+                }
+                catch (error) {
+                    callback(error instanceof Error ? error : new Error(String(error)));
+                }
+            });
+        }
+    });
+    const host = '127.0.0.1';
+    await new Promise((resolve) => server.listen(0, host, resolve));
+    const address = server.server.address();
+    if (address === null || typeof address === 'string')
+        throw new Error('the SMTP double has no port');
+    return {
+        host,
+        port: address.port,
+        mails,
+        next(to, options = {}) {
+            const recipient = to.toLowerCase();
+            const fits = (mail) => !taken.has(mail) &&
+                mail.to.includes(recipient) &&
+                (options.subject?.test(mail.subject) ?? true);
+            return new Promise((resolve, reject) => {
+                const take = (mail) => {
+                    taken.add(mail);
+                    arrived.off('mail', listen);
+                    clearTimeout(timer);
+                    resolve(mail);
+                };
+                const listen = (mail) => {
+                    if (fits(mail))
+                        take(mail);
+                };
+                const timer = setTimeout(() => {
+                    arrived.off('mail', listen);
+                    reject(new Error(`no mail to ${to}; the double has ${JSON.stringify(mails)}`));
+                }, options.timeoutMs ?? 10_000);
+                const here = mails.find(fits);
+                if (here === undefined)
+                    arrived.on('mail', listen);
+                else
+                    take(here);
+            });
+        },
+        refuse: (to) => refused.add(to.toLowerCase()),
+        accept: (to) => refused.delete(to.toLowerCase()),
+        stop: () => new Promise((resolve) => server.close(() => resolve()))
+    };
+}

package/dist/testing/stripe.d.ts

@@ -0,0 +1,128 @@
+/** A value of the JSON the double answers. */
+export type Json = string | number | boolean | null | Json[] | {
+    [key: string]: Json;
+};
+type JsonObject = {
+    [key: string]: Json;
+};
+export interface DoublePrice {
+    id: string;
+    object: 'price';
+    product: string;
+    lookup_key: string | null;
+    unit_amount: number;
+    currency: string;
+    active: boolean;
+    type: 'one_time' | 'recurring';
+    recurring: {
+        interval: string;
+        interval_count: number;
+    } | null;
+}
+export interface DoubleSubscription {
+    id: string;
+    object: 'subscription';
+    customer: string;
+    status: string;
+    latest_invoice: string | null;
+    items: {
+        object: 'list';
+        data: {
+            id: string;
+            object: 'subscription_item';
+            quantity: number;
+            price: DoublePrice;
+        }[];
+    };
+}
+export interface DoubleSession {
+    id: string;
+    object: 'checkout.session';
+    mode: string;
+    customer: string;
+    url: string;
+    subscription: string | null;
+    payment_status: 'paid' | 'unpaid';
+    amount_total: number | null;
+    currency: string | null;
+    metadata: Record<string, string>;
+    success_url: string;
+    cancel_url: string;
+    /** The price, the quantity, and the most the customer may set, as Checkout got them. */
+    item: {
+        price: string;
+        quantity: number;
+        max: number | null;
+    };
+    /** The whole request, as the API got it. */
+    request: JsonObject;
+}
+export interface DoubleEndpoint {
+    id: string;
+    object: 'webhook_endpoint';
+    url: string;
+    status: 'enabled' | 'disabled';
+}
+export interface StripeDouble {
+    /** For STRIPE_API_BASE of the app. */
+    url: string;
+    /** The signing secret of the webhook: STRIPE_WEBHOOK_SECRET of the app. */
+    webhookSecret: string;
+    /** Where the events go: the webhook of the app, set by startApp. */
+    target: string | null;
+    products: Map<string, {
+        id: string;
+        object: 'product';
+        name: string;
+        active: boolean;
+    }>;
+    prices: Map<string, DoublePrice>;
+    /** The configurations of the customer portal; the default one is from the Dashboard. */
+    portals: Map<string, JsonObject>;
+    endpoints: Map<string, DoubleEndpoint>;
+    customers: Map<string, {
+        id: string;
+        object: 'customer';
+        email: string;
+        metadata: Record<string, string>;
+        livemode: boolean;
+    }>;
+    subscriptions: Map<string, DoubleSubscription>;
+    sessions: Map<string, DoubleSession>;
+    /** Every request that changed something, like "POST /v1/products". */
+    writes: string[];
+    /** How often a subscription was read back. */
+    retrieved: number;
+    /** A webhook endpoint of another product, as an account copied from it brings one. */
+    addEndpoint(url: string, status?: 'enabled' | 'disabled'): string;
+    /**
+     * The webhook of the app at `url`, as the delivery service sets it up for each start: the one it
+     * set up before is disabled. The events go to `target`, where the app listens.
+     */
+    connect(url: string, target: string): void;
+    /** Signs an event of this type with this object and sends it to the target; its answer. */
+    send(type: string, object: Json | object, options?: {
+        id?: string;
+        secret?: string;
+    }): Promise<Response>;
+    /**
+     * What the Checkout page does when the customer pays: a subscription with its first invoice, or a
+     * purchase, paid at once or, `later`, by a payment that clears afterwards.
+     */
+    pay(sessionId: string, options?: {
+        quantity?: number;
+        later?: boolean;
+    }): Promise<void>;
+    /**
+     * Waits until the events the double sends on its own time arrived, like the end of a subscription
+     * after the API ended it; fails when the app did not take one.
+     */
+    idle(): Promise<void>;
+    stop(): Promise<void>;
+}
+/** What the Stripe-Signature header carries for this payload at this time. */
+export declare function stripeSignature(payload: string, secret: string, seconds: number): string;
+export declare function startStripe(options?: {
+    portal?: boolean;
+}): Promise<StripeDouble>;
+export {};