astroidjs 0.1.2 → 0.3.0

package/dist/config.d.ts

@@ -1,3 +1,9 @@
+import type { SectionCatalog } from "louise-toolkit/content";
+import type { RateRule } from "louise-toolkit/security";
+import type { CatalogMirrorConfig } from "./commerce/mirror.js";
+import type { astroidSectionCatalog } from "./components/sections.js";
+import type { PortalRoute } from "./portal/guard.js";
+import type { PwaConfig } from "./pwa/generate.js";
 /**
  * The starting shape the front-end takes. Not a fork — each archetype is a preset
  * of defaults (which sections/modules are on, nav shape) that the site then tunes.
@@ -7,17 +13,55 @@
  */
 export type Archetype = "marketing" | "storefront" | "wholesale" | "portfolio";
 /**
- * The section vocabulary — the editable home page is an ordered list of these, top
- * to bottom. Each maps to a themeable component in the Astroid section library.
- * Drawn from real usage across the target sites (annotated below).
+ * The section vocabulary — the editable home page is an ordered list of these,
+ * top to bottom.
+ *
+ * DERIVED from the section catalog, not hand-written (#277). It used to be its
+ * own union, and the two drifted in both directions: this named four kinds with
+ * no catalog entry and no component (`marquee`, `featured`, `story`, `visit`),
+ * while omitting eight that were real and renderable. A scaffold's config then
+ * listed sections that could never render, and nothing type-checked the gap.
+ *
+ * A type-only import, so the derivation adds no runtime dependency: `config.ts`
+ * is loaded by the `create-astroid` CLI, and this keeps its import graph
+ * exactly as it was.
  */
-export type SectionKind = "hero" | "marquee" | "featureGrid" | "featured" | "productGrid" | "gallery" | "story" | "visit" | "cta" | "testimonial" | "contact";
+export type SectionKind = keyof typeof astroidSectionCatalog;
+/**
+ * Each archetype's default home-page sections.
+ *
+ * Lives here, in TypeScript, rather than in `create-astroid`'s plain JS — the
+ * other half of #277. As a JS object literal it could name a section that
+ * didn't exist and nothing would say so; typed against {@link SectionKind}
+ * (itself derived from the catalog) a stale name is a compile error, and CI
+ * type-checks this package.
+ *
+ * The four kinds this used to name — `marquee`, `featured`, `story`, `visit` —
+ * had no catalog entry or component and could never render. Each is replaced by
+ * the real section that does its job: a marquee is a `banner`, curated picks
+ * are a `productGrid`, a brand-origin block is `aboutIntro`, and "visit" is
+ * exactly `locationHours`.
+ */
+export declare const ASTROID_ARCHETYPE_SECTIONS: Record<Archetype, SectionKind[]>;
 /**
  * Optional capabilities the site switches on. Pluggable, not core — a portfolio
- * site runs none of the commerce ones. `orderTracking` is shared across both
- * coffee brands, so it's first-class but still opt-in.
+ * site runs none of the commerce ones.
+ *
+ * **Every value here is read by something.** The union used to also name
+ * `orderTracking`, `subscriptions`, `giftCards`, and `privateLabel`, none of
+ * which had a single consumer anywhere in the package: setting one type-checked,
+ * passed validation, and did nothing at all — no scaffold, no CSP origin, no
+ * rate rule, no table. A config surface that accepts a setting it ignores is
+ * worse than a smaller one, because the only way to discover the truth is to
+ * deploy and notice the absence.
+ *
+ * They are removed rather than left as TODOs. `orderTracking` in particular has
+ * a real implementation waiting — `src/workflow/` is the ghostfire order tracker,
+ * generalized — but it is reached through `defineWorkflow`, not this flag, and
+ * pretending otherwise is what made the flag misleading. Re-add each one in the
+ * change that wires it.
  */
-export type ModuleKind = "orderTracking" | "subscriptions" | "giftCards" | "wholesaleInquiry" | "privateLabel";
+export type ModuleKind = "map" | "pwa" | "realtime" | "wholesaleInquiry";
 /** Commerce backend — mirrors Louise's provider set (louise-toolkit/commerce). */
 export type CommerceProvider = "stripe" | "square" | "fourthwall";
 export interface Theme {
@@ -40,14 +84,168 @@ export interface Theme {
 }
 export interface Portal {
     enabled: boolean;
-    /** Require a session to view the whole site (Meg Bowen's gated preview), not
-     *  just the account area. Default `false`. */
+    /**
+     * @deprecated NOT IMPLEMENTED — `defineAstroid` throws if this is set.
+     *
+     * It was meant to require a session for the whole site (a pre-launch client
+     * gallery), not just the account area, but nothing ever read it: the guard
+     * table is built from {@link Portal.routes} and `portalGuard` allows any
+     * unmatched path. Until it's wired, gate the site by naming the prefixes in
+     * `routes` — that is the mechanism this would have been sugar for.
+     */
     gated?: boolean;
-    /** Modules exposed inside the account area (e.g. `orderTracking`). */
+    /** Modules exposed inside the account area (e.g. `wholesaleInquiry`, which
+     *  adds the inquiries table even on an archetype that wouldn't have one). */
     features?: ModuleKind[];
+    /**
+     * Roles a portal account can hold, first being the default for a new account.
+     * Default `["customer"]`. These are the portal's OWN roles — entirely separate
+     * from the editor's `admin`, because the two auth instances don't share a
+     * user table.
+     */
+    roles?: string[];
+    /**
+     * Route guard table: everything under `prefix` needs one of `roles`. Matched
+     * in order, first match wins. Defaults to `/portal` + `/api/portal` for any
+     * signed-in portal user.
+     */
+    routes?: PortalRoute[];
+    /**
+     * Where a portal user lands, per role — used to bounce someone who reached an
+     * area they don't belong in. Default `/portal` for everyone.
+     */
+    home?: Record<string, string>;
+    /**
+     * Allow public sign-up. Default `false`: both consuming sites provision portal
+     * accounts by hand, and a portal is usually for people you already know.
+     */
+    signUp?: boolean;
+    /**
+     * Where the portal's Better Auth instance mounts — its own handler, separate
+     * from the editor's `/api/auth`. Default `/api/portal-auth`. Override when a
+     * site already ships a second instance at a different path (e.g. a shop
+     * account at `/api/shop-auth`) whose live cookies must not change.
+     */
+    basePath?: string;
+    /**
+     * Cookie prefix for the portal instance — MUST differ from the editor's
+     * (Better Auth's default), or signing into one instance signs you out of the
+     * other. Default `"portal"`. `defineAstroid` rejects a colliding value.
+     */
+    cookiePrefix?: string;
+    /**
+     * Table-name prefix for the portal's Better Auth tables. Default `"portal_"`
+     * (`portal_user`, …); set `""` to take the unprefixed `user`/`session` tables
+     * (the editor owns `louise_*`, so they don't collide). MUST differ from the
+     * editor's `louise_` prefix.
+     */
+    tablePrefix?: string;
 }
 export interface CommerceConfig {
-    provider: CommerceProvider;
+    /**
+     * Shorthand for a single-provider site. Assigns the provider to a role it can
+     * actually serve — `square`/`fourthwall` become the storefront, `stripe`
+     * becomes invoicing (its client has no catalog API).
+     */
+    provider?: CommerceProvider;
+    /** Catalog, cart, checkout. Needs a provider with a catalog API. */
+    storefront?: CommerceProvider;
+    /**
+     * Invoices for work that isn't a catalog item — commissions, originals.
+     * Independent of `storefront`: themidwestartist.com runs Stripe here and
+     * Fourthwall as the storefront, because neither can do the other's job.
+     */
+    invoicing?: CommerceProvider;
+    /** The catalog mirror's shape — its mode, table name, and owned columns. */
+    catalog?: CatalogMirrorConfig;
+}
+export interface QueuesConfig {
+    /**
+     * Force the queue consumer + cron on or off. Defaults to on whenever
+     * `commerce` is configured: a commerce provider means webhooks, and a webhook
+     * you process inline is a webhook you drop when the provider times out.
+     */
+    enabled?: boolean;
+    /**
+     * Cron for the safety-net re-sync, or `false` for none. Webhooks get missed —
+     * a provider outage, a deploy mid-delivery, a DLQ'd message — and without a
+     * periodic re-sync the site serves stale data until someone notices. Default
+     * hourly.
+     */
+    cron?: string | false;
+    /** Deliveries before Cloudflare routes a message to the DLQ. Default 5. */
+    maxRetries?: number;
+    /** Messages per consumer invocation. Default 10. */
+    maxBatchSize?: number;
+    /** Seconds the consumer waits to fill a batch. Default 30. */
+    maxBatchTimeout?: number;
+}
+export interface SeoConfig {
+    /**
+     * `<title>` template, `%s` standing in for the page title. Applied only when
+     * a page supplies its own title, so the home page reads "Acme Coffee" and not
+     * "Acme Coffee | Acme Coffee". Default `"%s | <site name>"`.
+     */
+    titleTemplate?: string;
+    /**
+     * schema.org `@type` for the business node in the JSON-LD graph. Defaults to
+     * the archetype's broad type (see `ARCHETYPE_BUSINESS_TYPE`); set a more
+     * specific subtype whenever you know one — `"CafeOrCoffeeShop"`,
+     * `"ArtGallery"`, `"HomeAndConstructionBusiness"` — since a narrower type is
+     * strictly better for rich results.
+     */
+    businessType?: string;
+    /** `@handle` for Twitter/X card attribution. */
+    twitterHandle?: string;
+    /** Open Graph locale, e.g. `"en_US"`. */
+    locale?: string;
+}
+export interface SecurityConfig {
+    /**
+     * Extra rate-limit rules for surfaces Astroid doesn't know about, and the seam
+     * for overriding a default budget. These are matched BEFORE the derived
+     * defaults (first match wins), so declaring a rule for a path Astroid already
+     * covers replaces that one rule rather than the whole set.
+     */
+    rateRules?: RateRule[];
+    /**
+     * Extra origins to allow in the generated Content-Security-Policy, merged with
+     * the ones Astroid derives from the enabled modules. Add a host here when you
+     * pull in a third party Astroid can't see (a chat widget, a video embed).
+     */
+    cspOrigins?: CspOrigins;
+}
+/** Per-directive origin lists contributed to the CSP. */
+export interface CspOrigins {
+    script?: string[];
+    frame?: string[];
+    connect?: string[];
+    font?: string[];
+    img?: string[];
+    worker?: string[];
+}
+export interface SettingsConfig {
+    /**
+     * Override the editable base `site_settings` columns. Defaults to Astroid's
+     * standard set (`ASTROID_SETTINGS_COLUMNS`). A **custom-heavy** site whose
+     * settings shape doesn't align with the base column names keeps everything in
+     * `custom` by passing `[]` — otherwise a key that happens to match a base
+     * column name (e.g. `contactEmail`) would route to that column instead of
+     * `custom`, where the site's render reads it.
+     */
+    columns?: string[];
+    /**
+     * Site-specific settings keys stored in the `site_settings.custom` JSON column,
+     * on top of (or, with `columns: []`, instead of) Astroid's base columns. The
+     * generated `settingsRoute` + Action accept these; the Settings panel writes
+     * them through the `settingsExtension` groups a site supplies to
+     * `mountSettings`. A site with a rich settings shape (coracle's footer columns,
+     * hours table, ui strings, shop/order config) lists their top-level keys here.
+     */
+    customKeys?: string[];
+    /** Extra media-library image keys beyond the base logo/favicon/OG defaults —
+     *  settings values validated as media-library URLs on write. */
+    imageKeys?: string[];
 }
 export interface DeployConfig {
     platform: "cloudflare";
@@ -69,12 +267,41 @@ export interface AstroidConfig {
     theme: Theme;
     /** The editable home page, top to bottom. Omit to take the archetype default. */
     sections?: SectionKind[];
+    /**
+     * A site-provided section catalog that REPLACES the built-in one for
+     * SERVER-side validation + sanitization of `pages.sections` (the generated
+     * pages route + versions route). A site with bespoke section designs — its own
+     * `.astro` components and field defs (coracle's 13 sections) — registers them
+     * here so writes to its custom `_type`s validate instead of 422-ing against the
+     * built-in vocabulary. The on-canvas editor already uses the site's catalog
+     * (its `mountSections` call passes it); this closes the server half so both
+     * write paths agree. Omit to use Astroid's built-in catalog.
+     */
+    sectionCatalog?: SectionCatalog;
     /** Optional capabilities switched on for this site. */
     modules?: ModuleKind[];
     /** Gated account/portal area (order tracking, client galleries). */
     portal?: Portal;
     /** Commerce backend. */
     commerce?: CommerceConfig;
+    /** Queue consumer + cron safety net. Defaults on when `commerce` is set. */
+    queues?: QueuesConfig;
+    /** Title template, structured-data type, and social-card attribution. */
+    seo?: SeoConfig;
+    /** Additions to the rate-limit rules + CSP origins Astroid derives. */
+    security?: SecurityConfig;
+    /** Site-specific editable settings — extra `custom` keys + image keys on top
+     *  of Astroid's base `site_settings` columns. */
+    settings?: SettingsConfig;
+    /**
+     * Force the contact form + `inquiries` table on or off. Omit to detect from
+     * the config (a `contact` section, or a wholesale-inquiry module). Set `true`
+     * when a bespoke section captures inquiries under a name Astroid can't see
+     * (coracle's custom `contactForm`); set `false` to suppress it entirely.
+     */
+    inquiries?: boolean;
+    /** Installable-app settings. Only read when `modules` includes `"pwa"`. */
+    pwa?: PwaConfig;
     deploy?: DeployConfig;
 }
 /**
@@ -89,7 +316,7 @@ export interface AstroidConfig {
  *   key: "coracle",
  *   archetype: "storefront",
  *   theme: { name: "Coracle Coffee", colors: { brand: "#1f6f78" } },
- *   sections: ["hero", "marquee", "featured", "productGrid", "visit"],
+ *   sections: ["hero", "banner", "productGrid", "locationHours", "contact"],
  *   commerce: { provider: "square" },
  *   deploy: { platform: "cloudflare" },
  * });

package/dist/config.js

@@ -19,7 +19,30 @@
 // `ModuleKind` are extracted from the real sites Astroid targets — a storefront
 // (coracle), a wholesale front (ghostfire), an artist portfolio (megbowen), and a
 // plain marketing baseline (louise-web).
+import { assertAuthIsolation } from "./auth/index.js";
+import { assertCommerceRoles } from "./commerce/roles.js";
 import { AstroidConfigError } from "./errors.js";
+/**
+ * Each archetype's default home-page sections.
+ *
+ * Lives here, in TypeScript, rather than in `create-astroid`'s plain JS — the
+ * other half of #277. As a JS object literal it could name a section that
+ * didn't exist and nothing would say so; typed against {@link SectionKind}
+ * (itself derived from the catalog) a stale name is a compile error, and CI
+ * type-checks this package.
+ *
+ * The four kinds this used to name — `marquee`, `featured`, `story`, `visit` —
+ * had no catalog entry or component and could never render. Each is replaced by
+ * the real section that does its job: a marquee is a `banner`, curated picks
+ * are a `productGrid`, a brand-origin block is `aboutIntro`, and "visit" is
+ * exactly `locationHours`.
+ */
+export const ASTROID_ARCHETYPE_SECTIONS = {
+    marketing: ["hero", "featureGrid", "cta", "contact"],
+    storefront: ["hero", "banner", "productGrid", "locationHours", "contact"],
+    wholesale: ["hero", "featureGrid", "aboutIntro", "contact"],
+    portfolio: ["hero", "gallery", "aboutIntro", "contact"],
+};
 /**
  * Define an Astroid project. An identity function in the shape of Astro's
  * `defineConfig`: it returns the config verbatim with full type-checking +
@@ -32,7 +55,7 @@ import { AstroidConfigError } from "./errors.js";
  *   key: "coracle",
  *   archetype: "storefront",
  *   theme: { name: "Coracle Coffee", colors: { brand: "#1f6f78" } },
- *   sections: ["hero", "marquee", "featured", "productGrid", "visit"],
+ *   sections: ["hero", "banner", "productGrid", "locationHours", "contact"],
  *   commerce: { provider: "square" },
  *   deploy: { platform: "cloudflare" },
  * });
@@ -48,5 +71,30 @@ export function defineAstroid(config) {
     if (!config.theme.colors || !config.theme.colors.brand) {
         throw new AstroidConfigError("Astroid config requires `theme.colors.brand` (the primary brand color)");
     }
+    // A provider assigned to a role its client can't serve (invoicing over
+    // Fourthwall, a storefront over Stripe) fails here rather than at runtime on
+    // the first invoice, as a missing function.
+    assertCommerceRoles(config.commerce);
+    // A portal is a SECOND Better Auth instance beside the editor's. Reject any
+    // isolation that would collide with the editor on the same origin (a shared
+    // cookie prefix silently cross-signs-out; a shared table prefix merges the two
+    // user tables) — the intermittent-prod failure the fixed defaults prevent.
+    assertAuthIsolation(config);
+    // `portal.gated` is declared and resolved but read by NOTHING — the guard
+    // table is built from `portal.routes` alone, and `portalGuard` allows any
+    // unmatched path. So a site that set it believed the whole site sat behind a
+    // login (a pre-launch client gallery) while every page outside /portal was
+    // public, and it type-checked.
+    //
+    // Refusing the flag is the only safe state until it's implemented. A security
+    // control that silently does nothing is strictly worse than one that isn't
+    // offered: the first gives false confidence, the second sends you looking for
+    // an answer. Fail loudly, at config load, naming the workaround.
+    if (config.portal?.gated) {
+        throw new AstroidConfigError("`portal.gated` is not implemented — it is accepted but wires no guard, so the site " +
+            "would be fully public while appearing gated. Remove it, and gate the whole site by " +
+            "listing the prefixes you mean in `portal.routes` (e.g. `[{ prefix: \"/\" }]` with your " +
+            "login and auth paths ahead of it).");
+    }
     return config;
 }

package/dist/email/index.d.ts

@@ -0,0 +1,4 @@
+export { astroidMailTheme, type MailThemeOverrides } from "./theme.js";
+export { type AstroidMailEnv, sendInquiryMail } from "./inquiry.js";
+export { createMailer, type DeliveryResult, EMAIL_SECRET_NAMES, type EmailSender, type MailerEnv, type MailerOptions, type MailerStatus, type OutgoingMail, resolveMailer, resolveMailerStatus, sendTransactional, } from "./send.js";
+export { type InquiryDetails, inquiryConfirmationEmail, inquiryNotificationEmail, magicLinkEmail, type MailContent, type MailTheme, passwordResetEmail, } from "./templates.js";

package/dist/email/index.js

@@ -0,0 +1,5 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+export { astroidMailTheme } from "./theme.js";
+export { sendInquiryMail } from "./inquiry.js";
+export { createMailer, EMAIL_SECRET_NAMES, resolveMailer, resolveMailerStatus, sendTransactional, } from "./send.js";
+export { inquiryConfirmationEmail, inquiryNotificationEmail, magicLinkEmail, passwordResetEmail, } from "./templates.js";

package/dist/email/inquiry.d.ts

@@ -0,0 +1,33 @@
+import type { AstroidConfig } from "../config.js";
+import type { SecretSource } from "../secrets.js";
+import type { EmailSender } from "./send.js";
+import { type DeliveryResult } from "./send.js";
+import { type MailThemeOverrides } from "./theme.js";
+/** The bindings the inquiry hook reads. All optional — an unprovisioned mail
+ *  setup logs instead of sending, per the dormant-until-provisioned convention. */
+export interface AstroidMailEnv {
+    /** Cloudflare Email Sending binding. */
+    EMAIL?: EmailSender;
+    /**
+     * Envelope sender; its domain must be onboarded for Email Sending. A
+     * `SecretSource` rather than a plain string so a Secrets Store binding works
+     * here too — and so the placeholder sentinel reads as unconfigured.
+     */
+    MAIL_FROM?: SecretSource;
+    /** Where owner notifications go. Also the first editor's address. */
+    OWNER_EMAIL?: string;
+}
+/**
+ * Send the notify + confirm pair for one contact-form submission.
+ *
+ * Wire it into the generated worker's form route:
+ *
+ * ```ts
+ * formRoute({ form: contactForm, onSubmit: (values, env) => sendInquiryMail(config, env, values) })
+ * ```
+ *
+ * Each half is skipped when its recipient is unknown rather than failing the
+ * batch: no `OWNER_EMAIL` means no notification to send, and a submission whose
+ * email didn't validate still deserves to reach the owner.
+ */
+export declare function sendInquiryMail(config: AstroidConfig, env: AstroidMailEnv, values: Record<string, unknown>, overrides?: MailThemeOverrides): Promise<DeliveryResult[]>;

package/dist/email/inquiry.js

@@ -0,0 +1,63 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The inquiry pair, wired to the contact form.
+//
+// `formRoute` fires `onSubmit` AFTER the row is inserted and off the response
+// path (`waitUntil`), which is exactly the store-and-forward shape this wants:
+// the submission is already durable, so mail is a notification of something that
+// already happened and can fail without the visitor ever knowing.
+//
+// Two messages, not one — every site converged on the pair. The owner needs the
+// message; the visitor needs to know it arrived, because a contact form with no
+// acknowledgement is indistinguishable from one that's broken.
+import { resolveMailer, sendTransactional } from "./send.js";
+import { inquiryConfirmationEmail, inquiryNotificationEmail } from "./templates.js";
+import { astroidMailTheme } from "./theme.js";
+/** Trimmed string, or undefined for anything else. */
+const str = (v) => {
+    const s = typeof v === "string" ? v.trim() : "";
+    return s || undefined;
+};
+/**
+ * Send the notify + confirm pair for one contact-form submission.
+ *
+ * Wire it into the generated worker's form route:
+ *
+ * ```ts
+ * formRoute({ form: contactForm, onSubmit: (values, env) => sendInquiryMail(config, env, values) })
+ * ```
+ *
+ * Each half is skipped when its recipient is unknown rather than failing the
+ * batch: no `OWNER_EMAIL` means no notification to send, and a submission whose
+ * email didn't validate still deserves to reach the owner.
+ */
+export async function sendInquiryMail(config, env, values, overrides) {
+    const theme = astroidMailTheme(config, overrides);
+    const details = {
+        name: [str(values.firstName), str(values.lastName)].filter(Boolean).join(" "),
+        email: str(values.email) ?? "",
+        regarding: str(values.regarding),
+        message: str(values.message) ?? "",
+    };
+    const owner = str(env.OWNER_EMAIL);
+    const mails = [
+        ...(owner
+            ? [
+                {
+                    to: owner,
+                    content: inquiryNotificationEmail(theme, details),
+                    // So the owner can answer by hitting reply, rather than copying an
+                    // address out of the body.
+                    ...(details.email ? { replyTo: details.email } : {}),
+                },
+            ]
+            : []),
+        ...(details.email
+            ? [{ to: details.email, content: inquiryConfirmationEmail(theme, details) }]
+            : []),
+    ];
+    // One resolver decides dormancy for the whole module: no binding, no sender
+    // address, or a sender still holding the placeholder sentinel all come back
+    // as `logOnly`, so nothing hands the Email API a dummy envelope.
+    return sendTransactional(await resolveMailer(env), mails);
+}

package/dist/email/send.d.ts

@@ -0,0 +1,120 @@
+import type { EmailSender, MailContent } from "louise-toolkit/email";
+import { type ModuleSecrets, type SecretSource } from "../secrets.js";
+export type { EmailSender };
+/**
+ * The secrets the mailer needs. Just the envelope sender: the EMAIL binding is a
+ * binding, not a secret, so it's gated by presence rather than by value.
+ *
+ * Named here so `astroid doctor` and the scaffold's `.dev.vars` seed read the
+ * same list the runtime gate does.
+ */
+export declare const EMAIL_SECRET_NAMES: readonly ["MAIL_FROM"];
+/**
+ * The mailer's resolved gate. Deliberately NOT `ModuleSecrets<"MAIL_FROM">`:
+ * `missing` here can name `EMAIL`, which is a binding rather than a secret, so
+ * the key type is widened to plain strings.
+ */
+export interface MailerStatus {
+    /** True only when a binding AND a real sender address are both present. */
+    configured: boolean;
+    values: ModuleSecrets<"MAIL_FROM">["values"];
+    /** What's unprovisioned — secret names and/or `"EMAIL"`. */
+    missing: string[];
+    /** Whether an Email Sending binding is present at all. */
+    hasBinding: boolean;
+}
+/** The env members the mailer reads. Structural, so a project's env fits. */
+export interface MailerEnv {
+    EMAIL?: EmailSender | null;
+    MAIL_FROM?: SecretSource;
+}
+/**
+ * Resolve the email module's dormancy.
+ *
+ * Both halves are required, and for the same reason: a binding with no sender
+ * address can't build an envelope, and a sender address with no binding has
+ * nothing to send through. Either one missing means log-and-continue, which
+ * under `wrangler dev` (no EMAIL binding at all) is the normal case — and the
+ * reason the magic-link flow is still workable locally.
+ */
+export declare function resolveMailerStatus(env: MailerEnv): Promise<MailerStatus>;
+/**
+ * Build `MailerOptions` from an env, with dormancy already decided.
+ *
+ * The point of routing through {@link resolveMailerStatus} rather than checking
+ * `!env.EMAIL` inline is that the placeholder sentinel counts: a scaffold seeds
+ * `MAIL_FROM=DUMMY_REPLACE_ME`, and handing that to the Email API as an
+ * envelope sender is exactly the "called upstream with a dummy credential"
+ * failure the convention exists to prevent.
+ */
+export declare function resolveMailer(env: MailerEnv, overrides?: Partial<Omit<MailerOptions, "binding" | "from">>): Promise<MailerOptions & {
+    status: MailerStatus;
+}>;
+/** One message queued for delivery. */
+export interface OutgoingMail {
+    to: string;
+    content: MailContent;
+    /** Reply-To — for an inquiry notification, the visitor's own address, so the
+     *  owner can just hit reply. */
+    replyTo?: string;
+}
+/** What happened to one message. Never an exception. */
+export interface DeliveryResult {
+    to: string;
+    subject: string;
+    delivered: boolean;
+    messageId?: string;
+    /** Why it wasn't delivered — `"not-configured"`, `"log-only"`, or the error. */
+    reason?: string;
+}
+export interface MailerOptions {
+    /**
+     * The Cloudflare Email Sending binding. Absent or null → the mailer is
+     * dormant: messages are logged, and every result comes back
+     * `delivered: false, reason: "not-configured"`.
+     */
+    binding?: EmailSender | null;
+    /** Envelope sender. Its domain must be onboarded for Email Sending. */
+    from: string | {
+        email: string;
+        name?: string;
+    };
+    /** Log instead of sending even when a binding exists (a dry run). */
+    logOnly?: boolean;
+    /** Sink for the dev log. Defaults to `console.info`; pass one in a test. */
+    log?: (message: string) => void;
+    /**
+     * Print the message BODY when a send is skipped.
+     *
+     * The body carries single-use sign-in and password-reset links, so it is only
+     * printed where we can tell we're in development. Set this explicitly when the
+     * detection can't (a local `wrangler dev` against a real account, a test). Do
+     * not set it on a deployed Worker: the log is `wrangler tail` and Logpush.
+     */
+    devLog?: boolean;
+}
+/**
+ * Send a batch of transactional messages, best effort.
+ *
+ * Delivery runs concurrently and independently: an inquiry sends a notification
+ * to the owner and a confirmation to the visitor, and the owner's copy must
+ * still arrive when the visitor typo'd their address. Callers get a result per
+ * message and decide whether to care.
+ *
+ * ```ts
+ * const results = await sendTransactional(
+ *   { binding: env.EMAIL, from: env.MAIL_FROM },
+ *   [
+ *     { to: owner, content: inquiryNotificationEmail(theme, i), replyTo: i.email },
+ *     { to: i.email, content: inquiryConfirmationEmail(theme, i) },
+ *   ],
+ * );
+ * ```
+ */
+export declare function sendTransactional(options: MailerOptions, mails: OutgoingMail[]): Promise<DeliveryResult[]>;
+/**
+ * Bind a mailer's options once so call sites read as `mailer([...])`. Useful
+ * where the binding and sender are resolved per request but the sends are
+ * scattered (an inquiry hook, an auth callback).
+ */
+export declare function createMailer(options: MailerOptions): (mails: OutgoingMail[]) => Promise<DeliveryResult[]>;