@saastemly/voidcommerce 0.1.0

package/src/catalog.ts

@@ -0,0 +1,673 @@
+/**
+ * Everything `vc init` can offer, and what choosing it means.
+ *
+ * ── Why a registry ───────────────────────────────────────────────────────
+ *
+ * The wizard is only as good as its descriptions. A checkbox that says
+ * "organization" tells nobody anything; one that says "teams that share a
+ * shop — a club ordering trophies as one account" is a decision somebody can
+ * make. So every entry carries a one-line `hint` written for the person
+ * choosing, not for the person who wrote the plugin.
+ *
+ * Each entry also carries what choosing it COSTS: the packages to install,
+ * the env keys it needs, and whether those keys are secrets. That is how the
+ * generator knows what to write into `env.ts`, `.env.example` and the
+ * deploy requirements without a second hand-kept list.
+ */
+
+export interface EnvKey {
+	key: string;
+	/** What breaks without it — the sentence an operator reads at preflight. */
+	breaks: string;
+	/** Safe to commit in `.env.production`. Everything else is a secret. */
+	plaintext?: boolean | undefined;
+	/** A working value for local development. */
+	dev?: string | undefined;
+	/** Where the real value comes from. */
+	where?: string | undefined;
+}
+
+export interface Choice {
+	id: string;
+	label: string;
+	hint: string;
+	/** npm packages the choice pulls in. */
+	packages?: string[] | undefined;
+	env?: EnvKey[] | undefined;
+	/** Chosen unless the person unticks it. */
+	recommended?: boolean | undefined;
+	/** Cannot be unticked; shown so the person knows it is there. */
+	required?: boolean | undefined;
+	/** Ids this choice needs; the wizard adds them. */
+	requires?: string[] | undefined;
+	/** Ids this choice cannot coexist with. */
+	conflicts?: string[] | undefined;
+}
+
+export interface Group {
+	id: string;
+	title: string;
+	/** One line under the title. */
+	intro?: string | undefined;
+	choices: Choice[];
+	/** `select` picks exactly one; `multiselect` any number. */
+	kind: "select" | "multiselect";
+}
+
+/* -------------------------------------------------------------------------- */
+/* Better Auth                                                                 */
+/* -------------------------------------------------------------------------- */
+
+export const SIGN_IN: Group = {
+	id: "signIn",
+	title: "How do people sign in?",
+	intro: "Every method proves the address; a shop needs that for the order confirmation anyway.",
+	kind: "multiselect",
+	choices: [
+		{
+			id: "magic-link",
+			label: "Magic link",
+			hint: "one tap on the device the email is open on — signs up too",
+			recommended: true,
+		},
+		{
+			id: "email-otp",
+			label: "Email code",
+			hint: "for when the email is on a different device from the checkout — signs up too",
+			recommended: true,
+		},
+		{
+			id: "passkey",
+			label: "Passkeys",
+			hint: "returning customers, no email round-trip; sign-in only",
+			packages: ["@better-auth/passkey"],
+			recommended: true,
+		},
+		{
+			id: "google",
+			label: "Google",
+			hint: "Better Auth's own social provider — not a hand-rolled OAuth flow",
+			recommended: true,
+			env: [
+				{ key: "GOOGLE_CLIENT_ID", breaks: "the Google button is drawn and fails", where: "Google Cloud console" },
+				{ key: "GOOGLE_CLIENT_SECRET", breaks: "the same", where: "Google Cloud console" },
+			],
+		},
+		{
+			id: "apple",
+			label: "Apple",
+			hint: "required by Apple if you also offer Google in an iOS app",
+			env: [
+				{ key: "APPLE_CLIENT_ID", breaks: "the Apple button is drawn and fails", where: "Apple developer console" },
+				{ key: "APPLE_CLIENT_SECRET", breaks: "the same", where: "Apple developer console" },
+			],
+		},
+		{
+			id: "github",
+			label: "GitHub",
+			hint: "developer-audience shops",
+			env: [
+				{ key: "GITHUB_CLIENT_ID", breaks: "the GitHub button is drawn and fails" },
+				{ key: "GITHUB_CLIENT_SECRET", breaks: "the same" },
+			],
+		},
+		{
+			id: "password",
+			label: "Password",
+			hint: "reused from somewhere already breached, needs a reset flow that is itself a takeover path — off unless you have a reason",
+		},
+		{
+			id: "username",
+			label: "Username",
+			hint: "sign in by a handle instead of an address; only with password",
+			requires: ["password"],
+		},
+		{
+			id: "phone",
+			label: "Phone number",
+			hint: "SMS codes — needs an SMS provider you wire yourself",
+		},
+		{
+			id: "anonymous",
+			label: "Guest accounts",
+			hint: "a cart before an address; upgraded to a real account on first sign-in",
+		},
+	],
+};
+
+export const AUTH_PLUGINS: Group = {
+	id: "auth",
+	title: "Account features",
+	intro: "Better Auth's official plugins. Each adds tables and endpoints; the admin panel grows screens for them.",
+	kind: "multiselect",
+	choices: [
+		{
+			id: "admin",
+			label: "Admin roles",
+			hint: "who may open the panel — required, because a shop has operators",
+			required: true,
+		},
+		{
+			id: "system-user",
+			label: "System identity",
+			hint: "the deployment authenticates as ITSELF to import its own catalogue — no human sign-in to bootstrap",
+			packages: ["@saastemly/better-system-user"],
+			required: true,
+			env: [
+				{
+					key: "SYSTEM_API_KEY",
+					breaks: "nothing can be imported — no catalogue, no content, no DNS",
+					where: "openssl rand -base64 48",
+				},
+			],
+		},
+		{
+			id: "api-key",
+			label: "API keys",
+			hint: "machine access for integrations and the storefront build — 10 requests/day by default, raised for you",
+			packages: ["@better-auth/api-key"],
+			recommended: true,
+		},
+		{
+			id: "two-factor",
+			label: "Two-factor",
+			hint: "TOTP for operators; a customer account rarely warrants it",
+			recommended: true,
+		},
+		{
+			id: "organization",
+			label: "Organizations",
+			hint: "teams that share a shop account — a club ordering trophies as one buyer with several members",
+		},
+		{
+			id: "multi-session",
+			label: "Multiple sessions",
+			hint: "switch between accounts without signing out — support staff who impersonate",
+		},
+		{
+			id: "jwt",
+			label: "JWT",
+			hint: "tokens for a service that cannot hold a cookie — a mobile app, a partner API",
+		},
+		{
+			id: "bearer",
+			label: "Bearer tokens",
+			hint: "the session token in a header instead of a cookie; the mobile-app case",
+		},
+		{
+			id: "haveibeenpwned",
+			label: "Breached-password check",
+			hint: "refuses a password that has appeared in a breach; only with password sign-in",
+			requires: ["password"],
+		},
+		{
+			id: "one-time-token",
+			label: "One-time tokens",
+			hint: "hand a signed-in session to another origin for one request — the storefront to the panel",
+		},
+		{
+			id: "generic-oauth",
+			label: "Custom OAuth provider",
+			hint: "an identity provider Better Auth does not ship — a national eID, a corporate SSO",
+		},
+		{
+			id: "oauth-proxy",
+			label: "OAuth proxy",
+			hint: "OAuth callbacks that work on preview deployments with changing URLs",
+		},
+		{
+			id: "siwe",
+			label: "Sign in with Ethereum",
+			hint: "wallet-based sign-in; almost certainly not for a trophy shop",
+		},
+		{
+			id: "device-authorization",
+			label: "Device flow",
+			hint: "sign in on a TV or a CLI by confirming on a phone",
+		},
+		{
+			id: "custom-session",
+			label: "Custom session data",
+			hint: "attach computed fields to every session response",
+		},
+	],
+};
+
+/* -------------------------------------------------------------------------- */
+/* betterCommerce                                                              */
+/* -------------------------------------------------------------------------- */
+
+export const COMMERCE_CATALOG: Group = {
+	id: "catalog",
+	title: "Catalogue",
+	kind: "multiselect",
+	choices: [
+		{
+			id: "catalog",
+			label: "Products as rows",
+			hint: "products, variants, prices, images, categories, collections, tags — editable in the panel",
+			required: true,
+		},
+		{
+			id: "catalog-import",
+			label: "Catalogue import",
+			hint: "push products from a file, a PIM or a spreadsheet — matched on handle, never deletes",
+			required: true,
+		},
+		{
+			id: "metafields",
+			label: "Custom fields",
+			hint: "typed data on any row without a new table — Shopify's metafields",
+			recommended: true,
+		},
+		{
+			id: "personalization",
+			label: "Personalization",
+			hint: "engraving, monograms, gift messages: validated at add-to-cart and priced per character, per unit or once per order",
+		},
+		{
+			id: "inventory",
+			label: "Inventory",
+			hint: "stock levels and reservations per location",
+			recommended: true,
+		},
+		{
+			id: "bundles",
+			label: "Bundles",
+			hint: "a kit is its components at a set price",
+		},
+		{
+			id: "price-lists",
+			label: "Price lists",
+			hint: "override or discount prices per customer group or date range",
+		},
+		{
+			id: "translations",
+			label: "Translations",
+			hint: "product copy in more than one language",
+		},
+		{
+			id: "search",
+			label: "Search",
+			hint: "a search index over the catalogue; memory locally, Meilisearch in production",
+			recommended: true,
+		},
+	],
+};
+
+export const COMMERCE_SALES: Group = {
+	id: "sales",
+	title: "Selling",
+	kind: "multiselect",
+	choices: [
+		{
+			id: "regions",
+			label: "Regions",
+			hint: "which countries you sell to, in which currency — required",
+			required: true,
+		},
+		{
+			id: "sales-channels",
+			label: "Sales channels",
+			hint: "the web shop, a POS, a marketplace — scope products and prices per channel",
+			recommended: true,
+		},
+		{
+			id: "discounts",
+			label: "Discounts and campaigns",
+			hint: "codes, automatic promotions, funded campaigns with a spend cap",
+			recommended: true,
+		},
+		{
+			id: "gift-cards",
+			label: "Gift cards",
+			hint: "sold as products, redeemed at checkout; balance derived from the ledger",
+		},
+		{
+			id: "loyalty",
+			label: "Loyalty points",
+			hint: "earn on paid orders, spend at checkout",
+		},
+		{
+			id: "subscriptions",
+			label: "Subscriptions",
+			hint: "recurring orders on a schedule",
+		},
+		{
+			id: "draft-orders",
+			label: "Draft orders",
+			hint: "an operator builds a cart for a buyer and converts it — quotes, phone orders",
+			recommended: true,
+		},
+		{
+			id: "order-edits",
+			label: "Order edits",
+			hint: "change a paid order — add a line, swap a size — with the difference charged or refunded",
+		},
+		{
+			id: "returns",
+			label: "Returns",
+			hint: "the buyer-facing road to a refund",
+			recommended: true,
+		},
+		{
+			id: "wishlists",
+			label: "Wishlists",
+			hint: "save for later; prices resolved on read, so a saved item shows today's price",
+			recommended: true,
+		},
+		{
+			id: "reviews",
+			label: "Reviews",
+			hint: "held for moderation; the verified badge is derived from a paid order, never claimed",
+			recommended: true,
+		},
+		{
+			id: "customer-groups",
+			label: "Customer groups",
+			hint: "segments with their own prices and rules — trade, VIP, staff",
+		},
+		{
+			id: "acp",
+			label: "Agentic commerce",
+			hint: "let an AI agent shop on a buyer's behalf through the Agentic Commerce Protocol",
+		},
+	],
+};
+
+export const COMMERCE_OPERATIONS: Group = {
+	id: "operations",
+	title: "Operations",
+	kind: "multiselect",
+	choices: [
+		{
+			id: "fulfillments",
+			label: "Fulfilment",
+			hint: "what happens when the money is confirmed — ship it, grant it, hand it to the ERP",
+			required: true,
+		},
+		{
+			id: "shipping-zones",
+			label: "Shipping zones",
+			hint: "what a buyer can be charged for delivery, by country — required to quote shipping",
+			required: true,
+		},
+		{
+			id: "tax-regions",
+			label: "Tax",
+			hint: "VAT by country, declared in code so a fresh deploy is never tax-free",
+			required: true,
+		},
+		{
+			id: "notifications",
+			label: "Notifications",
+			hint: "order confirmations and shipping updates, queued and retried",
+			required: true,
+		},
+		{
+			id: "nft",
+			label: "Token instead of a parcel",
+			hint: "a buyer who would rather not have the object can take an NFT of it instead — same price, same order, nothing shipped. Needs a mint provider before it mints anything",
+			recommended: false,
+		},
+		{
+			id: "events",
+			label: "Webhooks",
+			hint: "deliver commerce events to subscribers with retries and dead-lettering",
+			recommended: true,
+		},
+		{
+			id: "workflows",
+			label: "Workflows",
+			hint: "multi-step operations that survive a crash mid-way",
+		},
+		{
+			id: "files",
+			label: "Files",
+			hint: "uploads — product images, a customer's logo for engraving",
+			recommended: true,
+		},
+		{
+			id: "merchants",
+			label: "Marketplace",
+			hint: "several sellers in one shop, with payouts",
+		},
+		{
+			id: "store",
+			label: "Store settings",
+			hint: "name, support address, public settings the storefront reads",
+			required: true,
+		},
+		{
+			id: "runtime",
+			label: "Cache and locking",
+			hint: "required — the kernel's cache and lock providers",
+			required: true,
+		},
+	],
+};
+
+/* The NFT delivery choice lives with the other operations plugins: it is how
+   an order leaves the shop, not a thing in the catalogue. */
+
+export const PAYMENT: Group = {
+	id: "payment",
+	title: "Payment rail",
+	intro: "Exactly one. Carrying two means every reader works out which half is live.",
+	kind: "select",
+	choices: [
+		{
+			id: "adyen",
+			label: "Adyen",
+			hint: "European rails, MobilePay, local methods",
+			env: [
+				{ key: "ADYEN_API_KEY", breaks: "the shop cannot take money", where: "Adyen Customer Area" },
+				{ key: "ADYEN_MERCHANT_ACCOUNT", breaks: "the same", where: "Adyen Customer Area" },
+				{ key: "ADYEN_HMAC_KEY", breaks: "webhooks cannot be verified, so no order becomes paid", where: "Adyen Customer Area" },
+				{ key: "ADYEN_ENVIRONMENT", breaks: "anything but live charges real customers on the test rail", plaintext: true, dev: "test" },
+				{ key: "ADYEN_LIVE_PREFIX", breaks: "live Checkout calls are rejected", where: "Adyen Customer Area" },
+			],
+		},
+		{
+			id: "stripe",
+			label: "Stripe",
+			hint: "the default almost everywhere else",
+			env: [
+				{ key: "STRIPE_SECRET_KEY", breaks: "the shop cannot take money", where: "Stripe dashboard" },
+			],
+		},
+	],
+};
+
+export const TAX: Group = {
+	id: "tax",
+	title: "Tax calculation",
+	kind: "select",
+	choices: [
+		{
+			id: "stripe-tax",
+			label: "Stripe Tax",
+			hint: "asked per basket, so an unregistered shop charges nothing and a registered one charges the buyer's own rate — no rate to declare and none to keep up to date",
+			recommended: true,
+		},
+		{
+			id: "declared",
+			label: "Declared rates",
+			hint: "VAT per country in code, editable in the panel — right for one or a few countries",
+		},
+		{
+			id: "taxjar",
+			label: "TaxJar",
+			hint: "US sales tax by jurisdiction",
+			env: [{ key: "TAXJAR_API_KEY", breaks: "no tax is calculated" }],
+		},
+		{
+			id: "avalara",
+			label: "Avalara",
+			hint: "enterprise tax across many jurisdictions",
+			env: [
+				{ key: "AVALARA_ACCOUNT_ID", breaks: "no tax is calculated" },
+				{ key: "AVALARA_LICENSE_KEY", breaks: "the same" },
+			],
+		},
+	],
+};
+
+export const CARRIERS: Group = {
+	id: "carriers",
+	title: "Carriers for calculated shipping rates",
+	intro: "Optional. Flat-rate shipping needs none of these.",
+	kind: "multiselect",
+	choices: [
+		{ id: "shippo", label: "Shippo", hint: "many carriers through one API", env: [{ key: "SHIPPO_API_KEY", breaks: "calculated rates fall back to flat" }] },
+		{ id: "easypost", label: "EasyPost", hint: "the same, US-leaning", env: [{ key: "EASYPOST_API_KEY", breaks: "calculated rates fall back to flat" }] },
+		{ id: "ups", label: "UPS", hint: "your own UPS account, for negotiated rates an aggregator cannot see", env: [{ key: "UPS_CLIENT_ID", breaks: "UPS rates are not quoted" }, { key: "UPS_CLIENT_SECRET", breaks: "the same" }] },
+		{ id: "fedex", label: "FedEx", hint: "your own FedEx account, for negotiated rates an aggregator cannot see", env: [{ key: "FEDEX_CLIENT_ID", breaks: "FedEx rates are not quoted" }, { key: "FEDEX_CLIENT_SECRET", breaks: "the same" }] },
+		{ id: "dhl-express", label: "DHL Express", hint: "international", env: [{ key: "DHL_API_KEY", breaks: "DHL rates are not quoted" }] },
+		{ id: "usps", label: "USPS", hint: "US domestic post — the cheapest way to ship a small parcel inside the US", env: [{ key: "USPS_CLIENT_ID", breaks: "USPS rates are not quoted" }, { key: "USPS_CLIENT_SECRET", breaks: "the same" }] },
+		{ id: "royal-mail", label: "Royal Mail", hint: "UK post, for a shop whose customers are mostly in Britain", env: [{ key: "ROYAL_MAIL_CLIENT_ID", breaks: "Royal Mail rates are not quoted" }] },
+		{ id: "aramex", label: "Aramex", hint: "the carrier to reach the Gulf and wider Middle East reliably", env: [{ key: "ARAMEX_API_KEY", breaks: "Aramex rates are not quoted" }] },
+		{ id: "doordash-drive", label: "DoorDash Drive", hint: "same-day local delivery", env: [{ key: "DOORDASH_DEVELOPER_ID", breaks: "DoorDash is not offered" }] },
+		{ id: "stuart", label: "Stuart", hint: "same-day courier, Europe", env: [{ key: "STUART_CLIENT_ID", breaks: "Stuart is not offered" }] },
+	],
+};
+
+export const ERP: Group = {
+	id: "erp",
+	title: "ERP",
+	intro: "Where a paid order goes after the shop.",
+	kind: "select",
+	choices: [
+		{ id: "none", label: "None", hint: "orders live in the shop", recommended: true },
+		{
+			id: "business-central",
+			label: "Microsoft Dynamics 365 Business Central",
+			hint: "a paid order becomes a sales order",
+			env: [
+				{ key: "BC_TENANT_ID", breaks: "paid orders never reach the ERP — the shop and the warehouse disagree", where: "Azure app registration" },
+				{ key: "BC_CLIENT_ID", breaks: "the same", where: "Azure app registration" },
+				{ key: "BC_CLIENT_SECRET", breaks: "the same", where: "Azure app registration" },
+				{ key: "BC_COMPANY_ID", breaks: "the same", where: "Business Central" },
+				{ key: "BC_ENVIRONMENT", breaks: "calls go to the wrong tenant environment", plaintext: true, dev: "production" },
+			],
+		},
+	],
+};
+
+/* -------------------------------------------------------------------------- */
+/* Platform                                                                    */
+/* -------------------------------------------------------------------------- */
+
+export const EMAIL: Group = {
+	id: "email",
+	title: "Email",
+	intro: "One transport for sign-in codes, magic links and order confirmations. Without it nobody can sign in, because every sign-in method proves an address.",
+	kind: "select",
+	choices: [
+		{
+			id: "cloudflare-email",
+			label: "Cloudflare Email",
+			hint: "the Worker's own binding — no API key to issue, store or rotate; Cloudflare writes the SPF, DKIM and DMARC records itself. Needs the domain onboarded once, and a Workers Paid plan to reach anyone but you",
+			packages: ["@saastemly/better-email"],
+			recommended: true,
+			env: [
+				{
+					key: "EMAIL_FROM",
+					breaks: "Cloudflare refuses a sender outside the onboarded domain",
+					plaintext: true,
+					where: "an address at a domain onboarded for Email Sending",
+				},
+			],
+		},
+		{
+			id: "resend",
+			label: "Resend",
+			hint: "an API key and a verified domain; the free tier is 3,000 a month. MailDev stands in locally either way",
+			packages: ["@saastemly/better-email"],
+			env: [
+				{ key: "RESEND_API_KEY", breaks: "no mail at all: nobody can sign in, no confirmations", where: "resend.com" },
+				{ key: "EMAIL_FROM", breaks: "Resend refuses an unverified sender", plaintext: true, where: "a domain verified at Resend" },
+			],
+		},
+	],
+};
+
+export const DNS: Group = {
+	id: "dns",
+	title: "DNS",
+	intro: "So the deploy writes the zone's records, not a person in a registrar's UI. The worker's own hostname is a Cloudflare custom domain and needs no record here; the mail sender's do.",
+	kind: "select",
+	choices: [
+		{
+			id: "cloudflare",
+			label: "Cloudflare",
+			hint: "the zone the shop's domain is in — the deploy writes the mail records so confirmations are not spam",
+			packages: ["@saastemly/better-dns"],
+			recommended: true,
+			env: [
+				{ key: "CLOUDFLARE_DNS_TOKEN", breaks: "the storefront records are never written; the domain does not reach the shop", where: "a token with Zone:DNS:Edit and Zone:Zone:Read" },
+			],
+		},
+		{
+			id: "simply",
+			label: "Simply.com",
+			hint: "for a zone that stays there — but then the worker cannot have a custom domain, so the shop has no hostname",
+			packages: ["@saastemly/better-dns"],
+			env: [{ key: "SIMPLY_API_KEY", breaks: "the storefront records are never written", where: "Simply control panel" }],
+		},
+		{ id: "none", label: "None", hint: "you write the mail records by hand, and a deploy does not mean mail is trusted" },
+	],
+};
+
+export const CONTENT: Group = {
+	id: "content",
+	title: "Content",
+	kind: "multiselect",
+	choices: [
+		{ id: "blogs", label: "Blog", hint: "posts with scheduling, drafts and a public slug", packages: ["@saastemly/better-blogs"], recommended: true },
+		{ id: "faqs", label: "FAQ", hint: "grouped, ordered, localized — with launch content you declare in code", packages: ["@saastemly/better-faqs"], recommended: true },
+	],
+};
+
+export const UI: Group = {
+	id: "ui",
+	title: "Interfaces",
+	kind: "multiselect",
+	choices: [
+		{
+			id: "admin",
+			label: "Generated storefront and panel",
+			hint: "better-admin-ui — every table becomes a screen at /api-dashboard, each caller seeing their own scope: a customer their orders, staff everything. Standard theming; one line to turn off once you have built your own",
+			packages: ["@saastemly/better-admin-ui"],
+			recommended: true,
+		},
+		{
+			id: "custom",
+			label: "Custom storefront kit",
+			hint: "better-auth-ui and better-commerce-ui — hooks, query options and shadcn components you host in your own app, for full freedom in theming and branding",
+			packages: ["@better-auth-ui/react", "@saastemly/better-commerce-ui"],
+		},
+	],
+};
+
+/** The order the wizard walks them in. */
+export const GROUPS: Group[] = [
+	SIGN_IN,
+	AUTH_PLUGINS,
+	COMMERCE_CATALOG,
+	COMMERCE_SALES,
+	COMMERCE_OPERATIONS,
+	PAYMENT,
+	TAX,
+	CARRIERS,
+	ERP,
+	EMAIL,
+	DNS,
+	CONTENT,
+	UI,
+];
+
+/** Every choice, by id, for lookups the generator makes. */
+export const CHOICES = new Map<string, Choice>(
+	GROUPS.flatMap((group) => group.choices.map((choice) => [choice.id, choice] as const)),
+);