astroidjs 0.1.1 → 0.2.0

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));
+}

package/dist/queues/scaffold.d.ts

@@ -0,0 +1,44 @@
+import type { AstroidConfig, CommerceProvider } from "../config.js";
+/**
+ * The extra `CloudflareEnv` members the queue pipeline introduces, as a block
+ * `create-astroid` substitutes into the scaffolded `src/env.d.ts`.
+ *
+ * Substituted rather than always present because a declaration is a promise: a
+ * marketing site that types `COMMERCE_QUEUE` is claiming a binding its
+ * `wrangler.jsonc` never creates, and the first `env.COMMERCE_QUEUE.send()`
+ * someone writes against that type fails at runtime with the type system's
+ * blessing. Empty string when the project runs no consumer.
+ */
+export declare function generateAstroidEnvBindings(config: AstroidConfig): string;
+/**
+ * `src/queue.ts` — the consumer seam the generated worker imports.
+ *
+ * `astroidQueueHandler` already owns the dispatch every site wrote (periodic
+ * refresh, catalog-affecting webhook, no-op for everything else); what's left
+ * for the project is what "refresh" means, which is why this is a file and not
+ * a generated constant.
+ */
+export declare function generateAstroidQueueSeam(config: AstroidConfig): string;
+/**
+ * The provider webhook receiver — `src/pages/api/webhooks/<provider>.ts`.
+ *
+ * Thin on purpose: `handleWebhook` owns the ordering (verify the raw body before
+ * parsing) and the status-code contract (which codes ask the provider to retry
+ * and which tell it to stop). What's here is the provider's own header and
+ * verifier, plus the secret read.
+ *
+ * Returns null when the project has no commerce provider — nothing to receive.
+ */
+export declare function generateAstroidWebhookRoute(config: AstroidConfig, forProvider?: CommerceProvider): string | null;
+/**
+ * Every webhook receiver this project needs, as `{ path, contents }`.
+ *
+ * Plural because roles are: a site running Stripe for invoicing beside
+ * Fourthwall for the storefront receives from both, each with its own signing
+ * secret and header. One route per provider, not per role — a provider filling
+ * two roles still has one endpoint and one secret.
+ */
+export declare function generateAstroidWebhookRoutes(config: AstroidConfig): {
+    path: string;
+    contents: string;
+}[];