@pithy-sh/cloudflare 0.1.6 → 0.2.0

package/src/test-utils/inboundRecorder.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import { z } from "zod";
-import { CloudflareInvalidResponseError, CloudflareRequestError } from "../client/errors";
+import { CloudflareInvalidResponseError, cloudflareApiErrors, cloudflareRefusal } from "../client/errors";
 import type { CloudflareWorkersManager } from "../workers/workersManager";
 import type { IntegrationCreds } from "./harness";
 
@@ -169,10 +169,15 @@ export async function readObservedInbound(options: {
   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}.`,
+    // Composed where every Cloudflare refusal is — see `client/errors.ts`. The polling loop reads this
+    // on every failed attempt, so it is worth the code Cloudflare actually answered with.
+    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, 2000),
     });
   }
 
@@ -187,3 +192,12 @@ export 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: string): unknown {
+  try {
+    return JSON.parse(body);
+  } catch {
+    return undefined;
+  }
+}

package/src/tokens/accountTokensManager.ts

@@ -4,15 +4,34 @@
 import { z } from "zod";
 import {
   CloudflareNotConfiguredError,
-  CloudflareRequestError,
+  cloudflareApiErrors,
+  cloudflareRefusal,
   cloudflareRequest,
+  cloudflareSaid,
   decodeResponse,
   isAuthorizationError,
   messageOf,
+  statusOf,
 } from "../client/errors";
 import { CloudflareManager } from "../client/manager";
 import { CfTokenVerification } from "../user/userManager";
 
+/**
+ * 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" } as const;
+
 /**
  * One access policy to attach to a minted token: a set of permission groups (named, resolved to ids
  * at mint time) and the resources they apply to. This is the reusable unit — every use case that
@@ -132,30 +151,38 @@ export class CloudflareAccountTokensManager extends CloudflareManager {
    * with no permission at all. Every other failure still throws.
    */
   async getTokenName(tokenId: string): Promise<string | null> {
-    const raw = await cloudflareRequest(`get account token ${tokenId}`, async () => {
-      try {
-        return await this.getClient().accounts.tokens.get(tokenId, { account_id: this.accountId });
-      } catch (error) {
-        if (isAuthorizationError(error)) return null;
-        throw error;
-      }
-    });
+    const raw = await cloudflareRequest(
+      `get account token ${tokenId}`,
+      async () => {
+        try {
+          return await this.getClient().accounts.tokens.get(tokenId, { account_id: this.accountId });
+        } catch (error) {
+          if (isAuthorizationError(error)) return null;
+          throw error;
+        }
+      },
+      API_TOKENS_ENDPOINT,
+    );
     const parsed = TokenName.safeParse(raw);
     return parsed.success ? parsed.data.name : null;
   }
 
   /** Every permission group available to account-owned tokens in this account (SDK auto-paginates). */
   async listPermissionGroups(): Promise<CfPermissionGroup[]> {
-    return cloudflareRequest("list account token permission groups", async () => {
-      const out: CfPermissionGroup[] = [];
-      for await (const group of this.getClient().accounts.tokens.permissionGroups.list({
-        account_id: this.accountId,
-      })) {
-        const parsed = CfPermissionGroup.safeParse(group);
-        if (parsed.success) out.push(parsed.data);
-      }
-      return out;
-    });
+    return cloudflareRequest(
+      "list account token permission groups",
+      async () => {
+        const out: CfPermissionGroup[] = [];
+        for await (const group of this.getClient().accounts.tokens.permissionGroups.list({
+          account_id: this.accountId,
+        })) {
+          const parsed = CfPermissionGroup.safeParse(group);
+          if (parsed.success) out.push(parsed.data);
+        }
+        return out;
+      },
+      API_TOKENS_ENDPOINT,
+    );
   }
 
   /**
@@ -189,19 +216,40 @@ export class CloudflareAccountTokensManager extends CloudflareManager {
       raw = await this.getClient().accounts.tokens.create({ account_id: this.accountId, name, policies });
     } catch (error) {
       if (isAuthorizationError(error)) {
+        // The 403 keeps its own diagnosis — the token got in and may not create tokens, which is more
+        // than the generic three-way refusal can say — and it no longer keeps it *instead of*
+        // Cloudflare's answer. Round two moved the fallback below onto the shared composer and left
+        // this branch composing its own sentence, so the one status that carries a real diagnosis was
+        // also the one that dropped the API's `errors[]` on the floor. `cloudflareSaid` is that
+        // composition, exported for exactly this: a call site with a better problem line still gets
+        // the API's words, on one line, bounded, with the structured fields in `params`.
+        const said = cloudflareSaid(
+          "The Cloudflare API token is not allowed to create account tokens.",
+          cloudflareApiErrors(error),
+        );
         throw new CloudflareNotConfiguredError(
           {
-            message: "The Cloudflare API token is not allowed to create account tokens.",
+            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 new CloudflareRequestError(
-        { message: `Failed to mint account token '${name}'.`, detail: messageOf(error) },
-        { cause: error },
-      );
+      // The shared composer, never a hand-built refusal. The branch above is 403-only on purpose —
+      // `isAuthorizationError` stays strictly 403 because its other callers *swallow* a denial — and a
+      // 401 is the status the token bootstrap actually fails under, so every 401 landed here and
+      // printed one sentence with no code, no link and nothing to do. `permission` names the group
+      // this endpoint needs, because Cloudflare's docs link for `accounts/tokens` does not.
+      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");
   }
@@ -235,31 +283,41 @@ export class CloudflareAccountTokensManager extends CloudflareManager {
 
   /** Every account-owned token's metadata (SDK auto-paginates). No secret values — list is metadata only. */
   async listTokens(): Promise<AccountTokenSummary[]> {
-    return cloudflareRequest("list account tokens", async () => {
-      const out: AccountTokenSummary[] = [];
-      for await (const token of this.getClient().accounts.tokens.list({ account_id: this.accountId })) {
-        const parsed = AccountTokenSummary.safeParse(token);
-        if (parsed.success) out.push(parsed.data);
-      }
-      return out;
-    });
+    return cloudflareRequest(
+      "list account tokens",
+      async () => {
+        const out: AccountTokenSummary[] = [];
+        for await (const token of this.getClient().accounts.tokens.list({ account_id: this.accountId })) {
+          const parsed = AccountTokenSummary.safeParse(token);
+          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: string): Promise<AccountTokenSummary | null> {
-    return cloudflareRequest(`find account token ${name}`, async () => {
-      for await (const token of this.getClient().accounts.tokens.list({ account_id: this.accountId })) {
-        const parsed = AccountTokenSummary.safeParse(token);
-        if (parsed.success && parsed.data.name === name) return parsed.data;
-      }
-      return null;
-    });
+    return cloudflareRequest(
+      `find account token ${name}`,
+      async () => {
+        for await (const token of this.getClient().accounts.tokens.list({ account_id: this.accountId })) {
+          const parsed = AccountTokenSummary.safeParse(token);
+          if (parsed.success && parsed.data.name === name) return parsed.data;
+        }
+        return null;
+      },
+      API_TOKENS_ENDPOINT,
+    );
   }
 
   /** Delete an account token by id. */
   async deleteToken(tokenId: string): Promise<void> {
-    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,
     );
   }
 
@@ -269,17 +327,21 @@ export class CloudflareAccountTokensManager extends CloudflareManager {
    * when none match. Used by teardown.
    */
   async deleteTokensByName(name: string): Promise<number> {
-    return cloudflareRequest(`delete account tokens named ${name}`, async () => {
-      const ids: string[] = [];
-      for await (const token of this.getClient().accounts.tokens.list({ account_id: this.accountId })) {
-        const parsed = AccountTokenSummary.safeParse(token);
-        if (parsed.success && parsed.data.name === name) ids.push(parsed.data.id);
-      }
-      for (const id of ids) {
-        await this.getClient().accounts.tokens.delete(id, { account_id: this.accountId });
-      }
-      return ids.length;
-    });
+    return cloudflareRequest(
+      `delete account tokens named ${name}`,
+      async () => {
+        const ids: string[] = [];
+        for await (const token of this.getClient().accounts.tokens.list({ account_id: this.accountId })) {
+          const parsed = AccountTokenSummary.safeParse(token);
+          if (parsed.success && parsed.data.name === name) ids.push(parsed.data.id);
+        }
+        for (const id of ids) {
+          await this.getClient().accounts.tokens.delete(id, { account_id: this.accountId });
+        }
+        return ids.length;
+      },
+      API_TOKENS_ENDPOINT,
+    );
   }
 
   /**
@@ -289,8 +351,10 @@ export class CloudflareAccountTokensManager extends CloudflareManager {
    * builds on: a credential self-rolls without ever changing identity.
    */
   async rollTokenValue(tokenId: string): Promise<string> {
-    const raw = await cloudflareRequest(`roll account token value ${tokenId}`, () =>
-      this.getClient().accounts.tokens.value.update(tokenId, { account_id: this.accountId, body: {} }),
+    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/src/workers/buildsManager.ts

@@ -5,6 +5,8 @@ import { z } from "zod";
 import {
   CloudflareInvalidResponseError,
   CloudflareRequestError,
+  cloudflareApiErrors,
+  cloudflareRefusal,
   cloudflareRequest,
   decodeResponse,
   messageOf,
@@ -32,7 +34,17 @@ const NOT_FOUND = 12000;
 const CfEnvelope = z.object({
   result: z.unknown(),
   success: z.boolean().optional(),
-  errors: z.array(z.object({ code: z.number().optional(), message: z.string().optional() }).loose()).optional(),
+  errors: z
+    .array(
+      z
+        .object({
+          code: z.number().optional(),
+          message: z.string().optional(),
+          documentation_url: z.string().optional(),
+        })
+        .loose(),
+    )
+    .optional(),
 });
 
 /** Arguments for `createRepoConnection`. */
@@ -138,12 +150,15 @@ export class CloudflareBuildsManager extends CloudflareManager {
     // CF signals failure two ways: a non-2xx status, or a 200 body with `success: false`.
     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 is number => c !== undefined)
-        : [];
+      const errors = envelope.success ? (envelope.data.errors ?? []) : [];
+      const codes = errors.map((e) => e.code).filter((c): c is number => c !== undefined);
       const marker = codes.length > 0 ? `[cf-codes:${codes.join(",")}] ` : "";
-      throw new CloudflareRequestError({
-        message: `Cloudflare Builds returned ${response.status}.`,
+      // The shared composer, so the one manager on the raw-`fetch` escape hatch refuses with the same
+      // projection of Cloudflare's `errors[]` as the 133 calls that go through `cloudflareRequest`.
+      throw cloudflareRefusal({
+        problem: `Cloudflare Builds returned ${response.status}.`,
+        apiErrors: cloudflareApiErrors(errors),
+        status: response.status,
         detail: `${marker}${method} ${path} → ${response.status}: ${text}`.slice(0, 2000),
       });
     }

package/src/workers/workersManager.ts

@@ -5,11 +5,12 @@ import { NotFoundError, ValidationError } from "@pithy-sh/core/src/error/pithyEr
 import type { Cloudflare } from "cloudflare";
 import type { RouteCreateResponse, RouteListResponse } from "cloudflare/resources/workers/routes";
 import type { Deployment } from "cloudflare/resources/workers/scripts/deployments";
+import type { ScriptAndVersionSettingGetResponse } from "cloudflare/resources/workers/scripts/script-and-version-settings";
 import type { Script } from "cloudflare/resources/workers/scripts/scripts";
 import type { SecretListResponse } from "cloudflare/resources/workers/scripts/secrets";
 import type { SettingEditParams } from "cloudflare/resources/workers/scripts/settings";
 import type { VersionGetResponse, VersionListResponse } from "cloudflare/resources/workers/scripts/versions";
-import { CloudflareInvalidResponseError, cloudflareRequest, messageOf } from "../client/errors";
+import { CloudflareInvalidResponseError, cloudflareRequest, isNotFoundError, messageOf } from "../client/errors";
 import { CloudflareManager } from "../client/manager";
 
 /** Per-call SDK timeout + retry budget for Worker management operations. */
@@ -212,6 +213,45 @@ export class CloudflareWorkersManager extends CloudflareManager {
     );
   }
 
+  /**
+   * A deployed Worker's **plain-text vars**, keyed by binding name — or `null` when the account holds
+   * no Worker of that name.
+   *
+   * Read through `scripts/script-and-version-settings`, which answers the *deployed* script's binding
+   * list in one call. {@link listVersions} + {@link getVersion} would answer the same question in two,
+   * off the newest *uploaded* version — which is not necessarily the deployed one under gradual
+   * rollouts, and which costs a round trip to learn a version id nobody wanted. So: settings.
+   *
+   * **Only `plain_text`.** A `secret_text` binding's value is never returned by the API, and a caller
+   * that wanted one would be asking the wrong question anyway; every other binding kind is a resource
+   * reference rather than a value. So this is the vars block a `wrangler.jsonc` declares, read back.
+   *
+   * `null` for a missing Worker rather than a throw, because "there is no such Worker" is an ordinary
+   * answer to this question — it is what a first deploy looks like. Every other failure throws, so a
+   * caller can tell *not deployed* from *the account would not answer*: {@link CloudflareWorkersManager}
+   * has no business collapsing those two into one silence, and #537's gate reports them differently.
+   */
+  async getWorkerVars(scriptName: string): Promise<Record<string, string> | null> {
+    return cloudflareRequest(`get vars for '${scriptName}'`, async () => {
+      let settings: ScriptAndVersionSettingGetResponse;
+      try {
+        settings = await this.getClient().workers.scripts.scriptAndVersionSettings.get(
+          scriptName,
+          { account_id: this.accountId },
+          requestOptions,
+        );
+      } catch (error) {
+        if (isNotFoundError(error)) return null;
+        throw error;
+      }
+      const vars: Record<string, string> = {};
+      for (const binding of settings.bindings ?? []) {
+        if (binding.type === "plain_text") vars[binding.name] = binding.text;
+      }
+      return vars;
+    });
+  }
+
   /** Edit a Worker's settings (observability, logpush, tags, …). */
   async updateSettings(scriptName: string, settings: WorkerSettings): Promise<void> {
     await cloudflareRequest(`update settings for '${scriptName}'`, () =>

package/src/workflows/stepFailure.ts

@@ -1,8 +1,10 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 
+import { guaranteedErrorParams } from "@pithy-sh/core/src/error/messageParams";
 import { ErrorPayload, kitErrorStatus } from "@pithy-sh/core/src/error/payload";
 import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
 import {
   decodeWorkflowStepMessage,
   MAX_WORKFLOW_STEP_TEXT,
@@ -250,6 +252,34 @@ export const WORKFLOW_FAILED_STATUS = 500 as const;
  * 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 function terminalWorkflowError(args: {
   /** What the instance's steps said, or `null` when no step reported a failure. */
@@ -267,7 +297,7 @@ export function terminalWorkflowError(args: {
 
   const status = failure?.code === undefined ? undefined : kitErrorStatus(failure.code);
   if (failure?.sentence !== undefined && failure.code !== undefined && status !== undefined) {
-    const candidate = { code: failure.code, status, message, action, detail };
+    const candidate = { code: failure.code, status, message, action, detail, params: crossedParams(failure.code) };
     // Parsed rather than trusted. A recovered code is a string from a Worker we did not write, and one
     // kit member (`validation/invalid_input`) requires a field this boundary has no way to supply — so
     // a payload that would not validate must not be thrown from the error path. It falls through to
@@ -278,3 +308,16 @@ export function terminalWorkflowError(args: {
 
   return new PithyError({ code: WORKFLOW_FAILED_CODE, status: WORKFLOW_FAILED_STATUS, message, action, 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: string): MessageParams | undefined {
+  const names = guaranteedErrorParams(code);
+  if (names.length === 0) return undefined;
+  return Object.fromEntries(names.map((name) => [name, ""]));
+}