@pithy-sh/cloudflare 0.1.2 → 0.1.3

package/dist/ai/aiManager.d.ts

@@ -0,0 +1,99 @@
+import type { AIRunResponse } from "cloudflare/resources/ai/ai";
+import type { ModelListResponse } from "cloudflare/resources/ai/models/models";
+import { z } from "zod";
+import { CloudflareManager } from "../client/manager";
+/**
+ * The embeddings payload Cloudflare's text-embedding models return: a `shape` describing the
+ * `[count, dimensions]` of the result and a `data` array of one vector per input. Generic — this
+ * is the raw CF shape, carrying no application meaning, so callers can store or query it directly.
+ */
+export declare const VectorEmbeddings: z.ZodObject<{
+    shape: z.ZodArray<z.ZodNumber>;
+    data: z.ZodArray<z.ZodArray<z.ZodNumber>>;
+}, z.core.$strip>;
+export type VectorEmbeddings = z.infer<typeof VectorEmbeddings>;
+export declare const TextGeneration: z.ZodPipe<z.ZodUnion<readonly [z.ZodObject<{
+    response: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    choices: z.ZodArray<z.ZodObject<{
+        message: z.ZodObject<{
+            content: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>]>, z.ZodTransform<{
+    response: string;
+}, {
+    response: string;
+} | {
+    choices: {
+        message: {
+            content: string;
+        };
+    }[];
+}>>;
+export type TextGeneration = z.output<typeof TextGeneration>;
+/**
+ * The image-to-text payload Cloudflare's vision models return: a textual description of the image.
+ */
+export declare const ImageToText: z.ZodObject<{
+    description: z.ZodString;
+}, z.core.$strip>;
+export type ImageToText = z.infer<typeof ImageToText>;
+/** Options for `generateText`. */
+export interface GenerateTextOptions {
+    /** The model to run. Defaults to a generic instruct model. */
+    model?: string;
+    /** Upper bound on generated tokens. Omit for the model default. */
+    maxTokens?: number;
+}
+/** A single chat message passed to a text-generation model. */
+export interface ChatMessage {
+    /** The role of the speaker. */
+    role: "system" | "user" | "assistant";
+    /** The message content. */
+    content: string;
+}
+/** Options for `analyzeImage`. */
+export interface AnalyzeImageOptions {
+    /** The model to run. Defaults to a generic vision model. */
+    model?: string;
+    /** The instruction guiding the description. Defaults to a generic alt-text prompt. */
+    prompt?: string;
+    /** Upper bound on generated tokens. */
+    maxTokens?: number;
+}
+/**
+ * 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
+ * account id. Every model call carries no application logic; the caller chooses the model and
+ * interprets the result.
+ */
+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.
+     */
+    runModel(model: string, input: Record<string, unknown>): Promise<AIRunResponse>;
+    /**
+     * Generate text from a chat prompt. Returns the validated `{ response }` payload. A response that
+     * does not carry a string `response` field fails Zod and throws `cloudflare/invalid_response`.
+     */
+    generateText(messages: ChatMessage[], options?: GenerateTextOptions): Promise<TextGeneration>;
+    /**
+     * Generate embeddings for one or more texts. Returns the validated `{ shape, data }` payload. A
+     * response that does not match fails Zod and throws `cloudflare/invalid_response`.
+     */
+    generateEmbeddings(texts: string | string[], model?: string): Promise<VectorEmbeddings>;
+    /**
+     * Describe an image with a vision model. The image is raw bytes, base64-encoded for the model
+     * input. Returns the validated `{ description }` payload.
+     */
+    analyzeImage(image: Uint8Array, options?: AnalyzeImageOptions): Promise<ImageToText>;
+    /** List the AI models available to this account. Returns an empty array when none are present. */
+    listModels(): Promise<ModelListResponse[]>;
+    getServiceType(): string;
+    /** Prove access by listing models. Never throws. */
+    validateServiceAccess(): Promise<boolean>;
+}
+//# sourceMappingURL=aiManager.d.ts.map

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

@@ -0,0 +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"}

package/dist/ai/aiManager.js

@@ -0,0 +1,148 @@
+import { CloudflareInvalidResponseError, cloudflareRequest } from "../client/errors.js";
+import { CloudflareManager } from "../client/manager.js";
+import { fromUint8Array } from "js-base64";
+import { z } from "zod";
+//#region src/ai/aiManager.ts
+/**
+* The default text-generation model. A generic, well-supported instruct model — callers can
+* override per call via `runModel`. Not Leed-specific.
+*/
+const DEFAULT_TEXT_MODEL = "@cf/meta/llama-4-scout-17b-16e-instruct";
+/**
+* The default text-embedding model. `bge-m3` returns a `{ shape, data }` payload matching
+* `VectorEmbeddings`. Override per call via `runModel` for a different embedding model.
+*/
+const DEFAULT_EMBEDDING_MODEL = "@cf/baai/bge-m3";
+/** The default image-to-text (vision) model used by `analyzeImage`. */
+const DEFAULT_IMAGE_TO_TEXT_MODEL = "@cf/llava-hf/llava-1.5-7b-hf";
+/**
+* The embeddings payload Cloudflare's text-embedding models return: a `shape` describing the
+* `[count, dimensions]` of the result and a `data` array of one vector per input. Generic — this
+* is the raw CF shape, carrying no application meaning, so callers can store or query it directly.
+*/
+const VectorEmbeddings = z.object({
+	shape: z.array(z.number()).describe("The result shape as [count, dimensions]."),
+	data: z.array(z.array(z.number())).describe("One embedding vector per input text.")
+}).describe("A Cloudflare text-embedding result: vector shape plus one embedding per input.");
+/**
+* The text-generation payload Cloudflare's instruct models return over the REST API: the generated
+* text plus optional usage. Generic — no application-specific post-processing.
+*/
+/**
+* A text-generation result, normalized to `{ response }` whichever envelope the model returned.
+*
+* Workers AI answers in two shapes and which one you get depends on the model, not on the request.
+* Older models (`@cf/meta/llama-3.1-8b-instruct`) return a flat `{ response }`. Newer ones — including
+* the default `@cf/meta/llama-4-scout-17b-16e-instruct` — return the OpenAI chat-completion envelope
+* with the text at `choices[0].message.content` and **no** top-level `response` at all. Verified live
+* on 2026-07-29; llama-3.1 currently returns both, so the flat arm is matched first.
+*
+* Accepting both and normalizing keeps `generateText`'s contract stable across a model swap, which is
+* a per-call option — a caller overriding `model` should not have to know which era it belongs to.
+*/
+const FlatTextGeneration = z.object({ response: z.string().describe("The generated text, on the flat legacy envelope.") }).describe("The flat text-generation envelope older Workers AI models return.");
+const ChatCompletionText = z.object({ choices: z.array(z.object({ message: z.object({ content: z.string().describe("The generated text for this choice.") }).describe("The assistant message this choice carries.") }).describe("One completion choice.")).min(1).describe("The completions the model returned; the first is the answer.") }).describe("The OpenAI-compatible chat-completion envelope newer Workers AI models return.");
+const TextGeneration = z.union([FlatTextGeneration, ChatCompletionText]).describe("Either envelope, before normalization: the flat legacy one, or the OpenAI-compatible one.").transform((value, ctx) => {
+	if ("response" in value) return { response: value.response };
+	const first = value.choices[0];
+	if (!first) {
+		ctx.addIssue({
+			code: "custom",
+			message: "The chat-completion envelope carried no choices."
+		});
+		return z.NEVER;
+	}
+	return { response: first.message.content };
+}).describe("A Cloudflare text-generation result, normalized to the model's generated text.");
+/**
+* The image-to-text payload Cloudflare's vision models return: a textual description of the image.
+*/
+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.";
+/**
+* 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
+* account id. Every model call carries no application logic; the caller chooses the model and
+* interprets the result.
+*/
+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.
+	*/
+	async runModel(model, input) {
+		return cloudflareRequest(`AI run model '${model}'`, () => this.getClient().ai.run(model, {
+			account_id: this.accountId,
+			...input
+		}));
+	}
+	/**
+	* Generate text from a chat prompt. Returns the validated `{ response }` payload. A response that
+	* does not carry a string `response` field fails Zod and throws `cloudflare/invalid_response`.
+	*/
+	async generateText(messages, options) {
+		const model = options?.model ?? DEFAULT_TEXT_MODEL;
+		const raw = await this.runModel(model, {
+			messages,
+			...options?.maxTokens !== void 0 ? { max_tokens: options.maxTokens } : {}
+		});
+		const parsed = TextGeneration.safeParse(raw);
+		if (!parsed.success) throw new CloudflareInvalidResponseError({
+			message: "The AI text-generation response had an unexpected shape.",
+			detail: parsed.error.message
+		});
+		return parsed.data;
+	}
+	/**
+	* Generate embeddings for one or more texts. Returns the validated `{ shape, data }` payload. A
+	* response that does not match fails Zod and throws `cloudflare/invalid_response`.
+	*/
+	async generateEmbeddings(texts, model) {
+		const raw = await this.runModel(model ?? DEFAULT_EMBEDDING_MODEL, { text: texts });
+		const parsed = VectorEmbeddings.safeParse(raw);
+		if (!parsed.success) throw new CloudflareInvalidResponseError({
+			message: "The AI embeddings response had an unexpected shape.",
+			detail: parsed.error.message
+		});
+		return parsed.data;
+	}
+	/**
+	* Describe an image with a vision model. The image is raw bytes, base64-encoded for the model
+	* input. Returns the validated `{ description }` payload.
+	*/
+	async analyzeImage(image, options) {
+		const model = options?.model ?? DEFAULT_IMAGE_TO_TEXT_MODEL;
+		const raw = await this.runModel(model, {
+			image: fromUint8Array(image),
+			prompt: options?.prompt ?? DEFAULT_IMAGE_PROMPT,
+			...options?.maxTokens !== void 0 ? { max_tokens: options.maxTokens } : {}
+		});
+		const parsed = ImageToText.safeParse(raw);
+		if (!parsed.success) throw new CloudflareInvalidResponseError({
+			message: "The AI image-to-text response had an unexpected shape.",
+			detail: parsed.error.message
+		});
+		return parsed.data;
+	}
+	/** List the AI models available to this account. Returns an empty array when none are present. */
+	async listModels() {
+		return cloudflareRequest("AI list models", async () => {
+			const page = await this.getClient().ai.models.list({ account_id: this.accountId });
+			return Array.isArray(page.result) ? page.result : [];
+		});
+	}
+	getServiceType() {
+		return "Workers AI";
+	}
+	/** Prove access by listing models. Never throws. */
+	async validateServiceAccess() {
+		try {
+			return (await this.listModels()).length > 0;
+		} catch {
+			return false;
+		}
+	}
+};
+//#endregion
+export { CloudflareAIManager, ImageToText, TextGeneration, VectorEmbeddings };

package/dist/ai/vectorizeManager.d.ts

@@ -0,0 +1,67 @@
+import type { IndexDeleteByIDsResponse, IndexInfoResponse, IndexInsertResponse, IndexQueryResponse, IndexUpsertResponse } from "cloudflare/resources/vectorize/indexes/indexes";
+import { CloudflareManager, type CloudflareManagerConfig } from "../client/manager";
+/** Config for the Vectorize manager: the shared client config plus the index it targets. */
+export interface VectorizeManagerConfig extends CloudflareManagerConfig {
+    /** The Vectorize index name (the REST API addresses indexes by name, not binding). */
+    indexName: string;
+}
+/** A vector to insert or upsert: an id, its float values, and optional metadata/namespace. */
+export interface VectorizeVector {
+    /** The unique identifier for the vector. */
+    id: string;
+    /** The vector's float components. */
+    values: number[];
+    /** Arbitrary metadata stored alongside the vector. */
+    metadata?: Record<string, unknown>;
+    /** An optional namespace partitioning the index. */
+    namespace?: string;
+}
+/** Options narrowing a nearest-neighbor query. */
+export interface VectorizeQueryOptions {
+    /** The number of nearest neighbors to return. */
+    topK?: number;
+    /** Whether to return the matched vectors' values. */
+    returnValues?: boolean;
+    /** Whether to return no, indexed, or all metadata for matches. */
+    returnMetadata?: "none" | "indexed" | "all";
+    /** A metadata filter expression limiting results. */
+    filter?: unknown;
+}
+/**
+ * Out-of-Worker Vectorize access over the REST API: insert/upsert vectors, query nearest
+ * neighbors, fetch and delete by id, and describe the index from a CLI/CI/provisioning context.
+ * Inside a Worker you use the `Vectorize` binding directly — this manager is the REST counterpart,
+ * addressed by index name.
+ */
+export declare class CloudflareVectorizeManager extends CloudflareManager {
+    private readonly indexName;
+    constructor(config: VectorizeManagerConfig);
+    /** Serialize vectors as an NDJSON file, the body shape the REST insert/upsert endpoints expect. */
+    private vectorsToNdjsonFile;
+    /** Insert vectors. Returns the async-mutation id for the enqueued change. */
+    insert(vectors: VectorizeVector[]): Promise<IndexInsertResponse | null>;
+    /** Upsert vectors, overwriting any with matching ids. Returns the async-mutation id. */
+    upsert(vectors: VectorizeVector[]): Promise<IndexUpsertResponse | null>;
+    /** Query the index for the nearest neighbors of a vector. */
+    query(vector: number[], options?: VectorizeQueryOptions): Promise<IndexQueryResponse | null>;
+    /**
+     * Query by an existing vector's id: fetch its values, then run a nearest-neighbor query with
+     * them. Returns an empty result when the id is absent or has no values.
+     */
+    queryById(vectorId: string, options?: VectorizeQueryOptions): Promise<IndexQueryResponse | null>;
+    /** Fetch vectors by id. Returns an array (possibly empty); each element carries its values. */
+    getByIds(ids: string[]): Promise<VectorizeVector[]>;
+    /** Delete vectors by id. Returns the async-mutation id for the enqueued change. */
+    deleteByIds(ids: string[]): Promise<IndexDeleteByIDsResponse | null>;
+    /** Describe the index: dimensions, vector count, and processing watermarks. */
+    describe(): Promise<IndexInfoResponse | null>;
+    /** The index this manager targets and the account it lives in. */
+    getVectorizeInfo(): {
+        indexName: string;
+        accountId: string;
+    };
+    getServiceType(): string;
+    /** Prove access by reading the index record. Never throws. */
+    validateServiceAccess(): Promise<boolean>;
+}
+//# sourceMappingURL=vectorizeManager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vectorizeManager.d.ts","sourceRoot":"","sources":["../../src/ai/vectorizeManager.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,wBAAwB,EAExB,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,gDAAgD,CAAC;AAExD,OAAO,EAAE,iBAAiB,EAAE,KAAK,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAEpF,4FAA4F;AAC5F,MAAM,WAAW,sBAAuB,SAAQ,uBAAuB;IACrE,sFAAsF;IACtF,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,8FAA8F;AAC9F,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,qCAAqC;IACrC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,kDAAkD;AAClD,MAAM,WAAW,qBAAqB;IACpC,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,kEAAkE;IAClE,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,KAAK,CAAC;IAC5C,qDAAqD;IACrD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;GAKG;AACH,qBAAa,0BAA2B,SAAQ,iBAAiB;IAC/D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,YAAY,MAAM,EAAE,sBAAsB,EAMzC;IAED,mGAAmG;IACnG,OAAO,CAAC,mBAAmB;IAK3B,6EAA6E;IACvE,MAAM,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAO5E;IAED,wFAAwF;IAClF,MAAM,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAO5E;IAED,6DAA6D;IACvD,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAWjG;IAED;;;OAGG;IACG,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAOrG;IAED,+FAA+F;IACzF,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAQxD;IAED,mFAAmF;IAC7E,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,wBAAwB,GAAG,IAAI,CAAC,CAOzE;IAED,+EAA+E;IACzE,QAAQ,IAAI,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAIlD;IAED,kEAAkE;IAClE,gBAAgB,IAAI;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAE3D;IAED,cAAc,IAAI,MAAM,CAEvB;IAED,8DAA8D;IACxD,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;CACF"}

package/dist/ai/vectorizeManager.js

@@ -0,0 +1,101 @@
+import { CloudflareNotConfiguredError, cloudflareRequest } from "../client/errors.js";
+import { CloudflareManager } from "../client/manager.js";
+//#region src/ai/vectorizeManager.ts
+/**
+* Out-of-Worker Vectorize access over the REST API: insert/upsert vectors, query nearest
+* neighbors, fetch and delete by id, and describe the index from a CLI/CI/provisioning context.
+* Inside a Worker you use the `Vectorize` binding directly — this manager is the REST counterpart,
+* addressed by index name.
+*/
+var CloudflareVectorizeManager = class extends CloudflareManager {
+	indexName;
+	constructor(config) {
+		super(config);
+		if (!config.indexName) throw new CloudflareNotConfiguredError({ detail: "Missing indexName for Vectorize REST access." });
+		this.indexName = config.indexName;
+	}
+	/** Serialize vectors as an NDJSON file, the body shape the REST insert/upsert endpoints expect. */
+	vectorsToNdjsonFile(vectors) {
+		const ndjson = vectors.map((vector) => JSON.stringify(vector)).join("\n");
+		return new File([ndjson], "vectors.ndjson", { type: "application/x-ndjson" });
+	}
+	/** Insert vectors. Returns the async-mutation id for the enqueued change. */
+	async insert(vectors) {
+		return cloudflareRequest("Vectorize insert", () => this.getClient().vectorize.indexes.insert(this.indexName, {
+			account_id: this.accountId,
+			body: this.vectorsToNdjsonFile(vectors)
+		}));
+	}
+	/** Upsert vectors, overwriting any with matching ids. Returns the async-mutation id. */
+	async upsert(vectors) {
+		return cloudflareRequest("Vectorize upsert", () => this.getClient().vectorize.indexes.upsert(this.indexName, {
+			account_id: this.accountId,
+			body: this.vectorsToNdjsonFile(vectors)
+		}));
+	}
+	/** Query the index for the nearest neighbors of a vector. */
+	async query(vector, options) {
+		return cloudflareRequest("Vectorize query", () => this.getClient().vectorize.indexes.query(this.indexName, {
+			account_id: this.accountId,
+			vector,
+			...options?.topK !== void 0 ? { topK: options.topK } : {},
+			...options?.returnValues !== void 0 ? { returnValues: options.returnValues } : {},
+			...options?.returnMetadata !== void 0 ? { returnMetadata: options.returnMetadata } : {},
+			...options?.filter !== void 0 ? { filter: options.filter } : {}
+		}));
+	}
+	/**
+	* Query by an existing vector's id: fetch its values, then run a nearest-neighbor query with
+	* them. Returns an empty result when the id is absent or has no values.
+	*/
+	async queryById(vectorId, options) {
+		const first = (await this.getByIds([vectorId]))[0];
+		if (!first || !Array.isArray(first.values) || first.values.length === 0) return {
+			count: 0,
+			matches: []
+		};
+		return this.query(first.values, options);
+	}
+	/** Fetch vectors by id. Returns an array (possibly empty); each element carries its values. */
+	async getByIds(ids) {
+		return cloudflareRequest("Vectorize getByIds", async () => {
+			const response = await this.getClient().vectorize.indexes.getByIDs(this.indexName, {
+				account_id: this.accountId,
+				ids
+			});
+			return Array.isArray(response) ? response : [];
+		});
+	}
+	/** Delete vectors by id. Returns the async-mutation id for the enqueued change. */
+	async deleteByIds(ids) {
+		return cloudflareRequest("Vectorize deleteByIds", () => this.getClient().vectorize.indexes.deleteByIDs(this.indexName, {
+			account_id: this.accountId,
+			ids
+		}));
+	}
+	/** Describe the index: dimensions, vector count, and processing watermarks. */
+	async describe() {
+		return cloudflareRequest("Vectorize describe", () => this.getClient().vectorize.indexes.info(this.indexName, { account_id: this.accountId }));
+	}
+	/** The index this manager targets and the account it lives in. */
+	getVectorizeInfo() {
+		return {
+			indexName: this.indexName,
+			accountId: this.accountId
+		};
+	}
+	getServiceType() {
+		return "Vectorize";
+	}
+	/** Prove access by reading the index record. Never throws. */
+	async validateServiceAccess() {
+		try {
+			await this.getClient().vectorize.indexes.get(this.indexName, { account_id: this.accountId });
+			return true;
+		} catch {
+			return false;
+		}
+	}
+};
+//#endregion
+export { CloudflareVectorizeManager };

package/dist/ai/vectorizeProvisioner.d.ts

@@ -0,0 +1,123 @@
+import { z } from "zod";
+import { CloudflareManager } from "../client/manager";
+/** The distance metric an index scores nearest neighbors with. Fixed at creation — it cannot be changed later. */
+export declare const VectorizeMetric: z.ZodEnum<{
+    cosine: "cosine";
+    "dot-product": "dot-product";
+    euclidean: "euclidean";
+}>;
+export type VectorizeMetric = z.infer<typeof VectorizeMetric>;
+/**
+ * A Cloudflare-managed embedding preset. Naming one lets Cloudflare pick the dimensions and metric that
+ * match the model, so an index and the model that fills it cannot drift apart.
+ */
+export declare const VectorizePreset: z.ZodEnum<{
+    "@cf/baai/bge-base-en-v1.5": "@cf/baai/bge-base-en-v1.5";
+    "@cf/baai/bge-large-en-v1.5": "@cf/baai/bge-large-en-v1.5";
+    "@cf/baai/bge-small-en-v1.5": "@cf/baai/bge-small-en-v1.5";
+    "cohere/embed-multilingual-v2.0": "cohere/embed-multilingual-v2.0";
+    "openai/text-embedding-ada-002": "openai/text-embedding-ada-002";
+}>;
+export type VectorizePreset = z.infer<typeof VectorizePreset>;
+/** The shape of the vectors an index holds: how many components each carries, and how they are compared. */
+export declare const VectorizeIndexConfig: z.ZodObject<{
+    dimensions: z.ZodNumber;
+    metric: z.ZodEnum<{
+        cosine: "cosine";
+        "dot-product": "dot-product";
+        euclidean: "euclidean";
+    }>;
+}, z.core.$strip>;
+export type VectorizeIndexConfig = z.output<typeof VectorizeIndexConfig>;
+/** A Vectorize index's identity and shape, decoded from the create/get/list responses. */
+export declare const VectorizeIndexInfo: z.ZodObject<{
+    name: z.ZodString;
+    config: z.ZodObject<{
+        dimensions: z.ZodNumber;
+        metric: z.ZodEnum<{
+            cosine: "cosine";
+            "dot-product": "dot-product";
+            euclidean: "euclidean";
+        }>;
+    }, z.core.$strip>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type VectorizeIndexInfo = z.output<typeof VectorizeIndexInfo>;
+/** The type of a metadata property an index can filter on. Chosen per property when the metadata index is created. */
+export declare const VectorizeMetadataIndexType: z.ZodEnum<{
+    boolean: "boolean";
+    number: "number";
+    string: "string";
+}>;
+export type VectorizeMetadataIndexType = z.infer<typeof VectorizeMetadataIndexType>;
+/** One indexed metadata property on a Vectorize index — the unit that makes a metadata filter possible. */
+export declare const VectorizeMetadataIndex: z.ZodObject<{
+    propertyName: z.ZodString;
+    indexType: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodEnum<{
+        boolean: "boolean";
+        number: "number";
+        string: "string";
+    }>>;
+}, z.core.$strip>;
+export type VectorizeMetadataIndex = z.output<typeof VectorizeMetadataIndex>;
+/**
+ * How a new index is shaped: either an explicit dimensions/metric pair, or a Cloudflare embedding preset
+ * that resolves to one. Both are modeled because a caller that owns its embedding model wants the explicit
+ * pair, while a caller using a stock Cloudflare model is better served by the preset — naming the model once
+ * instead of restating its dimensions and risking a mismatch.
+ */
+export type VectorizeIndexSpec = {
+    dimensions: number;
+    metric: VectorizeMetric;
+} | {
+    preset: VectorizePreset;
+};
+/** Options a new index accepts beyond its name and shape. */
+export interface CreateVectorizeIndexOptions {
+    /** A human description stored on the index, surfaced in the Cloudflare dashboard. */
+    description?: string;
+}
+/**
+ * Account-level Vectorize control plane: **create and delete indexes, and manage their metadata indexes**.
+ * `pithy vector provision` uses this to stand up a per-environment index and declare which metadata
+ * properties are filterable; teardown uses it to remove them. Unlike {@link CloudflareVectorizeManager},
+ * which operates *within* one already-provisioned index (insert/query/delete vectors), this manager is
+ * account-scoped and addresses indexes **by name** — Vectorize indexes carry no separate uuid id.
+ *
+ * Every mutation here is enqueued: Vectorize applies index and metadata-index changes asynchronously, so a
+ * successful call means "accepted", not "visible". Poll {@link listMetadataIndexes} or the data-plane
+ * `describe()` watermarks rather than writing and immediately reading back.
+ */
+export declare class CloudflareVectorizeProvisioner extends CloudflareManager {
+    getServiceType(): string;
+    /** Prove access by listing indexes — a read, never a destructive create/delete. Never throws. */
+    validateServiceAccess(): Promise<boolean>;
+    /** Create a Vectorize index by name with an explicit dimensions/metric pair or a Cloudflare preset. */
+    createIndex(name: string, config: VectorizeIndexSpec, options?: CreateVectorizeIndexOptions): Promise<VectorizeIndexInfo>;
+    /** Delete a Vectorize index by name. Idempotent — a missing index is not an error, so teardown can re-run safely. */
+    deleteIndex(name: string): Promise<void>;
+    /** List every Vectorize index in the account — for prefix-scan reconcile teardown and drift checks. */
+    listIndexes(): Promise<VectorizeIndexInfo[]>;
+    /**
+     * Find an index by exact name, or `null` — for idempotent provisioning. Reads the one index rather than
+     * draining the account list, because a Vectorize index's name *is* its address (unlike a KV namespace,
+     * whose title is not addressable). A 404 — or a 410 for a deleted one — means absent, which is an answer,
+     * not a failure.
+     */
+    findIndexByName(name: string): Promise<VectorizeIndexInfo | null>;
+    /**
+     * Make a metadata property filterable. Cloudflare caps an index at 10 indexed properties, and only vectors
+     * written **after** the metadata index exists are covered — so declare these before the first insert.
+     * The change is enqueued asynchronously; the returned promise resolving means accepted, not live.
+     */
+    createMetadataIndex(indexName: string, propertyName: string, indexType: VectorizeMetadataIndexType): Promise<void>;
+    /** List an index's indexed metadata properties — the read that proves a `createMetadataIndex` has landed. */
+    listMetadataIndexes(indexName: string): Promise<VectorizeMetadataIndex[]>;
+    /**
+     * Stop filtering on a metadata property. Idempotent — a missing metadata index is not an error, matching
+     * {@link deleteIndex} so teardown can re-run safely. Absence here is `400`/40005, not `404`, which is why
+     * this uses {@link isAbsentMetadataIndexError} rather than the plain not-found check.
+     */
+    deleteMetadataIndex(indexName: string, propertyName: string): Promise<void>;
+}
+//# sourceMappingURL=vectorizeProvisioner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vectorizeProvisioner.d.ts","sourceRoot":"","sources":["../../src/ai/vectorizeProvisioner.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,kHAAkH;AAClH,eAAO,MAAM,eAAe;;;;EAEgF,CAAC;AAC7G,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;;EAQiF,CAAC;AAC9G,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,4GAA4G;AAC5G,eAAO,MAAM,oBAAoB;;;;;;;iBAS2E,CAAC;AAC7G,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAEzE,0FAA0F;AAC1F,eAAO,MAAM,kBAAkB;;;;;;;;;;;iBAMqF,CAAC;AACrH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAErE,sHAAsH;AACtH,eAAO,MAAM,0BAA0B;;;;EAEqE,CAAC;AAC7G,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAiBpF,2GAA2G;AAC3G,eAAO,MAAM,sBAAsB;;;;;;;iBAK+E,CAAC;AACnH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE7E;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,eAAe,CAAA;CAAE,CAAC;AAuC/G,6DAA6D;AAC7D,MAAM,WAAW,2BAA2B;IAC1C,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,8BAA+B,SAAQ,iBAAiB;IACnE,cAAc,IAAI,MAAM,CAEvB;IAED,iGAAiG;IAC3F,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;IAED,uGAAuG;IACjG,WAAW,CACf,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,kBAAkB,EAC1B,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,kBAAkB,CAAC,CAU7B;IAED,qHAAqH;IAC/G,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAS7C;IAED,uGAAuG;IACjG,WAAW,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAQjD;IAED;;;;;OAKG;IACG,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAUtE;IAED;;;;OAIG;IACG,mBAAmB,CACvB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,0BAA0B,GACpC,OAAO,CAAC,IAAI,CAAC,CAQf;IAED,6GAA6G;IACvG,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAS9E;IAED;;;;OAIG;IACG,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAYhF;CACF"}