@tollwyn/baukasten 0.0.2 → 1.2.3

package/dist/server/start.js

@@ -0,0 +1,65 @@
+// The stub server.js wraps the handler of adapter-node in a plain HTTP server of its own, so that
+// every line on stdout is JSON and the end is ordered.
+import { EventEmitter } from 'node:events';
+import { createServer } from 'node:http';
+import { exitAfterLog, log } from './adapter/log.js';
+import { portOf } from './config.js';
+import { SECURITY_HEADERS } from './headers.js';
+/**
+ * Open requests get this long after SIGTERM, the stop hooks of the product then this long; both end
+ * before the fixed start of the delivery service kills the product (stop-grace.test.ts).
+ */
+export const DRAIN_MS = 15_000;
+export const STOP_MS = 10_000;
+export function start(load) {
+    return serve(load, SECURITY_HEADERS);
+}
+export async function serve(load, headers) {
+    process.on('uncaughtException', (error) => {
+        log.error('uncaught exception', { error });
+        void exitAfterLog(1);
+    });
+    process.on('unhandledRejection', (error) => {
+        log.error('unhandled rejection', { error });
+        void exitAfterLog(1);
+    });
+    // adapter-node reads ORIGIN while it loads. An invalid PUBLIC_ORIGIN stays for the configuration,
+    // which names it with every other problem in one line.
+    const publicOrigin = process.env.PUBLIC_ORIGIN?.trim();
+    if (publicOrigin !== undefined && URL.canParse(publicOrigin)) {
+        process.env.ORIGIN = new URL(publicOrigin).origin;
+    }
+    let handler;
+    try {
+        // Loading runs `init`, which reads the configuration and starts the product.
+        ({ handler } = await load());
+    }
+    catch (error) {
+        log.error('cannot load the app', { error });
+        return exitAfterLog(1);
+    }
+    const port = portOf(process.env);
+    // The static files of adapter-node never reach the handle; they get the headers here.
+    const server = createServer((req, res) => {
+        for (const [name, value] of Object.entries(headers))
+            res.setHeader(name, value);
+        handler(req, res);
+    });
+    server.listen(port, () => log.info('listening', { port }));
+    const shutdown = (signal) => {
+        log.info('shutting down', { signal });
+        server.closeIdleConnections();
+        setTimeout(() => server.closeAllConnections(), DRAIN_MS).unref();
+        server.close(() => {
+            setTimeout(() => {
+                log.error('stopping took too long, ending the process');
+                void exitAfterLog(1);
+            }, STOP_MS).unref();
+            // The event adapter-node's own server emits after its last request; the types of Node know
+            // only its own events on process.
+            EventEmitter.prototype.emit.call(process, 'sveltekit:shutdown', signal);
+        });
+    };
+    process.once('SIGTERM', shutdown);
+    process.once('SIGINT', shutdown);
+}

package/dist/server/stripe.d.ts

@@ -0,0 +1,33 @@
+export declare const WEBHOOK_PATH = "/stripe/webhook";
+/** The events the webhook applies (billing.ts), and no other. */
+export declare const WEBHOOK_EVENTS: readonly ["checkout.session.completed", "checkout.session.async_payment_succeeded", "customer.subscription.created", "customer.subscription.updated", "customer.subscription.deleted", "invoice.paid"];
+/**
+ * What the restricted key of a product may do: the catalog (products, prices, the default customer
+ * portal), customers, Checkout, the portal, subscriptions to end them, and webhook endpoints, which
+ * the delivery service creates and the baukasten reads for those it did not create.
+ */
+export declare const KEY_RIGHTS: readonly [{
+    readonly ressource: "product";
+    readonly zugriff: "schreiben";
+}, {
+    readonly ressource: "price";
+    readonly zugriff: "schreiben";
+}, {
+    readonly ressource: "billing_portal.configuration";
+    readonly zugriff: "schreiben";
+}, {
+    readonly ressource: "billing_portal.session";
+    readonly zugriff: "schreiben";
+}, {
+    readonly ressource: "checkout.session";
+    readonly zugriff: "schreiben";
+}, {
+    readonly ressource: "customer";
+    readonly zugriff: "schreiben";
+}, {
+    readonly ressource: "subscription";
+    readonly zugriff: "schreiben";
+}, {
+    readonly ressource: "webhook_endpoint";
+    readonly zugriff: "schreiben";
+}];

package/dist/server/stripe.js

@@ -0,0 +1,29 @@
+// What every product names under `stripe` in its delivery manifest (`deploy/auslieferung.json`),
+// in the manifest's words: the webhook the delivery service sets up, and the rights of the
+// restricted key the product runs with. The contract test of the delivery service holds these lists
+// against the schema of the manifest.
+export const WEBHOOK_PATH = '/stripe/webhook';
+/** The events the webhook applies (billing.ts), and no other. */
+export const WEBHOOK_EVENTS = [
+    'checkout.session.completed',
+    'checkout.session.async_payment_succeeded',
+    'customer.subscription.created',
+    'customer.subscription.updated',
+    'customer.subscription.deleted',
+    'invoice.paid'
+];
+/**
+ * What the restricted key of a product may do: the catalog (products, prices, the default customer
+ * portal), customers, Checkout, the portal, subscriptions to end them, and webhook endpoints, which
+ * the delivery service creates and the baukasten reads for those it did not create.
+ */
+export const KEY_RIGHTS = [
+    { ressource: 'product', zugriff: 'schreiben' },
+    { ressource: 'price', zugriff: 'schreiben' },
+    { ressource: 'billing_portal.configuration', zugriff: 'schreiben' },
+    { ressource: 'billing_portal.session', zugriff: 'schreiben' },
+    { ressource: 'checkout.session', zugriff: 'schreiben' },
+    { ressource: 'customer', zugriff: 'schreiben' },
+    { ressource: 'subscription', zugriff: 'schreiben' },
+    { ressource: 'webhook_endpoint', zugriff: 'schreiben' }
+];

package/dist/server/terms.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The day the baukasten's part of the legal texts last changed (legal/, legal.test.ts holds their
+ * checksum with it); a change to that part sets it anew.
+ */
+export declare const BAUKASTEN_TERMS_DATE = "2026-10-08";
+/** The name of the terms from the two days, each YYYY-MM-DD, which sort like their dates. */
+export declare function termsVersion(baukasten: string, product: string): string;

package/dist/server/terms.js

@@ -0,0 +1,9 @@
+/**
+ * The day the baukasten's part of the legal texts last changed (legal/, legal.test.ts holds their
+ * checksum with it); a change to that part sets it anew.
+ */
+export const BAUKASTEN_TERMS_DATE = '2026-10-08';
+/** The name of the terms from the two days, each YYYY-MM-DD, which sort like their dates. */
+export function termsVersion(baukasten, product) {
+    return baukasten > product ? baukasten : product;
+}

package/dist/server/test-accounts.d.ts

@@ -0,0 +1,28 @@
+import type { Db, Queryable } from './ports.js';
+export interface TestAccount {
+    id: string;
+    /** Null for an account that was deleted: its row without the address stays for the numbers. */
+    email: string | null;
+    createdAt: Date;
+    via: string;
+    /** The states of its subscriptions, as Stripe last said. */
+    subscriptions: string[];
+    invoices: number;
+    purchases: number;
+}
+export interface TestData {
+    accounts: number;
+    invoices: number;
+    purchases: number;
+}
+/** The accounts from the test mode, oldest first. */
+export declare function testAccounts(db: Queryable): Promise<TestAccount[]>;
+export declare function testData(db: Queryable): Promise<TestData>;
+/**
+ * Deletes the accounts from the test mode with everything on them, their invoices, purchases and
+ * anonymous rows included (no real money moved), in one transaction. The tables of the product refer
+ * to an account with ON DELETE CASCADE, so its data goes with the account; a table that does not
+ * stops the deletion, and nothing is deleted. Stripe is not touched: the live key does not reach the
+ * objects of the test mode.
+ */
+export declare function deleteTestAccounts(db: Db): Promise<TestData>;

package/dist/server/test-accounts.js

@@ -0,0 +1,62 @@
+/** What else points at an account in the schema of the baukasten, deleted before the account. */
+const OF_ACCOUNTS = ['sessions', 'links', 'api_keys', 'subscriptions'];
+const TEST = "a.stripe_mode = 'test'";
+/** The accounts from the test mode, oldest first. */
+export async function testAccounts(db) {
+    const rows = await db.query(`SELECT a.id, a.email, a.created_at, a.via,
+			array(SELECT s.status FROM baukasten.subscriptions s WHERE s.account_id = a.id
+				ORDER BY s.updated_at) AS subscriptions,
+			(SELECT count(*)::int FROM baukasten.invoices i WHERE i.account_id = a.id) AS invoices,
+			(SELECT count(*)::int FROM baukasten.purchases p WHERE p.account_id = a.id) AS purchases
+		 FROM baukasten.accounts a WHERE ${TEST} ORDER BY a.created_at, a.id`);
+    return rows.map((row) => ({
+        id: row.id,
+        email: row.email,
+        createdAt: row.created_at,
+        via: row.via,
+        subscriptions: row.subscriptions,
+        invoices: row.invoices,
+        purchases: row.purchases
+    }));
+}
+export async function testData(db) {
+    const [row] = await db.query(`SELECT count(*)::int AS accounts,
+			(SELECT count(*)::int FROM baukasten.invoices i JOIN baukasten.accounts a ON a.id = i.account_id
+				WHERE ${TEST}) AS invoices,
+			(SELECT count(*)::int FROM baukasten.purchases p JOIN baukasten.accounts a ON a.id = p.account_id
+				WHERE ${TEST}) AS purchases
+		 FROM baukasten.accounts a WHERE ${TEST}`);
+    if (row === undefined)
+        throw new Error('counting the test accounts gave no row');
+    return row;
+}
+/**
+ * Deletes the accounts from the test mode with everything on them, their invoices, purchases and
+ * anonymous rows included (no real money moved), in one transaction. The tables of the product refer
+ * to an account with ON DELETE CASCADE, so its data goes with the account; a table that does not
+ * stops the deletion, and nothing is deleted. Stripe is not touched: the live key does not reach the
+ * objects of the test mode.
+ */
+export function deleteTestAccounts(db) {
+    return db.transaction(async (tx) => {
+        // Locked first: a write that points at one of them now waits for this transaction.
+        const accounts = await tx.query(`SELECT a.id FROM baukasten.accounts a WHERE ${TEST} ORDER BY a.id FOR UPDATE`);
+        const ids = accounts.map((account) => account.id);
+        const remove = async (table) => (await tx.query(`DELETE FROM baukasten.${table} WHERE account_id = ANY($1::uuid[]) RETURNING account_id`, [ids])).length;
+        for (const table of OF_ACCOUNTS)
+            await remove(table);
+        const invoices = await remove('invoices');
+        const purchases = await remove('purchases');
+        try {
+            await tx.query('DELETE FROM baukasten.accounts WHERE id = ANY($1::uuid[])', [ids]);
+        }
+        catch (error) {
+            if (error instanceof Error && Reflect.get(error, 'code') === '23503') {
+                const table = String(Reflect.get(error, 'table'));
+                throw new Error(`the table ${table} of the product refers to accounts without ON DELETE CASCADE; nothing was deleted`, { cause: error });
+            }
+            throw error;
+        }
+        return { accounts: ids.length, invoices, purchases };
+    });
+}

package/dist/server/via.d.ts

@@ -0,0 +1,9 @@
+/** The referral tag of an account that came without one. */
+export declare const NO_VIA = "ohne";
+/**
+ * At most as long as the delivery service takes a referral tag in the sales numbers (sales.test.ts
+ * holds it): a longer one would spoil every answer.
+ */
+export declare const VIA_MAX = 32;
+export declare const VIA_PATTERN: RegExp;
+export declare function parseVia(value: string | null): string | null;

package/dist/server/via.js

@@ -0,0 +1,15 @@
+// The referral tag of a link to the product, `?via=<tag>`: it travels in the links of the page that
+// was opened with it until the sign-up, and then stays with the account. Nothing keeps it in the
+// browser, neither a cookie nor web storage, which would need consent in the EU; whoever comes back
+// without the link counts as `ohne`.
+/** The referral tag of an account that came without one. */
+export const NO_VIA = 'ohne';
+/**
+ * At most as long as the delivery service takes a referral tag in the sales numbers (sales.test.ts
+ * holds it): a longer one would spoil every answer.
+ */
+export const VIA_MAX = 32;
+export const VIA_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export function parseVia(value) {
+    return value !== null && value.length <= VIA_MAX && VIA_PATTERN.test(value) ? value : null;
+}

package/dist/server/web.d.ts

@@ -0,0 +1,48 @@
+import { type ActionFailure, type Cookies } from '@sveltejs/kit';
+import { type Account } from './accounts.js';
+declare global {
+    namespace App {
+        interface Locals {
+            /** The account of the session; null without one, and on the machine paths. */
+            account: Account | null;
+        }
+    }
+}
+/**
+ * The only cookie of a product. `__Host-` keeps it to this host: no other product under the same
+ * domain can set or shadow it. Browsers take it on http://localhost too.
+ */
+export declare const SESSION_COOKIE = "__Host-session";
+export declare function setSessionCookie(cookies: Cookies, token: string): void;
+export declare function clearSessionCookie(cookies: Cookies): void;
+export declare function isMachinePath(path: string): boolean;
+/**
+ * The address of the client, for the limits. In production the edge of the fleet (Cloudflare) sets
+ * CF-Connecting-IP; locally a proxy appends to X-Forwarded-For. Without a usable header the limits
+ * count the socket, which is the proxy: that errs towards limiting. An IPv6 address counts by its
+ * /64, which one connection usually holds whole.
+ */
+export declare function clientAddress(headers: Headers, mode: 'production' | 'local', socket: () => string): string;
+/**
+ * Where a login may lead: a path of this site, or `home`. Browsers drop tabs and line breaks and read
+ * a backslash as a slash, so such a value is refused before it is resolved; dot segments could turn
+ * a path into `//host`, so the resolved path is checked again.
+ */
+export declare function safeNext(value: string | null, home: string): string;
+/**
+ * A request another origin made a browser send (CSRF). The products share the site tollwyn.com, so
+ * SameSite=Lax hands a sibling product the session cookie with its forms and fetches; only the
+ * origin tells them apart. On the pages every unsafe request needs the product's own origin. The
+ * machine paths serve software, which sends no origin, and read no cookie: there only what a
+ * browser sends across sites without asking first, a form, is refused. The check of SvelteKit is
+ * off (SVELTEKIT_OPTIONS), so that the API can answer it in JSON.
+ */
+export declare function isCrossSite(request: Request, origin: string): boolean;
+export declare function tooMany<T extends Record<string, unknown>>(event: {
+    setHeaders: (headers: Record<string, string>) => void;
+}, seconds: number, data: T): ActionFailure<T>;
+/** The account of the session, or off to the login, which leads back here. */
+export declare function requireAccount(event: {
+    locals: App.Locals;
+    url: URL;
+}): Account;

package/dist/server/web.js

@@ -0,0 +1,105 @@
+import { isIP } from 'node:net';
+import { fail, redirect } from '@sveltejs/kit';
+import { SESSION_DAYS } from './accounts.js';
+/**
+ * The only cookie of a product. `__Host-` keeps it to this host: no other product under the same
+ * domain can set or shadow it. Browsers take it on http://localhost too.
+ */
+export const SESSION_COOKIE = '__Host-session';
+export function setSessionCookie(cookies, token) {
+    cookies.set(SESSION_COOKIE, token, {
+        path: '/',
+        httpOnly: true,
+        secure: true,
+        sameSite: 'lax',
+        maxAge: SESSION_DAYS * 24 * 60 * 60
+    });
+}
+export function clearSessionCookie(cookies) {
+    cookies.delete(SESSION_COOKIE, { path: '/', httpOnly: true, secure: true, sameSite: 'lax' });
+}
+/** Machine endpoints never read the session: health must not touch the database, and the others
+ * read nothing before their own key or token is checked. */
+const MACHINE = ['/health', '/api/', '/stripe/', '/vertrieb/'];
+export function isMachinePath(path) {
+    return MACHINE.some((prefix) => prefix.endsWith('/')
+        ? path.startsWith(prefix)
+        : path === prefix || path.startsWith(`${prefix}/`));
+}
+/**
+ * The address of the client, for the limits. In production the edge of the fleet (Cloudflare) sets
+ * CF-Connecting-IP; locally a proxy appends to X-Forwarded-For. Without a usable header the limits
+ * count the socket, which is the proxy: that errs towards limiting. An IPv6 address counts by its
+ * /64, which one connection usually holds whole.
+ */
+export function clientAddress(headers, mode, socket) {
+    const raw = mode === 'production'
+        ? headers.get('cf-connecting-ip')
+        : (headers.get('x-forwarded-for')?.split(',').at(-1) ?? null);
+    const address = raw?.trim() ?? '';
+    return isIP(address) === 0 ? network(socket()) : network(address);
+}
+/** An IPv6 address as its /64, an IPv4 address mapped into IPv6 as that; IPv4 as it is. */
+function network(address) {
+    if (isIP(address) !== 6)
+        return address;
+    const lower = address.toLowerCase();
+    const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(lower)?.[1];
+    if (mapped !== undefined)
+        return mapped;
+    // A dotted quad at the end is the last two groups.
+    const hex = lower.replace(/(\d+)\.(\d+)\.(\d+)\.(\d+)$/, (_, a, b, c, d) => `${((Number(a) << 8) | Number(b)).toString(16)}:${((Number(c) << 8) | Number(d)).toString(16)}`);
+    const [head = '', tail] = hex.split('::');
+    const left = head === '' ? [] : head.split(':');
+    const right = tail === undefined || tail === '' ? [] : tail.split(':');
+    const groups = tail === undefined
+        ? left
+        : [...left, ...Array(8 - left.length - right.length).fill('0'), ...right];
+    const prefix = groups.slice(0, 4).map((group) => parseInt(group, 16).toString(16));
+    return `${prefix.join(':')}::/64`;
+}
+/**
+ * Where a login may lead: a path of this site, or `home`. Browsers drop tabs and line breaks and read
+ * a backslash as a slash, so such a value is refused before it is resolved; dot segments could turn
+ * a path into `//host`, so the resolved path is checked again.
+ */
+export function safeNext(value, home) {
+    if (value === null || !value.startsWith('/') || /[\s\\\p{Cc}]/u.test(value))
+        return home;
+    const here = 'http://product.invalid';
+    const url = new URL(value, here);
+    if (url.origin !== here || url.pathname.startsWith('//'))
+        return home;
+    return `${url.pathname}${url.search}${url.hash}`;
+}
+const SAFE_METHODS = ['GET', 'HEAD', 'OPTIONS'];
+const FORM_TYPES = ['application/x-www-form-urlencoded', 'multipart/form-data', 'text/plain'];
+/**
+ * A request another origin made a browser send (CSRF). The products share the site tollwyn.com, so
+ * SameSite=Lax hands a sibling product the session cookie with its forms and fetches; only the
+ * origin tells them apart. On the pages every unsafe request needs the product's own origin. The
+ * machine paths serve software, which sends no origin, and read no cookie: there only what a
+ * browser sends across sites without asking first, a form, is refused. The check of SvelteKit is
+ * off (SVELTEKIT_OPTIONS), so that the API can answer it in JSON.
+ */
+export function isCrossSite(request, origin) {
+    if (SAFE_METHODS.includes(request.method) || request.headers.get('origin') === origin) {
+        return false;
+    }
+    if (!isMachinePath(new URL(request.url).pathname))
+        return true;
+    const type = (request.headers.get('content-type') ?? '').split(';', 1)[0]?.trim().toLowerCase();
+    return FORM_TYPES.some((form) => form === type);
+}
+export function tooMany(event, seconds, data) {
+    event.setHeaders({ 'retry-after': String(seconds) });
+    return fail(429, data);
+}
+/** The account of the session, or off to the login, which leads back here. */
+export function requireAccount(event) {
+    const account = event.locals.account;
+    if (account === null) {
+        redirect(303, `/login?next=${encodeURIComponent(event.url.pathname + event.url.search)}`);
+    }
+    return account;
+}

package/dist/shopify/adapter/shopify.d.ts

@@ -0,0 +1,8 @@
+import type { ShopifyConfig } from '../config.js';
+import type { ShopifyApi } from '../ports.js';
+export declare class ShopifyFailed extends Error {
+    name: string;
+}
+export declare function shopifyApi(config: ShopifyConfig['shopify'], options: {
+    now: () => Date;
+}): ShopifyApi;

package/dist/shopify/adapter/shopify.js

@@ -0,0 +1,232 @@
+// In the tests of an app the same requests go to the double on this machine (testing/shopify.ts),
+// under /shops/<shop>/… and /partners/<org>/…. An error names the status and what Shopify called it,
+// never a token.
+import { z } from 'zod';
+import { SHOPIFY_API_VERSION } from '../constants.js';
+export class ShopifyFailed extends Error {
+    name = 'ShopifyFailed';
+}
+/** Each call waits this long at most; the request of a merchant waits on it. */
+const TIMEOUT_MS = 10_000;
+const TOKENS = z.object({
+    access_token: z.string().min(1),
+    scope: z.string(),
+    expires_in: z.number().int().positive(),
+    refresh_token: z.string().min(1),
+    refresh_token_expires_in: z.number().int().positive()
+});
+const TOKEN_ERROR = z.object({ error: z.string() });
+const GRAPHQL = z.object({
+    data: z.unknown().optional(),
+    errors: z
+        .array(z.object({
+        message: z.string(),
+        extensions: z.object({ code: z.string().optional() }).optional()
+    }))
+        .optional(),
+    extensions: z
+        .object({
+        cost: z
+            .object({
+            requestedQueryCost: z.number(),
+            throttleStatus: z.object({ currentlyAvailable: z.number(), restoreRate: z.number() })
+        })
+            .optional()
+    })
+        .optional()
+});
+const SHOP_INFO = z.object({
+    shop: z.object({
+        id: z.string().startsWith('gid://shopify/Shop/'),
+        email: z.string(),
+        plan: z.object({ partnerDevelopment: z.boolean() })
+    }),
+    currentAppInstallation: z.object({
+        app: z.object({ id: z.string().startsWith('gid://shopify/App/') })
+    })
+});
+const SUBSCRIPTION = z.object({
+    activeSubscription: z
+        .object({
+        trialEndsAt: z.iso.datetime({ offset: true }).nullable(),
+        items: z.array(z.object({ handle: z.string().nullable() }))
+    })
+        .nullable()
+});
+const SHOP_INFO_QUERY = `query BaukastenShop {
+	shop { id email plan { partnerDevelopment } }
+	currentAppInstallation { app { id } }
+}`;
+const SUBSCRIPTION_QUERY = `query BaukastenSubscription($appId: ID!, $shopId: ID!) {
+	activeSubscription(appId: $appId, shopId: $shopId) { trialEndsAt items { handle } }
+}`;
+const PARTNER_CHECK_QUERY = 'query BaukastenCheck { publicApiVersions { handle } }';
+/** A token of the token endpoint in the shape of the port; `expires_in` counts seconds. */
+function tokensOf(body, now) {
+    const at = (seconds) => new Date(now.getTime() + seconds * 1_000);
+    return {
+        accessToken: body.access_token,
+        accessExpiresAt: at(body.expires_in),
+        refreshToken: body.refresh_token,
+        refreshExpiresAt: at(body.refresh_token_expires_in),
+        scope: body.scope
+    };
+}
+/** How long to wait before the next query, from the cost Shopify reports, at least a second. */
+function throttleWait(extensions) {
+    const cost = extensions?.cost;
+    if (cost === undefined || cost.throttleStatus.restoreRate <= 0)
+        return 1_000;
+    const lacking = cost.requestedQueryCost - cost.throttleStatus.currentlyAvailable;
+    return Math.max(1_000, Math.ceil(lacking / cost.throttleStatus.restoreRate) * 1_000);
+}
+export function shopifyApi(config, options) {
+    const shopUrl = (shop, path) => config.api.kind === 'double'
+        ? `${config.api.url}/shops/${shop}${path}`
+        : `https://${shop}${path}`;
+    const partnerUrl = () => {
+        const path = `/${config.partner.organization}/api/${SHOPIFY_API_VERSION}/graphql.json`;
+        return config.api.kind === 'double'
+            ? `${config.api.url}/partners${path}`
+            : `https://partners.shopify.com${path}`;
+    };
+    async function post(url, headers, body) {
+        let response;
+        try {
+            response = await fetch(url, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', accept: 'application/json', ...headers },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(TIMEOUT_MS)
+            });
+        }
+        catch (error) {
+            throw new ShopifyFailed('Shopify unreachable', { cause: error });
+        }
+        const text = await response.text();
+        let json = null;
+        try {
+            json = text === '' ? null : JSON.parse(text);
+        }
+        catch {
+            // An answer that is no JSON is judged by its status alone.
+        }
+        return { status: response.status, headers: response.headers, json };
+    }
+    async function token(shop, grant) {
+        // No shop gets in before the app is linked (respondTo in shopify/hook.ts); this is the last guard.
+        if (config.clientId === null)
+            throw new ShopifyFailed('the app has no client ID yet');
+        const answer = await post(shopUrl(shop, '/admin/oauth/access_token'), {}, { client_id: config.clientId, client_secret: config.secret, ...grant });
+        if (answer.status === 200) {
+            const tokens = TOKENS.safeParse(answer.json);
+            if (tokens.success)
+                return { kind: 'tokens', tokens: tokensOf(tokens.data, options.now()) };
+            return { kind: 'failed', reason: 'tokens of an unknown form' };
+        }
+        const error = TOKEN_ERROR.safeParse(answer.json);
+        const named = error.success ? error.data.error : null;
+        // Shopify no longer takes the ID token or the refresh token: only the merchant can get a new one.
+        if (answer.status === 401 ||
+            (answer.status === 400 && (named === 'invalid_subject_token' || named === 'invalid_grant'))) {
+            return { kind: 'invalid' };
+        }
+        return {
+            kind: 'failed',
+            reason: `status ${answer.status}${named === null ? '' : ` (${named})`}`
+        };
+    }
+    async function graphql(shop, accessToken, query, variables) {
+        const answer = await post(shopUrl(shop, `/admin/api/${SHOPIFY_API_VERSION}/graphql.json`), { 'x-shopify-access-token': accessToken }, { query, variables });
+        if (answer.status === 401)
+            return { kind: 'unauthorized' };
+        if (answer.status === 429) {
+            const seconds = Number(answer.headers.get('retry-after'));
+            return {
+                kind: 'throttled',
+                waitMs: Number.isFinite(seconds) && seconds > 0 ? seconds * 1_000 : 1_000
+            };
+        }
+        if (answer.status !== 200)
+            throw new ShopifyFailed(`the Admin API answered ${answer.status}`);
+        const body = GRAPHQL.safeParse(answer.json);
+        if (!body.success)
+            throw new ShopifyFailed('the Admin API answered in an unknown form');
+        const errors = body.data.errors ?? [];
+        if (errors.some((error) => error.extensions?.code === 'THROTTLED')) {
+            return { kind: 'throttled', waitMs: throttleWait(body.data.extensions) };
+        }
+        if (errors.length > 0) {
+            return {
+                kind: 'errors',
+                errors: errors.map((error) => ({
+                    message: error.message,
+                    code: error.extensions?.code ?? null
+                }))
+            };
+        }
+        return { kind: 'data', data: body.data.data };
+    }
+    async function partner(query, variables) {
+        const answer = await post(partnerUrl(), { 'x-shopify-access-token': config.partner.token }, { query, variables });
+        if (answer.status !== 200)
+            throw new ShopifyFailed(`the Partner API answered ${answer.status}`);
+        const body = GRAPHQL.safeParse(answer.json);
+        if (!body.success)
+            throw new ShopifyFailed('the Partner API answered in an unknown form');
+        const errors = body.data.errors ?? [];
+        if (errors.length > 0) {
+            throw new ShopifyFailed(`the Partner API refused: ${errors.map((error) => error.extensions?.code ?? error.message).join(', ')}`);
+        }
+        return body.data.data;
+    }
+    return {
+        exchange: (shop, idToken) => token(shop, {
+            grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
+            subject_token: idToken,
+            subject_token_type: 'urn:ietf:params:oauth:token-type:id_token',
+            requested_token_type: 'urn:shopify:params:oauth:token-type:offline-access-token',
+            expiring: '1'
+        }),
+        refresh: (shop, refreshToken) => token(shop, { grant_type: 'refresh_token', refresh_token: refreshToken }),
+        async shopInfo(shop, accessToken) {
+            const answer = await graphql(shop, accessToken, SHOP_INFO_QUERY, {});
+            switch (answer.kind) {
+                case 'unauthorized':
+                    return null;
+                case 'throttled':
+                    throw new ShopifyFailed('the Admin API is over the limit of the shop');
+                case 'errors':
+                    throw new ShopifyFailed(`the Admin API refused: ${answer.errors.map((error) => error.code ?? error.message).join(', ')}`);
+                case 'data': {
+                    const info = SHOP_INFO.safeParse(answer.data);
+                    if (!info.success)
+                        throw new ShopifyFailed('the shop came in an unknown form');
+                    return {
+                        shopId: info.data.shop.id,
+                        appId: info.data.currentAppInstallation.app.id,
+                        email: info.data.shop.email,
+                        development: info.data.shop.plan.partnerDevelopment
+                    };
+                }
+            }
+        },
+        graphql,
+        async subscription(appId, shopId) {
+            const data = SUBSCRIPTION.safeParse(await partner(SUBSCRIPTION_QUERY, { appId, shopId }));
+            if (!data.success)
+                throw new ShopifyFailed('the subscription came in an unknown form');
+            const active = data.data.activeSubscription;
+            if (active === null)
+                return { kind: 'none' };
+            return {
+                kind: 'active',
+                handles: active.items.flatMap((item) => (item.handle === null ? [] : [item.handle])),
+                trialEndsAt: active.trialEndsAt === null ? null : new Date(active.trialEndsAt)
+            };
+        },
+        async partnerCheck() {
+            await partner(PARTNER_CHECK_QUERY, {});
+        }
+    };
+}