@pithy-sh/cloudflare 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pithy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# @pithy-sh/cloudflare
+
+One encapsulated client for every out-of-Worker Cloudflare operation.
+
+Inside a Worker you use bindings. Outside one — the CLI, CI, provisioning, anything on Node or Bun — and for the control-plane operations a binding cannot do, you use this. Never both, and never a hand-rolled `fetch` to the Cloudflare API.
+
+```sh
+bun add @pithy-sh/cloudflare
+```
+
+It is a library rather than a capability, so it has no `pithy add`. Every capability that provisions anything depends on it already.
+
+**Documentation: [pithy.sh/docs/core-concepts/bindings-or-rest](https://pithy.sh/docs/core-concepts/bindings-or-rest).** Which of the two a given operation takes, and why the rule is absolute. The package list is at [pithy.sh/docs/reference/packages](https://pithy.sh/docs/reference/packages).
+
+_Everything on the adopter side is on the site. `pithy.sh/docs` is canonical — new adopter prose goes there, not here._
+
+## Live integration tests
+
+Mocks prove our call *shapes*. They cannot prove the request, the response decoding, and the error handling are functionally correct against real Cloudflare — that only surfaces live. So every manager that makes real CF calls also has a `*.integration.test.ts` that creates a throwaway resource, exercises the manager against it, and tears it down. These are excluded from the default suite and run via `bun run test:integration` (the `vitest.integration.config.ts` project), gated on credentials so they skip cleanly without them.
+
+Credentials come from `packages/cloudflare/.dev.vars`, with `process.env` overlaid per key for anything the file does not set (`loadCloudflareEnv`). **Nothing creates that file.** It used to be a symlink to the root's, wired by a `vars:local` task; #154 removed both, and `pithy dev` and `pithy seed` generate `apps/<worker>/.dev.vars` in an adopter's project — `apps/` is the registry, so nothing regenerates a file in a kit package. Write it, or export the variables:
+
+```sh
+cat > .dev.vars <<'EOF'          # a real file, in this package, git-ignored
+CLOUDFLARE_ACCOUNT_ID=…
+CLOUDFLARE_API_TOKEN=…
+EOF
+bun run test:integration         # against the account in those creds
+```
+
+Exporting them instead works identically and is how CI runs — the workflow sets `CLOUDFLARE_*` and `SECRETS_STORE_ID` from the `E2E Integration Testing` environment with no `.dev.vars` present. Set a key in both places and the file wins.
+
+Point them at a **dedicated test account** — they create and delete real resources.
+
+Most managers need only `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID`. A few need more, and skip cleanly without it:
+
+- **R2** signs presigned URLs with S3 keys, not the CF token. Put them in `.dev.vars` as `R2_CREDENTIALS={"accessKeyId":"…","secretAccessKey":"…"}`; the R2 suite skips when absent.
+- **Secrets Store** reuses the store in `SECRETS_STORE_ID`.
+- **Images** and **Stream** consume paid quota — an account with them merely *enabled* (limit 0) rejects every upload/reservation. Those suites are additionally gated behind `PITHY_IMAGES_PAID=1` / `PITHY_STREAM_PAID=1`; set them only on an account with quota.
+- **Builds** needs a git repo connected via OAuth (not automatable headlessly) — tracked as a separate follow-up issue, not covered here.
+
+### The pattern
+
+`src/test-utils/harness.ts` carries the shared scaffolding so each test does not re-derive it:
+
+- `loadIntegrationCreds()` — reads `CLOUDFLARE_*` from `.dev.vars` (or `process.env`) and returns `hasCreds`. Gate the suite with `describe.skipIf(!creds.hasCreds)`.
+- `uniqueName(label)` — a collision-proof, lowercase `a-z0-9-` name for the throwaway resource. The label is the distinguishing part only (`"kv"`, `"d1"`); the harness composes the reserved `pithy-int-` prefix and the timestamp the reaper reads. A label that already carries the prefix is **refused**, so pass `uniqueName("kv")`, never `uniqueName("pithy-int-kv")`.
+- `withThrowawayResource(create, exercise, teardown)` — runs `exercise`, then **guarantees `teardown` in a `finally`** so a failed assertion never orphans a real resource. `create` runs outside the `try`, so a creation failure never tears down something that was never created.
+- `withNamedResource(name, create, exercise, teardown)` — the same guarantee for a **named write** (`putSecret(name, …)`, `createBucket(name)`), where a rejected `create` may still have landed. Teardown is armed before `create` runs and addresses the name, so pass an idempotent delete.
+- `reapStaleTestResources(kind)` — deletes debris of one kind an earlier crashed run left behind. You rarely call this directly: `src/test-utils/reap.ts` registers every kind and each `vitest.integration.config.ts` sweeps once per run via `globalSetup`. Add a kind there rather than a `beforeAll` to your suite — a hook inside a `describe.skipIf` does not run when the suite skips, which gated each reaper on the very credential whose absence lets debris pile up.
+
+`pithy-int-` is reserved on any account: everything a live test creates is inside it, `pithy init` refuses a project name that would land in it, and the reaper deletes nothing outside it. See [`docs/NAMING.md`](../../docs/NAMING.md). When the resource names are themselves under test, provision under the reserved project `RESERVED_TEST_PROJECT` rather than inventing a name — the project segment comes first and verbatim, so every name the product composes lands in the namespace too.
+
+Each test asserts the three things mocks cannot: a happy-path request succeeds, the response decodes to the expected shape, and at least one error/absent path behaves correctly (surfaced as our typed result or a `PithyError`).
+
+`src/kv/kvManager.integration.test.ts` is the reference — copy it. The KV namespace itself is created and deleted with the raw SDK (the manager addresses an existing namespace by id), so namespace lifecycle is the harness's `create`/`teardown`:
+
+```ts
+const creds = loadIntegrationCreds();
+
+describe.skipIf(!creds.hasCreds)("CloudflareKVManager — LIVE", () => {
+  const client = new Cloudflare({ apiToken: creds.apiToken });
+
+  test("round-trips a key, then reads an absent key as null", async () => {
+    await withThrowawayResource(
+      () => client.kv.namespaces.create({ account_id: creds.accountId, title: uniqueName("kv") }),
+      async (namespace) => {
+        const kv = new CloudflareKVManager({ accountId: creds.accountId, apiToken: creds.apiToken, namespaceId: namespace.id });
+        expect(await kv.validateServiceAccess()).toBe(true);     // happy path
+        await kv.set("greeting", "hello");
+        expect(await kv.get("greeting")).toBe("hello");          // decoded shape
+        await kv.delete("greeting");
+        expect(await kv.get("greeting")).toBeNull();             // absent path: 404 -> null
+      },
+      (namespace) => client.kv.namespaces.delete(namespace.id, { account_id: creds.accountId }).then(() => undefined),
+    );
+  });
+});
+```
+
+This reference landed first to lock the template; the remaining managers each copy it as their own reviewed slice under [#39](https://github.com/pithy-sh/pithy/issues/39).
+
+**This section stays here.** It is for whoever is working on this package, not for an adopter — the site documents the kit, and a contributor's test harness has no page on it. `src/test-utils/harness.ts`, `src/kv/kvManager.integration.test.ts` and `src/d1/d1Provisioner.integration.test.ts` each point a reader at it by name.
+
+## License
+
+MIT — adopter-side app value. The root `LICENSE` covers it.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@pithy-sh/cloudflare",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pithy-sh/pithy.git",
+    "directory": "packages/cloudflare"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.*"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./src/*": "./src/*.ts"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit false --outDir dist",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:node": "vitest run --project=node",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "clean": "rm -rf dist .turbo",
+    "reset": "bun run clean && rm -rf node_modules"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.1111.0",
+    "@aws-sdk/s3-request-presigner": "^3.1111.0",
+    "@cloudflare/workers-types": "^5.20260729.1",
+    "@pithy-sh/core": "workspace:*",
+    "cloudflare": "^7.0.0",
+    "js-base64": "^3.9.2",
+    "kysely": "^0.29.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@pithy-sh/tsconfig": "workspace:*",
+    "@types/node": "^22.15.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "kysely-d1": "^0.4.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.0"
+  }
+}

package/src/ai/aiManager.ts

@@ -0,0 +1,227 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { AIRunParams, AIRunResponse } from "cloudflare/resources/ai/ai";
+import type { ModelListResponse } from "cloudflare/resources/ai/models/models";
+import { fromUint8Array } from "js-base64";
+import { z } from "zod";
+import { CloudflareInvalidResponseError, cloudflareRequest } from "../client/errors";
+import { CloudflareManager } from "../client/manager";
+
+/**
+ * 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.
+ */
+export 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.");
+export type VectorEmbeddings = z.infer<typeof VectorEmbeddings>;
+
+/**
+ * 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.");
+
+export 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) {
+      // `.min(1)` makes this unreachable at runtime; the guard exists because
+      // `noUncheckedIndexedAccess` types the access as optional and a silent "" would be worse.
+      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.");
+export type TextGeneration = z.output<typeof TextGeneration>;
+
+/**
+ * The image-to-text payload Cloudflare's vision models return: a textual description of the image.
+ */
+export 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.");
+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;
+}
+
+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.
+ */
+export 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.
+   */
+  async runModel(model: string, input: Record<string, unknown>): Promise<AIRunResponse> {
+    return cloudflareRequest(`AI run model '${model}'`, () =>
+      this.getClient().ai.run(model, { account_id: this.accountId, ...input } as AIRunParams),
+    );
+  }
+
+  /**
+   * 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: ChatMessage[], options?: GenerateTextOptions): Promise<TextGeneration> {
+    const model = options?.model ?? DEFAULT_TEXT_MODEL;
+    const raw = await this.runModel(model, {
+      messages,
+      ...(options?.maxTokens !== undefined ? { 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: string | string[], model?: string): Promise<VectorEmbeddings> {
+    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: Uint8Array, options?: AnalyzeImageOptions): Promise<ImageToText> {
+    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 !== undefined ? { 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(): Promise<ModelListResponse[]> {
+    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(): string {
+    return "Workers AI";
+  }
+
+  /** Prove access by listing models. Never throws. */
+  async validateServiceAccess(): Promise<boolean> {
+    try {
+      const models = await this.listModels();
+      return models.length > 0;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/ai/vectorizeManager.ts

@@ -0,0 +1,161 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type {
+  IndexDeleteByIDsResponse,
+  IndexGetByIDsResponse,
+  IndexInfoResponse,
+  IndexInsertResponse,
+  IndexQueryResponse,
+  IndexUpsertResponse,
+} from "cloudflare/resources/vectorize/indexes/indexes";
+import { CloudflareNotConfiguredError, cloudflareRequest } from "../client/errors";
+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 class CloudflareVectorizeManager extends CloudflareManager {
+  private readonly indexName: string;
+
+  constructor(config: VectorizeManagerConfig) {
+    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. */
+  private vectorsToNdjsonFile(vectors: VectorizeVector[]): File {
+    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: VectorizeVector[]): Promise<IndexInsertResponse | null> {
+    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: VectorizeVector[]): Promise<IndexUpsertResponse | null> {
+    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: number[], options?: VectorizeQueryOptions): Promise<IndexQueryResponse | null> {
+    return cloudflareRequest("Vectorize query", () =>
+      this.getClient().vectorize.indexes.query(this.indexName, {
+        account_id: this.accountId,
+        vector,
+        ...(options?.topK !== undefined ? { topK: options.topK } : {}),
+        ...(options?.returnValues !== undefined ? { returnValues: options.returnValues } : {}),
+        ...(options?.returnMetadata !== undefined ? { returnMetadata: options.returnMetadata } : {}),
+        ...(options?.filter !== undefined ? { 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: string, options?: VectorizeQueryOptions): Promise<IndexQueryResponse | null> {
+    const vectors = await this.getByIds([vectorId]);
+    const first = vectors[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: string[]): Promise<VectorizeVector[]> {
+    return cloudflareRequest("Vectorize getByIds", async () => {
+      const response = (await this.getClient().vectorize.indexes.getByIDs(this.indexName, {
+        account_id: this.accountId,
+        ids,
+      })) as IndexGetByIDsResponse;
+      return (Array.isArray(response) ? response : []) as VectorizeVector[];
+    });
+  }
+
+  /** Delete vectors by id. Returns the async-mutation id for the enqueued change. */
+  async deleteByIds(ids: string[]): Promise<IndexDeleteByIDsResponse | null> {
+    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(): Promise<IndexInfoResponse | null> {
+    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(): { indexName: string; accountId: string } {
+    return { indexName: this.indexName, accountId: this.accountId };
+  }
+
+  getServiceType(): string {
+    return "Vectorize";
+  }
+
+  /** Prove access by reading the index record. Never throws. */
+  async validateServiceAccess(): Promise<boolean> {
+    try {
+      await this.getClient().vectorize.indexes.get(this.indexName, { account_id: this.accountId });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}