@cerios/salesforce-sobjectly 1.0.0 → 1.2.0

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

@@ -1,10 +1,28 @@
-const require_sf_cli = require("./sf-cli-DEVZQTR7.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");
 let node_path = require("node:path");
 let jiti = require("jiti");
 let node_readline = require("node:readline");
+//#region src/codegen/emit.ts
+/** Helpers shared by the modules that emit generated source. */
+const IDENTIFIER$1 = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/** Fields sorted by name, `Id` first, so the output is deterministic. */
+function sortedFields(describe) {
+	return [...describe.fields].sort((a, b) => a.name === "Id" ? -1 : b.name === "Id" ? 1 : compare(a.name, b.name));
+}
+/** An object key: the bare name when it is an identifier, otherwise a quoted string. */
+function propertyKey(name) {
+	return IDENTIFIER$1.test(name) ? name : JSON.stringify(name);
+}
+function escapeComment(value) {
+	return String(value ?? "").replace(/\*\//g, "*\\/").replace(/\r?\n/g, " ");
+}
+function compare(a, b) {
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+//#endregion
 //#region src/codegen/type-mapper.ts
 const ADDRESS_TYPE = "SalesforceAddress";
 const GEOLOCATION_TYPE = "SalesforceGeolocation";
@@ -39,17 +57,143 @@ const FIELD_TYPE_MAP = {
 	address: ADDRESS_TYPE,
 	location: GEOLOCATION_TYPE
 };
-/** Returns the TypeScript type for a field, including `| null` for nillable fields. */
-function mapFieldType(field, picklists = "union") {
-	const base = picklistType(field, picklists) ?? FIELD_TYPE_MAP[field.type] ?? "unknown";
+/**
+* Returns the TypeScript type for a field, including `| null` for nillable fields. With picklist
+* mode `"const"` or `"enum"`, `typeName` is the field's named picklist type; it replaces the union.
+*/
+function mapFieldType(field, picklists = "union", typeName) {
+	const base = picklistType(field, picklists, typeName) ?? FIELD_TYPE_MAP[field.type] ?? "unknown";
 	return field.nillable && base !== "unknown" ? `${base} | null` : base;
 }
-function picklistType(field, picklists) {
-	if (picklists !== "union" || field.type !== "picklist" && field.type !== "combobox") return;
-	const values = [...new Set((field.picklistValues ?? []).filter((entry) => entry.active).map((entry) => entry.value))];
+function picklistType(field, picklists, typeName) {
+	if (picklists === "string" || field.type !== "picklist" && field.type !== "combobox") return;
+	const values = activePicklistValues(field);
 	if (values.length === 0) return;
-	const union = values.map((value) => JSON.stringify(value)).join(" | ");
-	return field.restrictedPicklist && field.type === "picklist" ? union : `${union} | (string & {})`;
+	const members = picklists !== "union" && typeName !== void 0 ? typeName : values.map((value) => JSON.stringify(value)).join(" | ");
+	return field.restrictedPicklist && field.type === "picklist" ? members : `${members} | (string & {})`;
+}
+/** The distinct active values of a picklist, multi-select picklist or combobox, in describe order. */
+function activePicklistValues(field) {
+	if (field.type !== "picklist" && field.type !== "multipicklist" && field.type !== "combobox") return [];
+	return [...new Set((field.picklistValues ?? []).filter((entry) => entry.active).map((entry) => entry.value))];
+}
+//#endregion
+//#region src/codegen/picklist-types.ts
+function isNamedPicklistMode(mode) {
+	return mode === "const" || mode === "enum";
+}
+/** Appended to a picklist type name that is already taken, e.g. by the `CaseStatus` sObject. */
+const CLASH_SUFFIX = "Picklist";
+/**
+* Names the type of every picklist with active values: sObject and field in PascalCase, e.g.
+* `Case.Status` -> `CaseStatus` and `Case.Status__c` -> `CaseStatusCustom`. A name that is in
+* `taken` (the sObjects and other names the file defines) or already used by another picklist gets
+* the suffix `Picklist`; when that is taken too, this throws.
+*/
+function picklistTypeNames(describes, taken) {
+	const used = new Map([...taken].map((name) => [name, void 0]));
+	const result = /* @__PURE__ */ new Map();
+	for (const describe of [...describes].sort((a, b) => compare(a.name, b.name))) {
+		const names = /* @__PURE__ */ new Map();
+		for (const field of sortedFields(describe).filter((item) => activePicklistValues(item).length > 0)) {
+			const base = `${pascalApiName(describe.name, "sobject")}${pascalApiName(field.name, "field")}`;
+			if (IDENTIFIER$1.test(base)) {
+				const picklist = `${describe.name}.${field.name}`;
+				const name = resolveName(base, picklist, used);
+				used.set(name, picklist);
+				names.set(field.name, name);
+			}
+		}
+		if (names.size > 0) result.set(describe.name, names);
+	}
+	return result;
+}
+function resolveName(base, picklist, used) {
+	const name = used.has(base) ? `${base}${CLASH_SUFFIX}` : base;
+	if (used.has(name)) {
+		const owner = used.get(name);
+		const other = owner === void 0 ? "a type the generated file defines" : `the picklist type for ${owner}`;
+		throw new Error(`The picklist type "${name}" for ${picklist} clashes with ${other}; exclude one of the sObjects or use picklists: "union".`);
+	}
+	return name;
+}
+/**
+* An API name in PascalCase without underscores. A field's `__c` becomes `Custom`
+* (`Lead_Source__c` -> `LeadSourceCustom`) and an sObject's is dropped (`My_Object__c` ->
+* `MyObject`). Other suffixes are kept: `Foo__pc` -> `FooPc`, `Config__mdt` -> `ConfigMdt`.
+*/
+function pascalApiName(name, kind) {
+	const match = /^(.+?)__([a-z]+)$/.exec(name);
+	const body = match ? match[1] : name;
+	const suffix = match ? match[2] : "";
+	const suffixPart = suffix === "c" ? kind === "field" ? "Custom" : "" : capitalize(suffix);
+	return `${body.split("_").filter((part) => part.length > 0).map(capitalize).join("")}${suffixPart}`;
+}
+function capitalize(value) {
+	return value.charAt(0).toUpperCase() + value.slice(1);
+}
+/**
+* The member names for a picklist's values, in the same order. A value that is an identifier is
+* its own name; other values are sanitized (`"Closed Won"` -> `Closed_Won`, `"3rd Party"` ->
+* `_3rd_Party`). When the sanitized name is empty or taken, the value itself is the (quoted) name.
+*/
+function picklistMemberKeys(values, mode) {
+	const used = /* @__PURE__ */ new Set();
+	const claim = (key) => {
+		used.add(key);
+		return key;
+	};
+	const usable = (key) => key.length > 0 && key !== "__proto__" && !used.has(key) && (mode === "const" || !isNumericName(key));
+	const own = values.map((value) => IDENTIFIER$1.test(value) && usable(value) ? claim(value) : void 0);
+	return values.map((value, index) => {
+		const ownKey = own[index];
+		if (ownKey !== void 0) return ownKey;
+		const sanitized = sanitizeKey(value);
+		if (usable(sanitized)) return claim(sanitized);
+		if (usable(value)) return claim(value);
+		let counter = 2;
+		while (!usable(`${sanitized || "_"}_${counter}`)) counter++;
+		return claim(`${sanitized || "_"}_${counter}`);
+	});
+}
+function sanitizeKey(value) {
+	const key = value.normalize("NFKD").replace(/\p{M}/gu, "").replace(/[^A-Za-z0-9_]+/g, "_").replace(/^_+|_+$/g, "");
+	return /^[0-9]/.test(key) ? `_${key}` : key;
+}
+/** Names TypeScript rejects as enum members because they are numeric, e.g. `"1"` or `"-1"`. */
+function isNumericName(key) {
+	const number = Number(key);
+	return Number.isFinite(number) && String(number) === key;
+}
+/** The named type declarations for one sObject's picklists, in field order; `""` when there are none. */
+function picklistDeclarations(describe, names, mode) {
+	if (!names) return "";
+	return sortedFields(describe).flatMap((field) => {
+		const name = names.get(field.name);
+		return name === void 0 ? [] : [declaration(describe.name, field, name, mode)];
+	}).join("\n\n");
+}
+function declaration(sobject, field, name, mode) {
+	const values = activePicklistValues(field);
+	const keys = picklistMemberKeys(values, mode);
+	const doc = `/** Active values of ${escapeComment(`${sobject}.${field.name}`)} (${escapeComment(field.type)}). */`;
+	if (mode === "enum") {
+		const members = values.map((value, index) => `\t${propertyKey(keys[index])} = ${JSON.stringify(value)},`);
+		return [
+			doc,
+			`export enum ${name} {`,
+			...members,
+			"}"
+		].join("\n");
+	}
+	const members = values.map((value, index) => `\t${propertyKey(keys[index])}: ${JSON.stringify(value)},`);
+	return [
+		doc,
+		`export const ${name} = {`,
+		...members,
+		"} as const;",
+		`export type ${name} = (typeof ${name})[keyof typeof ${name}];`
+	].join("\n");
 }
 //#endregion
 //#region src/codegen/generator.ts
@@ -60,24 +204,28 @@ const FIELD_KINDS = /* @__PURE__ */ new Set([
 	"time",
 	"multipicklist"
 ]);
-const IDENTIFIER$1 = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
 /**
 * Generates the TypeScript source for a set of sObject describes: a read interface, create
-* and update input types per sObject, and the `SObjectRegistry` that ties them together.
+* and update input types per sObject, and the `SObjectRegistry` that ties them together. With
+* picklist mode `"const"` or `"enum"`, each picklist also gets a named type before its sObject.
 * The output is deterministic: sObjects are sorted by name and fields by name (`Id` first).
 */
 function generateSource(describes, options = {}) {
 	const sorted = [...describes].sort((a, b) => compare(a.name, b.name));
-	assertGeneratableNames(sorted);
+	const definedNames = assertGeneratableNames(sorted);
 	const names = new Set(sorted.map((describe) => describe.name));
+	const picklists = options.picklists ?? "union";
+	const picklistTypes = isNamedPicklistMode(picklists) ? picklistTypeNames(sorted, definedNames) : void 0;
 	const sections = [imports(sorted, options.importSource ?? "@cerios/salesforce-sobjectly")];
 	const objectHashes = [];
 	for (const describe of sorted) {
+		const typeNames = picklistTypes?.get(describe.name);
 		const objectSections = [
-			readInterface(describe, options.picklists ?? "union"),
+			isNamedPicklistMode(picklists) ? picklistDeclarations(describe, typeNames, picklists) : "",
+			readInterface(describe, picklists, typeNames),
 			inputType(describe, "CreateInput", "createable", lookup(options.excludeCreateFields, describe.name)),
 			inputType(describe, "UpdateInput", "updateable", lookup(options.excludeUpdateFields, describe.name))
-		];
+		].filter((section) => section.length > 0);
 		sections.push(...objectSections);
 		const fingerprint = [
 			...objectSections,
@@ -104,7 +252,10 @@ const RESERVED_TYPE_NAMES = /* @__PURE__ */ new Set([
 	ADDRESS_TYPE,
 	GEOLOCATION_TYPE
 ]);
-/** Fails with a clear message for sObject names the generated TypeScript can't represent. */
+/**
+* Fails with a clear message for sObject names the generated TypeScript can't represent. Returns
+* every name the file defines apart from picklist types, so those can avoid them.
+*/
 function assertGeneratableNames(describes) {
 	const seen = /* @__PURE__ */ new Map();
 	const generated = new Set(describes.flatMap((describe) => [`${describe.name}CreateInput`, `${describe.name}UpdateInput`]));
@@ -115,6 +266,11 @@ function assertGeneratableNames(describes) {
 		if (previous !== void 0) throw new Error(`sObjects "${previous}" and "${name}" differ only in case; list each sObject once.`);
 		seen.set(name.toLowerCase(), name);
 	}
+	return /* @__PURE__ */ new Set([
+		...RESERVED_TYPE_NAMES,
+		...generated,
+		...describes.map((describe) => describe.name)
+	]);
 }
 /** Looks up a per-sObject option case-insensitively (sObject names are case-insensitive in Salesforce). */
 function lookup(map, name) {
@@ -162,12 +318,11 @@ function imports(describes, importSource) {
 	if (fields.some((field) => field.type === "location")) used.push(GEOLOCATION_TYPE);
 	return used.length > 0 ? `import type { ${used.join(", ")} } from ${JSON.stringify(importSource)};` : "";
 }
-function sortedFields(describe) {
-	return [...describe.fields].sort((a, b) => a.name === "Id" ? -1 : b.name === "Id" ? 1 : compare(a.name, b.name));
-}
-function readInterface(describe, picklists) {
+function readInterface(describe, picklists, typeNames) {
 	const lines = sortedFields(describe).map((field) => {
-		return `${`\t/** ${escapeComment(field.label)} (${escapeComment(field.type)}) */`}\n\t${propertyKey(field.name)}: ${mapFieldType(field, picklists)};`;
+		const comment = `\t/** ${escapeComment(field.label)} (${escapeComment(field.type)}) */`;
+		const type = mapFieldType(field, picklists, typeNames?.get(field.name));
+		return `${comment}\n\t${propertyKey(field.name)}: ${type};`;
 	});
 	return `${describe.label ? `/** ${escapeComment(describe.label)} */\n` : ""}export interface ${describe.name} {\n${lines.join("\n")}\n}`;
 }
@@ -254,10 +409,6 @@ function recordTypeConstants(describes) {
 	const entries = describes.map((describe) => [describe.name, recordTypeNames(describe)]).filter(([, names]) => names.length > 0).map(([name, names]) => `\t${name}: [${names.map((value) => JSON.stringify(value)).join(", ")}],`);
 	return ["/** Record type DeveloperNames per sObject. Resolve ids with `sf.sobject(name).recordTypeId(developerName)`. */", `export const RECORD_TYPES = {${entries.length > 0 ? `\n${entries.join("\n")}\n` : ""}} as const;`].join("\n");
 }
-function activePicklistValues(field) {
-	if (field.type !== "picklist" && field.type !== "multipicklist" && field.type !== "combobox") return [];
-	return [...new Set((field.picklistValues ?? []).filter((entry) => entry.active).map((entry) => entry.value))];
-}
 function unionOrNever(values) {
 	return values.length > 0 ? values.map((value) => JSON.stringify(value)).join(" | ") : "never";
 }
@@ -280,15 +431,6 @@ function relationshipMap(entries) {
 function keyUnion(names) {
 	return names.map((name) => JSON.stringify(name)).join(" | ");
 }
-function propertyKey(name) {
-	return IDENTIFIER$1.test(name) ? name : JSON.stringify(name);
-}
-function escapeComment(value) {
-	return String(value ?? "").replace(/\*\//g, "*\\/").replace(/\r?\n/g, " ");
-}
-function compare(a, b) {
-	return a < b ? -1 : a > b ? 1 : 0;
-}
 //#endregion
 //#region src/codegen/validate-config.ts
 /** Thrown when a codegen config is invalid. Lists every problem found. */
@@ -302,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",
@@ -319,7 +474,23 @@ const AUTH_OPTIONS = {
 	],
 	sfCli: ["targetOrg"]
 };
-const PICKLIST_MODES = ["union", "string"];
+/** 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",
+	"const",
+	"enum"
+];
 const IDENTIFIER = /^[A-Za-z][A-Za-z0-9_]*$/;
 const VALIDATORS = {
 	$schema: (value, { problem }) => {
@@ -339,7 +510,7 @@ const VALIDATORS = {
 	excludeCreateFields: (value, context) => validateFieldMap("excludeCreateFields", value, context),
 	excludeUpdateFields: (value, context) => validateFieldMap("excludeUpdateFields", value, context),
 	picklists: (value, { problem }) => {
-		if (!PICKLIST_MODES.includes(value)) problem(`picklists: must be "union" or "string", got ${show(value)}.`);
+		if (!PICKLIST_MODES.includes(value)) problem(`picklists: must be one of ${PICKLIST_MODES.join(", ")}, got ${show(value)}.`);
 	},
 	constants: (value, { problem }) => {
 		if (typeof value !== "boolean") problem(`constants: must be true or false, got ${show(value)}.`);
@@ -425,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";
@@ -438,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 = [
@@ -507,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",
@@ -544,13 +731,24 @@ const AUTH_CHOICES = [
 		label: "JWT bearer (certificate-based, runs as a user)"
 	}
 ];
-const PICKLIST_CHOICES = [{
-	value: "union",
-	label: "Union of values, e.g. \"New\" | \"Closed\" (type-safe)"
-}, {
-	value: "string",
-	label: "Plain string"
-}];
+const PICKLIST_CHOICES = [
+	{
+		value: "union",
+		label: "Union of values, e.g. \"New\" | \"Closed\" (type-safe)"
+	},
+	{
+		value: "string",
+		label: "Plain string"
+	},
+	{
+		value: "const",
+		label: "Union plus a named constant per picklist, e.g. CaseStatus.Closed"
+	},
+	{
+		value: "enum",
+		label: "TypeScript enum per picklist (restricted picklists only accept enum members)"
+	}
+];
 const FORMAT_CHOICES = [{
 	value: "ts",
 	label: "TypeScript (sobjectly.config.ts, type-checked with defineConfig)"
@@ -673,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\";",
@@ -685,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");
@@ -754,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) {
@@ -923,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
@@ -976,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()));
@@ -1109,12 +1398,24 @@ 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() {
 		return FIELD_TYPE_MAP;
 	}
 });
+Object.defineProperty(exports, "PICKLIST_MODES", {
+	enumerable: true,
+	get: function() {
+		return PICKLIST_MODES;
+	}
+});
 Object.defineProperty(exports, "checkGenerated", {
 	enumerable: true,
 	get: function() {
@@ -1151,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() {
@@ -1206,4 +1513,4 @@ Object.defineProperty(exports, "validateConfig", {
 	}
 });
 
-//# sourceMappingURL=codegen-BgDgU2RR.cjs.map
+//# sourceMappingURL=codegen-Daud-Grz.cjs.map