@raisenow/tamaro-cli 3.1.0-dev.0 → 3.1.0-dev.1

package/README.md

@@ -282,7 +282,16 @@ pnpx @raisenow/tamaro-cli update-epms --tag WEB-123
 
 ## `validate`
 
-Validate the current configuration and fail on known issues such as invalid email templates.
+Validate the current configuration and fail on known issues such as invalid
+email templates, invalid `.env` values, or RaiseNow-generated tax receipts
+enabled without an uploaded organisation template.
+
+When `autogeneratedDonationReceiptEnabled` (or
+`autogenerated_donation_receipt_enabled`) is `true`, this command authenticates
+with EPMS (browser login or client credentials) and checks that a donation
+tax-receipt PDF template exists for each configured account. See the
+[Confluence guide](https://raisenow.atlassian.net/wiki/spaces/PD/pages/6231687230/Tamaro+CLI+Commands#Tax-receipt-validation--how-CS-resolves-it)
+for how to resolve a failed check.
 
 ### Example
 

package/dist/cli.js

@@ -12,9 +12,9 @@ import ky from "ky";
 import { createServer } from "node:http";
 import open from "open";
 import { globSync } from "glob";
+import { codeFrameColumns } from "@babel/code-frame";
 import Handlebars from "handlebars";
 import helpers from "handlebars-helpers";
-import { codeFrameColumns } from "@babel/code-frame";
 import { config, parse } from "dotenv";
 import { getPortPromise } from "portfinder";
 import prompts from "prompts";
@@ -280,6 +280,8 @@ var EpmsClient = class EpmsClient {
 	#cacheKey;
 	#epmsClient;
 	#authType;
+	/** In-memory account UUID → organisation UUID cache for this client instance. */
+	#organisationIdByAccountUuid = /* @__PURE__ */ new Map();
 	/**
 	* Creates an instance of EpmsClient.
 	*
@@ -308,14 +310,25 @@ var EpmsClient = class EpmsClient {
 		return this.#epmsClient.get("users/myself").json().then((response) => myselfSchema.parse(response));
 	}
 	async getOrganisationIdByAccountUuid(accountUuid) {
+		const cached = this.#organisationIdByAccountUuid.get(accountUuid);
+		if (cached) return cached;
 		try {
 			const organisationUuid = (await this.#epmsClient.get(`accounts/${accountUuid}`).json()).organisation.uuid;
 			if (!organisationUuid) throw new Error("Organisation UUID not found in response");
+			this.#organisationIdByAccountUuid.set(accountUuid, organisationUuid);
 			return organisationUuid;
 		} catch (error) {
 			throw new Error(`Organisation UUID not found for account UUID: ${accountUuid}`, { cause: error });
 		}
 	}
+	async listOrganisationFiles(organisationUuid) {
+		try {
+			const response = await this.#epmsClient.get(`organisations/${organisationUuid}/files`).json();
+			return Array.isArray(response) ? response : response.data ?? [];
+		} catch (error) {
+			throw new Error(`Failed to list organisation files for organisation UUID: ${organisationUuid}`, { cause: error });
+		}
+	}
 	async updateTamaro(configName, tag, json) {
 		return this.#epmsClient.put(`products/tamaro/${configName}/tags/${tag}`, { json }).json();
 	}
@@ -443,6 +456,99 @@ const assertArchiveTargetDoesNotExist = (archiveTarget) => {
 	if (fs.existsSync(archiveTarget)) halt(`Archive target already exists: ${archiveTarget}. Please remove it first.`);
 };
 //#endregion
+//#region src/lib/validators/validateDonationReceiptTemplates.ts
+/** Internal docs validation guide for CS */
+const DONATION_RECEIPT_VALIDATION_GUIDE_URL = "https://raisenow.atlassian.net/wiki/spaces/PD/pages/6231687230/Tamaro+CLI+Commands#Donation-tax-receipts";
+const FLAG_KEYS = ["autogeneratedDonationReceiptEnabled", "autogenerated_donation_receipt_enabled"];
+/**
+* Resolve which config.yml key enabled RaiseNow-generated donation tax
+* receipts. Supports both camelCase and snake_case keys used in customer
+* configs; returns undefined when the option is not strictly `true`.
+*/
+const isAutogeneratedDonationReceiptEnabled = (rawConfig) => {
+	if (!rawConfig || typeof rawConfig !== "object") return;
+	const config = rawConfig;
+	for (const key of FLAG_KEYS) if (config[key] === true) return key;
+};
+/**
+* Check that a donation tax receipt PDF template exists for the account in
+* the organisation files list. Matches Hub storage layout:
+* `{accountUuid}/donation-receipt-templates/{language}.pdf`
+*/
+const donationReceiptTemplateExists = (files, accountUuid) => {
+	const prefix = `${accountUuid}/donation-receipt-templates/`;
+	return files.some((file) => file.name.startsWith(prefix) && file.name.endsWith(".pdf") && file.name.slice(prefix.length).length > 0 && !file.name.slice(prefix.length).includes("/"));
+};
+/**
+* Locate the line of a top-level `key:` assignment in the config.yml source,
+* so the error can be rendered as a code frame pointing at the value.
+*/
+const findKeyLocation$1 = (source, key) => {
+	const lines = source.split("\n");
+	const assignment = new RegExp(String.raw`^\s*${key}\s*:`);
+	const index = lines.findIndex((line) => assignment.test(line));
+	if (index === -1) return;
+	const line = index + 1;
+	const valueStart = lines[index].indexOf(":") + 1;
+	return {
+		end: {
+			column: lines[index].length,
+			line
+		},
+		start: {
+			column: valueStart + 1,
+			line
+		}
+	};
+};
+/**
+* Format an error for a `key:` assignment as a code frame pointing at the
+* value, so it looks fancy like this:
+*
+* config.yml:51
+* 50 | show_stored_customer_donation_receipt: true
+* 51 | autogeneratedDonationReceiptEnabled: true
+*    |                                      ^^^^ No donation tax receipt PDF template found…
+*/
+const formatError$1 = (configYmlPath, source, key, message) => {
+	const location = findKeyLocation$1(source, key);
+	if (!location) return `${configYmlPath}: ${key}: ${message}`;
+	const frame = codeFrameColumns(source, location, {
+		forceColor: true,
+		highlightCode: true,
+		message
+	});
+	return `\n${configYmlPath}:${location.start.line}\n${frame}`;
+};
+/**
+* Validate that RaiseNow-generated tax receipts are only enabled when each
+* configured EPMS account has a donation tax receipt PDF template uploaded.
+*/
+const validateDonationReceiptTemplates = async (configYmlPath) => {
+	if (!fs.existsSync(configYmlPath)) return [];
+	const source = fs.readFileSync(configYmlPath, "utf8");
+	const flagKey = isAutogeneratedDonationReceiptEnabled(yaml.load(source));
+	if (!flagKey) return [];
+	const { accountUuidProd, accountUuidStage } = loadTamaroMetadataFromConfig(configYmlPath);
+	const errors = [];
+	const environments = [{
+		accountUuid: accountUuidStage,
+		env: "stage",
+		label: "Stage"
+	}, {
+		accountUuid: accountUuidProd,
+		env: "prod",
+		label: "Prod"
+	}];
+	for (const { accountUuid, env, label } of environments) {
+		if (!accountUuid) continue;
+		const epmsClient = epmsAuthenticate(env);
+		const organisationUuid = await epmsClient.getOrganisationIdByAccountUuid(accountUuid);
+		if (!donationReceiptTemplateExists(await epmsClient.listOrganisationFiles(organisationUuid), accountUuid)) errors.push(formatError$1(configYmlPath, source, flagKey, `No donation tax receipt PDF template found for the ${label} account (${accountUuid}). See: ${DONATION_RECEIPT_VALIDATION_GUIDE_URL}`));
+	}
+	return errors;
+};
+//#endregion
 //#region src/lib/validators/validateEmailTemplates.ts
 /**
 * Register custom Handlebars helpers - the same, which are used in the Email Service.
@@ -564,21 +670,16 @@ const TAMARO_CORE_REGISTRY_URL = "https://registry.npmjs.org/@raisenow/tamaro-co
 * Check that the configured version exists for "@raisenow/tamaro-core" on npm:
 * as a dist-tag (e.g. "latest", "lts_2026"), an exact version, or a partial
 * version ("2", "2.15") matching at least one published version.
-*
-* Returns undefined when the registry is unreachable, so offline builds are
-* not blocked by this check.
 */
 const coreVersionExists = async (version) => {
-	try {
-		const response = await fetch(TAMARO_CORE_REGISTRY_URL, { headers: { accept: "application/vnd.npm.install-v1+json" } });
-		if (!response.ok) return;
-		const metadata = await response.json();
-		const distTags = Object.keys(metadata["dist-tags"] ?? {});
-		const versions = Object.keys(metadata.versions ?? {});
-		return distTags.includes(version) || versions.includes(version) || versions.some((existing) => existing.startsWith(`${version}.`));
-	} catch {
-		return;
-	}
+	const metadata = await ky.get(TAMARO_CORE_REGISTRY_URL, {
+		headers: { accept: "application/vnd.npm.install-v1+json" },
+		retry: 0,
+		timeout: DEFAULT_HTTP_TIMEOUT
+	}).json();
+	const distTags = Object.keys(metadata["dist-tags"] ?? {});
+	const versions = Object.keys(metadata.versions ?? {});
+	return distTags.includes(version) || versions.includes(version) || versions.some((existing) => existing.startsWith(`${version}.`));
 };
 /**
 * Locate the line of a `KEY=` assignment in the .env source, so the error can
@@ -652,7 +753,11 @@ const validateEnv = async (dotEnvPath) => {
 * deployed.
 */
 const validate = async () => {
-	const errors = [...await validateEnv(".env"), ...validateEmailTemplates(globSync("email-config/templates/**/*.hbs").toSorted())];
+	const errors = [
+		...await validateEnv(".env"),
+		...validateEmailTemplates(globSync("email-config/templates/**/*.hbs").toSorted()),
+		...await validateDonationReceiptTemplates("config.yml")
+	];
 	if (errors.length > 0) {
 		logError("❌ Validation failed with the following errors:");
 		console.log(errors.map((el) => el.toString()).join("\n"));
@@ -1329,7 +1434,7 @@ const promptBucketTamaroEmailConfig = async () => {
 //#endregion
 //#region package.json
 var name = "@raisenow/tamaro-cli";
-var version = "3.1.0-dev.0";
+var version = "3.1.0-dev.1";
 //#endregion
 //#region src/cli.ts
 const cli = createCommand().name(name).description("CLI for Tamaro Customer Configurations development").version(version, "-v, --version");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raisenow/tamaro-cli",
-  "version": "3.1.0-dev.0",
+  "version": "3.1.0-dev.1",
   "author": {
     "name": "RaiseNow",
     "email": "development@raisenow.com"