@pithy-sh/cloudflare 0.1.5 → 0.1.7

package/dist/media/assetSeeder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assetSeeder.d.ts","sourceRoot":"","sources":["../../src/media/assetSeeder.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAE,KAAK,UAAU,EAAsB,MAAM,aAAa,CAAC;AAClE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAyB/D;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,sBAAsB,EAC/B,KAAK,EAAE,UAAU,GAAG,IAAI,EACxB,IAAI,EAAE;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC7D,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAMzB;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,uBAAuB,EAChC,KAAK,EAAE,UAAU,GAAG,IAAI,EACxB,IAAI,EAAE;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1F,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAwB1B"}
+{"version":3,"file":"assetSeeder.d.ts","sourceRoot":"","sources":["../../src/media/assetSeeder.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAE,KAAK,UAAU,EAAsB,MAAM,aAAa,CAAC;AAClE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAyB/D;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,sBAAsB,EAC/B,KAAK,EAAE,UAAU,GAAG,IAAI,EACxB,IAAI,EAAE;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC7D,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAMzB;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,uBAAuB,EAChC,KAAK,EAAE,UAAU,GAAG,IAAI,EACxB,IAAI,EAAE;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1F,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAiC1B"}

package/dist/media/assetSeeder.js

@@ -1,6 +1,6 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
-import { CloudflareRequestError, cloudflareRequest, decodeResponse } from "../client/errors.js";
+import { cloudflareApiErrors, cloudflareRefusal, cloudflareRequest, decodeResponse } from "../client/errors.js";
 import { withAssetOwnership } from "./ownership.js";
 import { z } from "zod";
 //#region src/media/assetSeeder.ts
@@ -61,12 +61,26 @@ async function uploadStreamBytes(manager, bytes, opts) {
 			method: "POST",
 			body: form
 		});
-		if (!response.ok) throw new CloudflareRequestError({
-			message: "The Stream direct upload failed.",
-			detail: `Stream direct upload returned ${response.status}: ${await response.text()}`
-		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw cloudflareRefusal({
+				problem: "The Stream direct upload failed.",
+				apiErrors: cloudflareApiErrors(parseEnvelope(body)),
+				status: response.status,
+				permission: "Stream",
+				detail: `Stream direct upload returned ${response.status}: ${body}`.slice(0, 2e3)
+			});
+		}
 	});
 	return { uid: mint.uid };
 }
+/** A CF response body as an object, or `undefined` when it is not JSON — `cloudflareApiErrors` reads either. */
+function parseEnvelope(body) {
+	try {
+		return JSON.parse(body);
+	} catch {
+		return;
+	}
+}
 //#endregion
 export { uploadImageBytes, uploadStreamBytes };

package/dist/r2/r2Credentials.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"r2Credentials.d.ts","sourceRoot":"","sources":["../../src/r2/r2Credentials.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,aAAa;;;iBAKiE,CAAC;AAC5F,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC"}
+{"version":3,"file":"r2Credentials.d.ts","sourceRoot":"","sources":["../../src/r2/r2Credentials.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,aAAa;;;iBASiE,CAAC;AAC5F,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC"}

package/dist/r2/r2Credentials.js

@@ -8,8 +8,8 @@ import { z } from "zod";
 * `@pithy-sh/secrets` validates the persisted credential envelope against it.
 */
 const R2Credentials = z.object({
-	accessKeyId: z.string().min(1).describe("The R2 S3 access key id."),
-	secretAccessKey: z.string().min(1).describe("The R2 S3 secret access key. Never logged or serialized to clients.")
+	accessKeyId: z.string().min(1).meta({ multiline: false }).describe("The R2 S3 access key id."),
+	secretAccessKey: z.string().min(1).meta({ multiline: false }).describe("The R2 S3 secret access key. Never logged or serialized to clients.")
 }).describe("The S3-compatible access-key/secret-key pair R2 uses to sign presigned URLs.");
 //#endregion
 export { R2Credentials };

package/dist/test-utils/emailRoutingRules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"emailRoutingRules.d.ts","sourceRoot":"","sources":["../../src/test-utils/emailRoutingRules.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAkClD,iEAAiE;AACjE,eAAO,MAAM,mBAAmB;;;;iBAMoB,CAAC;AAErD,yEAAyE;AACzE,eAAO,MAAM,kBAAkB;;;iBAKoB,CAAC;AAEpD,qDAAqD;AACrD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;iBAYsC,CAAC;AAEpE,qDAAqD;AACrD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAiBjE,+DAA+D;AAC/D,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAuBhH;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,GAAG,gBAAgB,EAAE,CAEjF"}
+{"version":3,"file":"emailRoutingRules.d.ts","sourceRoot":"","sources":["../../src/test-utils/emailRoutingRules.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAkClD,iEAAiE;AACjE,eAAO,MAAM,mBAAmB;;;;iBAMoB,CAAC;AAErD,yEAAyE;AACzE,eAAO,MAAM,kBAAkB;;;iBAKoB,CAAC;AAEpD,qDAAqD;AACrD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;iBAYsC,CAAC;AAEpE,qDAAqD;AACrD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAiBjE,+DAA+D;AAC/D,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA4BhH;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,GAAG,gBAAgB,EAAE,CAEjF"}

package/dist/test-utils/emailRoutingRules.js

@@ -1,6 +1,6 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
-import { CloudflareRequestError } from "../client/errors.js";
+import { cloudflareApiErrors, cloudflareRefusal } from "../client/errors.js";
 import { z } from "zod";
 //#region src/test-utils/emailRoutingRules.ts
 /**
@@ -67,11 +67,16 @@ async function listEmailRoutingRules(creds, zoneId) {
 	for (let page = 1; page <= MAX_RULE_PAGES; page += 1) {
 		const url = `https://api.cloudflare.com/client/v4/zones/${zoneId}/email/routing/rules?page=${page}&per_page=${RULES_PER_PAGE}`;
 		const response = await fetch(url, { headers: { Authorization: `Bearer ${creds.apiToken}` } });
-		if (!response.ok) throw new CloudflareRequestError({
-			message: "Could not read the zone's Email Routing rules.",
-			action: "Check the token carries Email Routing Rules: Read on this zone.",
-			detail: `Email Routing rule list returned ${response.status}.`
-		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw cloudflareRefusal({
+				problem: "Could not read the zone's Email Routing rules.",
+				apiErrors: cloudflareApiErrors(parseEnvelope(body)),
+				status: response.status,
+				permission: "Email Routing Rules",
+				detail: `Email Routing rule list returned ${response.status}: ${body}`.slice(0, 2e3)
+			});
+		}
 		const envelope = RuleListEnvelope.parse(await response.json());
 		const batch = envelope.result ?? [];
 		rules.push(...batch);
@@ -87,5 +92,13 @@ async function listEmailRoutingRules(creds, zoneId) {
 function namedRules(rules) {
 	return rules.filter((rule) => rule.name !== "");
 }
+/** A CF response body as an object, or `undefined` when it is not JSON — `cloudflareApiErrors` reads either. */
+function parseEnvelope(body) {
+	try {
+		return JSON.parse(body);
+	} catch {
+		return;
+	}
+}
 //#endregion
 export { EmailRoutingAction, EmailRoutingMatcher, EmailRoutingRule, listEmailRoutingRules, namedRules };

package/dist/test-utils/inboundRecorder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inboundRecorder.d.ts","sourceRoot":"","sources":["../../src/test-utils/inboundRecorder.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,kDAAkD;AAClD,eAAO,MAAM,wBAAwB,aAAa,CAAC;AAEnD,4GAA4G;AAC5G,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAapD;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,myCAmCnC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe;;;;;;;;iBAgBqD,CAAC;AAElF,6BAA6B;AAC7B,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE/D,8FAA8F;AAC9F,eAAO,MAAM,0BAA0B,2CAA2C,CAAC;AAEnF,yEAAyE;AACzE,eAAO,MAAM,mBAAmB,eAAe,CAAC;AAEhD;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE;IACnD,OAAO,EAAE,wBAAwB,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,2GAA2G;IAC3G,iBAAiB,EAAE,MAAM,CAAC;CAC3B,GAAG,OAAO,CAAC,IAAI,CAAC,CAQhB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE;IACjD,KAAK,EAAE,gBAAgB,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAuBlC"}
+{"version":3,"file":"inboundRecorder.d.ts","sourceRoot":"","sources":["../../src/test-utils/inboundRecorder.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,kDAAkD;AAClD,eAAO,MAAM,wBAAwB,aAAa,CAAC;AAEnD,4GAA4G;AAC5G,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAapD;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,myCAmCnC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe;;;;;;;;iBAgBqD,CAAC;AAElF,6BAA6B;AAC7B,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE/D,8FAA8F;AAC9F,eAAO,MAAM,0BAA0B,2CAA2C,CAAC;AAEnF,yEAAyE;AACzE,eAAO,MAAM,mBAAmB,eAAe,CAAC;AAEhD;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE;IACnD,OAAO,EAAE,wBAAwB,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,2GAA2G;IAC3G,iBAAiB,EAAE,MAAM,CAAC;CAC3B,GAAG,OAAO,CAAC,IAAI,CAAC,CAQhB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE;IACjD,KAAK,EAAE,gBAAgB,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CA4BlC"}

package/dist/test-utils/inboundRecorder.js

@@ -1,6 +1,6 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
-import { CloudflareInvalidResponseError, CloudflareRequestError } from "../client/errors.js";
+import { CloudflareInvalidResponseError, cloudflareApiErrors, cloudflareRefusal } from "../client/errors.js";
 import { z } from "zod";
 //#region src/test-utils/inboundRecorder.ts
 /**
@@ -127,11 +127,16 @@ async function readObservedInbound(options) {
 	const url = `https://api.cloudflare.com/client/v4/accounts/${creds.accountId}/storage/kv/namespaces/${namespaceId}/values/${encodeURIComponent(nonce)}`;
 	const response = await fetch(url, { headers: { Authorization: `Bearer ${creds.apiToken}` } });
 	if (response.status === 404) return null;
-	if (!response.ok) throw new CloudflareRequestError({
-		message: "Could not read the recorded inbound message.",
-		action: "Check the token carries Workers KV Storage: Edit on this account.",
-		detail: `KV read for the inbound record returned ${response.status}.`
-	});
+	if (!response.ok) {
+		const failure = await response.text();
+		throw cloudflareRefusal({
+			problem: "Could not read the recorded inbound message.",
+			apiErrors: cloudflareApiErrors(parseEnvelope(failure)),
+			status: response.status,
+			permission: "Workers KV Storage",
+			detail: `KV read for the inbound record returned ${response.status}: ${failure}`.slice(0, 2e3)
+		});
+	}
 	const body = JSON.parse(await response.text());
 	if (typeof body === "object" && body !== null && "failure" in body) throw new CloudflareInvalidResponseError({
 		message: "The inbound recorder could not read the message it was handed.",
@@ -139,5 +144,13 @@ async function readObservedInbound(options) {
 	});
 	return ObservedInbound.parse(body);
 }
+/** A CF response body as an object, or `undefined` when it is not JSON — `cloudflareApiErrors` reads either. */
+function parseEnvelope(body) {
+	try {
+		return JSON.parse(body);
+	} catch {
+		return;
+	}
+}
 //#endregion
 export { INBOUND_MODULE_NAME, INBOUND_NONCE_HEADER, INBOUND_RECORDER_BINDING, INBOUND_RECORDER_MODULE, ObservedInbound, PLACEHOLDER_INBOUND_MODULE, deployInboundRecorder, readObservedInbound };

package/dist/tokens/accountTokensManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"accountTokensManager.d.ts","sourceRoot":"","sources":["../../src/tokens/accountTokensManager.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AASxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,kHAAkH;IAClH,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,kGAAkG;IAClG,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,2EAA2E;IAC3E,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEzE;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;;iBAK8E,CAAC;AAC7G,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;iBAO6D,CAAC;AAC7F,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAErE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;iBAMuD,CAAC;AACxF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE;;;;;;;;;GASG;AACH,qBAAa,8BAA+B,SAAQ,iBAAiB;IACnE,cAAc,IAAI,MAAM,CAEvB;IAED,qGAAqG;IAC/F,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;IAED;;;;;;;OAOG;IACG,WAAW,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAKhD;IAED;;;;;;;;;;;;OAYG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAW1D;IAED,qGAAqG;IAC/F,oBAAoB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAWzD;IAED;;;;;;OAMG;IACG,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAE7E;IAED;;;;;;;OAOG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA2BzF;IAED;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAqB3B,2GAA2G;IACrG,UAAU,IAAI,OAAO,CAAC,mBAAmB,EAAE,CAAC,CASjD;IAED,oGAAoG;IAC9F,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAQvE;IAED,qCAAqC;IAC/B,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhD;IAED;;;;OAIG;IACG,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYtD;IAED;;;;;OAKG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAKrD;IAED;;;;;;OAMG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAKzF;CACF"}
+{"version":3,"file":"accountTokensManager.d.ts","sourceRoot":"","sources":["../../src/tokens/accountTokensManager.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAYxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAkB1D;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,kHAAkH;IAClH,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,kGAAkG;IAClG,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,2EAA2E;IAC3E,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEzE;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;;iBAK8E,CAAC;AAC7G,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;iBAO6D,CAAC;AAC7F,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAErE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;iBAMuD,CAAC;AACxF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE;;;;;;;;;GASG;AACH,qBAAa,8BAA+B,SAAQ,iBAAiB;IACnE,cAAc,IAAI,MAAM,CAEvB;IAED,qGAAqG;IAC/F,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;IAED;;;;;;;OAOG;IACG,WAAW,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAKhD;IAED;;;;;;;;;;;;OAYG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAe1D;IAED,qGAAqG;IAC/F,oBAAoB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAezD;IAED;;;;;;OAMG;IACG,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAE7E;IAED;;;;;;;OAOG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAgDzF;IAED;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAqB3B,2GAA2G;IACrG,UAAU,IAAI,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAajD;IAED,oGAAoG;IAC9F,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAYvE;IAED,qCAAqC;IAC/B,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMhD;IAED;;;;OAIG;IACG,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBtD;IAED;;;;;OAKG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAOrD;IAED;;;;;;OAMG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAKzF;CACF"}

package/dist/tokens/accountTokensManager.js

@@ -1,11 +1,26 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
-import { CloudflareNotConfiguredError, CloudflareRequestError, cloudflareRequest, decodeResponse, isAuthorizationError, messageOf } from "../client/errors.js";
+import { CloudflareNotConfiguredError, cloudflareApiErrors, cloudflareRefusal, cloudflareRequest, cloudflareSaid, decodeResponse, isAuthorizationError, messageOf, statusOf } from "../client/errors.js";
 import { CloudflareManager } from "../client/manager.js";
 import { CfTokenVerification } from "../user/userManager.js";
 import { z } from "zod";
 //#region src/tokens/accountTokensManager.ts
 /**
+* The account permission group behind every endpoint in this file, handed to `cloudflareRequest` so an
+* auth-class refusal names it.
+*
+* It has to be stated rather than derived, because Cloudflare's `documentation_url` for
+* `accounts/tokens` yields `accounts` — a segment `ACCOUNT_PERMISSIONS` deliberately does not map, since
+* account-scoped endpoints span every product. And it has to be on **every** call here rather than only
+* on the mint: `pithy token mint` is `rollToken → findTokenByName → listTokens`, then
+* `listPermissionGroups`, and every one of those runs before `tokens.create` on the same credential. A
+* hint reachable only from the mint is a hint an under-scoped bootstrap token never reaches (#534).
+*
+* `verifyToken` is the deliberate omission: any account token may call `/tokens/verify` with no
+* permission at all, so a refusal there is a dead token or the wrong account, never a missing grant.
+*/
+const API_TOKENS_ENDPOINT = { permission: "API Tokens" };
+/**
 * The whole-account resource scope for a token policy: `{ "com.cloudflare.api.account.<id>": "*" }`.
 * Account-level permission groups (Secrets Store, D1, Workers, …) scope to this. One helper so the
 * exact resource key format lives in a single place instead of being hand-spelled per use case.
@@ -106,7 +121,7 @@ var CloudflareAccountTokensManager = class extends CloudflareManager {
 				if (isAuthorizationError(error)) return null;
 				throw error;
 			}
-		});
+		}, API_TOKENS_ENDPOINT);
 		const parsed = TokenName.safeParse(raw);
 		return parsed.success ? parsed.data.name : null;
 	}
@@ -119,7 +134,7 @@ var CloudflareAccountTokensManager = class extends CloudflareManager {
 				if (parsed.success) out.push(parsed.data);
 			}
 			return out;
-		});
+		}, API_TOKENS_ENDPOINT);
 	}
 	/**
 	* Resolve permission-group names to their `{ id }` references against the account's live group list.
@@ -154,15 +169,23 @@ var CloudflareAccountTokensManager = class extends CloudflareManager {
 				policies
 			});
 		} catch (error) {
-			if (isAuthorizationError(error)) throw new CloudflareNotConfiguredError({
-				message: "The Cloudflare API token is not allowed to create account tokens.",
-				action: "Grant it 'Account API Tokens Write' (Account → API Tokens → Edit), then re-run.",
-				detail: `mint account token '${name}': ${messageOf(error)}`
-			}, { cause: error });
-			throw new CloudflareRequestError({
-				message: `Failed to mint account token '${name}'.`,
-				detail: messageOf(error)
-			}, { cause: error });
+			if (isAuthorizationError(error)) {
+				const said = cloudflareSaid("The Cloudflare API token is not allowed to create account tokens.", cloudflareApiErrors(error));
+				throw new CloudflareNotConfiguredError({
+					message: said.message,
+					action: "Grant it 'Account API Tokens Write' (Account → API Tokens → Edit), then re-run.",
+					params: said.params,
+					detail: `mint account token '${name}': ${messageOf(error)}`
+				}, { cause: error });
+			}
+			throw cloudflareRefusal({
+				problem: `Failed to mint account token '${name}'.`,
+				apiErrors: cloudflareApiErrors(error),
+				status: statusOf(error),
+				permission: "API Tokens",
+				detail: messageOf(error),
+				cause: error
+			});
 		}
 		return decodeResponse(MintedAccountToken, raw, "account token create");
 	}
@@ -196,7 +219,7 @@ var CloudflareAccountTokensManager = class extends CloudflareManager {
 				if (parsed.success) out.push(parsed.data);
 			}
 			return out;
-		});
+		}, API_TOKENS_ENDPOINT);
 	}
 	/** Find an account token by exact name, or `null` — for idempotent re-mint (SDK auto-paginates). */
 	async findTokenByName(name) {
@@ -206,11 +229,11 @@ var CloudflareAccountTokensManager = class extends CloudflareManager {
 				if (parsed.success && parsed.data.name === name) return parsed.data;
 			}
 			return null;
-		});
+		}, API_TOKENS_ENDPOINT);
 	}
 	/** Delete an account token by id. */
 	async deleteToken(tokenId) {
-		await cloudflareRequest(`delete account token ${tokenId}`, () => this.getClient().accounts.tokens.delete(tokenId, { account_id: this.accountId }));
+		await cloudflareRequest(`delete account token ${tokenId}`, () => this.getClient().accounts.tokens.delete(tokenId, { account_id: this.accountId }), API_TOKENS_ENDPOINT);
 	}
 	/**
 	* Delete every account token with the given name; returns how many were removed. Names are not
@@ -226,7 +249,7 @@ var CloudflareAccountTokensManager = class extends CloudflareManager {
 			}
 			for (const id of ids) await this.getClient().accounts.tokens.delete(id, { account_id: this.accountId });
 			return ids.length;
-		});
+		}, API_TOKENS_ENDPOINT);
 	}
 	/**
 	* Roll an existing token's secret: regenerate its value **in place**, keeping the same token id,
@@ -238,7 +261,7 @@ var CloudflareAccountTokensManager = class extends CloudflareManager {
 		const raw = await cloudflareRequest(`roll account token value ${tokenId}`, () => this.getClient().accounts.tokens.value.update(tokenId, {
 			account_id: this.accountId,
 			body: {}
-		}));
+		}), API_TOKENS_ENDPOINT);
 		return decodeResponse(RolledTokenValue, raw, "account token value roll");
 	}
 	/**

package/dist/workers/buildsManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"buildsManager.d.ts","sourceRoot":"","sources":["../../src/workers/buildsManager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"buildsManager.d.ts","sourceRoot":"","sources":["../../src/workers/buildsManager.ts"],"names":[],"mappings":"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"}

package/dist/workers/buildsManager.js

@@ -1,6 +1,6 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
-import { CloudflareInvalidResponseError, CloudflareRequestError, cloudflareRequest, decodeResponse, messageOf } from "../client/errors.js";
+import { CloudflareInvalidResponseError, CloudflareRequestError, cloudflareApiErrors, cloudflareRefusal, cloudflareRequest, decodeResponse, messageOf } from "../client/errors.js";
 import { CloudflareManager } from "../client/manager.js";
 import { CfBuild, CfBuildLog, CfBuildToken, CfBuildTrigger, CfRepoConnection } from "./buildsTypes.js";
 import { z } from "zod";
@@ -17,7 +17,8 @@ const CfEnvelope = z.object({
 	success: z.boolean().optional(),
 	errors: z.array(z.object({
 		code: z.number().optional(),
-		message: z.string().optional()
+		message: z.string().optional(),
+		documentation_url: z.string().optional()
 	}).loose()).optional()
 });
 /**
@@ -61,10 +62,13 @@ var CloudflareBuildsManager = class extends CloudflareManager {
 		const envelope = CfEnvelope.safeParse(parsed);
 		const apiReportedFailure = envelope.success && envelope.data.success === false;
 		if (!response.ok || apiReportedFailure) {
-			const codes = envelope.success ? (envelope.data.errors ?? []).map((e) => e.code).filter((c) => c !== void 0) : [];
+			const errors = envelope.success ? envelope.data.errors ?? [] : [];
+			const codes = errors.map((e) => e.code).filter((c) => c !== void 0);
 			const marker = codes.length > 0 ? `[cf-codes:${codes.join(",")}] ` : "";
-			throw new CloudflareRequestError({
-				message: `Cloudflare Builds returned ${response.status}.`,
+			throw cloudflareRefusal({
+				problem: `Cloudflare Builds returned ${response.status}.`,
+				apiErrors: cloudflareApiErrors(errors),
+				status: response.status,
 				detail: `${marker}${method} ${path} → ${response.status}: ${text}`.slice(0, 2e3)
 			});
 		}

package/dist/workflows/stepFailure.d.ts

@@ -170,6 +170,34 @@ export declare const WORKFLOW_FAILED_STATUS: 500;
  * the boundary — and nothing derived from the step's own `detail` is in it, because the step's
  * `detail` never left the step. The only fields promoted from the far side are `message` and `action`,
  * both already public, both already proved kit-authored by `kitSentence`.
+ *
+ * ## `params` did not cross either, and a recovered code still has to keep their promise
+ *
+ * `core`'s `GUARANTEED_ERROR_PARAMS` states the names a code's throw sites pass on **every** path, and
+ * a locale writes `{apiAnswer}` into its sentence against that statement. Re-raising a recovered code
+ * here is a throw site like any other — it just happens to be one whose inputs came over a wire that
+ * carries three fields. So every guaranteed name is supplied, as the empty string: `interpolate` leaves
+ * an unsupplied placeholder written out, and `{apiAnswer}` on a Spanish reader's screen is the exact
+ * defect the declaration exists to prevent. Empty is also the honest value — it is what the catalogs
+ * define as *no answer to quote*, and the answer genuinely did not cross.
+ *
+ * **One reader does lose something by it, and it is worth naming rather than glossing.** An earlier
+ * version of this comment said nothing was lost, on the grounds that the API's words are already inside
+ * the promoted English `message`. That is true of the operator's terminal, the `--json` line and any
+ * client with no catalog — but the contract is `t.maybe(payload.code, payload.params) ?? payload.message`
+ * (`core/src/i18n/translator.ts`), and `maybe` returns null only on a catalog **miss**. `es` has an entry
+ * for this code, so a Spanish reader gets the translated sentence with an empty `{apiAnswer}` rather
+ * than falling through to the English one that carries the answer:
+ *
+ * ```
+ * at the CLI          No se ha podido completar la llamada a Cloudflare: 10000 Authentication error.
+ * across a step       No se ha podido completar la llamada a Cloudflare.
+ * ```
+ *
+ * The step channel carries three fields and `params` is not one of them, so closing this means widening
+ * the channel or re-parsing the promoted sentence — the first is a change to a durable format, the
+ * second reconstructs data from prose. Neither belongs in a re-raise, so the gap stands and is written
+ * down here instead of being claimed away.
  */
 export declare function terminalWorkflowError(args: {
     /** What the instance's steps said, or `null` when no step reported a failure. */

package/dist/workflows/stepFailure.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stepFailure.d.ts","sourceRoot":"","sources":["../../src/workflows/stepFailure.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AAMjE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,gHAAgH;AAChH,eAAO,MAAM,qBAAqB;;;iBAQwD,CAAC;AAC3F,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE3E,qGAAqG;AACrG,eAAO,MAAM,mBAAmB;;;;;;iBAK0D,CAAC;AAC3F,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;iBAQ+D,CAAC;AAC/F,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAErE,gGAAgG;AAChG,MAAM,WAAW,mBAAmB;IAClC,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yGAAyG;IACzG,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAmBD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAqBnG;AAcD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,GAAG,mBAAmB,GAAG,IAAI,CAoB7F;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAG,sBAA+B,CAAC;AAEpE,oGAAoG;AACpG,eAAO,MAAM,sBAAsB,EAAG,GAAY,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,iFAAiF;IACjF,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACpC,8FAA8F;IAC9F,eAAe,EAAE,MAAM,CAAC;IACxB,uGAAuG;IACvG,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,UAAU,CAmBb"}
+{"version":3,"file":"stepFailure.d.ts","sourceRoot":"","sources":["../../src/workflows/stepFailure.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AAOjE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,gHAAgH;AAChH,eAAO,MAAM,qBAAqB;;;iBAQwD,CAAC;AAC3F,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE3E,qGAAqG;AACrG,eAAO,MAAM,mBAAmB;;;;;;iBAK0D,CAAC;AAC3F,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;iBAQ+D,CAAC;AAC/F,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAErE,gGAAgG;AAChG,MAAM,WAAW,mBAAmB;IAClC,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yGAAyG;IACzG,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAmBD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAqBnG;AAcD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,GAAG,mBAAmB,GAAG,IAAI,CAoB7F;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAG,sBAA+B,CAAC;AAEpE,oGAAoG;AACpG,eAAO,MAAM,sBAAsB,EAAG,GAAY,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,iFAAiF;IACjF,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACpC,8FAA8F;IAC9F,eAAe,EAAE,MAAM,CAAC;IACxB,uGAAuG;IACvG,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,UAAU,CAmBb"}

package/dist/workflows/stepFailure.js

@@ -2,8 +2,9 @@
 // SPDX-License-Identifier: MIT
 import { z } from "zod";
 import { PithyError } from "@pithy-sh/core/src/error/pithyError";
-import { ErrorPayload, kitErrorStatus } from "@pithy-sh/core/src/error/payload";
 import { MAX_WORKFLOW_STEP_TEXT, decodeWorkflowStepMessage, splitWorkflowStepCode } from "@pithy-sh/core/src/workflow/stepMessage";
+import { guaranteedErrorParams } from "@pithy-sh/core/src/error/messageParams";
+import { ErrorPayload, kitErrorStatus } from "@pithy-sh/core/src/error/payload";
 //#region src/workflows/stepFailure.ts
 /**
 * **The step's sentence, recovered from an instance the engine has already written its own over.**
@@ -200,6 +201,34 @@ const WORKFLOW_FAILED_STATUS = 500;
 * the boundary — and nothing derived from the step's own `detail` is in it, because the step's
 * `detail` never left the step. The only fields promoted from the far side are `message` and `action`,
 * both already public, both already proved kit-authored by `kitSentence`.
+*
+* ## `params` did not cross either, and a recovered code still has to keep their promise
+*
+* `core`'s `GUARANTEED_ERROR_PARAMS` states the names a code's throw sites pass on **every** path, and
+* a locale writes `{apiAnswer}` into its sentence against that statement. Re-raising a recovered code
+* here is a throw site like any other — it just happens to be one whose inputs came over a wire that
+* carries three fields. So every guaranteed name is supplied, as the empty string: `interpolate` leaves
+* an unsupplied placeholder written out, and `{apiAnswer}` on a Spanish reader's screen is the exact
+* defect the declaration exists to prevent. Empty is also the honest value — it is what the catalogs
+* define as *no answer to quote*, and the answer genuinely did not cross.
+*
+* **One reader does lose something by it, and it is worth naming rather than glossing.** An earlier
+* version of this comment said nothing was lost, on the grounds that the API's words are already inside
+* the promoted English `message`. That is true of the operator's terminal, the `--json` line and any
+* client with no catalog — but the contract is `t.maybe(payload.code, payload.params) ?? payload.message`
+* (`core/src/i18n/translator.ts`), and `maybe` returns null only on a catalog **miss**. `es` has an entry
+* for this code, so a Spanish reader gets the translated sentence with an empty `{apiAnswer}` rather
+* than falling through to the English one that carries the answer:
+*
+* ```
+* at the CLI          No se ha podido completar la llamada a Cloudflare: 10000 Authentication error.
+* across a step       No se ha podido completar la llamada a Cloudflare.
+* ```
+*
+* The step channel carries three fields and `params` is not one of them, so closing this means widening
+* the channel or re-parsing the promoted sentence — the first is a change to a durable format, the
+* second reconstructs data from prose. Neither belongs in a re-raise, so the gap stands and is written
+* down here instead of being claimed away.
 */
 function terminalWorkflowError(args) {
 	const { failure, fallbackMessage, detail } = args;
@@ -212,7 +241,8 @@ function terminalWorkflowError(args) {
 			status,
 			message,
 			action,
-			detail
+			detail,
+			params: crossedParams(failure.code)
 		};
 		const parsed = ErrorPayload.safeParse(candidate);
 		if (parsed.success) return new PithyError(parsed.data);
@@ -225,5 +255,17 @@ function terminalWorkflowError(args) {
 		detail
 	});
 }
+/**
+* The `params` a re-raised code owes a translating client: every name its throw sites guarantee, empty.
+*
+* `undefined` when the code guarantees none, so a payload for the other 60-odd codes is byte-identical
+* to what it was — an empty `params` object on every recovered error would be a new field on the wire
+* for no reader.
+*/
+function crossedParams(code) {
+	const names = guaranteedErrorParams(code);
+	if (names.length === 0) return void 0;
+	return Object.fromEntries(names.map((name) => [name, ""]));
+}
 //#endregion
 export { WORKFLOW_FAILED_CODE, WORKFLOW_FAILED_STATUS, WorkflowFailureDetail, WorkflowStepAttempt, WorkflowStepRecord, kitSentence, stepFailure, terminalWorkflowError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pithy-sh/cloudflare",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -36,7 +36,7 @@
     "@aws-sdk/client-s3": "^3.1111.0",
     "@aws-sdk/s3-request-presigner": "^3.1111.0",
     "@cloudflare/workers-types": "^5.20260729.1",
-    "@pithy-sh/core": "^0.2.0",
+    "@pithy-sh/core": "^0.3.1",
     "cloudflare": "^7.0.0",
     "js-base64": "^3.9.2"
   },