@saastemly/voidcommerce 0.6.0 → 0.8.0

package/src/deploy/secrets.ts

@@ -141,6 +141,26 @@ export function plaintextSecretNames(root: string): string[] {
 	return bare;
 }
 
+/**
+ * The declared values that are NOT encrypted, with their values.
+ *
+ * Separate from `plaintextSecretNames` on purpose: names are safe to print
+ * and values never are, so the function that returns values is the one you
+ * have to go looking for.
+ */
+export function plaintextSecretEntries(root: string): Array<{ name: string; value: string }> {
+	const path = join(root, SECRETS_FILE);
+	if (!existsSync(path)) return [];
+	const out: Array<{ name: string; value: string }> = [];
+	for (const line of readFileSync(path, "utf8").split("\n")) {
+		const match = /^\s*([A-Z][A-Z0-9_]*)\s*=\s*(.*)$/.exec(line);
+		if (!match || match[1]!.startsWith("DOTENV_")) continue;
+		const value = match[2]!.trim().replace(/^['"]|['"]$/g, "");
+		if (value && value !== "unset" && !value.startsWith("encrypted:")) out.push({ name: match[1]!, value });
+	}
+	return out;
+}
+
 export interface DecryptedSecrets {
 	/** A temp file in `.env` format, for `wrangler deploy --secrets-file`. */
 	path: string;
@@ -230,6 +250,7 @@ export async function secretsCommand(project: Project, args: string[]): Promise<
 
 	if (args.includes("--init")) return initSecrets(project);
 	if (args[0] === "set") return setSecretValue(project, args.slice(1));
+	if (args.includes("--sync")) return syncSecrets(project);
 
 	if (!existsSync(join(root, SECRETS_FILE))) {
 		console.log(
@@ -446,3 +467,50 @@ function upsertLine(path: string, name: string, value: string): void {
 	const pattern = new RegExp(`^\\s*${name}\\s*=.*$`, "m");
 	writeFileSync(path, pattern.test(body) ? body.replace(pattern, `${name}=${value}`) : `${body.replace(/\n*$/, "\n")}${name}=${value}\n`);
 }
+
+
+/**
+ * `vc secrets --sync` — add the keys this shop needs and does not declare.
+ *
+ * The manifest changes: a carrier is swapped, a plugin is added, and the set
+ * of required secrets moves with it. Without this the only way to declare a
+ * new one is to remember its exact name and type it in by hand, which is how
+ * a shop ends up deploying without a key it needed.
+ *
+ * Strictly additive. It never deletes a key that is no longer required,
+ * because "no longer required" and "safe to throw away" are different
+ * claims — the value may still be wanted, and it is not this command's to
+ * destroy. Extras are reported instead.
+ */
+async function syncSecrets(project: Project): Promise<number> {
+	const root = project.root;
+	const path = join(root, SECRETS_FILE);
+	if (!existsSync(path)) {
+		console.error(`\nvc: no ${SECRETS_FILE} yet. \`vc secrets --init\` writes one.\n`);
+		return 1;
+	}
+	const required = allEnvKeys(project.manifest).filter((key) => !key.plaintext);
+	const declared = declaredSecretNames(root);
+	const missing = required.filter((key) => !declared.has(key.key));
+	const extra = [...declared].filter((name) => !required.some((key) => key.key === name));
+
+	if (missing.length > 0) {
+		const body = readFileSync(path, "utf8").replace(/\n*$/, "\n");
+		const added = missing.flatMap((key) => ["", `# ${key.breaks}${key.where ? ` — from: ${key.where}` : ""}`, `${key.key}=unset`]);
+		writeFileSync(path, `${body}${added.join("\n")}\n`);
+		console.log(`\n${color.green("+")} ${missing.length} key${missing.length === 1 ? "" : "s"} added to ${SECRETS_FILE}, as \`unset\`:\n`);
+		for (const key of missing) console.log(`    ${color.cyan(`vc secrets set ${key.key}`)}  ${color.dim(key.where ?? "")}`);
+		console.log("");
+	} else {
+		console.log(`\n${color.green("✓")} every secret this shop needs is already declared.\n`);
+	}
+
+	if (extra.length > 0) {
+		console.log(
+			`${color.yellow("!")} ${extra.length} declared key${extra.length === 1 ? " is" : "s are"} no longer required by this shop:\n` +
+				`    ${extra.join("\n    ")}\n\n` +
+				color.dim("  Left alone — they cost nothing, and deleting a value you may still want\n  is not this command's call. Remove them by hand when you are sure.\n"),
+		);
+	}
+	return 0;
+}

package/src/generate/auth.ts

@@ -49,6 +49,20 @@ const social = (manifest: Manifest, id: string, envPrefix: string) =>
 		? `			${id}: { clientId: must(env, "${envPrefix}_CLIENT_ID"), clientSecret: must(env, "${envPrefix}_CLIENT_SECRET") },`
 		: null;
 
+/**
+ * Carriers with a provider behind them, and whether each needs `lib/shipping.ts`.
+ *
+ * Exported because `generate/index.ts` has to know which shops get that file,
+ * and a second hand-maintained list of carrier ids WILL drift from this one —
+ * it already did: adding Royal Mail here left the file ungenerated, so the
+ * generated `auth.ts` imported a price table that did not exist.
+ *
+ * The token needs nothing: no origin, no tariff. Everything else needs one or
+ * the other, so the rule is simply "any carrier but the token".
+ */
+export const WIRED_CARRIERS = ["royal-mail", "dhl-express", "shippo", "easypost", "ups", "fedex", "nft"] as const;
+export const needsShippingConfig = (id: string): boolean => WIRED_CARRIERS.includes(id as never) && id !== "nft";
+
 export function renderAuthTs(manifest: Manifest): string {
 	const { shop } = manifest;
 	const lines: Line[] = [];
@@ -68,6 +82,14 @@ export function renderAuthTs(manifest: Manifest): string {
 	const CARRIER_CALLS: Record<string, { call: string; label: string; import: string }> = {
 		// Every real carrier needs the ORIGIN it ships from, which is shop data
 		// rather than a credential — so it lives in an owned lib/shipping.ts.
+		"royal-mail": {
+			label: "Royal Mail",
+			// No `from`: Click & Drop posts from the account's registered
+			// address, so an origin here would be ignored. `services` is the
+			// price table in lib/shipping.ts, because nothing quotes Royal Mail.
+			call: `royalMailProvider({ apiKey: must(env, "CLICK_DROP_AUTH_KEY"), services: royalMailServices, currency: "${shop.currency}", carrierName: "Royal Mail" })`,
+			import: `import { royalMailProvider } from "@saastemly/better-commerce/providers/royal-mail";`,
+		},
 		"dhl-express": {
 			label: "DHL Express",
 			call: `dhlExpressProvider({ apiKey: must(env, "DHL_API_KEY"), apiSecret: must(env, "DHL_API_SECRET"), accountNumber: must(env, "DHL_ACCOUNT_NUMBER"), from: shipFrom })`,
@@ -101,8 +123,18 @@ export function renderAuthTs(manifest: Manifest): string {
 	};
 	const carriers = Object.keys(CARRIER_CALLS).filter((id) => has(manifest, id));
 	const carrierImports = carriers.map((id) => CARRIER_CALLS[id]!.import);
-	// The token needs no origin; every other carrier does.
-	if (carriers.some((id) => id !== "nft")) carrierImports.push(`import { shipFrom } from "./lib/shipping.ts";`);
+	// One import from lib/shipping.ts, naming only what is actually used —
+	// an unused binding is a type error in a shop with `noUnusedLocals`.
+	//
+	// The token needs no origin. Royal Mail needs no origin either: Click &
+	// Drop posts from the address registered on the account, so a `from` here
+	// would be silently ignored. It needs the price table instead, because
+	// nothing quotes Royal Mail.
+	const shipping = [
+		...(carriers.some((id) => id !== "nft" && id !== "royal-mail") ? ["shipFrom"] : []),
+		...(carriers.includes("royal-mail") ? ["royalMailServices"] : []),
+	];
+	if (shipping.length > 0) carrierImports.push(`import { ${shipping.join(", ")} } from "./lib/shipping.ts";`);
 	const wantsNft = has(manifest, "nft");
 	// One bridge for every carrier: which ships is decided by whose rate the
 	// buyer paid for, so a token order mints and a parcel order posts.

package/src/generate/index.ts

@@ -3,7 +3,7 @@ import { existsSync, lstatSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { CHOICES } from "../catalog";
 import { MANIFEST_FILE, type Manifest, has, isSingleApp, oneOrigin, packagesOf, specifier, workerHosts, writeManifest, zone } from "../manifest";
-import { renderAuthTs } from "./auth";
+import { renderAuthTs, WIRED_CARRIERS, needsShippingConfig } from "./auth";
 import {
 	envSummary,
 	renderEnvExample,
@@ -189,8 +189,10 @@ async function generateApi(root: string, dir: string, manifest: Manifest, result
 	if (has(manifest, "nft")) {
 		await put(root, at("lib/mint.ts"), renderMintTs(), result, own);
 	}
-	// Any carrier but the token quotes against an origin, which is shop data.
-	if (["dhl-express", "shippo", "easypost", "ups", "fedex"].some((id) => has(manifest, id))) {
+	// Any carrier but the token needs shop data of its own — an origin to quote
+	// against, or a price table. The list lives with the carriers themselves so
+	// it cannot drift from them.
+	if (WIRED_CARRIERS.some((id) => needsShippingConfig(id) && has(manifest, id))) {
 		await put(root, at("lib/shipping.ts"), renderShippingTs(manifest), result, own);
 	}
 	if (has(manifest, "business-central")) {
@@ -372,9 +374,17 @@ async function generateStrictRoot(root: string, manifest: Manifest, result: Gene
 		root,
 		".husky/pre-commit",
 		`#!/usr/bin/env sh
-# Generated by \`vc init\`. Refuses a commit that would put a secret in the
-# clear in .env.secrets — which cannot be undone by a later commit,
-# because the value stays in the history.
+# Generated by \`vc init\`.
+#
+# Encrypts any value sitting in the clear in .env.secrets, and re-stages the
+# file so the COMMIT carries the ciphertext rather than what you staged.
+# Encryption needs only the public key in that file, so this needs no
+# credential and works on a fresh clone.
+#
+# It refuses only when it cannot fix the problem itself: no key yet
+# (\`vc keys --init\`), or a .env.keys that is not gitignored. A secret
+# committed in the clear cannot be un-committed — the value stays in the
+# history and has to be treated as burned.
 bunx vc guard
 `,
 		result,

package/src/generate/support.ts

@@ -274,13 +274,22 @@ export async function destinationFor(orderId: string): Promise<string | null> {
  * deploy, so both are marked rather than left blank.
  */
 export function renderShippingTs(manifest: Manifest): string {
-	return `import type { DeliveryAddress } from "@saastemly/better-commerce/providers/delivery";
+	const royalMail = has(manifest, "royal-mail");
+	// Royal Mail posts from the address registered on the Click & Drop account,
+	// so an origin here would be ignored. Only carriers that QUOTE need one.
+	const origin = ["dhl-express", "shippo", "easypost", "ups", "fedex"].some((id) => has(manifest, id));
 
+	const imports = [
+		...(origin ? [`import type { DeliveryAddress } from "@saastemly/better-commerce/providers/delivery";`] : []),
+		...(royalMail ? [`import type { RoyalMailService } from "@saastemly/better-commerce/providers/royal-mail";`] : []),
+	];
+
+	const originBlock = `
 /**
  * The address every parcel is quoted and shipped FROM.
  *
- * TODO VERIFY: this is a placeholder. A carrier quotes against it, and DHL
- * refuses a shipment whose origin has no \`name\` and \`phone\`.
+ * TODO VERIFY: this is a placeholder. A carrier quotes against it, and most
+ * refuse a shipment whose origin has no \`name\` and \`phone\`.
  */
 export const shipFrom: DeliveryAddress = {
 	name: "${manifest.shop.name}",
@@ -291,6 +300,8 @@ export const shipFrom: DeliveryAddress = {
 	phone: "TODO VERIFY: +44…",
 };
 `;
+
+	return `${imports.join("\n")}\n${origin ? originBlock : ""}${royalMail ? ROYAL_MAIL_SERVICES() : ""}`;
 }
 
 export function renderErpTs(): string {
@@ -320,3 +331,56 @@ export const erpFulfillment = (currency: string): FulfillmentProvider =>
 	}).fulfillment();
 `;
 }
+
+
+/**
+ * Royal Mail's price table — YOUR prices, because nothing will quote them.
+ *
+ * This is the one carrier here that cannot be asked what postage costs. No
+ * Royal Mail API quotes rates: not Click & Drop, not Shipping V3, not
+ * anything on the developer portal. Click & Drop imports orders and prints
+ * labels; postage is charged afterwards at whatever your OBA agreement says.
+ *
+ * So the shop quotes from this table, and the table has to match the rate
+ * card on your account or you will undercharge every order and find out at
+ * the invoice. The codes below are real Royal Mail service codes; the prices
+ * are NOT — they are placeholders, in pence.
+ */
+const ROYAL_MAIL_SERVICES = (): string => `
+/**
+ * What this shop charges for Royal Mail, by total parcel weight.
+ *
+ * TODO VERIFY: every \`amount\` below is a placeholder in pence. Replace them
+ * with your own OBA rate card — Click & Drop → Settings → Shipping services
+ * lists exactly which services your account has, and the codes here must be
+ * among them. Service codes are account-specific: the published list is from
+ * 2021 and Royal Mail warn that "available services are unique to your OBA
+ * account and individual service agreements".
+ *
+ * The band whose \`maxGrams\` first covers the parcel wins, so order does not
+ * matter. A parcel heavier than every band gets no rate at all rather than a
+ * wrong one, and Click & Drop refuses anything over 30 kg.
+ */
+export const royalMailServices: RoyalMailService[] = [
+	{
+		code: "TPN24",
+		name: "Tracked 24",
+		estimatedDays: 1,
+		bands: [
+			{ maxGrams: 1000, amount: 0 /* TODO VERIFY */ },
+			{ maxGrams: 2000, amount: 0 /* TODO VERIFY */ },
+			{ maxGrams: 5000, amount: 0 /* TODO VERIFY */ },
+		],
+	},
+	{
+		code: "TPS48",
+		name: "Tracked 48",
+		estimatedDays: 2,
+		bands: [
+			{ maxGrams: 1000, amount: 0 /* TODO VERIFY */ },
+			{ maxGrams: 2000, amount: 0 /* TODO VERIFY */ },
+			{ maxGrams: 5000, amount: 0 /* TODO VERIFY */ },
+		],
+	},
+];
+`;