@pithy-sh/cloudflare 0.4.2 → 0.6.0

package/dist/oauth/scopes.d.ts

@@ -0,0 +1,62 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+/**
+ * The scopes every session asks for, whatever the project composes (#759).
+ *
+ * - `user-details.read` — `GET /user`, which is what turns an audit row's actor from a token's name into
+ *   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 `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.
+ * - `zone.read` — `pithy init` and `pithy worker add` offer the account's real zones, and `init` asks
+ *   before there is a project whose capabilities could say so. Read-only, as {@link OAUTH_SCOPES} says of it.
+ *
+ * Everything else comes from the project's own token permissions, through {@link sessionScopes}.
+ */
+export declare const SESSION_BASE_SCOPES: readonly ["user-details.read", "offline_access", "account-api-tokens.write", "account-settings.read", "zone.read"];
+/**
+ * The scopes Cloudflare's consent screen lists under **"Sensitive scopes"**, switched off, by the name it
+ * shows them under.
+ *
+ * **Approving with one switched off does not grant the rest.** The dashboard answers *"We could not
+ * complete the authorization. Please check your network connection and try again."* and no callback
+ * ever arrives (measured 2026-10-15). So `connect` names these before it opens the browser, and its
+ * timeout names them as the likeliest cause.
+ *
+ * **The list is ours to keep, because Cloudflare's is not published.** `GET /oauth/scopes` carries an
+ * id, a name, a category and nothing that marks a scope sensitive; only the consent screen says. Add to
+ * it when a consent screen shows another.
+ */
+export declare const SENSITIVE_SCOPES: Readonly<Record<string, string>>;
+/**
+ * The scopes a session needs to act for a project, and to mint every token it declares: the base, then
+ * the scope of each permission key, de-duped in first-seen order.
+ *
+ * **Derived, never listed.** Cloudflare's delegation rule binds the session as it binds a token — a mint
+ * whose groups the session does not hold is refused — so the request is exactly the union of what the
+ * project's tokens carry. A capability the project does not compose contributes nothing to it, and so
+ * nothing to the consent screen the adopter reads.
+ */
+export declare function sessionScopes(permissionKeys: readonly string[]): string[];
+/**
+ * The requested scopes a grant does not carry, in request order.
+ *
+ * `granted` is the token endpoint's `scope`: one space-separated string. Today Cloudflare fails rather
+ * than grant a subset, so this should always be empty; it is checked because that is Cloudflare's
+ * behavior to change, and a session missing `account-api-tokens.write` would fail at the first mint.
+ */
+export declare function missingScopes(requested: readonly string[], granted: string): string[];
+/** One sensitive scope a request carries, by its id and the name the consent screen shows. */
+export interface SensitiveScope {
+    /** The catalog id: `account-api-tokens.write`. */
+    id: string;
+    /** What the consent screen calls it: "Account API Tokens Write". */
+    name: string;
+}
+/** The sensitive scopes in a request, in request order. See {@link SENSITIVE_SCOPES}. */
+export declare function sensitiveScopesIn(scopes: readonly string[]): SensitiveScope[];
+//# sourceMappingURL=scopes.d.ts.map

package/dist/oauth/scopes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopes.d.ts","sourceRoot":"","sources":["../../src/oauth/scopes.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,mBAAmB,YAC9B,mBAAmB,EACnB,gBAAgB,EAChB,0BAA0B,EAC1B,uBAAuB,EACvB,WAAW,CACH,CAAC;AAEX;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE7D,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAMzE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAGrF;AAED,8FAA8F;AAC9F,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;CACd;AAED,yFAAyF;AACzF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,cAAc,EAAE,CAK7E"}

package/dist/oauth/scopes.js

@@ -0,0 +1,79 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { oauthScopesFor } from "../tokens/permissions.js";
+//#region src/oauth/scopes.ts
+/**
+* The scopes every session asks for, whatever the project composes (#759).
+*
+* - `user-details.read` — `GET /user`, which is what turns an audit row's actor from a token's name into
+*   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 `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.
+* - `zone.read` — `pithy init` and `pithy worker add` offer the account's real zones, and `init` asks
+*   before there is a project whose capabilities could say so. Read-only, as {@link OAUTH_SCOPES} says of it.
+*
+* Everything else comes from the project's own token permissions, through {@link sessionScopes}.
+*/
+const SESSION_BASE_SCOPES = [
+	"user-details.read",
+	"offline_access",
+	"account-api-tokens.write",
+	"account-settings.read",
+	"zone.read"
+];
+/**
+* The scopes Cloudflare's consent screen lists under **"Sensitive scopes"**, switched off, by the name it
+* shows them under.
+*
+* **Approving with one switched off does not grant the rest.** The dashboard answers *"We could not
+* complete the authorization. Please check your network connection and try again."* and no callback
+* ever arrives (measured 2026-10-15). So `connect` names these before it opens the browser, and its
+* timeout names them as the likeliest cause.
+*
+* **The list is ours to keep, because Cloudflare's is not published.** `GET /oauth/scopes` carries an
+* id, a name, a category and nothing that marks a scope sensitive; only the consent screen says. Add to
+* it when a consent screen shows another.
+*/
+const SENSITIVE_SCOPES = { "account-api-tokens.write": "Account API Tokens Write" };
+/**
+* The scopes a session needs to act for a project, and to mint every token it declares: the base, then
+* the scope of each permission key, de-duped in first-seen order.
+*
+* **Derived, never listed.** Cloudflare's delegation rule binds the session as it binds a token — a mint
+* whose groups the session does not hold is refused — so the request is exactly the union of what the
+* project's tokens carry. A capability the project does not compose contributes nothing to it, and so
+* nothing to the consent screen the adopter reads.
+*/
+function sessionScopes(permissionKeys) {
+	const scopes = [...SESSION_BASE_SCOPES];
+	for (const scope of oauthScopesFor(permissionKeys)) if (!scopes.includes(scope)) scopes.push(scope);
+	return scopes;
+}
+/**
+* The requested scopes a grant does not carry, in request order.
+*
+* `granted` is the token endpoint's `scope`: one space-separated string. Today Cloudflare fails rather
+* than grant a subset, so this should always be empty; it is checked because that is Cloudflare's
+* behavior to change, and a session missing `account-api-tokens.write` would fail at the first mint.
+*/
+function missingScopes(requested, granted) {
+	const held = new Set(granted.split(/\s+/).filter(Boolean));
+	return requested.filter((scope) => !held.has(scope));
+}
+/** The sensitive scopes in a request, in request order. See {@link SENSITIVE_SCOPES}. */
+function sensitiveScopesIn(scopes) {
+	return scopes.flatMap((id) => {
+		const name = SENSITIVE_SCOPES[id];
+		return name === void 0 ? [] : [{
+			id,
+			name
+		}];
+	});
+}
+//#endregion
+export { SENSITIVE_SCOPES, SESSION_BASE_SCOPES, missingScopes, sensitiveScopesIn, sessionScopes };

package/dist/queue/queueProvisioner.d.ts

@@ -0,0 +1,30 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+import { CloudflareManager } from "../client/manager";
+/** A queue's identity, decoded from the Queues API's `queue_id` and `queue_name`. */
+export declare const QueueInfo: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strip>;
+export type QueueInfo = z.output<typeof QueueInfo>;
+/**
+ * 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 declare class CloudflareQueueProvisioner extends CloudflareManager {
+    getServiceType(): string;
+    /** Prove access by listing queues — a read, never a create or a delete. Never throws. */
+    validateServiceAccess(): Promise<boolean>;
+    /** Find a queue by exact name in the account, or `null` — for idempotent provisioning. */
+    findQueueByName(name: string): Promise<QueueInfo | null>;
+    /** Create a queue by name; returns its id and name. */
+    createQueue(name: string): Promise<QueueInfo>;
+    /** Delete a queue by id. Idempotent — a missing queue is not an error, so teardown can re-run safely. */
+    deleteQueue(queueId: string): Promise<void>;
+}
+//# sourceMappingURL=queueProvisioner.d.ts.map

package/dist/queue/queueProvisioner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queueProvisioner.d.ts","sourceRoot":"","sources":["../../src/queue/queueProvisioner.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,qFAAqF;AACrF,eAAO,MAAM,SAAS;;;iBAKqD,CAAC;AAC5E,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAWnD;;;;;;;GAOG;AACH,qBAAa,0BAA2B,SAAQ,iBAAiB;IAC/D,cAAc,IAAI,MAAM,CAEvB;IAED,yFAAyF;IACnF,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;IAED,0FAA0F;IACpF,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAQ7D;IAED,uDAAuD;IACjD,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAKlD;IAED,yGAAyG;IACnG,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAShD;CACF"}

package/dist/queue/queueProvisioner.js

@@ -0,0 +1,72 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { cloudflareRequest, decodeResponse, isNotFoundError } from "../client/errors.js";
+import { CloudflareManager } from "../client/manager.js";
+import { z } from "zod";
+//#region src/queue/queueProvisioner.ts
+/** A queue's identity, decoded from the Queues API's `queue_id` and `queue_name`. */
+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.");
+/** 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.
+*/
+var CloudflareQueueProvisioner = class extends CloudflareManager {
+	getServiceType() {
+		return "Cloudflare Queues (control plane)";
+	}
+	/** Prove access by listing queues — a read, never a create or a delete. Never throws. */
+	async validateServiceAccess() {
+		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) {
+		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) {
+		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) {
+		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;
+			}
+		});
+	}
+};
+//#endregion
+export { CloudflareQueueProvisioner, QueueInfo };

package/dist/r2/r2Manager.d.ts

@@ -8,9 +8,18 @@ import { R2Credentials } from "./r2Credentials";
  * 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;
 }
 /** How long a presigned URL stays valid. Shared by every presign method so the option reads the same. */
 export interface PresignOptions {
@@ -97,6 +106,7 @@ export declare class CloudflareR2Manager extends CloudflareManager {
     private readonly accessKeyId;
     private readonly secretAccessKey;
     private s3Client;
+    private readonly s3Only;
     constructor(config: R2ManagerConfig);
     /** The S3-compatible client for R2, lazily created and cached for the manager's lifetime. */
     private getS3Client;

package/dist/r2/r2Manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"r2Manager.d.ts","sourceRoot":"","sources":["../../src/r2/r2Manager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"r2Manager.d.ts","sourceRoot":"","sources":["../../src/r2/r2Manager.ts"],"names":[],"mappings":"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"}

package/dist/r2/r2Manager.js

@@ -11,6 +11,13 @@ import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
 const PRESIGN_EXPIRY_SECONDS = 3600;
 /** How many parts one `ListParts` page returns. S3's own cap; the drain loop below relies on it. */
 const LIST_PARTS_PAGE_SIZE = 1e3;
+/**
+* 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 = () => "";
 /** An object's metadata as R2 reports it, without fetching the body. */
 const R2ObjectHead = z.object({
 	size: z.number().int().nonnegative().describe("The object's size in bytes."),
@@ -70,8 +77,17 @@ var CloudflareR2Manager = class extends CloudflareManager {
 	accessKeyId;
 	secretAccessKey;
 	s3Client = null;
+	s3Only;
 	constructor(config) {
-		super(config);
+		super(config.apiToken === void 0 ? {
+			...config,
+			apiToken: S3_ONLY,
+			tokenProvider: noApiToken
+		} : {
+			...config,
+			apiToken: config.apiToken
+		});
+		this.s3Only = config.apiToken === void 0;
 		if (!config.bucketName) throw new CloudflareNotConfiguredError({ detail: "Missing bucketName for R2 access." });
 		const credentials = R2Credentials.safeParse(config);
 		if (!credentials.success) throw new CloudflareNotConfiguredError({ detail: `Invalid R2 credentials: ${credentials.error.message}` });
@@ -395,6 +411,7 @@ var CloudflareR2Manager = class extends CloudflareManager {
 	* not merely that an S3 client could be built. Never throws.
 	*/
 	async validateServiceAccess() {
+		if (this.s3Only) return false;
 		try {
 			await this.getClient().r2.buckets.get(this.bucketName, { account_id: this.accountId });
 			return true;

package/dist/secrets/secretsStoreManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secretsStoreManager.d.ts","sourceRoot":"","sources":["../../src/secrets/secretsStoreManager.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,KAAK,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAKpF;;;;GAIG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;iBAeqE,CAAC;AAChG,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D,mGAAmG;AACnG,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAC;AA4BxE,gGAAgG;AAChG,MAAM,WAAW,yBAA0B,SAAQ,uBAAuB;IACxE,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,qBAAa,6BAA8B,SAAQ,iBAAiB;IAClE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,YAAY,MAAM,EAAE,yBAAyB,EAM5C;IAED,cAAc,IAAI,MAAM,CAEvB;IAED,iEAAiE;IAC3D,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;IAED;;;;;;;;;;;;;;;;;OAiBG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB5E;IAED;;;;;;;;;;;;;;;OAeG;IACG,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAmBtG;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BzF;IAED,4FAA4F;IACtF,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAc9C;IAED;;;;;;;;;;;;;OAaG;IACG,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAU1D;IAED;;;OAGG;IACG,WAAW,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CAU5C;IAED;;;;;;;;;;;;OAYG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAEzD;IAED,0EAA0E;IACpE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3C;IAED,kEAAkE;IAClE,mBAAmB,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAE5D;IAED,6GAA6G;YAC/F,YAAY;IAiB1B;;;;OAIG;YACW,UAAU;CAGzB"}
+{"version":3,"file":"secretsStoreManager.d.ts","sourceRoot":"","sources":["../../src/secrets/secretsStoreManager.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,KAAK,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAKpF;;;;GAIG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;iBAeqE,CAAC;AAChG,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D,mGAAmG;AACnG,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAC;AA4BxE,gGAAgG;AAChG,MAAM,WAAW,yBAA0B,SAAQ,uBAAuB;IACxE,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,qBAAa,6BAA8B,SAAQ,iBAAiB;IAClE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,YAAY,MAAM,EAAE,yBAAyB,EAM5C;IAED,cAAc,IAAI,MAAM,CAEvB;IAED,iEAAiE;IAC3D,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;IAED;;;;;;;;;;;;;;;;;OAiBG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB5E;IAED;;;;;;;;;;;;;;;OAeG;IACG,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAmBtG;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BzF;IAED,4FAA4F;IACtF,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAc9C;IAED;;;;;;;;;;;;;OAaG;IACG,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAU1D;IAED;;;OAGG;IACG,WAAW,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CAU5C;IAED;;;;;;;;;;;;OAYG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAEzD;IAED,0EAA0E;IACpE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3C;IAED,kEAAkE;IAClE,mBAAmB,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAE5D;IAED,6GAA6G;YAC/F,YAAY;IAiB1B;;;;OAIG;YACW,UAAU;CAGzB"}

package/dist/secrets/secretsStoreManager.js

@@ -2,8 +2,9 @@
 // SPDX-License-Identifier: MIT
 import { CloudflareNotConfiguredError, cloudflareRequest, decodeResponse } from "../client/errors.js";
 import { CloudflareManager } from "../client/manager.js";
-import { z } from "zod";
 import { ConflictError, NotFoundError } from "@pithy-sh/core/src/error/pithyError";
+import { z } from "zod";
+import { remedy } from "@pithy-sh/core/src/cli/command";
 import { JsonDate } from "@pithy-sh/core/src/data/codecs";
 //#region src/secrets/secretsStoreManager.ts
 /** Scopes attached to every secret we create. CF requires at least one; "workers" is the bind target. */
@@ -172,7 +173,7 @@ var CloudflareSecretsStoreManager = class extends CloudflareManager {
 		const target = named[0];
 		if (!target) throw new NotFoundError({
 			message: `Secret '${name}' is not in the store, so there is nothing to update.`,
-			action: "Run `pithy secrets provision` to establish the entry, then run this again.",
+			action: `${remedy("secrets provision").say((command) => `Run \`${command}\`.`)} It establishes the entry; then run this again.`,
 			detail: `update secret ${name}: no live entry of that name, and this verb never creates one`
 		});
 		if (named.length > 1) throw new ConflictError({

package/dist/test-utils/settle.d.ts

@@ -0,0 +1,79 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+/**
+ * **Waiting on an eventually consistent control plane, for the live suites.** One budget and one rule, shared
+ * by `@pithy-sh/cloudflare`'s Vectorize suite and `@pithy-sh/vector`'s, because the cloudflare suite kept a
+ * 60s budget and a single confirming read of its own and failed on exactly that (#709).
+ *
+ * **The budget is 120s, and 300s for a metadata index.** A Vectorize index became visible 25-50s after the
+ * call that made it, measured live, and an upsert became queryable in about 30s. A metadata index is slower:
+ * about 97s on one run of #709 and over 120s on the next, so its waits take {@link METADATA_INDEX_SETTLE_MS}.
+ *
+ * **A metadata-index wait compares names and types, never a count.** {@link metadataIndexesSettled} is the
+ * predicate; a list of the right length can still be the wrong list.
+ *
+ * **One confirming read proves nothing.** The metadata-index list is eventually consistent *and not
+ * monotonic*: a 3-minute probe watched it report `[]` for 26s, then both properties, then one of the two 18s
+ * later with nothing else running, then both again. So {@link waitForStable} waits for {@link STABLE_READS}
+ * agreeing reads in a row and hands back that snapshot, and a caller asserts against the snapshot rather
+ * than a fresh read, which can disagree with the one before it.
+ *
+ * **A test that waits several times shares one deadline across them.** Each wait's own budget bounds that
+ * wait and nothing else, so a test making eight of them in a row could outrun its vitest timeout with every
+ * step inside budget. Vitest then abandoned the body mid-poll: the failure said only "Test timed out", and the
+ * teardown that deletes the index never ran (#709). Pass the same {@link SettleOptions.deadline} to every
+ * wait and the step in progress when it passes fails by name, inside the body, where the teardown still runs.
+ */
+/** Ceiling for any one wait. Measured at 25-50s for a control-plane change, and about 30s for an upsert. */
+export declare const SETTLE_TIMEOUT_MS = 120000;
+/**
+ * Ceiling for a metadata-index wait, and only for that. A metadata index is the slowest change Vectorize
+ * applies: on #709 one settled in about 97s and the next was still unsettled at 120s, so the shared budget
+ * undercut exactly this wait. `pithy vector provision` waits on the same measurement.
+ */
+export declare const METADATA_INDEX_SETTLE_MS = 300000;
+/**
+ * Consecutive agreeing reads that count as settled. Three, because one confirming read can be a stale replica,
+ * and two in a row six seconds apart is a far weaker coincidence.
+ */
+export declare const STABLE_READS = 3;
+/** How often a poll re-checks. Vectorize applies changes in tens of seconds, so a tighter loop only burns quota. */
+export declare const POLL_INTERVAL_MS = 2000;
+/** How long to wait and how often to look. Every field defaults to the shared budget above. */
+export interface SettleOptions {
+    /** Give up after this long. Defaults to {@link SETTLE_TIMEOUT_MS}. */
+    timeoutMs?: number;
+    /** Re-check this often. Defaults to {@link POLL_INTERVAL_MS}. */
+    intervalMs?: number;
+    /** Agreeing reads in a row that count as settled, for {@link waitForStable}. Defaults to {@link STABLE_READS}. */
+    stableReads?: number;
+    /**
+     * An absolute deadline (ms since the epoch) shared by every wait in a test. A wait gives up at whichever
+     * comes first, its own `timeoutMs` or this, and says which.
+     */
+    deadline?: number;
+}
+/**
+ * Poll until `ready`, or fail with a message naming what was being waited for. A bare timeout tells the next
+ * reader nothing; naming the step tells them whether Cloudflare was slow or something is actually broken.
+ */
+export declare function waitFor(what: string, ready: () => Promise<boolean>, options?: SettleOptions): Promise<void>;
+/**
+ * Poll until `settled` holds on {@link STABLE_READS} consecutive reads, and return the last value read. The
+ * caller asserts against the returned snapshot, never against a fresh read.
+ */
+export declare function waitForStable<T>(what: string, read: () => Promise<T>, settled: (value: T) => boolean, options?: SettleOptions): Promise<T>;
+/**
+ * The settle predicate for a metadata-index list: every declared index is live, under its own name and its own
+ * type. The rule `compareMetadataIndexes` applies with nothing missing and nothing mismatched, restated here
+ * because this package cannot import `@pithy-sh/vector`. A count is not enough: a list of the right length
+ * with the wrong names passed the predicate this replaced. An undeclared extra does not block it.
+ */
+export declare function metadataIndexesSettled(declared: readonly {
+    propertyName: string;
+    indexType: string;
+}[]): (live: readonly {
+    propertyName: string;
+    indexType: string;
+}[]) => boolean;
+//# sourceMappingURL=settle.d.ts.map

package/dist/test-utils/settle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settle.d.ts","sourceRoot":"","sources":["../../src/test-utils/settle.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,4GAA4G;AAC5G,eAAO,MAAM,iBAAiB,SAAU,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,SAAU,CAAC;AAEhD;;;GAGG;AACH,eAAO,MAAM,YAAY,IAAI,CAAC;AAE9B,oHAAoH;AACpH,eAAO,MAAM,gBAAgB,OAAQ,CAAC;AAEtC,+FAA+F;AAC/F,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kHAAkH;IAClH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAmBD;;;GAGG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYrH;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACtB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,EAC9B,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,CAAC,CAAC,CAiBZ;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,SAAS;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EAAE,GAC/D,CAAC,IAAI,EAAE,SAAS;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EAAE,KAAK,OAAO,CAK3E"}

package/dist/test-utils/settle.js

@@ -0,0 +1,105 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/test-utils/settle.ts
+/**
+* **Waiting on an eventually consistent control plane, for the live suites.** One budget and one rule, shared
+* by `@pithy-sh/cloudflare`'s Vectorize suite and `@pithy-sh/vector`'s, because the cloudflare suite kept a
+* 60s budget and a single confirming read of its own and failed on exactly that (#709).
+*
+* **The budget is 120s, and 300s for a metadata index.** A Vectorize index became visible 25-50s after the
+* call that made it, measured live, and an upsert became queryable in about 30s. A metadata index is slower:
+* about 97s on one run of #709 and over 120s on the next, so its waits take {@link METADATA_INDEX_SETTLE_MS}.
+*
+* **A metadata-index wait compares names and types, never a count.** {@link metadataIndexesSettled} is the
+* predicate; a list of the right length can still be the wrong list.
+*
+* **One confirming read proves nothing.** The metadata-index list is eventually consistent *and not
+* monotonic*: a 3-minute probe watched it report `[]` for 26s, then both properties, then one of the two 18s
+* later with nothing else running, then both again. So {@link waitForStable} waits for {@link STABLE_READS}
+* agreeing reads in a row and hands back that snapshot, and a caller asserts against the snapshot rather
+* than a fresh read, which can disagree with the one before it.
+*
+* **A test that waits several times shares one deadline across them.** Each wait's own budget bounds that
+* wait and nothing else, so a test making eight of them in a row could outrun its vitest timeout with every
+* step inside budget. Vitest then abandoned the body mid-poll: the failure said only "Test timed out", and the
+* teardown that deletes the index never ran (#709). Pass the same {@link SettleOptions.deadline} to every
+* wait and the step in progress when it passes fails by name, inside the body, where the teardown still runs.
+*/
+/** Ceiling for any one wait. Measured at 25-50s for a control-plane change, and about 30s for an upsert. */
+const SETTLE_TIMEOUT_MS = 12e4;
+/**
+* Ceiling for a metadata-index wait, and only for that. A metadata index is the slowest change Vectorize
+* applies: on #709 one settled in about 97s and the next was still unsettled at 120s, so the shared budget
+* undercut exactly this wait. `pithy vector provision` waits on the same measurement.
+*/
+const METADATA_INDEX_SETTLE_MS = 3e5;
+/**
+* Consecutive agreeing reads that count as settled. Three, because one confirming read can be a stale replica,
+* and two in a row six seconds apart is a far weaker coincidence.
+*/
+const STABLE_READS = 3;
+/** How often a poll re-checks. Vectorize applies changes in tens of seconds, so a tighter loop only burns quota. */
+const POLL_INTERVAL_MS = 2e3;
+/** When a wait gives up, and the clause its timeout message ends the step name with. */
+function limitOf(options, started) {
+	const own = started + (options.timeoutMs ?? 12e4);
+	if (options.deadline !== void 0 && options.deadline < own) return {
+		deadline: options.deadline,
+		why: " (the shared deadline for this test ran out)"
+	};
+	return {
+		deadline: own,
+		why: ""
+	};
+}
+function seconds(ms) {
+	return Math.round(ms / 1e3);
+}
+function pause(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+* Poll until `ready`, or fail with a message naming what was being waited for. A bare timeout tells the next
+* reader nothing; naming the step tells them whether Cloudflare was slow or something is actually broken.
+*/
+async function waitFor(what, ready, options = {}) {
+	const started = Date.now();
+	const { deadline, why } = limitOf(options, started);
+	for (;;) {
+		if (await ready()) return;
+		if (Date.now() >= deadline) throw new Error(`Timed out after ${seconds(Date.now() - started)}s waiting for ${what}${why}. Cloudflare applies this change asynchronously — this is either a slower-than-usual apply or a real failure.`);
+		await pause(options.intervalMs ?? 2e3);
+	}
+}
+/**
+* Poll until `settled` holds on {@link STABLE_READS} consecutive reads, and return the last value read. The
+* caller asserts against the returned snapshot, never against a fresh read.
+*/
+async function waitForStable(what, read, settled, options = {}) {
+	const started = Date.now();
+	const needed = options.stableReads ?? 3;
+	const { deadline, why } = limitOf(options, started);
+	let agreed = 0;
+	let last = await read();
+	for (;;) {
+		agreed = settled(last) ? agreed + 1 : 0;
+		if (agreed >= needed) return last;
+		if (Date.now() >= deadline) throw new Error(`Timed out after ${seconds(Date.now() - started)}s waiting for ${what} to settle across ${needed} reads${why}. Last read: ${JSON.stringify(last)}.`);
+		await pause(options.intervalMs ?? 2e3);
+		last = await read();
+	}
+}
+/**
+* The settle predicate for a metadata-index list: every declared index is live, under its own name and its own
+* type. The rule `compareMetadataIndexes` applies with nothing missing and nothing mismatched, restated here
+* because this package cannot import `@pithy-sh/vector`. A count is not enough: a list of the right length
+* with the wrong names passed the predicate this replaced. An undeclared extra does not block it.
+*/
+function metadataIndexesSettled(declared) {
+	return (live) => {
+		const types = new Map(live.map((entry) => [entry.propertyName, entry.indexType]));
+		return declared.every((entry) => types.get(entry.propertyName) === entry.indexType);
+	};
+}
+//#endregion
+export { METADATA_INDEX_SETTLE_MS, POLL_INTERVAL_MS, SETTLE_TIMEOUT_MS, STABLE_READS, metadataIndexesSettled, waitFor, waitForStable };

package/dist/tokens/accountTokensManager.d.ts

@@ -57,7 +57,7 @@ export declare const MintedAccountToken: z.ZodObject<{
         active: "active";
         disabled: "disabled";
         expired: "expired";
-    }>>>;
+    }>>, unknown>;
 }, z.core.$strip>;
 export type MintedAccountToken = z.output<typeof MintedAccountToken>;
 /**
@@ -72,10 +72,10 @@ export declare const AccountTokenPolicy: z.ZodObject<{
     effect: z.ZodPreprocess<z.ZodOptional<z.ZodEnum<{
         allow: "allow";
         deny: "deny";
-    }>>>;
+    }>>, unknown>;
     permission_groups: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
-    }, z.core.$strip>>>>;
+    }, z.core.$strip>>>, unknown>;
     resources: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, z.core.$strip>;
 export type AccountTokenPolicy = z.output<typeof AccountTokenPolicy>;
@@ -96,17 +96,18 @@ export declare const AccountTokenSummary: z.ZodObject<{
         active: "active";
         disabled: "disabled";
         expired: "expired";
-    }>>>;
+    }>>, unknown>;
     policies: z.ZodCatch<z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodObject<{
         effect: z.ZodPreprocess<z.ZodOptional<z.ZodEnum<{
             allow: "allow";
             deny: "deny";
-        }>>>;
+        }>>, unknown>;
         permission_groups: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodObject<{
             id: z.ZodString;
-        }, z.core.$strip>>>>;
+        }, z.core.$strip>>>, unknown>;
         resources: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-    }, z.core.$strip>>>>>;
+    }, z.core.$strip>>>, unknown>>;
+    last_used_on: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
 }, z.core.$strip>;
 export type AccountTokenSummary = z.output<typeof AccountTokenSummary>;
 /**

package/dist/tokens/accountTokensManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"accountTokensManager.d.ts","sourceRoot":"","sources":["../../src/tokens/accountTokensManager.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAYxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAkB1D;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,kHAAkH;IAClH,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,kGAAkG;IAClG,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,2EAA2E;IAC3E,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEzE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIhF;AAeD;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;;iBAK8E,CAAC;AAC7G,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;iBAY6D,CAAC;AAC7F,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAErE;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;iBAwBkF,CAAC;AAClH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAErE;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;iBAuBuD,CAAC;AACxF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE;;;;;;;;;GASG;AACH,qBAAa,8BAA+B,SAAQ,iBAAiB;IACnE,cAAc,IAAI,MAAM,CAEvB;IAED,qGAAqG;IAC/F,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;IAED;;;;;;;OAOG;IACG,WAAW,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAKhD;IAED;;;;;;;;;;;;OAYG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAe1D;IAED,qGAAqG;IAC/F,oBAAoB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAezD;IAED;;;;;;OAMG;IACG,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAE7E;IAED;;;;;;;OAOG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAgDzF;IAED;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAqB3B,2GAA2G;IACrG,UAAU,IAAI,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAajD;IAED,oGAAoG;IAC9F,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAYvE;IAED,qCAAqC;IAC/B,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMhD;IAED;;;;OAIG;IACG,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBtD;IAED;;;;;OAKG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAOrD;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAKzF;CACF"}
+{"version":3,"file":"accountTokensManager.d.ts","sourceRoot":"","sources":["../../src/tokens/accountTokensManager.ts"],"names":[],"mappings":"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"}

package/dist/tokens/accountTokensManager.js

@@ -110,7 +110,8 @@ const AccountTokenSummary = z.object({
 		"disabled",
 		"expired"
 	]).describe("The lifecycle state Cloudflare holds for the token.").optional()).describe("The token's lifecycle status. Reported, because a `disabled` or `expired` token cannot attach a route however its policies read. `nullish` for the reason {@link AccountTokenPolicy} gives."),
-	policies: nullAsAbsent(z.array(AccountTokenPolicy).optional()).catch(void 0).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.")
+	policies: nullAsAbsent(z.array(AccountTokenPolicy).optional()).catch(void 0).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."),
+	last_used_on: z.string().nullable().optional().catch(void 0).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).");
 /**
 * Out-of-Worker control plane for **account-owned** Cloudflare API tokens: mint scoped, least-privilege