astroidjs 0.1.2 → 0.3.0

package/dist/commerce/checkout-scaffold.js

@@ -0,0 +1,306 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The checkout SEAM — the piece that made `archetype: "storefront"` a storefront
+// that couldn't take a card.
+//
+// Everything around this already existed: `verifyCheckout` re-prices server-side,
+// `checkoutIdempotencyKey` dedupes a double-clicked Pay button, the rate rule on
+// `/api/checkout` was in the middleware, `/checkout` and `/cart` were in the
+// noindex list, and the CSP already allowed Square's Web Payments hosts. What was
+// missing was the route in the middle, so none of it was reachable.
+//
+// SCOPE, deliberately narrow. This generates the server-authoritative PAYMENT
+// path and a card input — not a cart, not a checkout page, not shipping or tax.
+// Where a cart lives (localStorage, D1, a portal session), what it holds, and how
+// it renders are project decisions Astroid has no business making, and a
+// half-opinionated cart is worse than none. What is NOT a project decision is the
+// order of operations that keeps a charge correct, and that is what lives here.
+//
+// Square only, for now, and named rather than pretended-generic: Fourthwall
+// redirects to its own hosted checkout (no card token to charge) and Stripe has
+// no catalog API, so it fills the `invoicing` role rather than `storefront`.
+import { astroidCatalogMirror } from "./mirror.js";
+import { astroidCommerceRoles } from "./roles.js";
+/** Does this project take card payments in-page? Square storefront only. */
+export function usesCardCheckout(config) {
+    return astroidCommerceRoles(config.commerce).storefront === "square";
+}
+/**
+ * `src/pages/api/checkout.ts` — the server-authoritative payment route.
+ *
+ * Scaffold-once: a real store adds shipping, tax, an order record, a receipt
+ * email. What Astroid fixes is the sequence, because every step of it is a place
+ * where getting it wrong costs money rather than throwing an error.
+ *
+ * Returns null unless this project takes card payments.
+ */
+export function generateAstroidCheckoutRoute(config) {
+    if (!usesCardCheckout(config))
+        return null;
+    const { table } = astroidCatalogMirror(config);
+    return [
+        "// Server-authoritative checkout (POST /api/checkout).",
+        "//",
+        "// Scaffolded once and yours to extend — shipping, tax, an order row, a",
+        "// receipt email all belong here. What should NOT change is the ORDER of the",
+        "// steps below; each one is load-bearing:",
+        "//",
+        "//   1. Re-price every line from the D1 catalog mirror. The client's price is",
+        "//      a STALENESS CHECK, never an input to the charge. Accept `unitPrice`",
+        "//      from the request body and anyone can buy anything for a penny.",
+        "//   2. Refuse on mismatch rather than charging the server's number silently.",
+        "//      Being charged more than the page said is worse than being asked to",
+        "//      review the cart.",
+        "//   3. Derive the idempotency key from the verified cart AND the cart id, so",
+        "//      a double-clicked Pay button charges once while two customers buying",
+        "//      the same thing stay two charges.",
+        "//   4. Charge only when commerce is actually provisioned. With placeholder",
+        "//      secrets this simulates instead — it must never call Square with a",
+        "//      dummy credential.",
+        'import type { APIRoute } from "astro";',
+        'import { env } from "cloudflare:workers";',
+        "import {",
+        "  checkoutIdempotencyKey,",
+        "  readCatalog,",
+        "  resolveCommerceStatus,",
+        "  type SecretSource,",
+        "  verifyCheckout,",
+        "} from \"astroidjs\";",
+        'import { createPayment } from "louise-toolkit/commerce/square";',
+        'import { isSameOrigin } from "louise-toolkit/security";',
+        'import astroidConfig from "../../../astroid.config.js";',
+        "",
+        "export const prerender = false;",
+        "",
+        "/** Server-side prices, in minor units, straight from the catalog mirror. */",
+        "async function serverPrices(variantIds: string[]): Promise<Map<string, number>> {",
+        "  // `readCatalog` returns the product ARRAY (published only by default).",
+        "  const items = await readCatalog({",
+        "    db: env.DB,",
+        `    table: ${JSON.stringify(table)},`,
+        "  });",
+        "  const prices = new Map<string, number>();",
+        "  for (const item of items) {",
+        "    // The mirror stores MAJOR units (dollars); the charge is in minor units.",
+        "    // `Math.round` is not decoration — 19.99 * 100 is 1998.9999999999998, and",
+        "    // a float cent here fails the exact-equality staleness check on every",
+        "    // single checkout.",
+        "    if (variantIds.includes(item.externalId)) {",
+        "      prices.set(item.externalId, Math.round(item.price * 100));",
+        "    }",
+        "  }",
+        "  return prices;",
+        "}",
+        "",
+        "const json = (body: unknown, status = 200) =>",
+        "  new Response(JSON.stringify(body), {",
+        "    status,",
+        '    headers: { "content-type": "application/json" },',
+        "  });",
+        "",
+        "export const POST: APIRoute = async ({ request }) => {",
+        "  // Same-origin only. Checkout is the one public POST that moves money, so it",
+        "  // gets the CSRF gate every other public write already has (the contact form,",
+        "  // the vitals beacon): a cross-origin page must not be able to drive a charge",
+        "  // or probe prices, even though the card token itself is single-use. Requires",
+        "  // an Origin/Referer matching the host; a non-browser caller (a stripped",
+        "  // header) is refused. If you deliberately serve checkout from another origin,",
+        "  // this is the line to relax — it's yours.",
+        "  if (!isSameOrigin(request)) return json({ error: \"Forbidden\" }, 403);",
+        "",
+        "  const body = (await request.json().catch(() => null)) as {",
+        "    lines?: unknown;",
+        "    cartId?: unknown;",
+        "    sourceId?: unknown;",
+        "    verificationToken?: unknown;",
+        "    email?: unknown;",
+        "  } | null;",
+        "  if (!body) return json({ error: \"Invalid JSON\" }, 400);",
+        "",
+        "  // The cart id is the identity half of the idempotency key. It must be high",
+        "  // entropy and client-generated ONCE per cart (a v4 uuid in localStorage):",
+        "  // regenerate it per request and a double-click charges twice; make it",
+        "  // guessable and someone else's identical cart can dedupe into your charge.",
+        "  const cartId = typeof body.cartId === \"string\" ? body.cartId : \"\";",
+        "  if (!/^[0-9a-f-]{36}$/i.test(cartId)) {",
+        "    return json({ error: \"A uuid `cartId` is required\" }, 400);",
+        "  }",
+        "",
+        "  // 1 + 2: re-price and refuse on mismatch.",
+        "  const check = await verifyCheckout(body.lines, serverPrices);",
+        "  if (!check.ok) return json({ error: check.message, reason: check.reason }, 409);",
+        "",
+        "  // 3: stable per cart, distinct per customer.",
+        '  const idempotencyKey = await checkoutIdempotencyKey(check, "order", cartId);',
+        "",
+        "  // 4: dormant until provisioned. An unconfigured store still re-prices and",
+        "  // still refuses a stale cart — it just doesn't move money.",
+        "  // Cast as the toolkit's own `astroidModuleStatus` does: `readSecret`",
+        "  // accepts a plain string OR a Secrets Store binding, which CloudflareEnv",
+        "  // types more narrowly than the resolver's `SecretSource` map.",
+        "  const status = await resolveCommerceStatus(",
+        "    astroidConfig.commerce,",
+        "    env as unknown as Record<string, SecretSource>,",
+        "  );",
+        "  if (!status.configured) {",
+        "    console.info(",
+        '      `[astroid:commerce] simulated checkout — unprovisioned: ${status.missing.join(", ")}`,',
+        "    );",
+        "    return json({",
+        "      simulated: true,",
+        "      subtotalCents: check.subtotalCents,",
+        "      idempotencyKey,",
+        "    });",
+        "  }",
+        "",
+        "  const sourceId = typeof body.sourceId === \"string\" ? body.sourceId : \"\";",
+        '  if (!sourceId) return json({ error: "A card token (`sourceId`) is required" }, 400);',
+        "",
+        "  // Both are guaranteed real by the dormancy gate above; the narrowing here",
+        "  // is for the type system, which can't know that. `environment` is a UNION",
+        "  // (\"sandbox\" | \"production\"), not a free string — an unrecognised value",
+        "  // would otherwise silently select the sandbox host in production.",
+        '  const environment = env.SQUARE_ENVIRONMENT === "production" ? "production" : "sandbox";',
+        "  const payment = await createPayment(",
+        "    {",
+        '      accessToken: env.SQUARE_ACCESS_TOKEN ?? "",',
+        "      environment,",
+        "    },",
+        "    {",
+        "      sourceId,",
+        "      // The SERVER's number, never the client's.",
+        '      amountMoney: { amount: check.subtotalCents, currency: "USD" },',
+        '      locationId: env.SQUARE_LOCATION_ID ?? "",',
+        "      idempotencyKey,",
+        "      ...(typeof body.verificationToken === \"string\"",
+        "        ? { verificationToken: body.verificationToken }",
+        "        : {}),",
+        '      ...(typeof body.email === "string" ? { buyerEmailAddress: body.email } : {}),',
+        "    },",
+        "  );",
+        "",
+        "  // TODO(you): persist an order row, send a receipt, clear the cart.",
+        "  return json({",
+        "    paymentId: payment.id,",
+        "    status: payment.status,",
+        "    receiptUrl: payment.receiptUrl,",
+        "  });",
+        "};",
+        "",
+    ].join("\n");
+}
+/**
+ * `src/components/SquareCard.astro` — the card input.
+ *
+ * Square's Web Payments SDK renders the field in an iframe from their CDN and
+ * hands back a single-use token, so the raw card number never touches the Worker
+ * and the site stays out of PCI scope. That is the entire reason this is a
+ * component and not an `<input>`.
+ *
+ * Returns null unless this project takes card payments.
+ */
+export function generateAstroidSquareCard(config) {
+    if (!usesCardCheckout(config))
+        return null;
+    return [
+        "---",
+        "// Square Web Payments card input.",
+        "//",
+        "// The card field is an IFRAME served by Square's CDN — the raw number never",
+        "// enters this page's DOM and never reaches the Worker, which is what keeps the",
+        "// site out of PCI scope. `tokenize()` returns a single-use token; POST it to",
+        "// /api/checkout, which re-prices server-side before charging.",
+        "//",
+        "// The CSP already allows Square's hosts (astroidSecurity adds them when",
+        "// commerce is on), so no policy change is needed.",
+        'import { env } from "cloudflare:workers";',
+        "",
+        "// The PUBLIC application id — safe in the browser, unlike the access token.",
+        "// Absent (an unprovisioned store) → render nothing rather than a dead form.",
+        "const appId = env.SQUARE_APP_ID;",
+        "const locationId = env.SQUARE_LOCATION_ID;",
+        'const environment = env.SQUARE_ENVIRONMENT ?? "sandbox";',
+        "const ready = Boolean(appId && locationId);",
+        "---",
+        "",
+        "{",
+        "  ready ? (",
+        "    <div",
+        '      id="square-card-host"',
+        "      data-app-id={appId}",
+        "      data-location-id={locationId}",
+        "      data-environment={environment}",
+        "    >",
+        '      <div id="square-card" />',
+        "    </div>",
+        "  ) : (",
+        '    <p class="text-sm opacity-70">',
+        "      Card payments are not configured yet — set SQUARE_APP_ID and",
+        "      SQUARE_LOCATION_ID.",
+        "    </p>",
+        "  )",
+        "}",
+        "",
+        "{/* Processed (NOT is:inline) so Astro's security.csp hashes it into",
+        "    script-src. Per-request values ride on the host element's data-* rather",
+        "    than a define:vars script, which could not be hashed. */}",
+        "<script>",
+        '  import { mountCard } from "louise-toolkit/commerce/square-web";',
+        "",
+        '  const host = document.getElementById("square-card-host");',
+        "  if (host) {",
+        "    mountCard(",
+        '      host.dataset.appId ?? "",',
+        '      host.dataset.locationId ?? "",',
+        '      host.dataset.environment ?? "sandbox",',
+        '      "#square-card",',
+        "    )",
+        "      .then((card) => {",
+        "        // Expose the handle so your checkout form can tokenize on submit:",
+        "        //   const token = await window.__squareCard.tokenize();",
+        "        // then POST { lines, cartId, sourceId: token } to /api/checkout.",
+        "        (window as unknown as { __squareCard?: unknown }).__squareCard = card;",
+        '        host.dispatchEvent(new CustomEvent("square-card-ready", { bubbles: true }));',
+        "      })",
+        "      .catch((err) => {",
+        '        console.error("[astroid:commerce] card input failed to mount", err);',
+        "      });",
+        "  }",
+        "</script>",
+        "",
+    ].join("\n");
+}
+/**
+ * The wrangler `vars` the card input needs, or `[]`.
+ *
+ * PUBLIC values, so they are vars rather than entries in the secret roster: the
+ * application id is shipped to the browser by design, and the environment is a
+ * choice, not a credential. Putting them in `credentials` would also fold them
+ * into the dormancy gate, which is about whether the module can safely CALL
+ * Square — a different question from whether the card field can render.
+ */
+export function astroidCheckoutVars(config) {
+    if (!usesCardCheckout(config))
+        return [];
+    return [
+        // Public app id from the Square dashboard (Developer → Credentials).
+        { name: "SQUARE_APP_ID", value: "" },
+        // "sandbox" until you have tested a real card end to end.
+        { name: "SQUARE_ENVIRONMENT", value: "sandbox" },
+    ];
+}
+/**
+ * The `CloudflareEnv` members the card input adds, as a block `create-astroid`
+ * substitutes into `src/env.d.ts`. Empty without card checkout.
+ */
+export function generateAstroidCheckoutEnv(config) {
+    if (!usesCardCheckout(config))
+        return "";
+    return [
+        "  /** Square's PUBLIC application id — shipped to the browser to mount the",
+        "   *  Web Payments card field. Not a secret; see wrangler.jsonc `vars`. */",
+        "  SQUARE_APP_ID: string;",
+        '  /** Square API environment: "sandbox" or "production". */',
+        "  SQUARE_ENVIRONMENT: string;",
+    ].join("\n");
+}

package/dist/commerce/checkout.d.ts

@@ -0,0 +1,72 @@
+/** One line as the CLIENT sent it. Every field is untrusted. */
+export interface ClientLine {
+    /** Provider id of the variant/item being bought. */
+    variantId: string;
+    quantity: number;
+    /**
+     * The unit price, in minor units, that the customer was SHOWN. Compared
+     * against the server's price; never used to compute the charge.
+     */
+    unitPriceCents: number;
+}
+/** A line after the server has re-priced it. */
+export interface VerifiedLine {
+    variantId: string;
+    quantity: number;
+    /** The server's price. This is what gets charged. */
+    unitPriceCents: number;
+    subtotalCents: number;
+}
+export type CheckoutVerification = {
+    ok: true;
+    lines: VerifiedLine[];
+    subtotalCents: number;
+} | {
+    ok: false;
+    reason: "empty" | "unavailable" | "price-changed" | "invalid";
+    message: string;
+};
+/** Look up current prices, in minor units, keyed by variant id. Anything the
+ *  map omits is treated as no longer purchasable. */
+export type PriceLookup = (variantIds: string[]) => Promise<Map<string, number>>;
+/**
+ * Re-price a cart against the provider and decide whether it may proceed.
+ *
+ * ```ts
+ * const check = await verifyCheckout(body.lines, (ids) => serverPrices(env, ids));
+ * if (!check.ok) return json({ error: check.message }, 409);
+ * await charge(check.subtotalCents);   // the SERVER's number
+ * ```
+ */
+export declare function verifyCheckout(lines: unknown, lookup: PriceLookup): Promise<CheckoutVerification>;
+/**
+ * A deterministic idempotency key for one buyer's checkout attempt.
+ *
+ * Providers dedupe on this, so the same key must mean the same charge — which
+ * cuts both ways, and the second direction is the one that costs money. It is
+ * derived from the verified cart *and* `identity`, not from a random value or a
+ * timestamp: a customer double-clicking Pay sends the same key twice and is
+ * charged once, while a customer who changes their cart pays under a different
+ * key and is charged correctly.
+ *
+ * **`identity` is required, and it is what makes the key safe.** Without it the
+ * key was a pure function of the cart contents, so two DIFFERENT customers
+ * buying the same thing for the same price produced byte-identical keys. Stripe
+ * and Square scope idempotency keys per account and retain them for ~24h, so the
+ * provider replayed the first customer's PaymentIntent instead of creating the
+ * second's: the second buyer was never charged, no second order existed, and the
+ * site reported success. On a single-SKU storefront that is ordinary traffic,
+ * not an edge case.
+ *
+ * Pass something stable across a retry of THIS attempt and distinct between
+ * buyers — a cart id, a checkout-session id, or a portal user id. Do not pass a
+ * value that varies per request (a fresh uuid defeats the dedupe and a
+ * double-click charges twice), and do not pass a constant.
+ *
+ * `scope` remains the OPERATION — `"order"` vs `"refund"` — so the two can never
+ * collide for one buyer. It is not an identity and never was.
+ */
+export declare function checkoutIdempotencyKey(verified: {
+    lines: VerifiedLine[];
+    subtotalCents: number;
+}, scope: string, identity: string): Promise<string>;

package/dist/commerce/checkout.js

@@ -0,0 +1,124 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// Server-authoritative checkout.
+//
+// A cart arrives from the browser, so every number in it is a claim, not a fact.
+// The rule this encodes — taken from coracle.coffee's working checkout — is that
+// the client's price is a **staleness check**, never an input to the charge:
+// look the price up server-side, and if it disagrees with what the customer was
+// shown, refuse rather than silently charging a different amount. Refusing is
+// the customer-friendly branch too; being charged more than the page said is
+// worse than being asked to review the cart.
+//
+// The failure this prevents is not exotic. Accept `unitPrice` from the request
+// body and anyone can buy anything for a penny.
+import { AstroidUsageError } from "../errors.js";
+const MAX_QUANTITY = 999;
+/**
+ * Re-price a cart against the provider and decide whether it may proceed.
+ *
+ * ```ts
+ * const check = await verifyCheckout(body.lines, (ids) => serverPrices(env, ids));
+ * if (!check.ok) return json({ error: check.message }, 409);
+ * await charge(check.subtotalCents);   // the SERVER's number
+ * ```
+ */
+export async function verifyCheckout(lines, lookup) {
+    if (!Array.isArray(lines) || lines.length === 0) {
+        return { ok: false, reason: "empty", message: "Your cart is empty." };
+    }
+    const parsed = [];
+    for (const raw of lines) {
+        const l = raw;
+        // A non-integer or negative quantity is the other half of the price
+        // exploit: a quantity of -1 turns a charge into a refund on some providers.
+        if (typeof l?.variantId !== "string" ||
+            !l.variantId ||
+            typeof l.quantity !== "number" ||
+            !Number.isInteger(l.quantity) ||
+            l.quantity < 1 ||
+            l.quantity > MAX_QUANTITY ||
+            typeof l.unitPriceCents !== "number" ||
+            !Number.isFinite(l.unitPriceCents)) {
+            return { ok: false, reason: "invalid", message: "That cart isn't valid." };
+        }
+        parsed.push({ variantId: l.variantId, quantity: l.quantity, unitPriceCents: l.unitPriceCents });
+    }
+    const prices = await lookup([...new Set(parsed.map((l) => l.variantId))]);
+    const verified = [];
+    let subtotalCents = 0;
+    for (const line of parsed) {
+        const serverPrice = prices.get(line.variantId);
+        if (serverPrice === undefined) {
+            return {
+                ok: false,
+                reason: "unavailable",
+                message: "An item in your cart is no longer available.",
+            };
+        }
+        if (serverPrice !== line.unitPriceCents) {
+            return {
+                ok: false,
+                reason: "price-changed",
+                message: "Prices changed — please review your cart.",
+            };
+        }
+        const lineSubtotal = serverPrice * line.quantity;
+        verified.push({
+            variantId: line.variantId,
+            quantity: line.quantity,
+            unitPriceCents: serverPrice,
+            subtotalCents: lineSubtotal,
+        });
+        subtotalCents += lineSubtotal;
+    }
+    return { ok: true, lines: verified, subtotalCents };
+}
+/**
+ * A deterministic idempotency key for one buyer's checkout attempt.
+ *
+ * Providers dedupe on this, so the same key must mean the same charge — which
+ * cuts both ways, and the second direction is the one that costs money. It is
+ * derived from the verified cart *and* `identity`, not from a random value or a
+ * timestamp: a customer double-clicking Pay sends the same key twice and is
+ * charged once, while a customer who changes their cart pays under a different
+ * key and is charged correctly.
+ *
+ * **`identity` is required, and it is what makes the key safe.** Without it the
+ * key was a pure function of the cart contents, so two DIFFERENT customers
+ * buying the same thing for the same price produced byte-identical keys. Stripe
+ * and Square scope idempotency keys per account and retain them for ~24h, so the
+ * provider replayed the first customer's PaymentIntent instead of creating the
+ * second's: the second buyer was never charged, no second order existed, and the
+ * site reported success. On a single-SKU storefront that is ordinary traffic,
+ * not an edge case.
+ *
+ * Pass something stable across a retry of THIS attempt and distinct between
+ * buyers — a cart id, a checkout-session id, or a portal user id. Do not pass a
+ * value that varies per request (a fresh uuid defeats the dedupe and a
+ * double-click charges twice), and do not pass a constant.
+ *
+ * `scope` remains the OPERATION — `"order"` vs `"refund"` — so the two can never
+ * collide for one buyer. It is not an identity and never was.
+ */
+export async function checkoutIdempotencyKey(verified, scope, identity) {
+    // Empty is rejected rather than defaulted: a falsy identity would silently
+    // restore the collision this parameter exists to close, and a charge that
+    // goes missing is not something the caller finds out about.
+    if (typeof identity !== "string" || identity.trim().length === 0) {
+        throw new AstroidUsageError("checkoutIdempotencyKey requires a non-empty `identity` (a cart id, checkout-session id, " +
+            "or user id). Without it the key is a function of the cart alone, so two customers " +
+            "buying the same items collide and the second is never charged.");
+    }
+    const canonical = JSON.stringify({
+        scope,
+        identity,
+        total: verified.subtotalCents,
+        lines: verified.lines.map((l) => `${l.variantId}:${l.quantity}:${l.unitPriceCents}`).sort(),
+    });
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonical));
+    return [...new Uint8Array(digest)]
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("")
+        .slice(0, 40);
+}

package/dist/commerce/index.d.ts

@@ -0,0 +1,8 @@
+export { catalogNormalizer, type FourthwallProductLike, fourthwallToCatalogItem, type SquareItemLike, squareToCatalogItem, } from "./adapters.js";
+export { type CheckoutVerification, checkoutIdempotencyKey, type ClientLine, type PriceLookup, verifyCheckout, type VerifiedLine, } from "./checkout.js";
+export { astroidCatalogLoaderConfig, type CatalogDatabase, type CatalogProduct, type CatalogReadOptions, readCatalog, readCatalogItem, } from "./loader.js";
+export { astroidCatalogMirror, BUILT_IN_OWNED, type CatalogMirrorConfig, generateCatalogMigrationSql, generateCatalogTable, type OwnedColumn, PULLED_COLUMNS, } from "./mirror.js";
+export { COMMERCE_PROVIDER_SECRETS, type CommerceStatus, commerceSecretNames, type ProviderStatus, resolveCommerceStatus, } from "./secrets.js";
+export { assertCommerceRoles, astroidCommerceProviders, astroidCommerceRoles, type CommerceRole, hasStorefront, PROVIDER_ROLES, type ResolvedCommerceRoles, } from "./roles.js";
+export { astroidCatalogSync, astroidCatalogUpsert, type CatalogItem, type CatalogSyncOptions, type CatalogSyncResult, defaultSlug, type SyncDatabase, } from "./sync.js";
+export { astroidCheckoutVars, generateAstroidCheckoutEnv, generateAstroidCheckoutRoute, generateAstroidSquareCard, usesCardCheckout, } from "./checkout-scaffold.js";

package/dist/commerce/index.js

@@ -0,0 +1,9 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+export { catalogNormalizer, fourthwallToCatalogItem, squareToCatalogItem, } from "./adapters.js";
+export { checkoutIdempotencyKey, verifyCheckout, } from "./checkout.js";
+export { astroidCatalogLoaderConfig, readCatalog, readCatalogItem, } from "./loader.js";
+export { astroidCatalogMirror, BUILT_IN_OWNED, generateCatalogMigrationSql, generateCatalogTable, PULLED_COLUMNS, } from "./mirror.js";
+export { COMMERCE_PROVIDER_SECRETS, commerceSecretNames, resolveCommerceStatus, } from "./secrets.js";
+export { assertCommerceRoles, astroidCommerceProviders, astroidCommerceRoles, hasStorefront, PROVIDER_ROLES, } from "./roles.js";
+export { astroidCatalogSync, astroidCatalogUpsert, defaultSlug, } from "./sync.js";
+export { astroidCheckoutVars, generateAstroidCheckoutEnv, generateAstroidCheckoutRoute, generateAstroidSquareCard, usesCardCheckout, } from "./checkout-scaffold.js";

package/dist/commerce/loader.d.ts

@@ -0,0 +1,71 @@
+import type { CatalogItem } from "./sync.js";
+/** A product as the site renders it: the mirror row, decoded. */
+export interface CatalogProduct extends CatalogItem {
+    /** Public URL segment — owner-owned, stable across provider renames. */
+    slug: string;
+    status: "draft" | "published";
+    sortOrder: number;
+    featured: boolean;
+    /** Owned columns this project added, passed through untyped. */
+    [key: string]: unknown;
+}
+/** The D1 surface the read needs. Structural, so a real `D1Database` fits. */
+export interface CatalogDatabase {
+    prepare(query: string): {
+        bind(...values: unknown[]): {
+            first<T = Record<string, unknown>>(): Promise<T | null>;
+            all<T = Record<string, unknown>>(): Promise<{
+                results: T[];
+            }>;
+        };
+        all<T = Record<string, unknown>>(): Promise<{
+            results: T[];
+        }>;
+    };
+}
+export interface CatalogReadOptions {
+    db: CatalogDatabase;
+    table: string;
+    /**
+     * Include `draft` rows. Off by default: new remote items land as draft
+     * precisely so they don't appear until someone approves them, and a read that
+     * ignored that would undo the point of the status column. Turn it on for the
+     * editor's own views.
+     */
+    includeDrafts?: boolean;
+}
+/**
+ * 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 declare function readCatalog(options: CatalogReadOptions): Promise<CatalogProduct[]>;
+/** Read one product by its public slug. Null when absent or still a draft. */
+export declare function readCatalogItem(slug: string, options: CatalogReadOptions): Promise<CatalogProduct | 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 declare function astroidCatalogLoaderConfig(options: CatalogReadOptions & {
+    name?: string;
+}): {
+    name: string;
+    loadCatalog: (filter?: {
+        featured?: boolean;
+    }) => Promise<{
+        items: CatalogProduct[];
+    }>;
+    loadItem: (id: string) => Promise<CatalogProduct | null>;
+    idOf: (item: CatalogProduct) => string;
+};