alchemy 0.8.0 → 0.8.1

package/src/cloudflare/bindings.ts

@@ -11,6 +11,7 @@ import type { DurableObjectNamespace } from "./durable-object-namespace";
 import type { KVNamespace } from "./kv-namespace";
 import type { Pipeline } from "./pipeline";
 import type { Queue } from "./queue";
+import type { VectorizeIndex } from "./vectorize-index";
 import type { Worker } from "./worker";
 import type { Workflow } from "./workflow";
 
@@ -31,6 +32,7 @@ export type Binding =
   | R2Bucket
   | Secret
   | string
+  | VectorizeIndex
   | Worker
   | Workflow;
 

package/src/cloudflare/bound.ts

@@ -8,6 +8,7 @@ import type { DurableObjectNamespace as _DurableObjectNamespace } from "./durabl
 import type { KVNamespace as _KVNamespace } from "./kv-namespace";
 import type { Pipeline as _Pipeline } from "./pipeline";
 import type { Queue as _Queue } from "./queue";
+import type { VectorizeIndex as _VectorizeIndex } from "./vectorize-index";
 import type { Worker as _Worker } from "./worker";
 import type { Workflow as _Workflow } from "./workflow";
 
@@ -27,8 +28,10 @@ export type Bound<T extends Binding> = T extends _DurableObjectNamespace
               ? Workflow<P>
               : T extends _D1Database
                 ? D1Database
-                : T extends _Queue
-                  ? Queue
-                  : T extends _Pipeline<infer R>
-                    ? Pipeline<R>
-                    : Service;
+                : T extends _VectorizeIndex
+                  ? VectorizeIndex
+                  : T extends _Queue
+                    ? Queue
+                    : T extends _Pipeline<infer R>
+                      ? Pipeline<R>
+                      : Service;

package/src/cloudflare/index.ts

@@ -13,6 +13,8 @@ export * from "./permission-groups";
 export * from "./pipeline";
 export * from "./queue";
 export * from "./r2-rest-state-store";
+export * from "./vectorize-index";
+export * from "./vectorize-metadata-index";
 export * from "./worker";
 export { Workflow } from "./workflow";
 export * from "./wrangler.json";

package/src/cloudflare/vectorize-index.ts

@@ -0,0 +1,331 @@
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import {
+  CloudflareApi,
+  createCloudflareApi,
+  type CloudflareApiOptions,
+} from "./api";
+import { CloudflareApiError, handleApiError } from "./api-error";
+
+/**
+ * Properties for creating or updating a Vectorize Index
+ */
+export interface VectorizeIndexProps extends CloudflareApiOptions {
+  /**
+   * Name of the index
+   */
+  name: string;
+
+  /**
+   * Optional description of the index
+   */
+  description?: string;
+
+  /**
+   * Dimensions of the vectors
+   */
+  dimensions: number;
+
+  /**
+   * Distance metric used for vector similarity
+   */
+  metric: "cosine" | "euclidean" | "dot_product";
+
+  /**
+   * Whether to delete the index if removed
+   * If set to false, the index will remain but the resource will be removed from state
+   *
+   * @default true
+   */
+  delete?: boolean;
+
+  /**
+   * Whether to adopt an existing index with the same name if it exists
+   * If true and an index with the same name exists, it will be adopted rather than creating a new one
+   *
+   * @default false
+   */
+  adopt?: boolean;
+}
+
+/**
+ * Output returned after Vectorize Index creation/update
+ */
+export interface VectorizeIndex
+  extends Resource<"cloudflare::VectorizeIndex">,
+    VectorizeIndexProps {
+  type: "vectorize";
+
+  /**
+   * The unique identifier for the index (same as name)
+   */
+  id: string;
+
+  /**
+   * Time at which the index was created
+   */
+  createdAt?: number;
+}
+
+/**
+ * Creates and manages Cloudflare Vectorize Indexes.
+ *
+ * Vectorize is Cloudflare's vector database that enables vector search within Cloudflare Workers.
+ *
+ * @example
+ * // Create a basic vector index for text embeddings
+ * const basicIndex = await VectorizeIndex("text-embeddings", {
+ *   name: "text-embeddings",
+ *   config: {
+ *     dimensions: 768,
+ *     metric: "cosine"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a vector index with a description
+ * const descIndex = await VectorizeIndex("image-embeddings", {
+ *   name: "image-embeddings",
+ *   description: "Vector index for image embeddings using CLIP model",
+ *   config: {
+ *     dimensions: 512,
+ *     metric: "cosine"
+ *   }
+ * });
+ *
+ * @example
+ * // Adopt an existing index if it already exists instead of failing
+ * const existingIndex = await VectorizeIndex("existing-index", {
+ *   name: "existing-index",
+ *   adopt: true,
+ *   config: {
+ *     dimensions: 1024,
+ *     metric: "euclidean"
+ *   }
+ * });
+ *
+ * @see https://developers.cloudflare.com/vectorize/
+ */
+export const VectorizeIndex = Resource(
+  "cloudflare::VectorizeIndex",
+  async function (
+    this: Context<VectorizeIndex>,
+    id: string,
+    props: VectorizeIndexProps
+  ): Promise<VectorizeIndex> {
+    const api = await createCloudflareApi(props);
+    const indexName = props.name || id;
+
+    if (this.phase === "delete") {
+      console.log("Deleting Vectorize index:", indexName);
+      if (props.delete !== false) {
+        // Delete Vectorize index
+        await deleteIndex(api, indexName);
+      }
+
+      // Return void (a deleted index has no content)
+      return this.destroy();
+    } else {
+      let indexData: CloudflareVectorizeResponse;
+
+      if (this.phase === "create") {
+        console.log("Creating Vectorize index:", indexName);
+        try {
+          indexData = await createIndex(api, indexName, {
+            ...props,
+            name: indexName,
+          });
+        } catch (error) {
+          // Check if this is a "index already exists" error and adopt is enabled
+          if (
+            props.adopt &&
+            error instanceof CloudflareApiError &&
+            error.message.includes("already exists")
+          ) {
+            console.log(`Index ${indexName} already exists, adopting it`);
+            // Find the existing index
+            indexData = await getIndex(api, indexName);
+          } else {
+            // Re-throw the error if adopt is false or it's not a "index already exists" error
+            throw error;
+          }
+        }
+      } else {
+        // Update operation is not supported by Vectorize API
+        throw new Error(
+          "Updating Vectorize indexes is not supported by the Cloudflare API. " +
+            "To change an index, delete it and create a new one with the desired configuration."
+        );
+      }
+
+      return this({
+        type: "vectorize",
+        id: indexName,
+        name: indexName,
+        description: props.description,
+        dimensions: indexData.result.config.dimensions,
+        metric: indexData.result.config.metric as
+          | "cosine"
+          | "euclidean"
+          | "dot_product",
+        accountId: api.accountId,
+        createdAt: indexData.result.created_on
+          ? new Date(indexData.result.created_on).getTime()
+          : undefined,
+      });
+    }
+  }
+);
+
+interface CloudflareVectorizeResponse {
+  result: {
+    name: string;
+    description?: string;
+    created_on?: string;
+    config: {
+      dimensions: number;
+      metric: string;
+    };
+  };
+  success: boolean;
+  errors: Array<{ code: number; message: string }>;
+  messages: string[];
+}
+
+/**
+ * Create a new Vectorize index
+ */
+export async function createIndex(
+  api: CloudflareApi,
+  indexName: string,
+  props: VectorizeIndexProps
+): Promise<CloudflareVectorizeResponse> {
+  // Create new Vectorize index
+  const createPayload: any = {
+    name: indexName,
+    config: {
+      dimensions: props.dimensions,
+      metric: props.metric,
+    },
+  };
+
+  if (props.description) {
+    createPayload.description = props.description;
+  }
+
+  const createResponse = await api.post(
+    `/accounts/${api.accountId}/vectorize/v2/indexes`,
+    createPayload
+  );
+
+  if (!createResponse.ok) {
+    return await handleApiError(
+      createResponse,
+      "creating",
+      "Vectorize index",
+      indexName
+    );
+  }
+
+  return (await createResponse.json()) as CloudflareVectorizeResponse;
+}
+
+/**
+ * Get a Vectorize index
+ */
+export async function getIndex(
+  api: CloudflareApi,
+  indexName: string
+): Promise<CloudflareVectorizeResponse> {
+  const response = await api.get(
+    `/accounts/${api.accountId}/vectorize/v2/indexes/${indexName}`
+  );
+
+  if (!response.ok) {
+    return await handleApiError(
+      response,
+      "getting",
+      "Vectorize index",
+      indexName
+    );
+  }
+
+  return (await response.json()) as CloudflareVectorizeResponse;
+}
+
+/**
+ * Delete a Vectorize index
+ */
+export async function deleteIndex(
+  api: CloudflareApi,
+  indexName: string
+): Promise<void> {
+  // Delete Vectorize index
+  const deleteResponse = await api.delete(
+    `/accounts/${api.accountId}/vectorize/v2/indexes/${indexName}`
+  );
+
+  if (!deleteResponse.ok && deleteResponse.status !== 404) {
+    const errorData: any = await deleteResponse.json().catch(() => ({
+      errors: [{ message: deleteResponse.statusText }],
+    }));
+    throw new CloudflareApiError(
+      `Error deleting Vectorize index '${indexName}': ${errorData.errors?.[0]?.message || deleteResponse.statusText}`,
+      deleteResponse
+    );
+  }
+}
+
+/**
+ * List all Vectorize indexes in an account
+ */
+export async function listIndexes(
+  api: CloudflareApi
+): Promise<{ name: string; description?: string }[]> {
+  const response = await api.get(
+    `/accounts/${api.accountId}/vectorize/v2/indexes`
+  );
+
+  if (!response.ok) {
+    throw new CloudflareApiError(
+      `Failed to list indexes: ${response.statusText}`,
+      response
+    );
+  }
+
+  const data = (await response.json()) as {
+    success: boolean;
+    errors?: Array<{ code: number; message: string }>;
+    result?: Array<{
+      name: string;
+      description?: string;
+    }>;
+  };
+
+  if (!data.success) {
+    const errorMessage = data.errors?.[0]?.message || "Unknown error";
+    throw new Error(`Failed to list indexes: ${errorMessage}`);
+  }
+
+  // Transform API response
+  return (data.result || []).map((index) => ({
+    name: index.name,
+    description: index.description,
+  }));
+}
+
+/**
+ * Update a Vectorize index
+ *
+ * Note: The Cloudflare Vectorize API does not support updating indexes.
+ * This function will always throw an error.
+ */
+export async function updateIndex(
+  api: CloudflareApi,
+  indexName: string,
+  props: VectorizeIndexProps
+): Promise<CloudflareVectorizeResponse> {
+  throw new Error(
+    "Updating Vectorize indexes is not supported by the Cloudflare API. To change an index, delete it and create a new one."
+  );
+}

package/src/cloudflare/vectorize-metadata-index.ts

@@ -0,0 +1,239 @@
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import {
+  CloudflareApi,
+  createCloudflareApi,
+  type CloudflareApiOptions,
+} from "./api";
+import { CloudflareApiError, handleApiError } from "./api-error";
+import { VectorizeIndex } from "./vectorize-index";
+
+/**
+ * Properties for creating or deleting a Vectorize Metadata Index
+ */
+export interface VectorizeMetadataIndexProps extends CloudflareApiOptions {
+  /**
+   * Parent Vectorize Index
+   */
+  index: VectorizeIndex;
+
+  /**
+   * Name of the property in the metadata to create an index for
+   */
+  propertyName: string;
+
+  /**
+   * Type of the metadata index
+   */
+  indexType: "string" | "number" | "boolean";
+}
+
+/**
+ * Output returned after Vectorize Metadata Index creation/deletion
+ */
+export interface VectorizeMetadataIndex
+  extends Resource<"cloudflare::VectorizeMetadataIndex">,
+    VectorizeMetadataIndexProps {
+  /**
+   * ID of this metadata index (derived from propertyName)
+   */
+  id: string;
+
+  /**
+   * Mutation ID returned by the API after creation
+   */
+  mutationId?: string;
+}
+
+/**
+ * Creates and manages Cloudflare Vectorize Metadata Indexes.
+ *
+ * Vectorize Metadata Indexes enable filtering based on metadata properties when querying vectors.
+ * Each Vectorize Index can have up to 10 metadata indexes.
+ *
+ * @example
+ * // First create a Vectorize Index
+ * const vectorIndex = await VectorizeIndex("documents", {
+ *   name: "documents",
+ *   config: {
+ *     dimensions: 768,
+ *     metric: "cosine"
+ *   }
+ * });
+ *
+ * // Then create a metadata index for the "category" property
+ * const categoryIndex = await VectorizeMetadataIndex("category-index", {
+ *   index: vectorIndex,
+ *   propertyName: "category",
+ *   indexType: "string"
+ * });
+ *
+ * @example
+ * // Create a metadata index for a numeric property
+ * const yearIndex = await VectorizeMetadataIndex("year-index", {
+ *   index: vectorIndex,
+ *   propertyName: "year",
+ *   indexType: "number"
+ * });
+ *
+ * @see https://developers.cloudflare.com/vectorize/
+ */
+export const VectorizeMetadataIndex = Resource(
+  "cloudflare::VectorizeMetadataIndex",
+  async function (
+    this: Context<VectorizeMetadataIndex>,
+    id: string,
+    props: VectorizeMetadataIndexProps
+  ): Promise<VectorizeMetadataIndex> {
+    const api = await createCloudflareApi(props);
+    const indexName = props.index.name;
+    const propertyName = props.propertyName;
+
+    if (this.phase === "delete") {
+      // Delete metadata index
+      try {
+        await deleteMetadataIndex(api, indexName, propertyName);
+      } catch (error) {
+        if (
+          error instanceof CloudflareApiError &&
+          error.status === 400 &&
+          error.message.includes("does not exist")
+        ) {
+          // Index doesn't exist, which is what we want
+        } else {
+          throw error;
+        }
+      }
+      return this.destroy();
+    } else if (this.phase === "update") {
+      // Update operation is not supported
+      throw new Error(
+        "Updating Vectorize metadata indexes is not supported by the Cloudflare API. " +
+          "To change a metadata index, delete it and create a new one with the desired configuration."
+      );
+    } else {
+      const indexData = await createMetadataIndex(api, indexName, props);
+
+      return this({
+        id: propertyName, // Use propertyName as ID
+        index: props.index,
+        propertyName: props.propertyName,
+        indexType: props.indexType,
+        accountId: api.accountId,
+        mutationId: indexData.result.mutationId,
+      });
+    }
+  }
+);
+
+interface CloudflareMetadataIndexResponse {
+  result: {
+    mutationId: string;
+  };
+  success: boolean;
+  errors: Array<{ code: number; message: string }>;
+  messages: string[];
+}
+
+interface CloudflareMetadataIndexListResponse {
+  result: {
+    metadataIndexes: Array<{
+      propertyName: string;
+      indexType: "string" | "number" | "boolean";
+    }>;
+  };
+  success: boolean;
+  errors: Array<{ code: number; message: string }>;
+  messages: string[];
+}
+
+/**
+ * Create a new Vectorize metadata index
+ */
+export async function createMetadataIndex(
+  api: CloudflareApi,
+  indexName: string,
+  props: VectorizeMetadataIndexProps
+): Promise<CloudflareMetadataIndexResponse> {
+  // Create new metadata index
+  const createPayload = {
+    propertyName: props.propertyName,
+    indexType: props.indexType,
+  };
+
+  const createResponse = await api.post(
+    `/accounts/${api.accountId}/vectorize/v2/indexes/${indexName}/metadata_index/create`,
+    createPayload
+  );
+
+  if (!createResponse.ok) {
+    return await handleApiError(
+      createResponse,
+      "creating",
+      "Vectorize metadata index",
+      props.propertyName
+    );
+  }
+
+  return (await createResponse.json()) as CloudflareMetadataIndexResponse;
+}
+
+/**
+ * Delete a Vectorize metadata index
+ */
+export async function deleteMetadataIndex(
+  api: CloudflareApi,
+  indexName: string,
+  propertyName: string
+): Promise<void> {
+  const deleteResponse = await api.post(
+    `/accounts/${api.accountId}/vectorize/v2/indexes/${indexName}/metadata_index/delete`,
+    {
+      propertyName,
+    }
+  );
+
+  if (!deleteResponse.ok) {
+    await handleApiError(
+      deleteResponse,
+      "deleting",
+      "Vectorize metadata index",
+      propertyName
+    );
+  }
+}
+
+/**
+ * List all metadata indexes for a Vectorize index
+ */
+export async function listMetadataIndexes(
+  api: CloudflareApi,
+  indexName: string
+): Promise<
+  { propertyName: string; indexType: "string" | "number" | "boolean" }[]
+> {
+  const response = await api.get(
+    `/accounts/${api.accountId}/vectorize/v2/indexes/${indexName}/metadata_index/list`
+  );
+
+  if (response.status === 410) {
+    // Gone
+    return [];
+  }
+
+  if (!response.ok) {
+    throw new CloudflareApiError(
+      `Failed to list metadata indexes: ${response.statusText}`,
+      response
+    );
+  }
+
+  const data = (await response.json()) as CloudflareMetadataIndexListResponse;
+
+  if (!data.success) {
+    const errorMessage = data.errors?.[0]?.message || "Unknown error";
+    throw new Error(`Failed to list metadata indexes: ${errorMessage}`);
+  }
+
+  return data.result.metadataIndexes;
+}

package/src/cloudflare/worker.ts

@@ -611,6 +611,12 @@ async function prepareWorkerMetadata<B extends Bindings>(
         name: bindingName,
         pipeline: binding.name,
       });
+    } else if (binding.type === "vectorize") {
+      meta.bindings.push({
+        type: "vectorize",
+        name: bindingName,
+        index_name: binding.name,
+      });
     } else {
       // @ts-expect-error - we should never reach here
       throw new Error(`Unsupported binding type: ${binding.type}`);

package/src/cloudflare/wrangler.json.ts

@@ -187,6 +187,14 @@ export interface WranglerJsonSpec {
     class_name: string;
   }[];
 
+  /**
+   * Vectorize index bindings
+   */
+  vectorize_indexes?: {
+    binding: string;
+    index_name: string;
+  }[];
+
   /**
    * Plain text bindings (vars)
    */
@@ -239,6 +247,7 @@ function processBindings(spec: WranglerJsonSpec, bindings: Bindings): void {
     database_name: string;
   }[] = [];
   const queues: { binding: string; queue: string }[] = [];
+  const vectorizeIndexes: { binding: string; index_name: string }[] = [];
 
   // Process each binding
   for (const [bindingName, binding] of Object.entries(bindings)) {
@@ -302,6 +311,11 @@ function processBindings(spec: WranglerJsonSpec, bindings: Bindings): void {
         binding: bindingName,
         queue: binding.name,
       });
+    } else if (binding.type === "vectorize") {
+      vectorizeIndexes.push({
+        binding: bindingName,
+        index_name: binding.name,
+      });
     }
   }
 
@@ -327,4 +341,8 @@ function processBindings(spec: WranglerJsonSpec, bindings: Bindings): void {
   if (queues.length > 0) {
     spec.queues = queues;
   }
+
+  if (vectorizeIndexes.length > 0) {
+    spec.vectorize_indexes = vectorizeIndexes;
+  }
 }