astroidjs 0.1.2 → 0.2.0

package/dist/commerce/loader.js

@@ -0,0 +1,90 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The catalog read, and the Live Content Collection loader over it.
+//
+// `defineCatalogLoader` (louise-toolkit/astro) already owns the Astro-facing
+// plumbing. What each site then hand-wrote was the layer underneath — "read my
+// catalog out of D1" — and because that layer was per-site, so was the drift.
+// It doesn't need to be: once the mirror table's shape is fixed (see mirror.ts),
+// reading it is the same query whatever provider filled it in.
+//
+// That's what makes one loader definition serve a Square site and a Fourthwall
+// site: the loader never learns which provider it is. The sync normalized that
+// away before the row was written.
+/** JSON column → value, tolerating both a decoded object and a raw string. */
+function decodeJson(value) {
+    if (typeof value !== "string")
+        return value ?? null;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return null;
+    }
+}
+/** Mirror row → `CatalogProduct`. */
+function toProduct(row) {
+    const { images, variants, external_id, external_slug, sort_order, synced_at, ...rest } = row;
+    return {
+        ...rest,
+        externalId: String(external_id ?? ""),
+        externalSlug: typeof external_slug === "string" ? external_slug : undefined,
+        slug: String(row.slug ?? ""),
+        name: String(row.name ?? ""),
+        price: Number(row.price ?? 0),
+        images: decodeJson(images) ?? [],
+        variants: decodeJson(variants),
+        status: row.status === "published" ? "published" : "draft",
+        sortOrder: Number(sort_order ?? 0),
+        featured: Boolean(row.featured),
+    };
+}
+/**
+ * Read the catalog. Ordered by `sortOrder` then name, so an owner's manual
+ * ordering wins and everything they haven't ordered stays stable rather than
+ * shuffling per query.
+ */
+export async function readCatalog(options) {
+    const where = options.includeDrafts ? "" : " WHERE status = 'published'";
+    const { results } = await options.db
+        .prepare(`SELECT * FROM ${options.table}${where} ORDER BY sort_order ASC, name ASC`)
+        .all();
+    return (results ?? []).map(toProduct);
+}
+/** Read one product by its public slug. Null when absent or still a draft. */
+export async function readCatalogItem(slug, options) {
+    const where = options.includeDrafts ? "" : " AND status = 'published'";
+    const row = await options.db
+        .prepare(`SELECT * FROM ${options.table} WHERE slug = ?${where}`)
+        .bind(slug)
+        .first();
+    return row ? toProduct(row) : null;
+}
+/**
+ * The config to hand `defineCatalogLoader`, wired to the mirror.
+ *
+ * ```ts
+ * // src/loaders/catalog.ts
+ * import { defineCatalogLoader } from "louise-toolkit/astro";
+ * import { astroidCatalogLoaderConfig } from "astroidjs";
+ *
+ * export const catalogLoader = defineCatalogLoader(
+ *   astroidCatalogLoaderConfig({ db: env.DB, table: "products" }),
+ * );
+ * ```
+ *
+ * Identical for every provider — which is the whole point.
+ */
+export function astroidCatalogLoaderConfig(options) {
+    return {
+        name: options.name ?? "astroid-catalog",
+        loadCatalog: async (filter) => {
+            const items = await readCatalog(options);
+            return {
+                items: filter?.featured ? items.filter((i) => i.featured) : items,
+            };
+        },
+        loadItem: (id) => readCatalogItem(id, options),
+        idOf: (item) => item.slug,
+    };
+}

package/dist/commerce/mirror.d.ts

@@ -0,0 +1,67 @@
+import type { AstroidConfig } from "../config.js";
+/** A column the OWNER edits. Preserved verbatim across every sync. */
+export interface OwnedColumn {
+    type: "text" | "integer" | "real" | "boolean" | "json";
+    /** Restrict a text column to a fixed set (emits a Drizzle `enum`). */
+    values?: string[];
+    /** Default for new rows. Strings are quoted; others are emitted as literals. */
+    default?: string | number | boolean;
+    /** Doc comment on the generated column. */
+    note?: string;
+}
+export interface CatalogMirrorConfig {
+    /**
+     * `mirror` keeps the provider's catalog fields in D1 (fast reads, briefly
+     * stale); `overlay` keeps only the owner's fields and reads the catalog live.
+     * Default `mirror`.
+     */
+    mode?: "mirror" | "overlay";
+    /** Table name. Default `products`. */
+    table?: string;
+    /** The owner-editable columns, on top of the built-ins below. */
+    owned?: Record<string, OwnedColumn>;
+}
+/**
+ * Columns Astroid always PULLS, overwriting each sync. Fixed rather than
+ * configurable because they're the intersection of what every provider returns —
+ * a project that wants a provider-specific field puts it in `owned` and fills it
+ * itself, which also stops the sync from clobbering it.
+ */
+export declare const PULLED_COLUMNS: readonly ["name", "price", "images", "variants", "externalSlug", "syncedAt"];
+/**
+ * Owner columns every catalog needs, whatever the site. `slug` is deliberately
+ * owned, not pulled: it's the public URL, so a provider renaming a product must
+ * not silently break links and SEO.
+ */
+export declare const BUILT_IN_OWNED: Record<string, OwnedColumn>;
+/** The mirror config for a project, with defaults applied. Null when the project
+ *  has no storefront to mirror. */
+export declare function astroidCatalogMirror(config: AstroidConfig): Required<Pick<CatalogMirrorConfig, "mode" | "table">> & {
+    owned: Record<string, OwnedColumn>;
+};
+/**
+ * Drizzle source for the catalog table.
+ *
+ * `externalId` is unique — it's the sync's idempotency key, so a webhook and the
+ * cron re-sync racing on the same product can only ever collide into one row.
+ */
+export declare function generateCatalogTable(config: AstroidConfig): string | null;
+/**
+ * The `CREATE TABLE` for the catalog mirror, as a D1 migration.
+ *
+ * Derived from the SAME `astroidCatalogMirror(config)` declaration as
+ * {@link generateCatalogTable}, so the Drizzle schema and the table that
+ * actually exists cannot describe different shapes.
+ *
+ * It has to exist at all because nothing else creates this table. `--commerce`
+ * put `products` in `src/schema.ts` and the queue seam told you to sync into it,
+ * but no migration anywhere in the toolkit created it — so the first catalog
+ * sync hit a missing table, and (because `astroidCatalogSync` swallows per-item
+ * errors) reported success while writing nothing. The documented fallback,
+ * `drizzle-kit generate`, could not help: the template ships a hand-authored
+ * `0000_content.sql` with no drizzle journal, so drizzle-kit has no baseline and
+ * emits a duplicate `0000_` full-CREATE that collides on the next apply.
+ *
+ * Returns null when the project has no commerce.
+ */
+export declare function generateCatalogMigrationSql(config: AstroidConfig): string | null;

package/dist/commerce/mirror.js

@@ -0,0 +1,203 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The catalog mirror: an external provider is the source of truth, D1 is the
+// editable overlay on top of it.
+//
+// Every consuming site landed on the same split — a set of fields PULLED from
+// the provider and overwritten on every sync, and a disjoint set the owner edits
+// which must survive every sync. Get that boundary wrong in either direction and
+// you either clobber the owner's copy on the next cron tick, or serve a price
+// the provider no longer honours.
+//
+// What the sites did NOT agree on is how much to store, and it turns out to be
+// one primitive with two settings rather than two designs:
+//
+//   mirror   — pulled + owned columns both live in D1 (themidwestartist.com).
+//              Reads are one local query. The catalog can be stale between syncs.
+//   overlay  — only the owned columns live in D1, keyed by the provider's id
+//              (coracle.coffee's `product_display_meta`). The catalog is read
+//              live from the provider and joined at read time: never stale,
+//              but every read costs a provider round-trip (cache accordingly).
+//
+// `overlay` is just `mirror` with an empty pulled set, so one generator serves
+// both and a project can switch by changing one word.
+/**
+ * Columns Astroid always PULLS, overwriting each sync. Fixed rather than
+ * configurable because they're the intersection of what every provider returns —
+ * a project that wants a provider-specific field puts it in `owned` and fills it
+ * itself, which also stops the sync from clobbering it.
+ */
+export const PULLED_COLUMNS = [
+    "name",
+    "price",
+    "images",
+    "variants",
+    "externalSlug",
+    "syncedAt",
+];
+/**
+ * Owner columns every catalog needs, whatever the site. `slug` is deliberately
+ * owned, not pulled: it's the public URL, so a provider renaming a product must
+ * not silently break links and SEO.
+ */
+export const BUILT_IN_OWNED = {
+    slug: {
+        type: "text",
+        note: "Public URL segment. Owner-owned so a provider rename can't break links.",
+    },
+    status: {
+        type: "text",
+        values: ["draft", "published"],
+        default: "draft",
+        note: "New remote items land as draft — nothing goes live until someone says so.",
+    },
+    sortOrder: { type: "real", default: 0 },
+    featured: { type: "boolean", default: false },
+};
+/** The mirror config for a project, with defaults applied. Null when the project
+ *  has no storefront to mirror. */
+export function astroidCatalogMirror(config) {
+    const mirror = config.commerce?.catalog ?? {};
+    return {
+        mode: mirror.mode ?? "mirror",
+        table: mirror.table ?? "products",
+        // Built-ins first so a project can override one (e.g. widen `status`)
+        // without restating the rest.
+        owned: { ...BUILT_IN_OWNED, ...mirror.owned },
+    };
+}
+const SQL_NAME = (key) => key.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+/** Drizzle source for one owned column. */
+function ownedColumnSource(key, col) {
+    const name = JSON.stringify(SQL_NAME(key));
+    const lit = (v) => typeof v === "string" ? JSON.stringify(v) : `${v}`;
+    let expr;
+    switch (col.type) {
+        case "boolean":
+            expr = `integer(${name}, { mode: "boolean" })`;
+            break;
+        case "json":
+            expr = `text(${name}, { mode: "json" }).$type<JsonValue>()`;
+            break;
+        case "text":
+            expr = col.values?.length
+                ? `text(${name}, { enum: ${JSON.stringify(col.values)} })`
+                : `text(${name})`;
+            break;
+        default:
+            expr = `${col.type}(${name})`;
+    }
+    if (col.default !== undefined)
+        expr += `.notNull().default(${lit(col.default)})`;
+    return `  ${key}: ${expr},`;
+}
+/**
+ * Drizzle source for the catalog table.
+ *
+ * `externalId` is unique — it's the sync's idempotency key, so a webhook and the
+ * cron re-sync racing on the same product can only ever collide into one row.
+ */
+export function generateCatalogTable(config) {
+    if (!config.commerce)
+        return null;
+    const { mode, table, owned } = astroidCatalogMirror(config);
+    const lines = [];
+    const p = (s = "") => lines.push(s);
+    p(`// The catalog ${mode}. The provider is the source of truth; these rows are`);
+    p(mode === "mirror"
+        ? "// a local copy plus the owner's edits. Pulled columns are overwritten every"
+        : "// the owner's edits only — catalog fields are read live from the provider.");
+    p("// sync; owned columns are preserved. See astroidCatalogUpsert.");
+    p(`export const ${camel(table)} = sqliteTable(${JSON.stringify(table)}, {`);
+    p('  id: integer("id").primaryKey({ autoIncrement: true }),');
+    p("  // The provider's id for this item — the sync's idempotency key.");
+    p('  externalId: text("external_id").notNull().unique(),');
+    if (mode === "mirror") {
+        p("  // --- PULLED: overwritten on every sync, never hand-edit ---");
+        p('  name: text("name").notNull(),');
+        p('  price: real("price").notNull().default(0),');
+        p('  images: text("images", { mode: "json" }).$type<JsonValue>(),');
+        p('  variants: text("variants", { mode: "json" }).$type<JsonValue>(),');
+        p('  externalSlug: text("external_slug"),');
+    }
+    p('  syncedAt: integer("synced_at", { mode: "timestamp" }),');
+    p("  // --- OWNED: preserved across every sync ---");
+    for (const [key, col] of Object.entries(owned)) {
+        if (col.note)
+            p(`  /** ${col.note} */`);
+        p(ownedColumnSource(key, col));
+    }
+    p('  createdAt: integer("created_at", { mode: "timestamp" }).$defaultFn(() => new Date()),');
+    p("});");
+    p();
+    return lines.join("\n");
+}
+/** `product_display_meta` → `productDisplayMeta`. */
+function camel(name) {
+    return name.replace(/[_-](\w)/g, (_, c) => c.toUpperCase());
+}
+/** SQL column type + constraints for one owned column, matching
+ *  {@link ownedColumnSource}'s Drizzle output. */
+function ownedColumnSql(key, col) {
+    const name = SQL_NAME(key);
+    // Drizzle stores booleans and timestamps as INTEGER, json as TEXT.
+    const type = col.type === "boolean" ? "integer" : col.type === "json" ? "text" : col.type;
+    let sql = `  \`${name}\` ${type}`;
+    if (col.default !== undefined) {
+        const lit = typeof col.default === "string"
+            ? `'${col.default.replace(/'/g, "''")}'`
+            : typeof col.default === "boolean"
+                ? col.default
+                    ? "1"
+                    : "0"
+                : `${col.default}`;
+        sql += ` NOT NULL DEFAULT ${lit}`;
+    }
+    return sql;
+}
+/**
+ * The `CREATE TABLE` for the catalog mirror, as a D1 migration.
+ *
+ * Derived from the SAME `astroidCatalogMirror(config)` declaration as
+ * {@link generateCatalogTable}, so the Drizzle schema and the table that
+ * actually exists cannot describe different shapes.
+ *
+ * It has to exist at all because nothing else creates this table. `--commerce`
+ * put `products` in `src/schema.ts` and the queue seam told you to sync into it,
+ * but no migration anywhere in the toolkit created it — so the first catalog
+ * sync hit a missing table, and (because `astroidCatalogSync` swallows per-item
+ * errors) reported success while writing nothing. The documented fallback,
+ * `drizzle-kit generate`, could not help: the template ships a hand-authored
+ * `0000_content.sql` with no drizzle journal, so drizzle-kit has no baseline and
+ * emits a duplicate `0000_` full-CREATE that collides on the next apply.
+ *
+ * Returns null when the project has no commerce.
+ */
+export function generateCatalogMigrationSql(config) {
+    if (!config.commerce)
+        return null;
+    const { mode, table, owned } = astroidCatalogMirror(config);
+    const cols = [
+        "  `id` integer PRIMARY KEY AUTOINCREMENT NOT NULL",
+        "  `external_id` text NOT NULL",
+    ];
+    if (mode === "mirror") {
+        cols.push("  `name` text NOT NULL", "  `price` real NOT NULL DEFAULT 0", "  `images` text", "  `variants` text", "  `external_slug` text");
+    }
+    cols.push("  `synced_at` integer");
+    for (const [key, col] of Object.entries(owned))
+        cols.push(ownedColumnSql(key, col));
+    cols.push("  `created_at` integer");
+    return [
+        `-- The catalog ${mode} (${table}). Generated from your Astroid commerce config;`,
+        "-- keep it in step with src/schema.ts, which is generated from the same declaration.",
+        `CREATE TABLE IF NOT EXISTS \`${table}\` (`,
+        cols.join(",\n"),
+        ");",
+        "",
+        "-- The sync's idempotency key: a webhook and the cron re-sync racing on the same",
+        "-- product can then only ever collide into one row.",
+        `CREATE UNIQUE INDEX IF NOT EXISTS \`${table}_external_id_unique\` ON \`${table}\` (\`external_id\`);`,
+        "",
+    ].join("\n");
+}

package/dist/commerce/roles.d.ts

@@ -0,0 +1,38 @@
+import type { CommerceConfig, CommerceProvider } from "../config.js";
+/** What a provider is being used FOR. */
+export type CommerceRole = "storefront" | "invoicing";
+/**
+ * Which roles each provider can serve, derived from the surface its
+ * `louise-toolkit/commerce/*` client actually exposes — not from what the
+ * vendor's full API could theoretically do.
+ *
+ *   square      catalog + orders + payments, and `createInvoice`/`publishInvoice`
+ *   stripe      invoices + payment intents; NO catalog
+ *   fourthwall  catalog + cart; NO invoicing
+ */
+export declare const PROVIDER_ROLES: Record<CommerceProvider, readonly CommerceRole[]>;
+/** The providers filling each role. Either may be absent. */
+export interface ResolvedCommerceRoles {
+    storefront?: CommerceProvider;
+    invoicing?: CommerceProvider;
+}
+/**
+ * Resolve a `commerce` block into role assignments.
+ *
+ * The `provider` shorthand assigns to the provider's *natural* role — the one it
+ * can serve — so `{ provider: "square" }` is a storefront and
+ * `{ provider: "stripe" }` is invoicing. Guessing "storefront" for both would
+ * produce a storefront with no catalog API behind it.
+ */
+export declare function astroidCommerceRoles(commerce: CommerceConfig | undefined): ResolvedCommerceRoles;
+/** Every distinct provider this project talks to, in a stable order. */
+export declare function astroidCommerceProviders(commerce: CommerceConfig | undefined): CommerceProvider[];
+/** True when this project sells anything at all. */
+export declare const hasStorefront: (commerce: CommerceConfig | undefined) => boolean;
+/**
+ * Reject a role assignment the provider's client cannot serve. Called from
+ * `defineAstroid`, so `invoicing: "fourthwall"` fails at config load with a
+ * message naming the alternatives — rather than at runtime, on the first
+ * invoice, as a missing function.
+ */
+export declare function assertCommerceRoles(commerce: CommerceConfig | undefined): void;

package/dist/commerce/roles.js

@@ -0,0 +1,93 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// Provider ROLES, not "the provider".
+//
+// The obvious model is one commerce provider per site. It's wrong, and the
+// toolkit's own clients prove it: `louise-toolkit/commerce/stripe` has no
+// catalog API whatsoever — it exposes invoices, customers, and payment intents.
+// `fourthwall` is the mirror image: a catalog and a cart, no invoicing. Square
+// happens to do both. A single `CommerceProvider` abstraction that assumed
+// catalog + checkout would therefore have a permanent hole wherever Stripe sits.
+//
+// That's not hypothetical. themidwestartist.com runs Stripe for **invoicing**
+// (commissions, originals) alongside Fourthwall for the **storefront** (merch) —
+// two providers, one site, each doing the half it can do.
+//
+// So a project assigns providers to roles, and Astroid validates the assignment
+// against what each provider's client can actually serve.
+import { AstroidConfigError } from "../errors.js";
+/**
+ * Which roles each provider can serve, derived from the surface its
+ * `louise-toolkit/commerce/*` client actually exposes — not from what the
+ * vendor's full API could theoretically do.
+ *
+ *   square      catalog + orders + payments, and `createInvoice`/`publishInvoice`
+ *   stripe      invoices + payment intents; NO catalog
+ *   fourthwall  catalog + cart; NO invoicing
+ */
+export const PROVIDER_ROLES = {
+    square: ["storefront", "invoicing"],
+    stripe: ["invoicing"],
+    fourthwall: ["storefront"],
+};
+/**
+ * Resolve a `commerce` block into role assignments.
+ *
+ * The `provider` shorthand assigns to the provider's *natural* role — the one it
+ * can serve — so `{ provider: "square" }` is a storefront and
+ * `{ provider: "stripe" }` is invoicing. Guessing "storefront" for both would
+ * produce a storefront with no catalog API behind it.
+ */
+export function astroidCommerceRoles(commerce) {
+    if (!commerce)
+        return {};
+    const roles = {};
+    if (commerce.provider) {
+        const natural = PROVIDER_ROLES[commerce.provider];
+        // Square serves both; the shorthand means the storefront, since that's the
+        // role that shapes the site (a catalog, a cart, product pages).
+        roles[natural.includes("storefront") ? "storefront" : "invoicing"] = commerce.provider;
+    }
+    if (commerce.storefront)
+        roles.storefront = commerce.storefront;
+    if (commerce.invoicing)
+        roles.invoicing = commerce.invoicing;
+    return roles;
+}
+/** Every distinct provider this project talks to, in a stable order. */
+export function astroidCommerceProviders(commerce) {
+    const { storefront, invoicing } = astroidCommerceRoles(commerce);
+    return [...new Set([storefront, invoicing].filter((p) => !!p))];
+}
+/** True when this project sells anything at all. */
+export const hasStorefront = (commerce) => Boolean(astroidCommerceRoles(commerce).storefront);
+/**
+ * Reject a role assignment the provider's client cannot serve. Called from
+ * `defineAstroid`, so `invoicing: "fourthwall"` fails at config load with a
+ * message naming the alternatives — rather than at runtime, on the first
+ * invoice, as a missing function.
+ */
+export function assertCommerceRoles(commerce) {
+    if (!commerce)
+        return;
+    const known = (provider) => {
+        if (!PROVIDER_ROLES[provider]) {
+            throw new AstroidConfigError(`Unknown commerce provider ${JSON.stringify(provider)} (expected ${Object.keys(PROVIDER_ROLES).join(" | ")})`);
+        }
+    };
+    const check = (role, provider) => {
+        if (!provider)
+            return;
+        known(provider);
+        if (!PROVIDER_ROLES[provider].includes(role)) {
+            const able = Object.keys(PROVIDER_ROLES).filter((p) => PROVIDER_ROLES[p].includes(role));
+            throw new AstroidConfigError(`commerce: ${provider} can't serve the "${role}" role — its louise-toolkit client has no ${role === "storefront" ? "catalog" : "invoicing"} API. Providers that can: ${able.join(", ")}.`);
+        }
+    };
+    // The shorthand assigns itself to a role it can serve, so it only has to be a
+    // provider we know about.
+    if (commerce.provider)
+        known(commerce.provider);
+    check("storefront", commerce.storefront);
+    check("invoicing", commerce.invoicing);
+}

package/dist/commerce/secrets.d.ts

@@ -0,0 +1,74 @@
+import type { CommerceConfig, CommerceProvider } from "../config.js";
+import { type ModuleSecrets, type SecretSource } from "../secrets.js";
+/**
+ * Per-provider secret names, split by what they gate.
+ *
+ * `credentials` is what the provider's `louise-toolkit/commerce/*` client needs
+ * to make a call at all; `webhook` is the signing secret its receiver verifies
+ * with. They're separable on purpose — a site can receive verified webhooks
+ * before it has finished provisioning API access, and the reverse is the normal
+ * state of a brand-new integration.
+ *
+ * Names match what the scaffolded `env.d.ts` declares, so a project can read
+ * `env.SQUARE_ACCESS_TOKEN` and have it typed.
+ */
+export declare const COMMERCE_PROVIDER_SECRETS: Record<CommerceProvider, {
+    readonly credentials: readonly string[];
+    readonly webhook: string;
+}>;
+/**
+ * Where a developer actually gets each provider's credentials.
+ *
+ * Carried next to the names because the scaffold's job is to leave someone able
+ * to finish provisioning without a search: a `.env.example` line that says
+ * `SQUARE_ACCESS_TOKEN=DUMMY_REPLACE_ME` and nothing else has told them what to
+ * do, only that something is missing.
+ */
+export declare const COMMERCE_PROVIDER_SETUP: Record<CommerceProvider, string>;
+/**
+ * Every secret name this project's commerce configuration needs, deduplicated
+ * and in a stable order.
+ *
+ * Deduplication is the point: a site running Square in both roles has one
+ * access token, not two, and seeding `SQUARE_ACCESS_TOKEN` twice into a
+ * `.dev.vars` would be a bug rather than a redundancy.
+ */
+export declare function commerceSecretNames(commerce: CommerceConfig | undefined): string[];
+/** One provider's resolved gate. */
+export interface ProviderStatus {
+    provider: CommerceProvider;
+    /** Which role(s) this provider fills for the project. */
+    roles: ("storefront" | "invoicing")[];
+    /** API credentials — false means no live call can be made. */
+    credentials: ModuleSecrets<string>;
+    /** Webhook signing secret — false means the receiver answers 503. */
+    webhook: ModuleSecrets<string>;
+    /** True only when both halves resolved. */
+    configured: boolean;
+}
+/** The whole commerce module's gate, per provider. */
+export interface CommerceStatus {
+    /** True when the project has commerce configured AND every provider is live. */
+    configured: boolean;
+    /** True when the project declares no commerce at all — not the same as dormant. */
+    enabled: boolean;
+    providers: ProviderStatus[];
+    /** Every unprovisioned secret name across all providers, in declaration order. */
+    missing: string[];
+}
+/**
+ * Resolve the commerce module's dormancy from the runtime env.
+ *
+ * ```ts
+ * const status = await resolveCommerceStatus(config.commerce, env);
+ * const products = status.configured
+ *   ? await syncThenRead(env)          // live
+ *   : await readCatalog({ db: env.DB, table });  // whatever the mirror already holds
+ * ```
+ *
+ * Note what "dormant" means for commerce specifically: the D1 mirror is still
+ * readable, so an unprovisioned storefront serves the catalog it last synced
+ * (usually the seeded sample rows) rather than an error page. That is the whole
+ * reason the mirror exists as a separate layer from the provider client.
+ */
+export declare function resolveCommerceStatus(commerce: CommerceConfig | undefined, env: Record<string, SecretSource>): Promise<CommerceStatus>;