@pithy-sh/cloudflare 0.4.2 → 0.6.0

package/src/client/clients.ts

@@ -4,6 +4,8 @@
 import { CloudflareAIManager } from "../ai/aiManager";
 import { CloudflareVectorizeManager } from "../ai/vectorizeManager";
 import { CloudflareVectorizeProvisioner } from "../ai/vectorizeProvisioner";
+import { CloudflareAnalyticsManager } from "../analytics/analyticsManager";
+import { CloudflareArtifactsManager } from "../artifacts/artifactsManager";
 import { CloudflareD1Manager } from "../d1/d1Manager";
 import { CloudflareD1Provisioner } from "../d1/d1Provisioner";
 import { CloudflareEmailRoutingManager } from "../email/emailRoutingManager";
@@ -14,6 +16,7 @@ import { CloudflareKVProvisioner } from "../kv/kvProvisioner";
 import { CloudflareImageManager } from "../media/imageManager";
 import { CloudflareStreamManager } from "../media/streamManager";
 import { CloudflareQueueManager } from "../queue/queueManager";
+import { CloudflareQueueProvisioner } from "../queue/queueProvisioner";
 import type { R2Credentials } from "../r2/r2Credentials";
 import { CloudflareR2Manager } from "../r2/r2Manager";
 import { CloudflareR2Provisioner } from "../r2/r2Provisioner";
@@ -35,7 +38,7 @@ import type { CloudflareManagerConfig } from "./manager";
  *
  * Resource-scoped managers (KV, D1, queues, Vectorize indexes, secret stores, hostname zones, R2
  * buckets) are keyed by their resource id, so repeated calls for the same id return one shared
- * instance. Account-scoped managers (AI, Images, Stream, Workers, Builds, Turnstile) are singletons.
+ * instance. Account-scoped managers (AI, Images, Stream, Analytics, Workers, Builds, Turnstile) are singletons.
  */
 export class CloudflareClients {
   private readonly config: CloudflareManagerConfig;
@@ -62,6 +65,8 @@ export class CloudflareClients {
 
   private streamManager?: CloudflareStreamManager;
 
+  private analyticsManager?: CloudflareAnalyticsManager;
+
   private workersManager?: CloudflareWorkersManager;
 
   private buildsManager?: CloudflareBuildsManager;
@@ -81,6 +86,10 @@ export class CloudflareClients {
 
   private r2ProvisionerManager?: CloudflareR2Provisioner;
 
+  private queueProvisionerManager?: CloudflareQueueProvisioner;
+
+  private artifactsManager?: CloudflareArtifactsManager;
+
   private vectorizeProvisionerManager?: CloudflareVectorizeProvisioner;
 
   constructor(config: CloudflareManagerConfig) {
@@ -167,6 +176,12 @@ export class CloudflareClients {
     return this.streamManager;
   }
 
+  /** The account-scoped GraphQL Analytics manager. */
+  analytics(): CloudflareAnalyticsManager {
+    this.analyticsManager ??= new CloudflareAnalyticsManager(this.config);
+    return this.analyticsManager;
+  }
+
   /** The account-scoped Workers (scripts/deployments) manager. */
   workers(): CloudflareWorkersManager {
     this.workersManager ??= new CloudflareWorkersManager(this.config);
@@ -209,6 +224,18 @@ export class CloudflareClients {
     return this.r2ProvisionerManager;
   }
 
+  /** The account-scoped Queues control plane — create, find, and delete queues. */
+  queueProvisioner(): CloudflareQueueProvisioner {
+    this.queueProvisionerManager ??= new CloudflareQueueProvisioner(this.config);
+    return this.queueProvisionerManager;
+  }
+
+  /** The account-scoped Artifacts control plane — list and delete the repos in a namespace (#673). */
+  artifacts(): CloudflareArtifactsManager {
+    this.artifactsManager ??= new CloudflareArtifactsManager(this.config);
+    return this.artifactsManager;
+  }
+
   /** The account-scoped Vectorize control plane — create, find, list, and delete indexes and their metadata indexes. */
   vectorizeProvisioner(): CloudflareVectorizeProvisioner {
     this.vectorizeProvisionerManager ??= new CloudflareVectorizeProvisioner(this.config);

package/src/client/manager.ts

@@ -17,6 +17,15 @@ export interface CloudflareManagerConfig {
   apiToken: string;
   /** The Cloudflare account id all operations target (`CLOUDFLARE_ACCOUNT_ID`). */
   accountId: string;
+  /**
+   * The token to call with *now*, read at every call, when it can change during the manager's life (#759).
+   *
+   * A signed-in session's access token lasts an hour and is renewed on disk ahead of that, so a manager
+   * built at the start of a long run would otherwise keep sending the token it was constructed with.
+   * Absent, {@link apiToken} is the token for good — which is every command that finishes inside the hour
+   * dispatch guarantees it.
+   */
+  tokenProvider?: () => string;
 }
 
 /**
@@ -26,9 +35,10 @@ export interface CloudflareManagerConfig {
  * (`validateServiceAccess`).
  */
 export abstract class CloudflareManager {
-  private readonly client: Cloudflare;
+  /** The SDK client, and the token it was built for — rebuilt when {@link getApiToken} answers another. */
+  private client: { token: string; sdk: Cloudflare };
 
-  private readonly apiToken: string;
+  private readonly token: () => string;
 
   protected readonly accountId: string;
 
@@ -39,22 +49,30 @@ export abstract class CloudflareManager {
     if (!config.accountId) {
       throw new CloudflareNotConfiguredError({ detail: "Missing accountId in CloudflareManagerConfig." });
     }
-    this.client = new Cloudflare({ apiToken: config.apiToken });
-    this.apiToken = config.apiToken;
+    const initial = config.apiToken;
+    this.token = config.tokenProvider ?? (() => initial);
+    this.client = { token: initial, sdk: new Cloudflare({ apiToken: initial }) };
     this.accountId = config.accountId;
   }
 
   /** The configured SDK client. Subclasses route typed calls through this. */
   protected getClient(): Cloudflare {
-    return this.client;
+    const token = this.getApiToken();
+    if (token !== this.client.token) this.client = { token, sdk: new Cloudflare({ apiToken: token }) };
+    return this.client.sdk;
   }
 
   /**
    * The raw API token, for subclasses that fall back to direct `fetch()` for endpoints the typed
    * SDK does not cover (e.g. Workers Builds, event subscriptions). The documented escape hatch.
+   * Read through the provider at every call, so it is the current token, never the constructed one.
    */
   protected getApiToken(): string {
-    return this.apiToken;
+    const token = this.token();
+    if (!token) {
+      throw new CloudflareNotConfiguredError({ detail: "The tokenProvider answered no apiToken." });
+    }
+    return token;
   }
 
   /** The account id all operations target. */

package/src/d1/d1Manager.ts

@@ -7,7 +7,7 @@ import type { D1 } from "cloudflare/resources/d1/d1";
 import type { QueryResult } from "cloudflare/resources/d1/database";
 import { CloudflareNotConfiguredError, cloudflareRequest, reasonOf } from "../client/errors";
 import { CloudflareManager, type CloudflareManagerConfig } from "../client/manager";
-import { D1PreparedStatementREST } from "./d1PreparedStatement";
+import { D1_QUERY_REQUEST, D1PreparedStatementREST } from "./d1PreparedStatement";
 
 /** Config for the D1 manager: the shared client config plus the database it targets. */
 export interface D1ManagerConfig extends CloudflareManagerConfig {
@@ -68,7 +68,7 @@ export class CloudflareD1Manager extends CloudflareManager implements D1Database
 
   async exec(query: string): Promise<D1ExecResult> {
     const response = await cloudflareRequest("D1 exec", () =>
-      this.getClient().d1.database.query(this.databaseId, { account_id: this.accountId, sql: query }),
+      this.getClient().d1.database.query(this.databaseId, { account_id: this.accountId, sql: query }, D1_QUERY_REQUEST),
     );
     const result = response.result[0];
     return { count: result?.results?.length ?? 0, duration: result?.meta?.duration ?? 0 };
@@ -89,7 +89,11 @@ export class CloudflareD1Manager extends CloudflareManager implements D1Database
   /** Run one SQL statement and return its raw REST result sets. */
   async executeQuery(sql: string, params?: string[]): Promise<QueryResult[]> {
     const response = await cloudflareRequest("D1 query", () =>
-      this.getClient().d1.database.query(this.databaseId, { account_id: this.accountId, sql, params }),
+      this.getClient().d1.database.query(
+        this.databaseId,
+        { account_id: this.accountId, sql, params },
+        D1_QUERY_REQUEST,
+      ),
     );
     return response.result;
   }

package/src/d1/d1PreparedStatement.ts

@@ -31,6 +31,17 @@ function mapMeta(restMeta?: QueryResult.Meta): D1Meta & Record<string, unknown>
   };
 }
 
+/**
+ * The request options every D1 query is sent with: **no retries** (#709).
+ *
+ * The SDK retries a request twice by default, on a connection timeout, a 408, a 409, a 429 or a 5xx. That is
+ * safe for a read of a resource and wrong for a query, which is not idempotent: D1 can apply a statement and
+ * answer slowly, and the resent copy then runs against the changed database. A migration's `CREATE TABLE` did
+ * exactly that and failed `table already exists`, on a step that had succeeded. Sent once, a slow answer
+ * surfaces as the timeout it was, and `cloudflareRequest` already tells the operator to check before retrying.
+ */
+export const D1_QUERY_REQUEST = { maxRetries: 0 } as const;
+
 /** The REST `params` array is strings; coerce each bound value the way the D1 REST API expects. */
 function toStringParams(params: unknown[]): string[] {
   return params.map((value) => {
@@ -88,7 +99,11 @@ export class D1PreparedStatementREST<T = Record<string, unknown>> implements D1P
   async raw<U = unknown[]>(options?: { columnNames?: boolean }): Promise<U[] | [string[], ...U[]]> {
     const params = this.boundParams.length > 0 ? toStringParams(this.boundParams) : undefined;
     const response = await cloudflareRequest("D1 raw query", () =>
-      this.client.d1.database.raw(this.databaseId, { account_id: this.accountId, sql: this.sql, params }),
+      this.client.d1.database.raw(
+        this.databaseId,
+        { account_id: this.accountId, sql: this.sql, params },
+        D1_QUERY_REQUEST,
+      ),
     );
     const rawResult = response.result[0];
     const rows = (rawResult?.results?.rows ?? []) as U[];
@@ -102,7 +117,11 @@ export class D1PreparedStatementREST<T = Record<string, unknown>> implements D1P
   private async executeQuery<U>(): Promise<D1Result<U>> {
     const params = this.boundParams.length > 0 ? toStringParams(this.boundParams) : undefined;
     const response = await cloudflareRequest("D1 query", () =>
-      this.client.d1.database.query(this.databaseId, { account_id: this.accountId, sql: this.sql, params }),
+      this.client.d1.database.query(
+        this.databaseId,
+        { account_id: this.accountId, sql: this.sql, params },
+        D1_QUERY_REQUEST,
+      ),
     );
     const queryResult = response.result[0];
     return {

package/src/media/imageManager.ts

@@ -8,7 +8,8 @@ import type {
   DirectUploadCreateResponse,
 } from "cloudflare/resources/images/v2/direct-uploads";
 import type { V2ListParams } from "cloudflare/resources/images/v2/v2";
-import { cloudflareRequest } from "../client/errors";
+import { z } from "zod";
+import { CloudflareInvalidResponseError, cloudflareRequest } from "../client/errors";
 import { CloudflareManager } from "../client/manager";
 
 /**
@@ -29,6 +30,59 @@ function encodeMetadata(metadata: unknown): unknown {
   return metadata === undefined || metadata === null ? metadata : JSON.stringify(metadata);
 }
 
+/** One of the account's Images URL-signing keys. The value is the HMAC secret signed URLs are minted with. */
+export const ImagesSigningKey = z
+  .object({
+    name: z.string().min(1).describe("The key's name. Cloudflare provisions one named `default`."),
+    value: z.string().min(1).describe("The key itself — the HMAC-SHA256 secret a signed delivery URL is minted with."),
+  })
+  .describe("One Cloudflare Images URL-signing key.");
+export type ImagesSigningKey = z.infer<typeof ImagesSigningKey>;
+
+const SigningKeysResponse = z
+  .object({ keys: z.array(ImagesSigningKey).optional().describe("The account's signing keys.") })
+  .describe("The Images signing-keys response.");
+
+/** One Images variant, and whether it serves an image without a signature whatever the image requires. */
+export const ImagesVariant = z
+  .object({
+    id: z.string().describe("The variant's name, as it appears in a delivery URL."),
+    neverRequireSignedURLs: z
+      .boolean()
+      .describe("Whether this variant serves every image unsigned, even one uploaded with requireSignedURLs."),
+  })
+  .describe("One Cloudflare Images variant's signing posture.");
+export type ImagesVariant = z.infer<typeof ImagesVariant>;
+
+const VariantsResponse = z
+  .object({
+    variants: z
+      .record(
+        z.string(),
+        z
+          .object({
+            id: z.string().describe("The variant name."),
+            neverRequireSignedURLs: z.boolean().optional().describe("Whether it ignores signing."),
+          })
+          .describe("One variant as the API returns it."),
+      )
+      .optional()
+      .describe("Every variant, keyed by name."),
+  })
+  .describe("The Images variants response.");
+
+/** Parse an Images response the SDK types loosely, refusing a shape we cannot read. */
+function parseResponse<T>(schema: z.ZodType<T>, response: unknown, what: string): T {
+  const result = schema.safeParse(response);
+  if (!result.success) {
+    throw new CloudflareInvalidResponseError({
+      message: `An Images ${what} response had an unexpected shape.`,
+      detail: result.error.message,
+    });
+  }
+  return result.data;
+}
+
 /**
  * Out-of-Worker Cloudflare Images access over the REST API: upload, fetch, edit, delete, list, and
  * direct-upload URLs from a CLI/CI/provisioning context. Image metadata is an arbitrary
@@ -109,6 +163,44 @@ export class CloudflareImageManager extends CloudflareManager {
     });
   }
 
+  /**
+   * The account's URL-signing keys — what a signed delivery URL for an image uploaded with
+   * `requireSignedURLs` is minted with. Cloudflare provisions a `default` key per account.
+   */
+  async signingKeys(): Promise<ImagesSigningKey[]> {
+    return cloudflareRequest("Images list signing keys", async () => {
+      const response = await this.getClient().images.v1.keys.list({ account_id: this.accountId }, requestOptions);
+      return parseResponse(SigningKeysResponse, response, "signing keys").keys ?? [];
+    });
+  }
+
+  /** Create a named signing key, or roll it if it exists. Answers with every key the account then holds. */
+  async createSigningKey(name: string): Promise<ImagesSigningKey[]> {
+    return cloudflareRequest(`Images create signing key '${name}'`, async () => {
+      const response = await this.getClient().images.v1.keys.update(
+        name,
+        { account_id: this.accountId },
+        requestOptions,
+      );
+      return parseResponse(SigningKeysResponse, response, "signing keys").keys ?? [];
+    });
+  }
+
+  /**
+   * Every variant, with whether it serves unsigned. A variant set to `neverRequireSignedURLs` delivers a
+   * private image to anyone holding its URL, which is why media's provisioning reads this.
+   */
+  async listVariants(): Promise<ImagesVariant[]> {
+    return cloudflareRequest("Images list variants", async () => {
+      const response = await this.getClient().images.v1.variants.list({ account_id: this.accountId }, requestOptions);
+      const variants = parseResponse(VariantsResponse, response, "variants").variants ?? {};
+      return Object.values(variants).map((variant) => ({
+        id: variant.id,
+        neverRequireSignedURLs: variant.neverRequireSignedURLs === true,
+      }));
+    });
+  }
+
   getServiceType(): string {
     return "Cloudflare Images";
   }

package/src/media/streamManager.ts

@@ -68,6 +68,19 @@ function parseDownloadStatus(response: unknown): StreamDownloadStatus {
   return result.data;
 }
 
+/**
+ * A Stream signing key: what a signed playback token for a video uploaded with `requireSignedURLs` is
+ * signed with. The JWK is base64 of the key's JSON, as Cloudflare returns it — a single line, so it is
+ * the form stored, where the PEM is not.
+ */
+export const StreamSigningKey = z
+  .object({
+    id: z.string().min(1).describe("The key id — the `kid` a signed token names."),
+    jwk: z.string().min(1).describe("The RSA private key as base64-encoded JWK, as Cloudflare returns it."),
+  })
+  .describe("One Cloudflare Stream signing key.");
+export type StreamSigningKey = z.infer<typeof StreamSigningKey>;
+
 /**
  * Out-of-Worker Cloudflare Stream access over the REST API: delete, fetch, edit, direct uploads,
  * and download (MP4 + audio-only) management from a CLI/CI/provisioning context. Video metadata is
@@ -182,6 +195,27 @@ export class CloudflareStreamManager extends CloudflareManager {
     );
   }
 
+  /**
+   * Create a signing key. Cloudflare returns the private half once, on creation, and never again — so the
+   * caller stores it, and a lost key is replaced by creating another.
+   */
+  async createSigningKey(): Promise<StreamSigningKey> {
+    return cloudflareRequest("Stream create signing key", async () => {
+      const response = await this.getClient().stream.keys.create(
+        { account_id: this.accountId, body: {} },
+        requestOptions,
+      );
+      const parsed = StreamSigningKey.safeParse(response);
+      if (!parsed.success) {
+        throw new CloudflareInvalidResponseError({
+          message: "A Stream signing-key response had an unexpected shape.",
+          detail: parsed.error.message,
+        });
+      }
+      return parsed.data;
+    });
+  }
+
   getServiceType(): string {
     return "Cloudflare Stream";
   }

package/src/oauth/callback.ts

@@ -0,0 +1,70 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { commandName } from "@pithy-sh/core/src/cli/command";
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+
+/** What a callback said: a code to redeem, or Cloudflare's refusal. */
+export type CallbackAnswer = { kind: "code"; code: string } | { kind: "error"; error: string; description: string };
+
+/** What the address must match: the `state` and `redirect_uri` this sign-in sent. */
+export interface CallbackExpectation {
+  /** The `state` in the authorize URL. */
+  state: string;
+  /** The `redirect_uri` in the authorize URL, verbatim. */
+  redirectUri: string;
+}
+
+/**
+ * Read the address a browser landed on — from the loopback listener or pasted by hand — into an answer.
+ *
+ * **One reader for both paths, so they cannot check different things.** A remote session pastes what its
+ * browser shows, because the redirect lands on the browser's own loopback interface, where nothing is
+ * listening (measured over SSH, 2026-10-15). The pasted address is held to exactly what a delivered
+ * callback is: the same origin and path this sign-in sent, the same `state`, and a `code` or an `error`.
+ *
+ * Accepting a paste is safe because of PKCE, not because of this check — a code is worthless without the
+ * verifier, and the verifier never left this process. The `state` check is what stops a code from a
+ * *different* sign-in being redeemed into this one.
+ */
+export function readCallback(address: string, expect: CallbackExpectation): CallbackAnswer {
+  const text = address.trim().replace(/^["']|["']$/g, "");
+  let url: URL;
+  try {
+    url = new URL(text);
+  } catch {
+    throw notTheAddress(expect, "it is not an address");
+  }
+  const sent = new URL(expect.redirectUri);
+  if (url.origin !== sent.origin || url.pathname !== sent.pathname) {
+    throw notTheAddress(expect, `it is ${url.origin}${url.pathname}`);
+  }
+  if (url.searchParams.get("state") !== expect.state) {
+    throw new ValidationError({
+      message: "That address belongs to a different sign-in: its state does not match.",
+      action: `Paste the address from the browser tab this sign-in opened, or run ${commandName("cloudflare connect")} again.`,
+      detail: "callback state did not match the state this sign-in sent",
+    });
+  }
+  const error = url.searchParams.get("error");
+  if (error !== null) {
+    return { kind: "error", error, description: url.searchParams.get("error_description") ?? error };
+  }
+  const code = url.searchParams.get("code");
+  if (code === null || code === "") {
+    throw new ValidationError({
+      message: "That address carries no code and no error.",
+      action: "Paste the whole address from the browser's address bar, after you approve.",
+      detail: "callback had neither `code` nor `error`",
+    });
+  }
+  return { kind: "code", code };
+}
+
+function notTheAddress(expect: CallbackExpectation, why: string): ValidationError {
+  return new ValidationError({
+    message: `That is not the address this sign-in sent the browser to: ${why}.`,
+    action: `Paste the whole address your browser landed on. It starts with ${expect.redirectUri}.`,
+    detail: `expected ${expect.redirectUri}`,
+  });
+}

package/src/oauth/catalog.ts

@@ -0,0 +1,39 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { cloudflareRequest, decodeResponse } from "../client/errors";
+
+/** One OAuth scope, as Cloudflare's catalog lists it. */
+export const OAuthScope = z
+  .object({
+    id: z.string().describe("The scope a client requests: `d1.write`."),
+    name: z.string().describe("Its display name, which is the permission group's own: `D1 Write`."),
+    category: z.string().optional().describe("Cloudflare's grouping, e.g. `developer_platform`."),
+  })
+  .describe("One scope in `GET /oauth/scopes`.");
+export type OAuthScope = z.output<typeof OAuthScope>;
+
+const ScopeList = z.object({ result: z.array(OAuthScope) });
+
+/** The catalog's endpoint. Global: it needs authentication and no account. */
+export const OAUTH_SCOPES_URL = "https://api.cloudflare.com/client/v4/oauth/scopes";
+
+/**
+ * **Cloudflare's OAuth scope catalog: every scope a third-party client may register (#759).**
+ *
+ * The third column of the permission table is checked against this the way the group names are checked
+ * against the account, because a scope id that drifts from it is a sign-in Cloudflare refuses with
+ * `invalid_scope` — at the consent screen of an adopter, rather than in this repository's CI.
+ */
+export async function listOAuthScopes(options: {
+  apiToken: string;
+  fetch?: (url: string, init: { headers: Record<string, string> }) => Promise<Response>;
+}): Promise<OAuthScope[]> {
+  const send = options.fetch ?? ((url, init) => globalThis.fetch(url, init));
+  const raw = await cloudflareRequest("list OAuth scopes", async () => {
+    const response = await send(OAUTH_SCOPES_URL, { headers: { authorization: `Bearer ${options.apiToken}` } });
+    return (await response.json()) as unknown;
+  });
+  return decodeResponse(ScopeList, raw, "oauth scopes list").result;
+}