astroidjs 0.1.2 → 0.3.0

package/dist/project/scaffold.js

@@ -0,0 +1,166 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// Every SCAFFOLD-ONCE file a config implies, in one list.
+//
+// This exists because the split between "generated" and "scaffolded" was drawn
+// in the wrong place. `generateAstroidProject` returns the regenerated trio, and
+// that trio emits STATIC IMPORTS of scaffold-once modules:
+//
+//   src/worker.ts      → import { handleQueueMessage } from "./queue.js"
+//   src/middleware.ts  → import { resolvePortalUser } from "./portal-auth.js"
+//
+// The files behind those imports were written in exactly one place —
+// `create-astroid`'s CLI — and nothing else could produce them. So turning a
+// module on AFTER scaffold, by editing the one typed config the framework is
+// built around, regenerated a trio importing files that did not exist. `astroid
+// doctor` reported "healthy" and the project failed in Vite.
+//
+// Aggregating them here makes `astroid generate` able to complete a config
+// change, `astroid doctor` able to notice one it hasn't, and `create-astroid`
+// stop hand-listing the same nine files a third time.
+//
+// SCAFFOLD-ONCE means what it says: every file here is written only when ABSENT.
+// Each one exists to be edited (what a catalog refresh means, which events
+// matter, what a reset email says), so regenerating over it would destroy the
+// work the seam exists to hold.
+import { generateAstroidCheckoutRoute, generateAstroidSquareCard, } from "../commerce/checkout-scaffold.js";
+import { generateCatalogMigrationSql } from "../commerce/mirror.js";
+import { generateAstroidVitalsBeacon } from "../analytics/index.js";
+import { generateAstroidActions } from "./actions.js";
+import { cwvBeaconScript } from "louise-toolkit/analytics";
+import { generateMapEmbedComponent, generateMapTileRoute } from "../map/scaffold.js";
+import { generateAstroidGalleryPage } from "../portfolio/scaffold.js";
+import { astroidPortal } from "../portal/config.js";
+import { generateAstroidPortalAuth, generateAstroidPortalAuthRoute } from "../portal/scaffold.js";
+import { generateAstroidEditSession } from "../realtime/scaffold.js";
+import { generatePwaHeaders, generateServiceWorker, generateWebManifest } from "../pwa/generate.js";
+import { astroidUsesQueues } from "../queues/messages.js";
+import { generateAstroidQueueSeam, generateAstroidWebhookRoutes } from "../queues/scaffold.js";
+/**
+ * Every scaffold-once file this config implies.
+ *
+ * Ordered by module so a `generate` that writes several prints them in a stable
+ * sequence. Returns `[]` for a plain marketing site with no modules — the
+ * baseline floor is entirely the regenerated trio plus the static template.
+ */
+export function generateAstroidScaffoldFiles(config) {
+    const files = [];
+    // --- commerce: the catalog table's migration ------------------------------
+    // Numbered 0003 so it lands after the template's 0000_content and the auth
+    // pair (0001, 0002) that `create-astroid` writes. Without it `--commerce`
+    // scaffolded a `products` table into src/schema.ts that no migration ever
+    // created, and the first sync wrote nothing while reporting success.
+    const catalogSql = generateCatalogMigrationSql(config);
+    if (catalogSql)
+        files.push({ path: "migrations/0003_catalog.sql", contents: catalogSql });
+    // --- the CWV beacon -------------------------------------------------------
+    // A static file under public/, so it is same-origin and covered by
+    // `script-src 'self'` — an inline script carrying generated content could not
+    // be hashed into the CSP and would be blocked.
+    const beacon = generateAstroidVitalsBeacon(config, cwvBeaconScript());
+    files.push({ path: beacon.path, contents: beacon.contents });
+    // --- site-owned schema tables --------------------------------------------
+    // Always: the generated src/schema.ts re-exports `./schema.site.js`, so the
+    // file must exist even when empty. A project declares tables Astroid doesn't
+    // manage here (an existing overlay predating Astroid, a redirects map, a
+    // customer address book) and they flow to drizzle-kit + the worker for free.
+    files.push({
+        path: "src/schema.site.ts",
+        contents: [
+            "// Site-owned Drizzle tables — the ones Astroid doesn't manage. Declare them",
+            "// here; the generated src/schema.ts re-exports everything from this file, so",
+            "// drizzle-kit sees them and the worker can import them. Empty by default.",
+            "//",
+            "// e.g.  export const redirects = sqliteTable(\"redirects\", { … });",
+            "export {};",
+            "",
+        ].join("\n"),
+    });
+    // --- the typed Astro Actions surface --------------------------------------
+    // Always: every project has editable pages, and the routes alone leave the
+    // Astro-native half of ADR 0001 unbuilt. Scaffold-once because it is meant to
+    // be added to.
+    files.push({ path: "src/actions/index.ts", contents: generateAstroidActions(config) });
+    // --- commerce: the server-authoritative payment seam ----------------------
+    // Scaffold-once: a real store adds shipping, tax, an order row, a receipt.
+    // What's fixed is the sequence that keeps a charge correct.
+    const checkoutRoute = generateAstroidCheckoutRoute(config);
+    if (checkoutRoute)
+        files.push({ path: "src/pages/api/checkout.ts", contents: checkoutRoute });
+    const squareCard = generateAstroidSquareCard(config);
+    if (squareCard)
+        files.push({ path: "src/components/SquareCard.astro", contents: squareCard });
+    // --- queues: the consumer seam + one receiver per commerce provider --------
+    // Both exist to be edited (what a refresh means; which events matter), which
+    // is why `astroid generate` must never rewrite them.
+    if (astroidUsesQueues(config)) {
+        files.push({ path: "src/queue.ts", contents: generateAstroidQueueSeam(config) });
+        // One receiver per provider — a site can run two (invoicing + storefront).
+        for (const route of generateAstroidWebhookRoutes(config)) {
+            files.push({ path: route.path, contents: route.contents });
+        }
+    }
+    // --- portfolio: the gallery page -----------------------------------------
+    // "Which assets appear, in what order" is the first thing a portfolio changes.
+    const gallery = generateAstroidGalleryPage(config);
+    if (gallery)
+        files.push({ path: "src/pages/work.astro", contents: gallery });
+    // --- pwa: the service worker, manifest, and its headers -------------------
+    // Static files under public/, not generated source — a service worker is not
+    // bundled, and `_headers` is shared with whatever else writes to it.
+    const sw = generateServiceWorker(config);
+    if (sw) {
+        files.push({ path: "public/sw.js", contents: sw });
+        const manifest = generateWebManifest(config);
+        if (manifest)
+            files.push({ path: "public/manifest.webmanifest", contents: manifest });
+        const headers = generatePwaHeaders(config);
+        if (headers) {
+            files.push({
+                path: "public/_headers",
+                contents: headers,
+                apply: "append-once",
+                // The service-worker path is the one token this stanza always contains
+                // and nothing else in a `_headers` file would.
+                marker: "/sw.js",
+            });
+        }
+    }
+    // --- map: the tile route + embed component --------------------------------
+    // Generated into the project rather than shipped in astroidjs so maplibre-gl
+    // stays a dependency of the projects that actually draw a map.
+    const tileRoute = generateMapTileRoute(config);
+    if (tileRoute)
+        files.push({ path: "src/pages/map/basemap.pmtiles.ts", contents: tileRoute });
+    const mapEmbed = generateMapEmbedComponent(config);
+    if (mapEmbed)
+        files.push({ path: "src/components/MapEmbed.astro", contents: mapEmbed });
+    // --- realtime: the per-page edit-session Durable Object -------------------
+    // Scaffold-once because it must import `cloudflare:workers` (runtime-only) and
+    // because `persist` is the seam a project tunes.
+    const editSession = generateAstroidEditSession(config);
+    if (editSession)
+        files.push({ path: "src/edit-session.ts", contents: editSession });
+    // --- portal: the second auth instance + its mounted catch-all -------------
+    // A site edits the reset email and the role a new account gets, but not the
+    // mount/cookie/table prefixes that keep the two instances isolated.
+    const portalAuth = generateAstroidPortalAuth(config);
+    if (portalAuth) {
+        files.push({ path: "src/portal-auth.ts", contents: portalAuth });
+        const route = generateAstroidPortalAuthRoute(config);
+        // Always non-null alongside portalAuth (same `astroidPortal` gate), but the
+        // types don't know that and a silent drop here is a portal that cannot
+        // authenticate — so assert it rather than `?.`-ing it away.
+        //
+        // The route file lives at the mount path, because Astro routing is
+        // file-path-based: a portal mounted at `/api/shop-auth` needs its catch-all
+        // at `src/pages/api/shop-auth/[...all].ts`, not the default `/api/portal-auth`.
+        // Derive it from the resolved basePath so a configured mount and its route
+        // can't drift.
+        const portal = astroidPortal(config);
+        if (route) {
+            files.push({ path: `src/pages${portal.basePath}/[...all].ts`, contents: route });
+        }
+    }
+    return files;
+}

package/dist/pwa/generate.d.ts

@@ -0,0 +1,49 @@
+import type { AstroidConfig } from "../config.js";
+/** Tuning for the PWA scaffold. Every field has a sensible derivation. */
+export interface PwaConfig {
+    /**
+     * URL prefix the app is installed at. Default `"/"`.
+     *
+     * A narrower scope (`"/order"`) is usually right: it keeps the worker off the
+     * marketing pages entirely, which is both safer and a smaller cache.
+     */
+    scope?: string;
+    /** Home screen name. Defaults to the brand name. */
+    shortName?: string;
+    description?: string;
+    /** `standalone` (default) hides browser chrome; `browser` opts out of it. */
+    display?: "standalone" | "minimal-ui" | "fullscreen" | "browser";
+    orientation?: "any" | "portrait" | "landscape";
+    /** Splash background. Defaults to white. */
+    backgroundColor?: string;
+    /** Theme colour. Defaults to the brand colour. */
+    themeColor?: string;
+    /** Extra paths to precache alongside the scope root. */
+    shell?: string[];
+}
+/** True when this project switched the PWA on. */
+export declare const usesPwa: (config: AstroidConfig) => boolean;
+/** Resolved PWA settings — config over derivation over default. */
+export declare function resolvePwa(config: AstroidConfig): Required<Omit<PwaConfig, "shell">> & {
+    shell: string[];
+};
+/**
+ * `public/manifest.webmanifest`.
+ *
+ * Icons are declared but NOT generated — a brand's icon is not something a
+ * scaffold can invent, and emitting placeholders would produce an installable
+ * app with a grey square for a face. The generated README step says to add them.
+ */
+export declare function generateWebManifest(config: AstroidConfig): string | null;
+/** `public/sw.js`. Plain JS — a service worker is not bundled. */
+export declare function generateServiceWorker(config: AstroidConfig): string | null;
+/**
+ * The `public/_headers` block the PWA needs.
+ *
+ * `Service-Worker-Allowed` is emitted ONLY when the scope is broader than the
+ * script's own location — which, with `sw.js` at the root, never is. Emitting it
+ * unconditionally (as the reference does) is harmless but misleading: it implies
+ * a requirement that isn't there, and someone later moving the script will trust
+ * a header that no longer says what they need.
+ */
+export declare function generatePwaHeaders(config: AstroidConfig): string | null;

package/dist/pwa/generate.js

@@ -0,0 +1,218 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The PWA scaffold — a scoped service worker, a manifest, and the headers they
+// need.
+//
+// The scoping is the whole design, not a detail. A Louise site is CMS-edited:
+// an editor signs in, flips edit mode on, and edits the live page in place. A
+// service worker that cached HTML across the whole origin would serve that
+// editor a stale copy of the page they are trying to change — and the bug would
+// present as "my edits don't save", which is about as far from the cause as a
+// report can get.
+//
+// So the generated worker is scoped, and inside its scope it still refuses to
+// touch anything dynamic:
+//
+//   • `/api/*`        never cached — checkout, auth, and every Louise write
+//   • editor routes   never cached — the studio must always be live
+//   • edit-mode URLs  never cached — `?louise` marks a request as an editing
+//                     session, and caching one poisons it for everyone
+//
+// Everything else is the ordinary split: navigations network-first with a
+// cached offline shell, hashed assets cache-first because their names change
+// when their content does.
+/** True when this project switched the PWA on. */
+export const usesPwa = (config) => (config.modules ?? []).includes("pwa");
+/** Resolved PWA settings — config over derivation over default. */
+export function resolvePwa(config) {
+    const pwa = config.pwa ?? {};
+    // Normalized to a leading slash and no trailing one (except root), because
+    // scope comparison is a string prefix test and "/order/" vs "/order" would
+    // silently exclude the scope root itself.
+    const raw = pwa.scope ?? "/";
+    const scope = raw === "/" ? "/" : `/${raw.replace(/^\/+|\/+$/g, "")}`;
+    return {
+        scope,
+        shortName: pwa.shortName ?? config.theme.name,
+        description: pwa.description ?? `${config.theme.name} — installable app.`,
+        display: pwa.display ?? "standalone",
+        orientation: pwa.orientation ?? "any",
+        backgroundColor: pwa.backgroundColor ?? "#ffffff",
+        themeColor: pwa.themeColor ?? config.theme.colors.brand,
+        shell: [scope, "/manifest.webmanifest", ...(pwa.shell ?? [])],
+    };
+}
+/**
+ * `public/manifest.webmanifest`.
+ *
+ * Icons are declared but NOT generated — a brand's icon is not something a
+ * scaffold can invent, and emitting placeholders would produce an installable
+ * app with a grey square for a face. The generated README step says to add them.
+ */
+export function generateWebManifest(config) {
+    if (!usesPwa(config))
+        return null;
+    const pwa = resolvePwa(config);
+    return `${JSON.stringify({
+        name: config.theme.name,
+        short_name: pwa.shortName,
+        description: pwa.description,
+        id: pwa.scope,
+        start_url: pwa.scope,
+        scope: pwa.scope,
+        display: pwa.display,
+        orientation: pwa.orientation,
+        background_color: pwa.backgroundColor,
+        theme_color: pwa.themeColor,
+        icons: [
+            { src: "/icons/icon-192.png", sizes: "192x192", type: "image/png", purpose: "any" },
+            { src: "/icons/icon-512.png", sizes: "512x512", type: "image/png", purpose: "any" },
+            // A maskable icon is a separate asset, not a flag on the same file: the
+            // platform crops it to its own shape, so the artwork needs padding the
+            // `any` icon shouldn't have.
+            { src: "/icons/maskable-192.png", sizes: "192x192", type: "image/png", purpose: "maskable" },
+            { src: "/icons/maskable-512.png", sizes: "512x512", type: "image/png", purpose: "maskable" },
+        ],
+    }, null, 2)}\n`;
+}
+/** `public/sw.js`. Plain JS — a service worker is not bundled. */
+export function generateServiceWorker(config) {
+    if (!usesPwa(config))
+        return null;
+    const pwa = resolvePwa(config);
+    // Cache name carries the project key so two Astroid apps on one origin (a
+    // preview deploy, say) can't read each other's entries.
+    const cacheName = `${config.key}-pwa-v1`;
+    return [
+        `// Service worker for the ${config.theme.name} PWA, scoped to ${pwa.scope}.`,
+        "//",
+        "// Generated by Astroid. Safe to edit — bump CACHE to invalidate everything",
+        "// on the next visit.",
+        "//",
+        "// What it deliberately never caches, and why:",
+        "//   /api/*        checkout, auth, and every Louise write — a cached POST",
+        "//                 response or a stale session is worse than being offline",
+        "//   editor routes the studio must always be live",
+        "//   ?louise URLs  an edit-mode request; caching one would serve an editor a",
+        "//                 stale copy of the page they're editing, and the bug would",
+        "//                 present as 'my changes don't save'",
+        `const CACHE = ${JSON.stringify(cacheName)};`,
+        `const SCOPE = ${JSON.stringify(pwa.scope)};`,
+        `const SHELL = ${JSON.stringify([...new Set(pwa.shell)])};`,
+        "",
+        "self.addEventListener('install', (event) => {",
+        "  event.waitUntil(",
+        "    caches",
+        "      .open(CACHE)",
+        "      // Best-effort: one 404 or redirect in the shell must not fail the",
+        "      // whole install and leave the app without a worker.",
+        "      .then((c) => Promise.allSettled(SHELL.map((u) => c.add(u))))",
+        "      .then(() => self.skipWaiting()),",
+        "  );",
+        "});",
+        "",
+        "self.addEventListener('activate', (event) => {",
+        "  event.waitUntil(",
+        "    caches",
+        "      .keys()",
+        "      .then((keys) => Promise.all(keys.filter((k) => k !== CACHE).map((k) => caches.delete(k))))",
+        "      .then(() => self.clients.claim()),",
+        "  );",
+        "});",
+        "",
+        "/** Requests that must always hit the network. */",
+        "function isDynamic(url) {",
+        "  return (",
+        "    url.pathname.startsWith('/api/') ||",
+        "    url.pathname.startsWith('/login') ||",
+        "    url.pathname.startsWith('/admin') ||",
+        "    // Louise's edit mode. `has()` rather than a value check: `?louise` with",
+        "    // no value is the usual form.",
+        "    url.searchParams.has('louise')",
+        "  );",
+        "}",
+        "",
+        "/** Hashed build output — the filename changes when the content does, so it",
+        " *  can be cached forever without a staleness risk. */",
+        "function isImmutable(url) {",
+        "  return url.pathname.startsWith('/_astro/') || url.pathname.startsWith('/icons/');",
+        "}",
+        "",
+        "self.addEventListener('fetch', (event) => {",
+        "  const req = event.request;",
+        "  // Only GET: a cached POST response would be a correctness bug, not a",
+        "  // speedup.",
+        "  if (req.method !== 'GET') return;",
+        "",
+        "  const url = new URL(req.url);",
+        "  // Cross-origin requests belong to whoever serves them.",
+        "  if (url.origin !== self.location.origin) return;",
+        "  if (isDynamic(url)) return;",
+        "  // Outside the scope this worker has no business intercepting — the rest of",
+        "  // the site is CMS-edited and must stay live.",
+        "  if (SCOPE !== '/' && !url.pathname.startsWith(SCOPE)) return;",
+        "",
+        "  if (req.mode === 'navigate') {",
+        "    // Network-first: a page is only worth serving from cache when the network",
+        "    // failed, since the content behind it changes.",
+        "    event.respondWith(",
+        "      fetch(req)",
+        "        .then((res) => {",
+        "          const copy = res.clone();",
+        "          caches",
+        "            .open(CACHE)",
+        "            .then((c) => c.put(req, copy))",
+        "            .catch(() => {});",
+        "          return res;",
+        "        })",
+        "        .catch(() => caches.match(req).then((r) => r || caches.match(SCOPE))),",
+        "    );",
+        "    return;",
+        "  }",
+        "",
+        "  if (isImmutable(url)) {",
+        "    event.respondWith(",
+        "      caches.match(req).then(",
+        "        (cached) =>",
+        "          cached ||",
+        "          fetch(req).then((res) => {",
+        "            const copy = res.clone();",
+        "            caches",
+        "              .open(CACHE)",
+        "              .then((c) => c.put(req, copy))",
+        "              .catch(() => {});",
+        "            return res;",
+        "          }),",
+        "      ),",
+        "    );",
+        "  }",
+        "  // Everything else falls through to the browser's own handling.",
+        "});",
+        "",
+    ].join("\n");
+}
+/**
+ * The `public/_headers` block the PWA needs.
+ *
+ * `Service-Worker-Allowed` is emitted ONLY when the scope is broader than the
+ * script's own location — which, with `sw.js` at the root, never is. Emitting it
+ * unconditionally (as the reference does) is harmless but misleading: it implies
+ * a requirement that isn't there, and someone later moving the script will trust
+ * a header that no longer says what they need.
+ */
+export function generatePwaHeaders(config) {
+    if (!usesPwa(config))
+        return null;
+    return [
+        "",
+        "# The service worker must revalidate on every load, or a bad worker sticks",
+        "# around until its cache entry expires — and it controls every page in scope.",
+        "/sw.js",
+        "  Cache-Control: no-cache",
+        "",
+        "/manifest.webmanifest",
+        "  Content-Type: application/manifest+json",
+        "  Cache-Control: public, max-age=3600",
+        "",
+    ].join("\n");
+}

package/dist/pwa/index.d.ts

@@ -0,0 +1 @@
+export { generatePwaHeaders, generateServiceWorker, generateWebManifest, type PwaConfig, resolvePwa, usesPwa, } from "./generate.js";

package/dist/pwa/index.js

@@ -0,0 +1,2 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+export { generatePwaHeaders, generateServiceWorker, generateWebManifest, resolvePwa, usesPwa, } from "./generate.js";

package/dist/queues/consumer.d.ts

@@ -0,0 +1,29 @@
+import { type AstroidQueueMessage } from "./messages.js";
+export interface QueueHandlerOptions {
+    /**
+     * Re-sync whatever the provider owns — the catalog mirror, a cache. Called
+     * for a periodic refresh and for webhooks that touched the catalog.
+     *
+     * Throwing marks the message for retry, which is usually right: a failed
+     * refresh means the site is serving stale data.
+     */
+    refreshCatalog?: () => void | Promise<void>;
+    /**
+     * Anything else this project queues. Runs for every message, after the
+     * catalog dispatch above, so a project can add its own kinds without
+     * reimplementing the refresh logic.
+     */
+    onMessage?: (message: AstroidQueueMessage) => void | Promise<void>;
+}
+/**
+ * Build the per-message handler to hand to `processBatch`.
+ *
+ * ```ts
+ * async queue(batch, env) {
+ *   await processBatch(batch, astroidQueueHandler({
+ *     refreshCatalog: () => refreshCatalog(env),
+ *   }));
+ * }
+ * ```
+ */
+export declare function astroidQueueHandler(options?: QueueHandlerOptions): (message: AstroidQueueMessage) => Promise<void>;

package/dist/queues/consumer.js

@@ -0,0 +1,37 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The consumer side.
+//
+// `processBatch` (louise-toolkit/queues) already owns per-message ack/retry, and
+// Cloudflare Queues owns redelivery and DLQ routing. What every site then wrote
+// on top was the same dispatch: a periodic refresh runs the re-sync, a webhook
+// runs it only if the event actually touched the catalog, and everything else
+// acks as a no-op.
+//
+// That last part matters more than it looks. Order, payment, and subscription
+// events are read live from the provider, so there is nothing local to update —
+// but they still arrive, in volume. A consumer that treats every event as
+// actionable turns a busy sales day into a catalog-refresh storm.
+import { affectsCatalog } from "./messages.js";
+/**
+ * Build the per-message handler to hand to `processBatch`.
+ *
+ * ```ts
+ * async queue(batch, env) {
+ *   await processBatch(batch, astroidQueueHandler({
+ *     refreshCatalog: () => refreshCatalog(env),
+ *   }));
+ * }
+ * ```
+ */
+export function astroidQueueHandler(options = {}) {
+    return async (message) => {
+        if (message.kind === "catalog_refresh") {
+            await options.refreshCatalog?.();
+        }
+        else if (message.kind === "webhook" && affectsCatalog(message.provider, message.type)) {
+            await options.refreshCatalog?.();
+        }
+        await options.onMessage?.(message);
+    };
+}

package/dist/queues/index.d.ts

@@ -0,0 +1,4 @@
+export { astroidQueueHandler, type QueueHandlerOptions } from "./consumer.js";
+export { affectsCatalog, ASTROID_DEFAULT_CRON, ASTROID_HEALTH_CRON, ASTROID_QUEUE_BINDING, type AstroidQueueMessage, astroidCron, astroidCrons, astroidQueueNames, astroidUsesQueues, type CatalogRefreshMessage, type WebhookMessage, } from "./messages.js";
+export { generateAstroidEnvBindings, generateAstroidQueueSeam, generateAstroidWebhookRoute, generateAstroidWebhookRoutes, } from "./scaffold.js";
+export { handleWebhook, type QueueProducer, type WebhookRouteOptions, type WebhookVerifyInput, } from "./webhook.js";

package/dist/queues/index.js

@@ -0,0 +1,5 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+export { astroidQueueHandler } from "./consumer.js";
+export { affectsCatalog, ASTROID_DEFAULT_CRON, ASTROID_HEALTH_CRON, ASTROID_QUEUE_BINDING, astroidCron, astroidCrons, astroidQueueNames, astroidUsesQueues, } from "./messages.js";
+export { generateAstroidEnvBindings, generateAstroidQueueSeam, generateAstroidWebhookRoute, generateAstroidWebhookRoutes, } from "./scaffold.js";
+export { handleWebhook, } from "./webhook.js";

package/dist/queues/messages.d.ts

@@ -0,0 +1,60 @@
+import type { AstroidConfig } from "../config.js";
+/**
+ * Whether this project runs a queue consumer + cron.
+ *
+ * On by default whenever commerce is configured: a commerce provider means
+ * webhooks, and a webhook processed inline is a webhook you drop the moment the
+ * provider's delivery timeout is shorter than your catalog sync.
+ */
+export declare function astroidUsesQueues(config: AstroidConfig): boolean;
+/** Hourly. Frequent enough that stale data has a bounded lifetime, rare enough
+ *  to be free. */
+export declare const ASTROID_DEFAULT_CRON = "0 * * * *";
+/** The cron expression for the safety-net re-sync, or null when disabled. */
+export declare function astroidCron(config: AstroidConfig): string | null;
+/**
+ * Daily, at an off-peak-ish minute. The health scan crawls the site's own pages,
+ * so it is deliberately NOT on the hourly catalog cron — hourly would be a
+ * self-inflicted crawl 24× a day to recompute counts that move slowly.
+ */
+export declare const ASTROID_HEALTH_CRON = "17 4 * * *";
+/**
+ * Every cron expression the project needs, in the order they're declared in
+ * `wrangler.jsonc`.
+ *
+ * Cloudflare fires ONE `scheduled` handler for all of them and identifies which
+ * by `controller.cron`, so the generated handler dispatches on that string. That
+ * is why this list is derived in one place rather than assembled at each call
+ * site: the wrangler `triggers.crons` array and the handler's dispatch have to
+ * agree exactly, and a mismatch is a job that silently never runs.
+ */
+export declare function astroidCrons(config: AstroidConfig): string[];
+/** Binding name for the project's queue producer. */
+export declare const ASTROID_QUEUE_BINDING = "COMMERCE_QUEUE";
+/** Queue names derived from the project key — the main queue and its DLQ. */
+export declare function astroidQueueNames(config: AstroidConfig): {
+    queue: string;
+    dlq: string;
+};
+/**
+ * A provider webhook, thinned to what a consumer needs. The raw `payload` is
+ * carried through deliberately: the consumer's needs change faster than the
+ * webhook contract, and a message that only kept the fields today's consumer
+ * reads can't be replayed from the DLQ once that changes.
+ */
+export interface WebhookMessage {
+    kind: "webhook";
+    /** Which integration sent it — `"square"`, `"stripe"`, `"fourthwall"`. */
+    provider: string;
+    /** The provider's event type, e.g. `"catalog.version.updated"`. */
+    type: string;
+    payload: unknown;
+}
+/** The periodic (or manually triggered) full re-sync. */
+export interface CatalogRefreshMessage {
+    kind: "catalog_refresh";
+}
+/** Everything the project's queue carries. Match on `kind`. */
+export type AstroidQueueMessage = WebhookMessage | CatalogRefreshMessage;
+/** Whether a provider event should trigger a catalog re-sync. */
+export declare function affectsCatalog(provider: string, type: string): boolean;

package/dist/queues/messages.js

@@ -0,0 +1,71 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// What flows through the project's queue, and when it matters.
+/**
+ * Whether this project runs a queue consumer + cron.
+ *
+ * On by default whenever commerce is configured: a commerce provider means
+ * webhooks, and a webhook processed inline is a webhook you drop the moment the
+ * provider's delivery timeout is shorter than your catalog sync.
+ */
+export function astroidUsesQueues(config) {
+    return config.queues?.enabled ?? Boolean(config.commerce);
+}
+/** Hourly. Frequent enough that stale data has a bounded lifetime, rare enough
+ *  to be free. */
+export const ASTROID_DEFAULT_CRON = "0 * * * *";
+/** The cron expression for the safety-net re-sync, or null when disabled. */
+export function astroidCron(config) {
+    if (!astroidUsesQueues(config))
+        return null;
+    const cron = config.queues?.cron;
+    if (cron === false)
+        return null;
+    return cron ?? ASTROID_DEFAULT_CRON;
+}
+/**
+ * Daily, at an off-peak-ish minute. The health scan crawls the site's own pages,
+ * so it is deliberately NOT on the hourly catalog cron — hourly would be a
+ * self-inflicted crawl 24× a day to recompute counts that move slowly.
+ */
+export const ASTROID_HEALTH_CRON = "17 4 * * *";
+/**
+ * Every cron expression the project needs, in the order they're declared in
+ * `wrangler.jsonc`.
+ *
+ * Cloudflare fires ONE `scheduled` handler for all of them and identifies which
+ * by `controller.cron`, so the generated handler dispatches on that string. That
+ * is why this list is derived in one place rather than assembled at each call
+ * site: the wrangler `triggers.crons` array and the handler's dispatch have to
+ * agree exactly, and a mismatch is a job that silently never runs.
+ */
+export function astroidCrons(config) {
+    const crons = [ASTROID_HEALTH_CRON];
+    const catalog = astroidCron(config);
+    if (catalog)
+        crons.push(catalog);
+    return crons;
+}
+/** Binding name for the project's queue producer. */
+export const ASTROID_QUEUE_BINDING = "COMMERCE_QUEUE";
+/** Queue names derived from the project key — the main queue and its DLQ. */
+export function astroidQueueNames(config) {
+    return { queue: `${config.key}-commerce`, dlq: `${config.key}-commerce-dlq` };
+}
+/**
+ * Event-type prefixes that invalidate a cached catalog, per provider.
+ *
+ * Prefix matching rather than an exhaustive list on purpose: providers add event
+ * types, and the failure mode of matching one too many is a redundant refresh,
+ * while missing one is a storefront serving a price that no longer exists.
+ */
+const CATALOG_EVENT_PREFIXES = {
+    square: ["catalog.", "inventory.", "item.", "item_variation."],
+    stripe: ["product.", "price.", "plan."],
+    fourthwall: ["product.", "variant.", "collection."],
+};
+/** Whether a provider event should trigger a catalog re-sync. */
+export function affectsCatalog(provider, type) {
+    const prefixes = CATALOG_EVENT_PREFIXES[provider] ?? [];
+    return prefixes.some((prefix) => type.startsWith(prefix));
+}