@pithy-sh/cloudflare 0.5.0 → 0.7.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/errors.ts

@@ -3,6 +3,7 @@
 
 import { PithyError, UpstreamError, UpstreamTimeoutError } from "@pithy-sh/core/src/error/pithyError";
 import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
+import type { UnmarkedString } from "@pithy-sh/core/src/privacy/types";
 import { MAX_WORKFLOW_STEP_TEXT } from "@pithy-sh/core/src/workflow/stepMessage";
 import type { z } from "zod";
 
@@ -17,11 +18,11 @@ import type { z } from "zod";
 /** Variable parts each subclass accepts; `code`/`status` are fixed by the subclass. */
 interface CloudflareErrorArgs {
   /** Override the public, safe-to-expose message. */
-  message?: string;
+  message?: UnmarkedString;
   /** A remediation hint (CLI action line). */
-  action?: string;
+  action?: UnmarkedString;
   /** Internal context for logs + audit. Never serialized to clients. */
-  detail?: string;
+  detail?: UnmarkedString;
   /**
    * Values a translating client interpolates into its own wording for this code. Client-facing, so —
    * unlike `action` and `detail` — these cross the boundary with `message`.

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/scopes.ts

@@ -10,8 +10,8 @@ import { oauthScopesFor } from "../tokens/permissions";
  *   the person who signed in.
  * - `offline_access` — the only way Cloudflare issues a refresh token. Without it a session dies at the
  *   hour and every command after it opens a browser (measured 2026-10-15).
- * - `account-api-tokens.write` — the mint. A session mints `ci-system` and every worker-consumer token
- *   the project declares, so the hand-made bootstrap token stops being a setup step.
+ * - `account-api-tokens.write` — the mint. A session mints `ci-system` and `runtime` as the project
+ *   composes them, so the hand-made bootstrap token stops being a setup step.
  * - `account-settings.read` — `GET /accounts`, so the account is discovered rather than stored. On its own
  *   it lists the account; `d1.write` alone listed nothing (both measured 2026-10-15), so discovery must not
  *   lean on whichever other scope a project happens to request.

package/src/queue/queueProvisioner.ts

@@ -0,0 +1,79 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { cloudflareRequest, decodeResponse, isNotFoundError } from "../client/errors";
+import { CloudflareManager } from "../client/manager";
+
+/** A queue's identity, decoded from the Queues API's `queue_id` and `queue_name`. */
+export const QueueInfo = z
+  .object({
+    id: z.string().describe("The CF-assigned queue id, which the REST API addresses a queue by."),
+    name: z.string().describe("The queue name a producer binding names it by."),
+  })
+  .describe("A Cloudflare Queue's identity, as the Queues API returns it.");
+export type QueueInfo = z.output<typeof QueueInfo>;
+
+/** The Queues API's own spelling of a queue's identity, mapped onto {@link QueueInfo}. */
+const QueueRecord = z
+  .object({
+    queue_id: z.string().describe("The CF-assigned queue id."),
+    queue_name: z.string().describe("The queue name."),
+  })
+  .transform(({ queue_id, queue_name }) => ({ id: queue_id, name: queue_name }))
+  .describe("A queue as the Queues API returns it.");
+
+/**
+ * Account-level Queues control plane: **find, create and delete queues** (#662).
+ *
+ * `pithy provision` creates the queue behind every `queue` binding a composition declares, and `pithy feature
+ * destroy` deletes a feature's. A `queues.producers` entry names a queue, and `wrangler deploy` refuses one that
+ * does not exist, so the entry is only honest because this stands the queue up. Addressed by account — unlike
+ * {@link CloudflareQueueManager}, which targets one queue to send into.
+ */
+export class CloudflareQueueProvisioner extends CloudflareManager {
+  getServiceType(): string {
+    return "Cloudflare Queues (control plane)";
+  }
+
+  /** Prove access by listing queues — a read, never a create or a delete. Never throws. */
+  async validateServiceAccess(): Promise<boolean> {
+    try {
+      await this.getClient().queues.list({ account_id: this.accountId });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Find a queue by exact name in the account, or `null` — for idempotent provisioning. */
+  async findQueueByName(name: string): Promise<QueueInfo | null> {
+    return cloudflareRequest(`find queue ${name}`, async () => {
+      for await (const queue of this.getClient().queues.list({ account_id: this.accountId })) {
+        const parsed = QueueRecord.safeParse(queue);
+        if (parsed.success && parsed.data.name === name) return parsed.data;
+      }
+      return null;
+    });
+  }
+
+  /** Create a queue by name; returns its id and name. */
+  async createQueue(name: string): Promise<QueueInfo> {
+    const response = await cloudflareRequest(`create queue ${name}`, () =>
+      this.getClient().queues.create({ account_id: this.accountId, queue_name: name }),
+    );
+    return decodeResponse(QueueRecord, response, "queue create");
+  }
+
+  /** Delete a queue by id. Idempotent — a missing queue is not an error, so teardown can re-run safely. */
+  async deleteQueue(queueId: string): Promise<void> {
+    await cloudflareRequest(`delete queue ${queueId}`, async () => {
+      try {
+        await this.getClient().queues.delete(queueId, { account_id: this.accountId });
+      } catch (error) {
+        if (isNotFoundError(error)) return;
+        throw error;
+      }
+    });
+  }
+}

package/src/r2/r2Manager.ts

@@ -33,11 +33,29 @@ const LIST_PARTS_PAGE_SIZE = 1000;
  * the bucket it targets. R2 signs presigned URLs with the S3 keys, not the CF API token — both
  * come from config (no environment coupling).
  */
-export interface R2ManagerConfig extends CloudflareManagerConfig, R2Credentials {
+export interface R2ManagerConfig extends Omit<CloudflareManagerConfig, "apiToken">, R2Credentials {
   /** The R2 bucket all object operations target. */
   bucketName: string;
+  /**
+   * A Cloudflare API token, for the one call here that is not S3: {@link CloudflareR2Manager.validateServiceAccess}.
+   *
+   * **Absent in a Worker (#728).** Every object operation is S3, signed with the key pair, so a Worker's
+   * object store holds no API token: the application's one is `runtime`, and R2 needs none of it. Without
+   * one, `validateServiceAccess` answers `false` and nothing calls the Cloudflare API. An empty string is
+   * still refused, because that is an unresolved value rather than a decision.
+   */
+  apiToken?: string;
 }
 
+/**
+ * What the base client is built with when the config carries no API token. Never sent: {@link noApiToken}
+ * is the provider, and the base reads the token through it at every call and refuses an empty one.
+ */
+const S3_ONLY = "r2-s3-only";
+
+/** The token provider of an S3-only manager: no token, so any Cloudflare API call is refused before it is sent. */
+const noApiToken = (): string => "";
+
 /** How long a presigned URL stays valid. Shared by every presign method so the option reads the same. */
 export interface PresignOptions {
   /** Lifetime in seconds. Defaults to one hour — long enough for a large upload, short enough to leak little. */
@@ -168,8 +186,15 @@ export class CloudflareR2Manager extends CloudflareManager {
 
   private s3Client: S3Client | null = null;
 
+  private readonly s3Only: boolean;
+
   constructor(config: R2ManagerConfig) {
-    super(config);
+    super(
+      config.apiToken === undefined
+        ? { ...config, apiToken: S3_ONLY, tokenProvider: noApiToken }
+        : { ...config, apiToken: config.apiToken },
+    );
+    this.s3Only = config.apiToken === undefined;
     if (!config.bucketName) {
       throw new CloudflareNotConfiguredError({ detail: "Missing bucketName for R2 access." });
     }
@@ -538,6 +563,8 @@ export class CloudflareR2Manager extends CloudflareManager {
    * not merely that an S3 client could be built. Never throws.
    */
   async validateServiceAccess(): Promise<boolean> {
+    // An S3-only manager holds no API token to read the bucket record with.
+    if (this.s3Only) return false;
     try {
       await this.getClient().r2.buckets.get(this.bucketName, { account_id: this.accountId });
       return true;

package/src/tokens/accountTokensManager.ts

@@ -185,6 +185,18 @@ export const AccountTokenSummary = z
       .describe(
         "The token's access policies, when the list response carries them. **A live token's own scope is the record of how it was minted** — it is how a `ci-system` token minted before zone-scoped routes (#651) can be told from one minted after, without reading the token record (which needs a grant these least-privilege tokens deliberately lack). Absent and empty are different facts: a response that says nothing means the scope could not be read, never that the token has none.",
       ),
+    // **Not `nullAsAbsent`, and that is the field.** Everywhere else a `null` means the response did not say;
+    // here it is Cloudflare's answer — nothing has ever authenticated with this token. Absent stays "did
+    // not say", and a shape this does not model degrades to absent rather than dropping the token, for the
+    // reason `policies` gives.
+    last_used_on: z
+      .string()
+      .nullable()
+      .optional()
+      .catch(undefined)
+      .describe(
+        "When something last authenticated with the token, as Cloudflare measures it against the live account. Read because `pithy token forget` acts on it (#762): `null` means never, so a local copy may be its only one. Absent means the response did not say, which is not a claim either way.",
+      ),
   })
   .describe("An existing account-owned API token's metadata (never its secret value).");
 export type AccountTokenSummary = z.output<typeof AccountTokenSummary>;

package/src/tokens/permissions.ts

@@ -51,6 +51,28 @@ export const PERMISSION_GROUPS = {
   // domain — a proxied DNS record and a certificate — on any zone the account holds (measured, #709;
   // docs/TOKENS.md). So a token carrying the base can reach every zone's hostnames whatever this scopes.
   "routes:write": ["Workers Routes Write"],
+  // **Reading the account's analytics, and nothing else (#728).** The GraphQL Analytics API's account-level
+  // datasets — Stream minutes viewed, Images delivered — answer to this group. Cloudflare also has
+  // "Analytics Read", which is the **zone** group and reaches none of them.
+  //
+  // A second credential class for the kit: every other key here acts on resources the project owns,
+  // and this one reads the Cloudflare account. Its grain is the whole account, never one environment, so
+  // a capability reading it narrows the answer itself — media joins it to this environment's own assets.
+  "analytics:read": ["Account Analytics Read"],
+  // **Media's Cloudflare products, so the catalog can mint what an operator used to make by hand (#728).**
+  // A direct upload, a signing change and a delete on Cloudflare Images and on Stream. Both groups are
+  // account-scoped and edit only the account's Images and Stream libraries; they are carried by the one
+  // `runtime` token a deployed application holds, never by `ci-system`.
+  "images:write": ["Images Write"],
+  "stream:write": ["Stream Write"],
+  // **Creating and deleting the queue behind a `queue` binding (#662).** `pithy provision` creates one per
+  // binding and `pithy feature destroy` deletes a feature's, so `ci-system` carries it wherever a composition
+  // binds a queue. A Worker sends through its producer binding and needs no API token for it.
+  "queues:write": ["Queues Write"],
+  // **Listing and deleting the repos in a feature's Artifacts namespace, then the namespace (#673).** `pithy feature
+  // destroy` reaps them, because a repo costs storage and nothing else deletes one, so `ci-system` carries it wherever
+  // a composition binds `artifacts`. The account catalog names the group Write; the API schema's label says Edit. A Worker creates, reads and mints through its binding and needs no API token for any of it.
+  "artifacts:write": ["Artifacts Write"],
 } as const;
 
 /** A known permission key — one of {@link PERMISSION_GROUPS}'s keys. */
@@ -89,6 +111,11 @@ export const OAUTH_SCOPES = {
   "ai:read": ["ai.read"],
   "zone:read": ["zone.read"],
   "routes:write": ["workers-routes.write"],
+  "analytics:read": ["account-analytics.read"],
+  "images:write": ["images.write"],
+  "stream:write": ["stream.write"],
+  "queues:write": ["queues.write"],
+  "artifacts:write": ["artifacts.write"],
 } as const satisfies Record<PermissionKey, readonly string[]>;
 
 /**