@cerios/salesforce-sobjectly 1.1.0 → 1.2.0

package/dist/{codegen-Bylrt2Ju.cjs → codegen-Daud-Grz.cjs}

@@ -1,4 +1,4 @@
-const require_sf_cli = require("./sf-cli-R6LHwqoo.cjs");
+const require_sf_cli = require("./sf-cli-S2BrCbik.cjs");
 let node_crypto = require("node:crypto");
 let node_fs = require("node:fs");
 let node_fs_promises = require("node:fs/promises");
@@ -444,15 +444,28 @@ var CodegenConfigError = class extends Error {
 		this.problems = problems;
 	}
 };
-/** The env-variable options each env-based auth type accepts. */
+/** The options each auth type accepts: its credential keys, then the deprecated `*Env` keys. */
 const AUTH_OPTIONS = {
 	clientCredentials: [
+		"loginUrl",
+		"clientId",
+		"clientSecret",
 		"loginUrlEnv",
 		"clientIdEnv",
 		"clientSecretEnv"
 	],
-	accessToken: ["accessTokenEnv", "instanceUrlEnv"],
+	accessToken: [
+		"accessToken",
+		"instanceUrl",
+		"accessTokenEnv",
+		"instanceUrlEnv"
+	],
 	jwtBearer: [
+		"loginUrl",
+		"clientId",
+		"username",
+		"privateKey",
+		"privateKeyPath",
 		"loginUrlEnv",
 		"clientIdEnv",
 		"usernameEnv",
@@ -461,6 +474,17 @@ const AUTH_OPTIONS = {
 	],
 	sfCli: ["targetOrg"]
 };
+/** The deprecated `*Env` auth options, each mapped to the credential key that replaces it. */
+const DEPRECATED_AUTH_OPTIONS = {
+	loginUrlEnv: "loginUrl",
+	clientIdEnv: "clientId",
+	clientSecretEnv: "clientSecret",
+	accessTokenEnv: "accessToken",
+	instanceUrlEnv: "instanceUrl",
+	usernameEnv: "username",
+	privateKeyEnv: "privateKey",
+	privateKeyPathEnv: "privateKeyPath"
+};
 const PICKLIST_MODES = [
 	"union",
 	"string",
@@ -572,8 +596,17 @@ function validateAuth(value, { json, problem }) {
 		problem(`auth.type: must be one of ${Object.keys(AUTH_OPTIONS).join(", ")}, got ${show(type)}.`);
 		return;
 	}
-	for (const [key, option] of Object.entries(rest)) if (!allowed.includes(key)) problem(`auth.${key}: not an option of "${String(type)}". Valid options: ${allowed.join(", ")}.`);
-	else if (typeof option !== "string" || option.length === 0) problem(`auth.${key}: must be a non-empty string, got ${show(option)}.`);
+	for (const [key, option] of Object.entries(rest)) if (!allowed.includes(key)) {
+		const valid = allowed.filter((name) => !(name in DEPRECATED_AUTH_OPTIONS));
+		problem(`auth.${key}: not an option of "${String(type)}". Valid options: ${valid.join(", ")}.`);
+	} else validateAuthOption(key, option, rest, problem);
+}
+function validateAuthOption(key, option, setting, problem) {
+	const replacement = DEPRECATED_AUTH_OPTIONS[key];
+	if (replacement !== void 0 && replacement in setting) problem(`auth.${key}: use either ${replacement} or ${key}, not both.`);
+	else if (replacement !== void 0) {
+		if (typeof option !== "string" || option.length === 0) problem(`auth.${key}: must be a non-empty string, got ${show(option)}.`);
+	} else if (option !== void 0 && typeof option !== "string") problem(`auth.${key}: must be a string, got ${show(option)}.`);
 }
 function show(value) {
 	if (value === void 0) return "undefined";
@@ -585,24 +618,6 @@ function show(value) {
 	}
 }
 //#endregion
-//#region src/codegen/config.ts
-/**
-* Type-checks a `sobjectly.config.ts`. The listed `sobjects` become a literal union, so a typo in
-* a per-sObject option is a compile error:
-*
-* ```ts
-* export default defineConfig({
-* 	apiVersion: "v66.0",
-* 	output: "src/generated/sobjects.ts",
-* 	sobjects: ["Account", "Contact"],
-* 	excludeCreateFields: { Acount: ["Name"] }, // ❌ "Acount" is not in sobjects
-* });
-* ```
-*/
-function defineConfig(config) {
-	return config;
-}
-//#endregion
 //#region src/codegen/load-config.ts
 /** Config file names, in lookup order. */
 const CONFIG_FILE_NAMES = [
@@ -654,25 +669,50 @@ function readJson(path) {
 	}
 }
 //#endregion
+//#region src/codegen/config.ts
+/**
+* Type-checks a `sobjectly.config.ts`. The listed `sobjects` become a literal union, so a typo in
+* a per-sObject option is a compile error:
+*
+* ```ts
+* export default defineConfig({
+* 	apiVersion: "v66.0",
+* 	output: "src/generated/sobjects.ts",
+* 	sobjects: ["Account", "Contact"],
+* 	excludeCreateFields: { Acount: ["Name"] }, // ❌ "Acount" is not in sobjects
+* });
+* ```
+*/
+function defineConfig(config) {
+	return config;
+}
+//#endregion
 //#region src/codegen/init.ts
 const SOBJECT_NAME = /^[A-Za-z][A-Za-z0-9_]*$/;
 const NPM_SCRIPT = "sobjects:generate";
-/** The environment variables each auth type reads by default. */
-const AUTH_ENV_VARS = {
+/** The credential keys `init` writes per auth type, each with the environment variable it suggests. */
+const AUTH_FIELDS = {
 	clientCredentials: [
-		"SF_LOGIN_URL",
-		"SF_CLIENT_ID",
-		"SF_CLIENT_SECRET"
+		["loginUrl", "SF_LOGIN_URL"],
+		["clientId", "SF_CLIENT_ID"],
+		["clientSecret", "SF_CLIENT_SECRET"]
 	],
-	accessToken: ["SF_ACCESS_TOKEN", "SF_INSTANCE_URL"],
+	accessToken: [["accessToken", "SF_ACCESS_TOKEN"], ["instanceUrl", "SF_INSTANCE_URL"]],
 	jwtBearer: [
-		"SF_LOGIN_URL",
-		"SF_CLIENT_ID",
-		"SF_USERNAME",
-		"SF_PRIVATE_KEY_PATH"
+		["loginUrl", "SF_LOGIN_URL"],
+		["clientId", "SF_CLIENT_ID"],
+		["username", "SF_USERNAME"],
+		["privateKeyPath", "SF_PRIVATE_KEY_PATH"]
 	],
 	sfCli: []
 };
+/** The environment variables the config written by `init` reads, per auth type. */
+const AUTH_ENV_VARS = {
+	clientCredentials: AUTH_FIELDS.clientCredentials.map(([, envName]) => envName),
+	accessToken: AUTH_FIELDS.accessToken.map(([, envName]) => envName),
+	jwtBearer: AUTH_FIELDS.jwtBearer.map(([, envName]) => envName),
+	sfCli: []
+};
 const AUTH_CHOICES = [
 	{
 		value: "clientCredentials",
@@ -831,7 +871,6 @@ function renderJsonConfig(answers) {
 	return `${JSON.stringify(config, null, "	")}\n`;
 }
 function renderTypeScriptConfig(answers) {
-	const envVars = AUTH_ENV_VARS[answers.auth];
 	const sobjects = answers.sobjects.map((name) => JSON.stringify(name)).join(", ");
 	return [
 		"import { defineConfig } from \"@cerios/salesforce-sobjectly/codegen\";",
@@ -843,26 +882,38 @@ function renderTypeScriptConfig(answers) {
 		`\toutput: ${JSON.stringify(answers.output)},`,
 		"	// The sObjects to generate types for.",
 		`\tsobjects: [${sobjects}],`,
-		`\t// ${authComment(answers.auth, envVars)}`,
+		`\t// ${authComment(answers.auth)}`,
 		`\tauth: ${renderAuth(answers)},`,
 		`\tpicklists: ${JSON.stringify(answers.picklists)},`,
 		"});",
 		""
 	].join("\n");
 }
+/** The JSON auth setting: credentials are `"${NAME}"` placeholders, read from the environment. */
 function authSetting(answers) {
-	return answers.auth === "sfCli" && answers.targetOrg ? {
+	if (answers.auth === "sfCli") return answers.targetOrg ? {
 		type: "sfCli",
 		targetOrg: answers.targetOrg
-	} : { type: answers.auth };
+	} : { type: "sfCli" };
+	const fields = AUTH_FIELDS[answers.auth].map(([key, envName]) => [key, `\${${envName}}`]);
+	return {
+		type: answers.auth,
+		...Object.fromEntries(fields)
+	};
 }
+/** The TypeScript auth setting: credentials are read with `process.env`. */
 function renderAuth(answers) {
-	const setting = authSetting(answers);
-	const targetOrg = setting.targetOrg ? `, targetOrg: ${JSON.stringify(setting.targetOrg)}` : "";
-	return `{ type: ${JSON.stringify(setting.type)}${targetOrg} }`;
+	if (answers.auth === "sfCli") return `{ type: "sfCli"${answers.targetOrg ? `, targetOrg: ${JSON.stringify(answers.targetOrg)}` : ""} }`;
+	const fields = AUTH_FIELDS[answers.auth].map(([key, envName]) => `\t\t${key}: process.env.${envName},`);
+	return [
+		"{",
+		`\t\ttype: ${JSON.stringify(answers.auth)},`,
+		...fields,
+		"	}"
+	].join("\n");
 }
-function authComment(auth, envVars) {
-	return auth === "sfCli" ? "Uses an org you are logged into with the Salesforce CLI (sf org login web)." : `Reads ${formatList(envVars)} from the environment.`;
+function authComment(auth) {
+	return auth === "sfCli" ? "Uses an org you are logged into with the Salesforce CLI (sf org login web)." : "Fill these in from process.env (any variable names), a secret store or elsewhere. Keep secrets out of this file.";
 }
 async function maybeUpdateEnvExample(options, auth) {
 	const path = (0, node_path.join)(options.cwd, ".env.example");
@@ -912,9 +963,10 @@ function printNextSteps(log, answers, scriptAdded, cwd) {
 		"Next steps:",
 		cli ? `  1. Log in with the Salesforce CLI: sf org login web${answers.targetOrg ? ` --alias ${answers.targetOrg}` : " --set-default"}` : `  1. Put ${formatList(AUTH_ENV_VARS[answers.auth])} in a .env file${envIgnored ? "" : " (and add .env to .gitignore)"}.`,
 		`  2. Generate the types: ${command}`,
-		"  3. Use them:",
+		"  3. Use them, logging in with the config's auth:",
+		"       import { loadAuth } from \"@cerios/salesforce-sobjectly/codegen\";",
 		`       import { API_VERSION, type SObjectRegistry } from "./${answers.output.replace(/\.(ts|mts|cts)$/, "")}";`,
-		"       const sf = new SalesforceClient<SObjectRegistry>({ apiVersion: API_VERSION, auth });"
+		"       const sf = new SalesforceClient<SObjectRegistry>({ apiVersion: API_VERSION, auth: await loadAuth() });"
 	].join("\n"));
 }
 function formatList(items) {
@@ -1081,7 +1133,7 @@ async function buildSource(input, options) {
 	const env = options.env ?? process.env;
 	const outputPath = (0, node_path.isAbsolute)(config.output) ? config.output : (0, node_path.resolve)(options.cwd ?? process.cwd(), config.output);
 	const client = new require_sf_cli.SalesforceClient({
-		auth: resolveAuth(config.auth, env),
+		auth: resolveAuth(config.auth, env, { warn: (message) => logger.warn(message) }),
 		apiVersion,
 		transport: config.transport,
 		retry: true
@@ -1134,39 +1186,118 @@ function normalizeSource(source) {
 	}
 	return result;
 }
-/** Turns the config's auth setting into an auth provider, reading env-based credentials. */
-function resolveAuth(auth, env) {
+/** Where the JWT private key comes from, in order of preference, with each default variable. */
+const PRIVATE_KEY_SOURCES = [["privateKey", "SF_PRIVATE_KEY"], ["privateKeyPath", "SF_PRIVATE_KEY_PATH"]];
+/** A `"${NAME}"` placeholder. Only a whole value counts, so a secret that contains `${` is kept as-is. */
+const ENV_PLACEHOLDER = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
+/**
+* Turns the config's auth setting into an auth provider. Each credential comes from its key in
+* the setting (a `"${NAME}"` placeholder is read from `env`), else from the variable a deprecated
+* `*Env` key names, else from its default `SF_*` variable. Throws one error listing every
+* missing credential.
+*/
+function resolveAuth(auth, env, options = {}) {
 	const setting = auth ?? { type: "clientCredentials" };
 	if ("getToken" in setting) return setting;
-	const read = (name) => {
-		const value = env[name];
-		if (!value) throw new Error(`Environment variable ${name} is not set.`);
+	const problems = [];
+	const lookup = (key, defaultEnv) => readCredential(setting, key, defaultEnv, env, options.warn);
+	const read = (key, defaultEnv) => {
+		const { value, problem } = lookup(key, defaultEnv);
+		if (problem) problems.push(problem);
 		return value;
 	};
 	switch (setting.type) {
-		case "accessToken": return require_sf_cli.accessToken({
-			accessToken: read(setting.accessTokenEnv ?? "SF_ACCESS_TOKEN"),
-			instanceUrl: read(setting.instanceUrlEnv ?? "SF_INSTANCE_URL")
-		});
-		case "jwtBearer": return jwtBearerFromEnv(setting, env, read);
-		case "sfCli": return require_sf_cli.sfCli({ targetOrg: setting.targetOrg });
-		case "clientCredentials": return require_sf_cli.clientCredentials({
-			loginUrl: read(setting.loginUrlEnv ?? "SF_LOGIN_URL"),
-			clientId: read(setting.clientIdEnv ?? "SF_CLIENT_ID"),
-			clientSecret: read(setting.clientSecretEnv ?? "SF_CLIENT_SECRET")
-		});
+		case "accessToken": {
+			const token = {
+				accessToken: read("accessToken", "SF_ACCESS_TOKEN"),
+				instanceUrl: read("instanceUrl", "SF_INSTANCE_URL")
+			};
+			throwIfMissing(setting.type, problems);
+			return require_sf_cli.accessToken(token);
+		}
+		case "jwtBearer": {
+			const loginUrl = read("loginUrl", "SF_LOGIN_URL");
+			const clientId = read("clientId", "SF_CLIENT_ID");
+			const username = read("username", "SF_USERNAME");
+			const configured = PRIVATE_KEY_SOURCES.filter(([key]) => key in setting);
+			const found = (configured.length > 0 ? configured : PRIVATE_KEY_SOURCES).map(([key, defaultEnv]) => ({
+				key,
+				...lookup(key, defaultEnv)
+			}));
+			const source = found.find((item) => item.value);
+			if (source === void 0) problems.push(`no private key: ${found.map((item) => item.problem).join(", and ")}`);
+			throwIfMissing(setting.type, problems);
+			const privateKey = source?.key === "privateKeyPath" ? (0, node_fs.readFileSync)(source.value, "utf8") : source?.value ?? "";
+			return require_sf_cli.jwtBearer({
+				loginUrl,
+				clientId,
+				username,
+				privateKey
+			});
+		}
+		case "sfCli": {
+			const targetOrg = "targetOrg" in setting ? read("targetOrg", "") : void 0;
+			throwIfMissing(setting.type, problems);
+			return require_sf_cli.sfCli({ targetOrg });
+		}
+		case "clientCredentials": {
+			const credentials = {
+				loginUrl: read("loginUrl", "SF_LOGIN_URL"),
+				clientId: read("clientId", "SF_CLIENT_ID"),
+				clientSecret: read("clientSecret", "SF_CLIENT_SECRET")
+			};
+			throwIfMissing(setting.type, problems);
+			return require_sf_cli.clientCredentials(credentials);
+		}
 		default: throw new Error(`Unknown codegen auth type "${setting.type}".`);
 	}
 }
-function jwtBearerFromEnv(setting, env, read) {
-	const keyEnv = setting.privateKeyEnv ?? "SF_PRIVATE_KEY";
-	const privateKey = env[keyEnv] ? read(keyEnv) : (0, node_fs.readFileSync)(read(setting.privateKeyPathEnv ?? "SF_PRIVATE_KEY_PATH"), "utf8");
-	return require_sf_cli.jwtBearer({
-		loginUrl: read(setting.loginUrlEnv ?? "SF_LOGIN_URL"),
-		clientId: read(setting.clientIdEnv ?? "SF_CLIENT_ID"),
-		username: read(setting.usernameEnv ?? "SF_USERNAME"),
-		privateKey
-	});
+/**
+* Loads the sobjectly config and returns an auth provider for its `auth` setting, so the client
+* logs in the same way as `sobjectly generate`:
+* `new SalesforceClient({ apiVersion: API_VERSION, auth: await loadAuth() })`.
+* Throws when no config file is found, or one error listing every missing credential.
+*/
+async function loadAuth(options = {}) {
+	const cwd = options.cwd ?? process.cwd();
+	let configPath = options.configPath === void 0 ? void 0 : (0, node_path.resolve)(cwd, options.configPath);
+	if (configPath === void 0) {
+		const found = findConfigFiles(cwd);
+		if (found.length > 1) options.warn?.(`found ${found.join(" and ")}; using ${found[0]}. Remove the other one.`);
+		configPath = found[0];
+	}
+	if (configPath === void 0) throw new Error(`No sobjectly config file found in ${cwd} (looked for ${CONFIG_FILE_NAMES.join(", ")}).\nPass { configPath } to loadAuth(), run "npx sobjectly init" to create a config, or pass an auth provider such as clientCredentials() to SalesforceClient directly.`);
+	const { config } = await loadConfig(configPath);
+	return resolveAuth(config.auth, options.env ?? process.env, { warn: options.warn });
+}
+function readCredential(setting, key, defaultEnv, env, warn) {
+	const values = setting;
+	if (key in values) {
+		const configured = values[key];
+		const name = typeof configured === "string" ? ENV_PLACEHOLDER.exec(configured)?.[1] : void 0;
+		if (name !== void 0) return fromEnv(env, name, ` (from auth.${key} "${String(configured)}")`);
+		return typeof configured === "string" && configured.length > 0 ? { value: configured } : {
+			value: "",
+			problem: `auth.${key} is empty or undefined (if it reads process.env, that variable is not set)`
+		};
+	}
+	const envKey = `${key}Env`;
+	const legacy = values[envKey];
+	if (typeof legacy === "string") {
+		warn?.(`auth.${envKey} is deprecated and will be removed in 2.0. Use ${key}: process.env.${legacy} in a TypeScript config, or "${key}": "\${${legacy}}" in JSON.`);
+		return fromEnv(env, legacy, "");
+	}
+	return fromEnv(env, defaultEnv, "");
+}
+function fromEnv(env, name, origin) {
+	const value = env[name];
+	return value ? { value } : {
+		value: "",
+		problem: `environment variable ${name}${origin} is not set`
+	};
+}
+function throwIfMissing(type, problems) {
+	if (problems.length > 0) throw new Error(`Missing Salesforce credentials for auth "${type}":\n${problems.map((problem) => `  - ${problem}`).join("\n")}\nFill them in under auth in the config, or set the environment variables (e.g. with --env-file .env).`);
 }
 async function resolveSObjectNames(client, config, logger) {
 	const exclude = new Set((config.exclude ?? []).map((name) => name.toLowerCase()));
@@ -1267,6 +1398,12 @@ Object.defineProperty(exports, "CodegenConfigError", {
 		return CodegenConfigError;
 	}
 });
+Object.defineProperty(exports, "DEPRECATED_AUTH_OPTIONS", {
+	enumerable: true,
+	get: function() {
+		return DEPRECATED_AUTH_OPTIONS;
+	}
+});
 Object.defineProperty(exports, "FIELD_TYPE_MAP", {
 	enumerable: true,
 	get: function() {
@@ -1315,6 +1452,12 @@ Object.defineProperty(exports, "generateSource", {
 		return generateSource;
 	}
 });
+Object.defineProperty(exports, "loadAuth", {
+	enumerable: true,
+	get: function() {
+		return loadAuth;
+	}
+});
 Object.defineProperty(exports, "loadConfig", {
 	enumerable: true,
 	get: function() {
@@ -1370,4 +1513,4 @@ Object.defineProperty(exports, "validateConfig", {
 	}
 });
 
-//# sourceMappingURL=codegen-Bylrt2Ju.cjs.map
+//# sourceMappingURL=codegen-Daud-Grz.cjs.map