@pithy-sh/cloudflare 0.5.0 → 0.7.0

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 };

package/dist/artifacts/artifactsManager.d.ts

@@ -0,0 +1,52 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { CloudflareManager } from "../client/manager";
+/**
+ * Account-level Artifacts control plane: **list and delete the repos in a namespace, then the namespace** (#673).
+ *
+ * Inside a Worker a repo is reached through the `artifacts` binding. This is the other side of that: `pithy feature
+ * destroy` reaps every repo in a feature's namespace, because repos cost storage and nothing else ever deletes one.
+ * There is no create here, because Cloudflare creates a namespace the first time a repo is created in it and the kit
+ * creates repos only from the Worker. There is a namespace delete, because nothing else removes one.
+ *
+ * The SDK this package targets exposes no Artifacts resource, so this uses the documented escape hatch — the raw
+ * token and `fetch` — against the paths [the REST API](https://developers.cloudflare.com/artifacts/api/rest-api/)
+ * publishes, and validates what comes back.
+ */
+export declare class CloudflareArtifactsManager extends CloudflareManager {
+    getServiceType(): string;
+    /** Prove access by listing namespaces — a read, never a write. Never throws. */
+    validateServiceAccess(): Promise<boolean>;
+    /**
+     * Every repo name in a namespace, across every page. **A namespace that does not exist has none**: Cloudflare
+     * makes one on its first repo, so a feature that never created a repo has no namespace, and teardown of it is a
+     * clean no-op rather than a failure.
+     */
+    listRepos(namespace: string): Promise<string[]>;
+    /**
+     * Delete one repo and every token on it. **Resolves whether one was there**, so teardown re-runs safely: a repo
+     * already gone is `false`, not an error. Cloudflare answers `202 Accepted`, so the storage may take a moment to
+     * be released after this returns.
+     */
+    deleteRepo(namespace: string, name: string): Promise<boolean>;
+    /**
+     * Delete a namespace, once it is empty. Cloudflare makes one on the first repo and nothing else ever deletes it,
+     * so a feature's would outlive the feature. `DELETE /accounts/{id}/artifacts/namespaces/{namespace}` is in
+     * Cloudflare's published API schema, not on the Artifacts REST page: it deletes an empty namespace, answers `204`,
+     * and answers `409` while a repo remains.
+     *
+     * **Three answers, none of them a failure of teardown.** `deleted` it was there; `absent` it is already gone or was
+     * never created, so a re-run is a clean no-op; `occupied` a repo is still in it — a repo delete is `202 Accepted`,
+     * so one just reaped can hold the namespace a moment longer, and the caller decides how long to wait.
+     */
+    deleteNamespace(namespace: string): Promise<"deleted" | "absent" | "occupied">;
+    private namespacePath;
+    private send;
+    /**
+     * One REST call, its envelope unwrapped. `null` for a 404 — the namespace or the repo is not there, which every
+     * caller here reads as nothing to do. {@link OCCUPIED} for a 409 when the caller asks for it — a namespace that
+     * still holds a repo. Any other failure is Cloudflare's refusal, in Cloudflare's words.
+     */
+    private call;
+}
+//# sourceMappingURL=artifactsManager.d.ts.map

package/dist/artifacts/artifactsManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifactsManager.d.ts","sourceRoot":"","sources":["../../src/artifacts/artifactsManager.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAoCtD;;;;;;;;;;;GAWG;AACH,qBAAa,0BAA2B,SAAQ,iBAAiB;IAC/D,cAAc,IAAI,MAAM,CAEvB;IAED,gFAAgF;IAC1E,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;IAED;;;;OAIG;IACG,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAmBpD;IAED;;;;OAIG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOlE;IAED;;;;;;;;;OASG;IACG,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC,CAOnF;IAED,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,IAAI;IAIZ;;;;OAIG;YACW,IAAI;CAwCnB"}