@pithy-sh/cloudflare 0.4.2 → 0.6.0

package/README.md

@@ -16,7 +16,7 @@ _Everything on the adopter side is on the site. `pithy.sh/docs` is canonical —
 
 ## Live integration tests
 
-Mocks prove our call *shapes*. They cannot prove the request, the response decoding, and the error handling are functionally correct against real Cloudflare — that only surfaces live. So every manager that makes real CF calls also has a `*.integration.test.ts` that creates a throwaway resource, exercises the manager against it, and tears it down. These are excluded from the default suite and run via `bun run test:integration` (the `vitest.integration.config.ts` project), gated on credentials so they skip cleanly without them.
+Mocks prove our call *shapes*. They cannot prove the request, the response decoding, and the error handling are functionally correct against real Cloudflare — that only surfaces live. So every manager that makes real CF calls also has a `*.integration.test.ts` that creates a throwaway resource, exercises the manager against it, and tears it down. These are excluded from the default suite and run via turbo's `test:integration` (the `vitest.integration.config.ts` project), gated on credentials so they skip cleanly without them. Turbo builds `@pithy-sh/core` first, because the suites import it through its `exports` map into `dist/`; the package's own `bun run test:integration` skips that build, so it fails on a fresh checkout until something has built core.
 
 Credentials come from `packages/cloudflare/.dev.vars`, with `process.env` overlaid per key for anything the file does not set (`loadCloudflareEnv`). **Nothing creates that file.** It used to be a symlink to the root's, wired by a `vars:local` task; #154 removed both, and `pithy dev` and `pithy seed` generate `apps/<worker>/.dev.vars` in an adopter's project — `apps/` is the registry, so nothing regenerates a file in a kit package. Write it, or export the variables:
 
@@ -25,10 +25,10 @@ cat > .dev.vars <<'EOF'          # a real file, in this package, git-ignored
 CLOUDFLARE_ACCOUNT_ID=…
 CLOUDFLARE_API_TOKEN=…
 EOF
-bun run test:integration         # against the account in those creds
+bunx turbo run test:integration --filter=@pithy-sh/cloudflare   # builds core first, then runs against those creds
 ```
 
-Exporting them instead works identically and is how CI runs — the workflow sets `CLOUDFLARE_*` and `SECRETS_STORE_ID` from the `E2E Integration Testing` environment with no `.dev.vars` present. Set a key in both places and the file wins.
+Exporting them instead works identically and is how CI runs — the workflow sets `CLOUDFLARE_*` and `SECRETS_STORE_ID` from the `E2E Integration Testing` environment with no `.dev.vars` present, and runs the suites through turbo, which builds first and hands a task only the variables `test:integration` lists in `passThroughEnv` (`turbo.jsonc`). Set a key in both places and the file wins.
 
 Point them at a **dedicated test account** — they create and delete real resources.
 

package/dist/ai/aiManager.d.ts

@@ -64,6 +64,17 @@ export interface AnalyzeImageOptions {
     /** Upper bound on generated tokens. */
     maxTokens?: number;
 }
+/**
+ * The REST path that runs `model`: `/accounts/<id>/ai/run/@cf/baai/bge-m3`, the model's slashes literal.
+ *
+ * **Not the SDK's `ai.run` (#709).** cloudflare 7.0.0 builds that path with its `path` tag, which
+ * percent-encodes every path parameter, the `/`s inside a model name included. Cloudflare routes on the
+ * literal slashes, so `/ai/run/@cf%2Fbaai%2Fbge-m3` answers 7000 "No route for that URI" for every model.
+ * The path is built here instead, and a name that could change its shape is refused by {@link AI_MODEL_NAME}.
+ *
+ * @throws ValidationError (`validation/invalid_input`) when `model` is not a Workers AI model name.
+ */
+export declare function aiRunPath(accountId: string, model: string): string;
 /**
  * Out-of-Worker Workers AI access over the REST API: run any model, generate text, generate
  * embeddings, analyze an image, and list models from a CLI/CI/provisioning context. Inside a
@@ -74,7 +85,10 @@ export interface AnalyzeImageOptions {
 export declare class CloudflareAIManager extends CloudflareManager {
     /**
      * Run a Cloudflare AI model by name with an arbitrary JSON input. The single seam every typed
-     * helper builds on. The account id is injected for you; the rest of `input` is the model's body.
+     * helper builds on. The account is addressed for you; `input` is the model's body.
+     *
+     * Through the SDK's raw `post` to {@link aiRunPath}, not `ai.run`, whose path encoding Cloudflare cannot
+     * route. A malformed model name throws `validation/invalid_input` before any request is sent.
      */
     runModel(model: string, input: Record<string, unknown>): Promise<AIRunResponse>;
     /**

package/dist/ai/aiManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aiManager.d.ts","sourceRoot":"","sources":["../../src/ai/aiManager.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAe,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAE/E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAiBtD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;iBAKgE,CAAC;AAC9F,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAuChE,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;GAckE,CAAC;AAC9F,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D;;GAEG;AACH,eAAO,MAAM,WAAW;;iBAI8D,CAAC;AACvF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,kCAAkC;AAClC,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,+DAA+D;AAC/D,MAAM,WAAW,WAAW;IAC1B,+BAA+B;IAC/B,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACtC,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,kCAAkC;AAClC,MAAM,WAAW,mBAAmB;IAClC,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,iBAAiB;IACxD;;;OAGG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAIpF;IAED;;;OAGG;IACG,YAAY,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC,CAclG;IAED;;;OAGG;IACG,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAU5F;IAED;;;OAGG;IACG,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,WAAW,CAAC,CAezF;IAED,kGAAkG;IAC5F,UAAU,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAK/C;IAED,cAAc,IAAI,MAAM,CAEvB;IAED,oDAAoD;IAC9C,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;CACF"}
+{"version":3,"file":"aiManager.d.ts","sourceRoot":"","sources":["../../src/ai/aiManager.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAE/E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAiBtD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;iBAKgE,CAAC;AAC9F,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAuChE,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;GAckE,CAAC;AAC9F,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D;;GAEG;AACH,eAAO,MAAM,WAAW;;iBAI8D,CAAC;AACvF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,kCAAkC;AAClC,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,+DAA+D;AAC/D,MAAM,WAAW,WAAW;IAC1B,+BAA+B;IAC/B,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACtC,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,kCAAkC;AAClC,MAAM,WAAW,mBAAmB;IAClC,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAgBD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CASlE;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,iBAAiB;IACxD;;;;;;OAMG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAMpF;IAED;;;OAGG;IACG,YAAY,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC,CAclG;IAED;;;OAGG;IACG,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAU5F;IAED;;;OAGG;IACG,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,WAAW,CAAC,CAezF;IAED,kGAAkG;IAC5F,UAAU,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAK/C;IAED,cAAc,IAAI,MAAM,CAEvB;IAED,oDAAoD;IAC9C,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;CACF"}

package/dist/ai/aiManager.js

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MIT
 import { CloudflareInvalidResponseError, cloudflareRequest } from "../client/errors.js";
 import { CloudflareManager } from "../client/manager.js";
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
 import { fromUint8Array } from "js-base64";
 import { z } from "zod";
 //#region src/ai/aiManager.ts
@@ -62,6 +63,35 @@ const TextGeneration = z.union([FlatTextGeneration, ChatCompletionText]).describ
 const ImageToText = z.object({ description: z.string().describe("The model's textual description of the image.") }).describe("A Cloudflare image-to-text result: a description of the supplied image.");
 const DEFAULT_IMAGE_PROMPT = "Describe this image in a concise sentence suitable for alt text.";
 /**
+* What a Workers AI model name may look like: `@<namespace>/` and then one to three segments, each made of
+* letters, digits, `.`, `_` and `-` and starting with a letter or digit — `@cf/baai/bge-m3`,
+* `@cf/llava-hf/llava-1.5-7b-hf`, `@hf/thebloke/deepseek-coder-6.7b-instruct-awq`.
+*
+* **The name goes into the request path unencoded, so this pattern is the whole of the defense.** A segment
+* cannot be `.` or `..` (it must start with a letter or digit), and nothing that ends a path, opens a query
+* or a fragment, or escapes a character (`?`, `#`, `%`, `\`, whitespace) is in the alphabet. A name outside
+* it is refused before a request exists.
+*/
+const AI_MODEL_NAME = /^@[a-z0-9][a-z0-9-]*(?:\/[A-Za-z0-9][A-Za-z0-9._-]*){1,3}$/;
+/**
+* The REST path that runs `model`: `/accounts/<id>/ai/run/@cf/baai/bge-m3`, the model's slashes literal.
+*
+* **Not the SDK's `ai.run` (#709).** cloudflare 7.0.0 builds that path with its `path` tag, which
+* percent-encodes every path parameter, the `/`s inside a model name included. Cloudflare routes on the
+* literal slashes, so `/ai/run/@cf%2Fbaai%2Fbge-m3` answers 7000 "No route for that URI" for every model.
+* The path is built here instead, and a name that could change its shape is refused by {@link AI_MODEL_NAME}.
+*
+* @throws ValidationError (`validation/invalid_input`) when `model` is not a Workers AI model name.
+*/
+function aiRunPath(accountId, model) {
+	if (!AI_MODEL_NAME.test(model)) throw new ValidationError({
+		message: `"${model.slice(0, 120)}" is not a Workers AI model name.`,
+		action: "Pass a model name such as @cf/baai/bge-m3. The Workers AI model catalog lists them.",
+		detail: `model name ${JSON.stringify(model)} does not match ${AI_MODEL_NAME}`
+	});
+	return `/accounts/${encodeURIComponent(accountId)}/ai/run/${model}`;
+}
+/**
 * Out-of-Worker Workers AI access over the REST API: run any model, generate text, generate
 * embeddings, analyze an image, and list models from a CLI/CI/provisioning context. Inside a
 * Worker you use the `Ai` binding directly — this manager is the REST counterpart, addressed by
@@ -71,13 +101,16 @@ const DEFAULT_IMAGE_PROMPT = "Describe this image in a concise sentence suitable
 var CloudflareAIManager = class extends CloudflareManager {
 	/**
 	* Run a Cloudflare AI model by name with an arbitrary JSON input. The single seam every typed
-	* helper builds on. The account id is injected for you; the rest of `input` is the model's body.
+	* helper builds on. The account is addressed for you; `input` is the model's body.
+	*
+	* Through the SDK's raw `post` to {@link aiRunPath}, not `ai.run`, whose path encoding Cloudflare cannot
+	* route. A malformed model name throws `validation/invalid_input` before any request is sent.
 	*/
 	async runModel(model, input) {
-		return cloudflareRequest(`AI run model '${model}'`, () => this.getClient().ai.run(model, {
-			account_id: this.accountId,
-			...input
-		}));
+		const path = aiRunPath(this.accountId, model);
+		return cloudflareRequest(`AI run model '${model}'`, async () => {
+			return (await this.getClient().post(path, { body: input })).result;
+		});
 	}
 	/**
 	* Generate text from a chat prompt. Returns the validated `{ response }` payload. A response that
@@ -147,4 +180,4 @@ var CloudflareAIManager = class extends CloudflareManager {
 	}
 };
 //#endregion
-export { CloudflareAIManager, ImageToText, TextGeneration, VectorEmbeddings };
+export { CloudflareAIManager, ImageToText, TextGeneration, VectorEmbeddings, aiRunPath };

package/dist/analytics/analyticsManager.d.ts

@@ -0,0 +1,78 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+import { CloudflareManager } from "../client/manager";
+import { type AnalyticsDataset } from "./datasets";
+/**
+ * **Cloudflare's GraphQL Analytics API, for the account-level datasets the kit reads (#728).**
+ *
+ * One endpoint, `POST /graphql`, reached through the SDK's raw `post` like every other call the typed SDK
+ * does not cover — never a hand-rolled `fetch` (CLAUDE.md §Cloudflare access). It answers HTTP 200 with
+ * `{ data, errors }` even when it refuses, so `errors` is read on every answer and a non-empty one is a
+ * refusal in Cloudflare's own words.
+ *
+ * The token it runs on is the application's one `runtime` token, carrying "Account Analytics Read", whose grain is
+ * the whole account. This manager narrows nothing on its own: every query takes the keys it is about, and
+ * the caller decides which keys those are.
+ */
+/**
+ * The most groups one Turnstile read asks for. A group is one sitekey and one event type, and Cloudflare
+ * documents ten event types, so a project's one or two widgets need a few dozen. An answer that fills the
+ * limit is refused rather than read short.
+ */
+export declare const TURNSTILE_EVENT_GROUP_LIMIT = 1000;
+/**
+ * How many keys one query filters on. The answer is one group per key, so this is also the `limit`, and
+ * it sits far under the 10,000 `maxPageSize` the datasets advertise — a large library is several bounded
+ * queries, never one unbounded filter.
+ */
+export declare const ANALYTICS_KEY_CHUNK = 500;
+/** One dataset's limits, as `viewer.accounts.settings` reports them. Every duration is in seconds. */
+export declare const DatasetLimits: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    maxDuration: z.ZodNumber;
+    notOlderThan: z.ZodNumber;
+    maxPageSize: z.ZodNumber;
+}, z.core.$strip>;
+export type DatasetLimits = z.infer<typeof DatasetLimits>;
+/** A window and the keys to read it for. */
+export interface WindowQuery {
+    /** The window's start, inclusive. */
+    since: Date;
+    /** The window's end, exclusive. */
+    until: Date;
+}
+/** Out-of-band reads of the account's delivery analytics. */
+export declare class CloudflareAnalyticsManager extends CloudflareManager {
+    getServiceType(): string;
+    /** Whether the token can read the account's analytics settings. Never throws. */
+    validateServiceAccess(): Promise<boolean>;
+    /**
+     * Run one query and hand back its `data`, refusing in Cloudflare's own words when `errors` is non-empty.
+     * The status is a 200 either way, so the envelope is the only place a refusal can be read.
+     */
+    private query;
+    /** The one account in an answer, refused when the token's viewer cannot see it. */
+    private onlyAccount;
+    /**
+     * Each dataset's limits for this account — whether it is served at all, its retention, and the widest
+     * window one query may ask for. Read, never assumed: the numbers differ per dataset and per plan.
+     */
+    datasetLimits(datasets: readonly AnalyticsDataset[]): Promise<Partial<Record<AnalyticsDataset, DatasetLimits>>>;
+    /** Minutes of video delivered per Stream uid inside the window, for the uids given. Absent means none. */
+    streamMinutesViewed(window: WindowQuery & {
+        uids: readonly string[];
+    }): Promise<Map<string, number>>;
+    /** Delivery requests per hosted image id inside the window, for the ids given. Absent means none. */
+    imageRequests(window: WindowQuery & {
+        imageIds: readonly string[];
+    }): Promise<Map<string, number>>;
+    /**
+     * Turnstile events per sitekey and event type inside the window, for the sitekeys given (#731). The sitekey
+     * filter is what scopes the account-wide dataset to the widgets the caller is about. Absent means none.
+     */
+    turnstileEvents(window: WindowQuery & {
+        siteKeys: readonly string[];
+    }): Promise<Map<string, Map<string, number>>>;
+}
+//# sourceMappingURL=analyticsManager.d.ts.map

package/dist/analytics/analyticsManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyticsManager.d.ts","sourceRoot":"","sources":["../../src/analytics/analyticsManager.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,KAAK,gBAAgB,EAAoD,MAAM,YAAY,CAAC;AAErG;;;;;;;;;;;GAWG;AAEH;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,OAAO,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC,sGAAsG;AACtG,eAAO,MAAM,aAAa;;;;;iBAOiF,CAAC;AAC5G,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAgE1D,4CAA4C;AAC5C,MAAM,WAAW,WAAW;IAC1B,qCAAqC;IACrC,KAAK,EAAE,IAAI,CAAC;IACZ,mCAAmC;IACnC,KAAK,EAAE,IAAI,CAAC;CACb;AASD,6DAA6D;AAC7D,qBAAa,0BAA2B,SAAQ,iBAAiB;IAC/D,cAAc,IAAI,MAAM,CAEvB;IAED,iFAAiF;IAC3E,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;IAED;;;OAGG;YACW,KAAK;IAsBnB,mFAAmF;IACnF,OAAO,CAAC,WAAW;IAWnB;;;OAGG;IACG,aAAa,CACjB,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GACpC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,gBAAgB,EAAE,aAAa,CAAC,CAAC,CAAC,CA2B3D;IAED,0GAA0G;IACpG,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG;QAAE,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAuBzG;IAED,qGAAqG;IAC/F,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG;QAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CA2BvG;IAED;;;OAGG;IACG,eAAe,CACnB,MAAM,EAAE,WAAW,GAAG;QAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,GACpD,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAmC3C;CACF"}

package/dist/analytics/analyticsManager.js

@@ -0,0 +1,206 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { CloudflareInvalidResponseError, cloudflareRefusal, cloudflareRequest, decodeResponse } from "../client/errors.js";
+import { CloudflareManager } from "../client/manager.js";
+import { IMAGE_REQUESTS, STREAM_MINUTES, TURNSTILE_EVENTS } from "./datasets.js";
+import { z } from "zod";
+//#region src/analytics/analyticsManager.ts
+/**
+* **Cloudflare's GraphQL Analytics API, for the account-level datasets the kit reads (#728).**
+*
+* One endpoint, `POST /graphql`, reached through the SDK's raw `post` like every other call the typed SDK
+* does not cover — never a hand-rolled `fetch` (CLAUDE.md §Cloudflare access). It answers HTTP 200 with
+* `{ data, errors }` even when it refuses, so `errors` is read on every answer and a non-empty one is a
+* refusal in Cloudflare's own words.
+*
+* The token it runs on is the application's one `runtime` token, carrying "Account Analytics Read", whose grain is
+* the whole account. This manager narrows nothing on its own: every query takes the keys it is about, and
+* the caller decides which keys those are.
+*/
+/**
+* The most groups one Turnstile read asks for. A group is one sitekey and one event type, and Cloudflare
+* documents ten event types, so a project's one or two widgets need a few dozen. An answer that fills the
+* limit is refused rather than read short.
+*/
+const TURNSTILE_EVENT_GROUP_LIMIT = 1e3;
+/**
+* How many keys one query filters on. The answer is one group per key, so this is also the `limit`, and
+* it sits far under the 10,000 `maxPageSize` the datasets advertise — a large library is several bounded
+* queries, never one unbounded filter.
+*/
+const ANALYTICS_KEY_CHUNK = 500;
+/** One dataset's limits, as `viewer.accounts.settings` reports them. Every duration is in seconds. */
+const DatasetLimits = z.object({
+	enabled: z.boolean().describe("Whether Cloudflare serves this dataset to this account at all."),
+	maxDuration: z.number().describe("The widest window one query may ask for, in seconds."),
+	notOlderThan: z.number().describe("How far back the dataset reaches, in seconds — its retention."),
+	maxPageSize: z.number().describe("The largest `limit` one query may pass.")
+}).describe("One analytics dataset's limits for this account, as Cloudflare's settings node reports them.");
+/** The GraphQL error code for a spent rate budget — the one refusal a caller may retry. */
+const RATE_BUDGET_CODE = "budget";
+/** One entry of a GraphQL `errors` array. */
+const GraphQLError = z.object({
+	message: z.string().optional().describe("Cloudflare's own sentence for the failure."),
+	extensions: z.object({ code: z.string().optional().describe("Cloudflare's machine code for the failure.") }).partial().optional().describe("Cloudflare's structured extras.")
+}).describe("One error the GraphQL endpoint answered.");
+/** The envelope every GraphQL answer arrives in. `data` is decoded per query. */
+const GraphQLAnswer = z.object({
+	data: z.unknown().optional().describe("The query's result, when it ran."),
+	errors: z.array(GraphQLError).nullish().describe("Why the query did not run, when it did not.")
+}).describe("The GraphQL endpoint's answer envelope.");
+/** The one account a query is about, from `viewer.accounts(filter: { accountTag })`. */
+function accountOf(account) {
+	return z.object({ viewer: z.object({ accounts: z.array(account).describe("The accounts the filter matched.") }).describe("The authenticated viewer.") }).describe("A GraphQL answer about one account.");
+}
+const StreamMinutesGroup = z.object({
+	sum: z.object({ minutesViewed: z.number().describe("Minutes of video delivered.") }).describe("The summed metrics."),
+	dimensions: z.object({ uid: z.string().describe("The Stream video uid.") }).describe("The group's key.")
+}).describe("Minutes delivered for one video.");
+const ImageRequestsGroup = z.object({
+	count: z.number().describe("Delivery requests for the image."),
+	dimensions: z.object({ imageId: z.string().describe("The Cloudflare Images id.") }).describe("The group's key.")
+}).describe("Delivery requests for one hosted image.");
+const TurnstileEventGroup = z.object({
+	count: z.number().describe("Events of this type for this sitekey."),
+	dimensions: z.object({
+		siteKey: z.string().describe("The widget's public sitekey."),
+		eventType: z.string().describe("The Turnstile event type, as Cloudflare names it.")
+	}).describe("The group's key.")
+}).describe("Events of one type for one Turnstile widget.");
+/** Split keys into bounded chunks. */
+function chunks(items, size) {
+	const out = [];
+	for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
+	return out;
+}
+/** Out-of-band reads of the account's delivery analytics. */
+var CloudflareAnalyticsManager = class extends CloudflareManager {
+	getServiceType() {
+		return "Analytics";
+	}
+	/** Whether the token can read the account's analytics settings. Never throws. */
+	async validateServiceAccess() {
+		try {
+			await this.datasetLimits([STREAM_MINUTES]);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Run one query and hand back its `data`, refusing in Cloudflare's own words when `errors` is non-empty.
+	* The status is a 200 either way, so the envelope is the only place a refusal can be read.
+	*/
+	async query(operation, query, variables) {
+		const raw = await cloudflareRequest(operation, () => this.getClient().post("/graphql", { body: {
+			query,
+			variables
+		} }), { permission: "Account Analytics Read" });
+		const answer = decodeResponse(GraphQLAnswer, raw, operation);
+		const errors = answer.errors ?? [];
+		if (errors.length > 0) throw cloudflareRefusal({
+			problem: `Cloudflare request failed: ${operation}.`,
+			apiErrors: errors.map((error) => ({ ...error.message === void 0 ? {} : { message: error.message } })),
+			permission: "Account Analytics Read",
+			...errors.some((error) => error.extensions?.code === RATE_BUDGET_CODE) ? { status: 429 } : {},
+			detail: JSON.stringify(errors)
+		});
+		return answer.data;
+	}
+	/** The one account in an answer, refused when the token's viewer cannot see it. */
+	onlyAccount(schema, data, operation) {
+		const [account] = decodeResponse(accountOf(schema), data, operation).viewer.accounts;
+		if (account === void 0) throw new CloudflareInvalidResponseError({
+			message: `Cloudflare answered no account for ${operation}. The token cannot see this account.`,
+			detail: `viewer.accounts was empty for account ${this.accountId}`
+		});
+		return account;
+	}
+	/**
+	* Each dataset's limits for this account — whether it is served at all, its retention, and the widest
+	* window one query may ask for. Read, never assumed: the numbers differ per dataset and per plan.
+	*/
+	async datasetLimits(datasets) {
+		const fields = datasets.map((dataset) => `${dataset} { enabled maxDuration notOlderThan maxPageSize }`).join(" ");
+		const operation = "read analytics dataset limits";
+		const data = await this.query(operation, `query ($account: string!) { viewer { accounts(filter: { accountTag: $account }) { settings { ${fields} } } } }`, { account: this.accountId });
+		const shape = z.object({ settings: z.object(Object.fromEntries(datasets.map((dataset) => [dataset, DatasetLimits.nullish()]))).describe("The datasets asked about. A dataset this account is not served is null or absent.") }).describe("The account's analytics settings.");
+		const settings = this.onlyAccount(shape, data, operation).settings;
+		const limits = {};
+		for (const dataset of datasets) {
+			const entry = settings[dataset];
+			if (entry !== null && entry !== void 0) limits[dataset] = entry;
+		}
+		return limits;
+	}
+	/** Minutes of video delivered per Stream uid inside the window, for the uids given. Absent means none. */
+	async streamMinutesViewed(window) {
+		const totals = /* @__PURE__ */ new Map();
+		const operation = "read Stream minutes viewed";
+		for (const uids of chunks(window.uids, 500)) {
+			const data = await this.query(operation, `query ($account: string!, $filter: AccountStreamMinutesViewedAdaptiveGroupsFilter_InputObject, $limit: uint64!) { viewer { accounts(filter: { accountTag: $account }) { ${STREAM_MINUTES}(filter: $filter, limit: $limit) { sum { minutesViewed } dimensions { uid } } } } }`, {
+				account: this.accountId,
+				filter: {
+					datetime_geq: window.since.toISOString(),
+					datetime_lt: window.until.toISOString(),
+					uid_in: uids
+				},
+				limit: uids.length
+			});
+			const groups = this.onlyAccount(z.object({ [STREAM_MINUTES]: z.array(StreamMinutesGroup).describe("Minutes per video.") }), data, operation)[STREAM_MINUTES];
+			for (const group of groups) totals.set(group.dimensions.uid, (totals.get(group.dimensions.uid) ?? 0) + group.sum.minutesViewed);
+		}
+		return totals;
+	}
+	/** Delivery requests per hosted image id inside the window, for the ids given. Absent means none. */
+	async imageRequests(window) {
+		const totals = /* @__PURE__ */ new Map();
+		const operation = "read Images delivery requests";
+		for (const imageIds of chunks(window.imageIds, 500)) {
+			const data = await this.query(operation, `query ($account: string!, $filter: AccountImagesHostedRequestsAdaptiveGroupsFilter_InputObject, $limit: uint64!) { viewer { accounts(filter: { accountTag: $account }) { ${IMAGE_REQUESTS}(filter: $filter, limit: $limit) { count dimensions { imageId } } } } }`, {
+				account: this.accountId,
+				filter: {
+					datetime_geq: window.since.toISOString(),
+					datetime_lt: window.until.toISOString(),
+					imageId_in: imageIds
+				},
+				limit: imageIds.length
+			});
+			const groups = this.onlyAccount(z.object({ [IMAGE_REQUESTS]: z.array(ImageRequestsGroup).describe("Requests per image.") }), data, operation)[IMAGE_REQUESTS];
+			for (const group of groups) totals.set(group.dimensions.imageId, (totals.get(group.dimensions.imageId) ?? 0) + group.count);
+		}
+		return totals;
+	}
+	/**
+	* Turnstile events per sitekey and event type inside the window, for the sitekeys given (#731). The sitekey
+	* filter is what scopes the account-wide dataset to the widgets the caller is about. Absent means none.
+	*/
+	async turnstileEvents(window) {
+		const totals = /* @__PURE__ */ new Map();
+		if (window.siteKeys.length === 0) return totals;
+		const operation = "read Turnstile events";
+		const data = await this.query(operation, `query ($account: string!, $filter: AccountTurnstileAdaptiveGroupsFilter_InputObject!, $limit: uint64!) { viewer { accounts(filter: { accountTag: $account }) { ${TURNSTILE_EVENTS}(filter: $filter, limit: $limit) { count dimensions { siteKey eventType } } } } }`, {
+			account: this.accountId,
+			filter: {
+				datetime_geq: window.since.toISOString(),
+				datetime_lt: window.until.toISOString(),
+				siteKey_in: [...window.siteKeys]
+			},
+			limit: TURNSTILE_EVENT_GROUP_LIMIT
+		});
+		const groups = this.onlyAccount(z.object({ [TURNSTILE_EVENTS]: z.array(TurnstileEventGroup).describe("Events per sitekey and type.") }), data, operation)[TURNSTILE_EVENTS];
+		if (groups.length >= 1e3) throw new CloudflareInvalidResponseError({
+			message: `Cloudflare answered ${groups.length} Turnstile event groups, the most one read asks for. The counts past them are missing.`,
+			detail: `${TURNSTILE_EVENTS} filled limit ${TURNSTILE_EVENT_GROUP_LIMIT} for ${window.siteKeys.length} sitekeys`
+		});
+		for (const group of groups) {
+			const { siteKey, eventType } = group.dimensions;
+			const events = totals.get(siteKey) ?? /* @__PURE__ */ new Map();
+			events.set(eventType, (events.get(eventType) ?? 0) + group.count);
+			totals.set(siteKey, events);
+		}
+		return totals;
+	}
+};
+//#endregion
+export { ANALYTICS_KEY_CHUNK, CloudflareAnalyticsManager, DatasetLimits, TURNSTILE_EVENT_GROUP_LIMIT };

package/dist/analytics/datasets.d.ts

@@ -0,0 +1,26 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+/**
+ * **The analytics datasets the kit reads, by their GraphQL names**, in a module of their own. A Worker
+ * names a dataset to read its limits and to word a refusal, and importing the manager to learn a string
+ * would put the Cloudflare SDK on every module that does (#731). Nothing here imports anything.
+ */
+/** Minutes of Stream video delivered, groupable by video `uid`. Account-level, US-only under a metadata boundary. */
+export declare const STREAM_MINUTES = "streamMinutesViewedAdaptiveGroups";
+/**
+ * Hosted Images delivery requests, groupable by `imageId` — the id Cloudflare Images assigns at upload.
+ *
+ * Not `imagesRequestsAdaptiveGroups`: that dataset groups by time and nothing else, so it can only ever
+ * answer an account total, which cannot be scoped to an environment. This one carries the image id,
+ * found by schema introspection on 2026-10-17.
+ */
+export declare const IMAGE_REQUESTS = "imagesHostedRequestsAdaptiveGroups";
+/**
+ * Turnstile challenge events, groupable by `siteKey` and `eventType` (#731). Account-level, and served under
+ * a US and an EU metadata boundary alike, so a boundary does not rule it out. Found by schema introspection
+ * on 2026-10-18; Cloudflare marks it Beta.
+ */
+export declare const TURNSTILE_EVENTS = "turnstileAdaptiveGroups";
+/** The datasets this manager queries. */
+export type AnalyticsDataset = typeof STREAM_MINUTES | typeof IMAGE_REQUESTS | typeof TURNSTILE_EVENTS;
+//# sourceMappingURL=datasets.d.ts.map

package/dist/analytics/datasets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"datasets.d.ts","sourceRoot":"","sources":["../../src/analytics/datasets.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AAEH,qHAAqH;AACrH,eAAO,MAAM,cAAc,sCAAsC,CAAC;AAElE;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,uCAAuC,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,4BAA4B,CAAC;AAE1D,yCAAyC;AACzC,MAAM,MAAM,gBAAgB,GAAG,OAAO,cAAc,GAAG,OAAO,cAAc,GAAG,OAAO,gBAAgB,CAAC"}

package/dist/analytics/datasets.js

@@ -0,0 +1,26 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/analytics/datasets.ts
+/**
+* **The analytics datasets the kit reads, by their GraphQL names**, in a module of their own. A Worker
+* names a dataset to read its limits and to word a refusal, and importing the manager to learn a string
+* would put the Cloudflare SDK on every module that does (#731). Nothing here imports anything.
+*/
+/** Minutes of Stream video delivered, groupable by video `uid`. Account-level, US-only under a metadata boundary. */
+const STREAM_MINUTES = "streamMinutesViewedAdaptiveGroups";
+/**
+* Hosted Images delivery requests, groupable by `imageId` — the id Cloudflare Images assigns at upload.
+*
+* Not `imagesRequestsAdaptiveGroups`: that dataset groups by time and nothing else, so it can only ever
+* answer an account total, which cannot be scoped to an environment. This one carries the image id,
+* found by schema introspection on 2026-10-17.
+*/
+const IMAGE_REQUESTS = "imagesHostedRequestsAdaptiveGroups";
+/**
+* Turnstile challenge events, groupable by `siteKey` and `eventType` (#731). Account-level, and served under
+* a US and an EU metadata boundary alike, so a boundary does not rule it out. Found by schema introspection
+* on 2026-10-18; Cloudflare marks it Beta.
+*/
+const TURNSTILE_EVENTS = "turnstileAdaptiveGroups";
+//#endregion
+export { IMAGE_REQUESTS, STREAM_MINUTES, TURNSTILE_EVENTS };

package/dist/analytics/window.d.ts

@@ -0,0 +1,50 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
+import type { DatasetLimits } from "./analyticsManager";
+/**
+ * **The window an analytics read covers, and the limits it is held to (#728, #731).**
+ *
+ * Written once for every capability that reads Cloudflare's GraphQL Analytics. The rules are the same for
+ * each: the last {@link DEFAULT_WINDOW_DAYS} days by default, a window that ends before it starts refused,
+ * and a window past the dataset's retention or wider than one read may ask for refused, naming the cap in
+ * days. The refusal is each caller's own code, so it is handed to a factory rather than thrown here.
+ */
+/** The default window, in days, ending now. Fits every dataset the kit reads. */
+export declare const DEFAULT_WINDOW_DAYS = 30;
+/** A resolved window: `since` inclusive, `until` exclusive. */
+export interface AnalyticsWindow {
+    since: Date;
+    until: Date;
+}
+/** Why a window was refused, in the fields a caller's error class takes. */
+export interface WindowRefusal {
+    /** The sentence the caller reads. */
+    message: string;
+    /** The cap and the dataset, for a client that translates. */
+    params?: MessageParams;
+    /** The numbers behind it, for the log. */
+    detail: string;
+}
+/** Builds the caller's own error for a refused window. */
+export type RefuseWindow = (refusal: WindowRefusal) => Error;
+/** One dataset as a read names it: the GraphQL node, and how an operator would say it. */
+export interface MeasuredDataset {
+    dataset: string;
+    label: string;
+}
+/**
+ * The window a request asks for: the last {@link DEFAULT_WINDOW_DAYS} days by default, a `since` alone
+ * running to now, and an `until` alone reaching back the default span. A window that ends before it
+ * starts is refused.
+ */
+export declare function resolveAnalyticsWindow(input: {
+    since?: Date;
+    until?: Date;
+}, now: Date, refuse: RefuseWindow): AnalyticsWindow;
+/**
+ * Hold a window to one dataset's limits, read from the account's own settings rather than assumed. The
+ * refusal names the cap in days, so a caller can pick a window that works.
+ */
+export declare function checkAnalyticsWindow(window: AnalyticsWindow, limits: DatasetLimits, measured: MeasuredDataset, now: Date, refuse: RefuseWindow): void;
+//# sourceMappingURL=window.d.ts.map

package/dist/analytics/window.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"window.d.ts","sourceRoot":"","sources":["../../src/analytics/window.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;;;;;GAOG;AAEH,iFAAiF;AACjF,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAItC,+DAA+D;AAC/D,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,IAAI,CAAC;IACZ,KAAK,EAAE,IAAI,CAAC;CACb;AAED,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,0DAA0D;AAC1D,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,aAAa,KAAK,KAAK,CAAC;AAE7D,0FAA0F;AAC1F,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAOD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE;IAAE,KAAK,CAAC,EAAE,IAAI,CAAC;IAAC,KAAK,CAAC,EAAE,IAAI,CAAA;CAAE,EACrC,GAAG,EAAE,IAAI,EACT,MAAM,EAAE,YAAY,GACnB,eAAe,CAUjB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,eAAe,EACzB,GAAG,EAAE,IAAI,EACT,MAAM,EAAE,YAAY,GACnB,IAAI,CAmBN"}

package/dist/analytics/window.js

@@ -0,0 +1,67 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/analytics/window.ts
+/**
+* **The window an analytics read covers, and the limits it is held to (#728, #731).**
+*
+* Written once for every capability that reads Cloudflare's GraphQL Analytics. The rules are the same for
+* each: the last {@link DEFAULT_WINDOW_DAYS} days by default, a window that ends before it starts refused,
+* and a window past the dataset's retention or wider than one read may ask for refused, naming the cap in
+* days. The refusal is each caller's own code, so it is handed to a factory rather than thrown here.
+*/
+/** The default window, in days, ending now. Fits every dataset the kit reads. */
+const DEFAULT_WINDOW_DAYS = 30;
+const DAY_MS = 864e5;
+/** Whole days in a span of seconds, for a cap stated to a person. */
+function days(seconds) {
+	return Math.floor(seconds / 86400);
+}
+/**
+* The window a request asks for: the last {@link DEFAULT_WINDOW_DAYS} days by default, a `since` alone
+* running to now, and an `until` alone reaching back the default span. A window that ends before it
+* starts is refused.
+*/
+function resolveAnalyticsWindow(input, now, refuse) {
+	const until = input.until ?? now;
+	const since = input.since ?? /* @__PURE__ */ new Date(until.getTime() - 30 * DAY_MS);
+	if (since.getTime() >= until.getTime()) throw refuse({
+		message: "That window ends before it starts. Put since before until.",
+		detail: `since ${since.toISOString()} is not before until ${until.toISOString()}`
+	});
+	return {
+		since,
+		until
+	};
+}
+/**
+* Hold a window to one dataset's limits, read from the account's own settings rather than assumed. The
+* refusal names the cap in days, so a caller can pick a window that works.
+*/
+function checkAnalyticsWindow(window, limits, measured, now, refuse) {
+	const reach = (now.getTime() - window.since.getTime()) / 1e3;
+	if (reach > limits.notOlderThan) {
+		const maxDays = days(limits.notOlderThan);
+		throw refuse({
+			message: `That window starts ${days(reach)} days ago. Cloudflare keeps ${measured.label} for ${maxDays} days.`,
+			params: {
+				maxDays,
+				dataset: measured.dataset
+			},
+			detail: `${measured.dataset} notOlderThan ${limits.notOlderThan}s; window reaches ${Math.round(reach)}s`
+		});
+	}
+	const span = (window.until.getTime() - window.since.getTime()) / 1e3;
+	if (span > limits.maxDuration) {
+		const maxDays = days(limits.maxDuration);
+		throw refuse({
+			message: `That window spans ${days(span)} days. Cloudflare answers at most ${maxDays} days of ${measured.label} at once.`,
+			params: {
+				maxDays,
+				dataset: measured.dataset
+			},
+			detail: `${measured.dataset} maxDuration ${limits.maxDuration}s; window spans ${Math.round(span)}s`
+		});
+	}
+}
+//#endregion
+export { DEFAULT_WINDOW_DAYS, checkAnalyticsWindow, resolveAnalyticsWindow };