@tollwyn/baukasten 0.0.2 → 1.2.3

package/dist/shopify/texts.js

@@ -0,0 +1,49 @@
+const who = (customer) => [customer.id, customer.email, customer.phone].filter((part) => part !== null).join(', ');
+export const SHOPIFY_TEXTS = {
+    en: {
+        outside: {
+            title: (name) => name,
+            text: (name) => `${name} runs in the admin of your Shopify store. Open it there, under Apps.`,
+            privacy: 'Privacy policy'
+        },
+        unavailable: {
+            title: 'Not available right now',
+            text: 'Shopify did not answer as it should. Please try again in a moment.'
+        },
+        dataRequest: {
+            subject: (name) => `${name}: a customer asks for their data`,
+            text: ({ name, shop, customer, data }) => [
+                `Shopify passed on a request of a customer of your store ${shop} (${who(customer)}) for the personal data ${name} keeps about them.`,
+                '',
+                data === null
+                    ? `${name} keeps no personal data about this customer.`
+                    : `${name} keeps these data about this customer:\n\n${data}`,
+                '',
+                'Please pass this on to your customer with your answer to their request.'
+            ].join('\n')
+        }
+    },
+    de: {
+        outside: {
+            title: (name) => name,
+            text: (name) => `${name} läuft in der Verwaltung Ihres Shopify-Shops. Öffnen Sie es dort, unter Apps.`,
+            privacy: 'Datenschutz'
+        },
+        unavailable: {
+            title: 'Gerade nicht verfügbar',
+            text: 'Shopify hat nicht geantwortet, wie es sollte. Bitte versuchen Sie es gleich noch einmal.'
+        },
+        dataRequest: {
+            subject: (name) => `${name}: Ein Kunde fragt nach seinen Daten`,
+            text: ({ name, shop, customer, data }) => [
+                `Shopify hat die Anfrage eines Kunden Ihres Shops ${shop} (${who(customer)}) nach den Personendaten weitergegeben, die ${name} über ihn hält.`,
+                '',
+                data === null
+                    ? `${name} hält keine Personendaten über diesen Kunden.`
+                    : `${name} hält diese Daten über diesen Kunden:\n\n${data}`,
+                '',
+                'Bitte geben Sie das mit Ihrer Antwort auf seine Anfrage an Ihren Kunden weiter.'
+            ].join('\n')
+        }
+    }
+};

package/dist/shopify/toml.d.ts

@@ -0,0 +1,22 @@
+export declare const APP_TOML = "shopify.app.toml";
+/** The domain under which the fleet runs every product, <subdomain>.tollwyn.com. */
+export declare const FLEET_DOMAIN = "tollwyn.com";
+/** What the server reads of the configuration. */
+export interface AppToml {
+    /** The client ID; null until the app is linked at Shopify. */
+    clientId: string | null;
+    /** The handle of the app in the admin, admin.shopify.com/store/<shop>/apps/<handle>. */
+    handle: string;
+    /** The scopes the app asks for: tokens granted fewer are exchanged anew. */
+    scopes: string;
+}
+/** The client ID, handle and scopes of the app, or what keeps the server from reading them. */
+export declare function appToml(text: string): {
+    kind: 'ok';
+    toml: AppToml;
+} | {
+    kind: 'problems';
+    problems: string[];
+};
+/** What keeps the configuration from fitting the baukasten and the subdomain of the app. */
+export declare function appTomlProblems(text: string, subdomain: string): string[];

package/dist/shopify/toml.js

@@ -0,0 +1,125 @@
+import { parse } from 'smol-toml';
+import { z } from 'zod';
+import { COMPLIANCE_TOPICS, SHOPIFY_API_VERSION, SHOPIFY_AUTH_PATH, SHOPIFY_WEBHOOK_PATH } from './constants.js';
+export const APP_TOML = 'shopify.app.toml';
+/** The domain under which the fleet runs every product, <subdomain>.tollwyn.com. */
+export const FLEET_DOMAIN = 'tollwyn.com';
+const HANDLE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const RUNTIME = z.looseObject({
+    client_id: z.string('must be the client ID of the app, or empty until it is linked'),
+    handle: z
+        .string('must be the handle of the app, like invoice-sync')
+        .regex(HANDLE, 'must be the handle of the app, like invoice-sync'),
+    access_scopes: z.looseObject({ scopes: z.string('must list the scopes of the app') }, 'must list the scopes of the app')
+});
+const SUBSCRIPTION = z.looseObject({
+    topics: z.array(z.string()).optional(),
+    compliance_topics: z.array(z.string()).optional(),
+    uri: z.string('must name where the webhooks go')
+});
+const FULL = z.looseObject({
+    name: z.string('must name the app').trim().min(1, 'must name the app'),
+    embedded: z.literal(true, 'must be true: the app runs in the admin'),
+    access_scopes: z.looseObject({
+        use_legacy_install_flow: z
+            .literal(false, 'must be false or left out: Shopify installs the app (managed installation)')
+            .optional()
+    }),
+    auth: z.looseObject({
+        redirect_urls: z.array(z.string(), 'must list the redirect URL of the baukasten')
+    }),
+    webhooks: z.looseObject({
+        api_version: z.literal(SHOPIFY_API_VERSION, `must be ${SHOPIFY_API_VERSION}, the version of the baukasten`),
+        subscriptions: z.array(SUBSCRIPTION).min(1, 'must subscribe the webhooks of the baukasten')
+    }),
+    build: z
+        .looseObject({
+        automatically_update_urls_on_dev: z
+            .literal(false, 'must be false or left out: the URLs of the app are those of its subdomain')
+            .optional()
+    })
+        .optional()
+});
+/** Tables the baukasten does not serve: their requests would reach the app unchecked. */
+const UNSERVED = {
+    app_proxy: 'an app proxy',
+    events: 'the events of Shopify',
+    customer_authentication: 'customer accounts'
+};
+function read(text) {
+    try {
+        return { kind: 'ok', value: parse(text) };
+    }
+    catch (error) {
+        return { kind: 'broken', reason: error instanceof Error ? error.message : String(error) };
+    }
+}
+function issues(error) {
+    return error.issues.map((issue) => `${APP_TOML}: ${issue.path.join('.')} ${issue.message}`);
+}
+/** The client ID, handle and scopes of the app, or what keeps the server from reading them. */
+export function appToml(text) {
+    const parsed = read(text);
+    if (parsed.kind === 'broken') {
+        return { kind: 'problems', problems: [`${APP_TOML} is no TOML: ${parsed.reason}`] };
+    }
+    const toml = RUNTIME.safeParse(parsed.value);
+    if (!toml.success)
+        return { kind: 'problems', problems: issues(toml.error) };
+    const clientId = toml.data.client_id.trim();
+    return {
+        kind: 'ok',
+        toml: {
+            clientId: clientId === '' ? null : clientId,
+            handle: toml.data.handle,
+            scopes: toml.data.access_scopes.scopes
+        }
+    };
+}
+/** What keeps the configuration from fitting the baukasten and the subdomain of the app. */
+export function appTomlProblems(text, subdomain) {
+    const parsed = read(text);
+    if (parsed.kind === 'broken')
+        return [`${APP_TOML} is no TOML: ${parsed.reason}`];
+    const runtime = RUNTIME.safeParse(parsed.value);
+    const full = FULL.safeParse(parsed.value);
+    const problems = [
+        ...(runtime.success ? [] : issues(runtime.error)),
+        ...(full.success ? [] : issues(full.error))
+    ];
+    const tables = z.looseObject({}).parse(parsed.value);
+    for (const [table, what] of Object.entries(UNSERVED)) {
+        if (table in tables) {
+            problems.push(`${APP_TOML}: [${table}] is ${what}, which this version does not serve`);
+        }
+    }
+    const origin = `https://${subdomain}.${FLEET_DOMAIN}`;
+    const url = z.looseObject({ application_url: z.unknown() }).parse(parsed.value).application_url;
+    if (url !== origin)
+        problems.push(`${APP_TOML}: application_url must be ${origin}`);
+    if (!full.success)
+        return problems;
+    const redirects = full.data.auth.redirect_urls;
+    const redirect = `${origin}${SHOPIFY_AUTH_PATH}`;
+    if (redirects.length !== 1 || redirects[0] !== redirect) {
+        problems.push(`${APP_TOML}: auth.redirect_urls must be ["${redirect}"]`);
+    }
+    const subscriptions = full.data.webhooks.subscriptions;
+    for (const subscription of subscriptions) {
+        if (subscription.uri !== SHOPIFY_WEBHOOK_PATH) {
+            problems.push(`${APP_TOML}: every webhook goes to ${SHOPIFY_WEBHOOK_PATH}, where the baukasten checks it, not to ${subscription.uri}`);
+        }
+    }
+    const topics = new Set(subscriptions.flatMap((s) => s.topics ?? []));
+    const compliance = new Set(subscriptions.flatMap((s) => s.compliance_topics ?? []));
+    if (!topics.has('app/uninstalled')) {
+        problems.push(`${APP_TOML}: the webhooks lack the topic app/uninstalled`);
+    }
+    for (const topic of COMPLIANCE_TOPICS.filter((t) => !compliance.has(t))) {
+        problems.push(`${APP_TOML}: the webhooks lack the compliance topic ${topic}`);
+    }
+    for (const topic of [...compliance].filter((t) => !COMPLIANCE_TOPICS.includes(t))) {
+        problems.push(`${APP_TOML}: ${topic} is no compliance topic`);
+    }
+    return problems;
+}

package/dist/shopify/webhooks.d.ts

@@ -0,0 +1,65 @@
+import type { Language } from '../product.js';
+import type { Log } from '../server/log.js';
+import type { Db, Mailer, Queryable } from '../server/ports.js';
+import type { Shops } from './shops.js';
+/** A request about a customer of a shop, from customers/redact or customers/data_request. */
+export interface CustomerRequest {
+    shop: string;
+    customer: {
+        id: string;
+        email: string | null;
+        phone: string | null;
+    };
+    /** The orders it concerns, by their ids at Shopify. */
+    orders: string[];
+}
+/** A webhook of a topic of the app's own, as Shopify sent it. */
+export interface Delivery {
+    topic: string;
+    shop: string;
+    payload: unknown;
+}
+/** What the baukasten calls in the app for its webhooks. */
+export interface WebhookHooks {
+    /** customers/redact: deletes what the app keeps of the customer, in the transaction of the webhook. */
+    redactCustomer?: (tx: Queryable, request: CustomerRequest) => Promise<void>;
+    /**
+     * customers/data_request: what the app keeps of the customer, as text for the merchant, which the
+     * baukasten mails to the shop; null when it keeps nothing of them.
+     */
+    customerData?: (db: Queryable, request: CustomerRequest) => Promise<string | null>;
+    /** Every other topic of shopify.app.toml, once per webhook, in its transaction. */
+    webhook?: (tx: Queryable, delivery: Delivery) => Promise<void>;
+}
+export type Received = {
+    kind: 'unsigned';
+} | {
+    kind: 'malformed';
+    reason: string;
+} | {
+    kind: 'queued';
+} | {
+    kind: 'repeated';
+};
+/** An applied webhook is remembered this long, so that Shopify sending it again applies it once. */
+export declare const KEPT_MS: number;
+/** After a failure a webhook waits this long before its next try; after the last, it gives up. */
+export declare const RETRY_AFTER_MS: number[];
+export declare function createWebhooks(deps: {
+    db: Db;
+    shops: Shops;
+    secret: string;
+    hooks: WebhookHooks;
+    mail: Mailer;
+    /** The name of the app, in the mail of a data request. */
+    name: string;
+    language: Language;
+    log: Log;
+    now: () => Date;
+}): {
+    receive: (body: Uint8Array, headers: Headers) => Promise<Received>;
+    work: () => Promise<{
+        retryAt: Date | null;
+        forgetAt: Date | null;
+    }>;
+};

package/dist/shopify/webhooks.js

@@ -0,0 +1,220 @@
+// A webhook without the signature of the client secret gets 401 before anything is read, as the
+// review of the App Store tests. A signed one is kept and answered at once, since Shopify waits
+// five seconds, and a run applies it after; its shop and payload, which may hold personal data, go
+// once it is applied.
+import { z } from 'zod';
+import { webhookSigned } from './hmac.js';
+import { shopDomain } from './shop.js';
+import { SHOPIFY_TEXTS } from './texts.js';
+/** An applied webhook is remembered this long, so that Shopify sending it again applies it once. */
+export const KEPT_MS = 7 * 24 * 3_600_000;
+/** After a failure a webhook waits this long before its next try; after the last, it gives up. */
+export const RETRY_AFTER_MS = [
+    60_000,
+    5 * 60_000,
+    30 * 60_000,
+    2 * 3_600_000,
+    6 * 3_600_000,
+    12 * 3_600_000
+];
+const ID = z.union([z.number().int(), z.string()]).transform(String);
+const CUSTOMER_REQUEST = z.object({
+    customer: z.object({
+        id: ID,
+        email: z
+            .string()
+            .nullish()
+            .transform((v) => v ?? null),
+        phone: z
+            .string()
+            .nullish()
+            .transform((v) => v ?? null)
+    }),
+    orders_to_redact: z.array(ID).optional(),
+    orders_requested: z.array(ID).optional()
+});
+/**
+ * Where a payload of a topic of the baukasten names its shop. The signature covers the body, not the
+ * headers: the shop the body names counts, and a body without the field is refused, so that a signed
+ * body cannot be sent for another shop. Only a field that names no shop, like the placeholder
+ * `{shop}.myshopify.com` of the samples of Shopify, leaves the shop of the header.
+ */
+const SHOP_IN_PAYLOAD = {
+    'app/uninstalled': 'myshopify_domain',
+    'shop/redact': 'shop_domain',
+    'customers/redact': 'shop_domain',
+    'customers/data_request': 'shop_domain'
+};
+const TRIGGERED_AT = z.iso.datetime({ offset: true });
+export function createWebhooks(deps) {
+    const { db, shops, hooks, log, now } = deps;
+    function customerRequest(shop, payload) {
+        const { customer, orders_to_redact: redact, orders_requested: requested } = CUSTOMER_REQUEST.parse(payload);
+        // customers/redact names the orders to redact, customers/data_request those requested.
+        return { shop, customer, orders: redact ?? requested ?? [] };
+    }
+    /**
+     * Mails the merchant what the app keeps of the customer: Shopify wants the answer with the shop. A
+     * shop the app does not know (never opened, or deleted) has nothing in the app to answer with.
+     */
+    async function answerRequest(tx, request) {
+        const data = (await hooks.customerData?.(tx, request)) ?? null;
+        const to = await shops.email(tx, request.shop);
+        if (to === null) {
+            if (data !== null) {
+                throw new Error('the app keeps data of a customer of a shop it does not know');
+            }
+            log.info('shopify: a request about a customer of a shop the app does not know', {
+                shop: request.shop
+            });
+            return;
+        }
+        const texts = SHOPIFY_TEXTS[deps.language].dataRequest;
+        await deps.mail.send({
+            to,
+            subject: texts.subject(deps.name),
+            text: texts.text({ name: deps.name, shop: request.shop, customer: request.customer, data })
+        });
+    }
+    async function apply(tx, webhook) {
+        const { topic, shop, payload } = webhook;
+        switch (topic) {
+            case 'app/uninstalled':
+                if (await shops.uninstall(tx, shop, webhook.triggered_at)) {
+                    log.info('shopify: a shop removed the app', { shop });
+                }
+                else {
+                    log.info('shopify: an app/uninstalled that ends no installation: the shop is unknown, removed already, or added the app again after it', { shop });
+                }
+                return;
+            case 'shop/redact':
+                await shops.redact(tx, shop);
+                // Every other webhook of the shop goes with it, waiting or given up; this one empties as
+                // it is applied.
+                await tx.query('DELETE FROM baukasten.shopify_webhooks WHERE shop = $1 AND id <> $2', [
+                    shop,
+                    webhook.id
+                ]);
+                log.info('shopify: the data of a shop are deleted', { shop });
+                return;
+            case 'customers/redact':
+                await hooks.redactCustomer?.(tx, customerRequest(shop, payload));
+                return;
+            case 'customers/data_request':
+                await answerRequest(tx, customerRequest(shop, payload));
+                return;
+            default:
+                if (hooks.webhook === undefined) {
+                    log.error('shopify: a webhook of a topic the app takes no hook for', { topic });
+                    return;
+                }
+                await hooks.webhook(tx, { topic, shop, payload });
+        }
+    }
+    async function receive(body, headers) {
+        if (!webhookSigned(body, headers.get('x-shopify-hmac-sha256'), deps.secret)) {
+            return { kind: 'unsigned' };
+        }
+        const topic = headers.get('x-shopify-topic');
+        const id = headers.get('x-shopify-webhook-id');
+        let payload;
+        try {
+            payload = JSON.parse(Buffer.from(body).toString('utf8'));
+        }
+        catch {
+            return { kind: 'malformed', reason: 'no JSON' };
+        }
+        const field = topic === null ? undefined : SHOP_IN_PAYLOAD[topic];
+        const named = field !== undefined && typeof payload === 'object' && payload !== null
+            ? Reflect.get(payload, field)
+            : undefined;
+        if (field !== undefined && typeof named !== 'string') {
+            return { kind: 'malformed', reason: `without ${field}` };
+        }
+        const shop = shopDomain(typeof named === 'string' ? named : null) ??
+            shopDomain(headers.get('x-shopify-shop-domain'));
+        if (topic === null || shop === null || id === null || id === '') {
+            return { kind: 'malformed', reason: 'without topic, shop or id' };
+        }
+        // When the event happened: Shopify tries a webhook again for hours, and a late app/uninstalled
+        // must not end an installation that came after it. Without the header, from when it came.
+        const triggered = headers.get('x-shopify-triggered-at');
+        if (triggered !== null && !TRIGGERED_AT.safeParse(triggered).success) {
+            return { kind: 'malformed', reason: 'X-Shopify-Triggered-At is no time' };
+        }
+        const received = now();
+        const kept = await db.query(`INSERT INTO baukasten.shopify_webhooks
+				(id, topic, shop, payload, triggered_at, received_at, next_at)
+			 VALUES ($1, $2, $3, $4, $5, $6, $6)
+			 ON CONFLICT (id) DO NOTHING RETURNING id`, [
+            id,
+            topic,
+            shop,
+            JSON.stringify(payload),
+            triggered === null ? received : new Date(triggered),
+            received
+        ]);
+        return kept.length === 0 ? { kind: 'repeated' } : { kind: 'queued' };
+    }
+    /** Applies the oldest webhook that is due, in its transaction; false when none is due. */
+    async function next() {
+        // The webhook the transaction took, for the record of its failure after the rollback.
+        const taken = { webhook: null };
+        try {
+            return await db.transaction(async (tx) => {
+                const [webhook] = await tx.query(`SELECT id, topic, shop, payload, triggered_at, attempts FROM baukasten.shopify_webhooks
+					 WHERE applied_at IS NULL AND failed_at IS NULL AND next_at <= $1
+					 ORDER BY received_at, id LIMIT 1 FOR UPDATE SKIP LOCKED`, [now()]);
+                if (webhook === undefined)
+                    return false;
+                taken.webhook = webhook;
+                await apply(tx, webhook);
+                await tx.query(`UPDATE baukasten.shopify_webhooks SET applied_at = $2, shop = NULL, payload = NULL
+					 WHERE id = $1`, [webhook.id, now()]);
+                return true;
+            });
+        }
+        catch (error) {
+            if (taken.webhook === null)
+                throw error;
+            await failed(taken.webhook, error);
+            return true;
+        }
+    }
+    async function failed(webhook, error) {
+        const attempts = webhook.attempts + 1;
+        const wait = RETRY_AFTER_MS[attempts - 1];
+        const about = { id: webhook.id, topic: webhook.topic, shop: webhook.shop, attempts, error };
+        if (wait === undefined) {
+            log.error('shopify: a webhook failed for the last time; it stays with its payload', about);
+            await db.query('UPDATE baukasten.shopify_webhooks SET attempts = $2, failed_at = $3 WHERE id = $1', [webhook.id, attempts, now()]);
+            return;
+        }
+        log.warn('shopify: a webhook failed; it is tried again', about);
+        await db.query('UPDATE baukasten.shopify_webhooks SET attempts = $2, next_at = $3 WHERE id = $1', [webhook.id, attempts, new Date(now().getTime() + wait)]);
+    }
+    /**
+     * Applies every webhook that is due, one after the other, and forgets those applied longer ago than
+     * KEPT_MS. Says when the next waits to be tried again (`retryAt`) and when the next applied one is
+     * to be forgotten (`forgetAt`), so that the run looks then; null for none.
+     */
+    async function work() {
+        for (;;) {
+            if (!(await next()))
+                break;
+        }
+        await db.query('DELETE FROM baukasten.shopify_webhooks WHERE applied_at <= $1', [
+            new Date(now().getTime() - KEPT_MS)
+        ]);
+        const [left] = await db.query(`SELECT min(next_at) FILTER (WHERE applied_at IS NULL AND failed_at IS NULL) AS retry_at,
+				min(applied_at) AS applied_at
+			 FROM baukasten.shopify_webhooks`);
+        if (left === undefined)
+            throw new Error('min() gave no row');
+        return {
+            retryAt: left.retry_at,
+            forgetAt: left.applied_at === null ? null : new Date(left.applied_at.getTime() + KEPT_MS)
+        };
+    }
+    return { receive, work };
+}

package/dist/stubs.d.ts

@@ -0,0 +1,15 @@
+/** The stubs by their path in the product, with exactly their content. */
+export declare const STUBS: Readonly<Record<string, string>>;
+/**
+ * The files the product owns, by their path: the command writes each only where it is missing. The
+ * configuration fails loudly until it is filled in.
+ */
+export declare const STARTING_POINTS: Readonly<Record<string, string>>;
+/** The stubs of a Shopify app, by their path, with exactly their content. */
+export declare const SHOPIFY_STUBS: Readonly<Record<string, string>>;
+/**
+ * The files a Shopify app owns, by their path, written only where they are missing. The
+ * configuration fails loudly until it is filled in; shopify.app.toml waits for the subdomain of the
+ * app, its name, handle and scopes, and for the client ID, which linking the app gives it.
+ */
+export declare const SHOPIFY_STARTING_POINTS: Readonly<Record<string, string>>;