feat: update AI Search type definitions for V5 namespace binding spec

Aligns ai-search.d.ts with the V5 binding spec (path-based namespaces).

Key changes:
- Rename AiSearchAccountService -> AiSearchNamespace (namespace-scoped, not account-scoped)
- Rename AiSearchInstanceService -> AiSearchInstance
- Add delete(name) to AiSearchNamespace (namespace-level deletion)
- Remove delete() from AiSearchInstance (moved to namespace level)
- Add update(), stats(), items, jobs to AiSearchInstance
- Add sub-service types: AiSearchItems, AiSearchItem, AiSearchJobs, AiSearchJob
- Add item/job metadata types and request/response types
- Remove AiSearchNameNotSetError (V4 concept, namespace always present in V5)
- Update Ai.aiSearch() return type and JSDoc
- Update AutoRAG @see references

Author: G4brym

types/defines/ai-search.d.ts

@@ -1,9 +1,10 @@
-// AI Search V2 API Error Interfaces
+// ============ AI Search Error Interfaces ============
+
 export interface AiSearchInternalError extends Error {}
 export interface AiSearchNotFoundError extends Error {}
-export interface AiSearchNameNotSetError extends Error {}
 
-// AI Search V2 Request Types
+// ============ AI Search Request Types ============
+
 export type AiSearchSearchRequest = {
   messages: Array<{
     role: 'system' | 'developer' | 'user' | 'assistant' | 'tool';
@@ -28,7 +29,6 @@ export type AiSearchSearchRequest = {
       [key: string]: unknown;
     };
     reranking?: {
-      /** Enable reranking (default false) */
       enabled?: boolean;
       model?: '@cf/baai/bge-reranker-base' | '';
       /** Match threshold (0-1, default 0.4) */
@@ -72,7 +72,8 @@ export type AiSearchChatCompletionsRequest = {
   [key: string]: unknown;
 };
 
-// AI Search V2 Response Types
+// ============ AI Search Response Types ============
+
 export type AiSearchSearchResponse = {
   search_query: string;
   chunks: Array<{
@@ -107,6 +108,8 @@ export type AiSearchListResponse = Array<{
   [key: string]: unknown;
 }>;
 
+// ============ AI Search Config Types ============
+
 export type AiSearchConfig = {
   /** Instance ID (1-32 chars, pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$) */
   id: string;
@@ -124,57 +127,285 @@ export type AiSearchConfig = {
   ai_search_model?: string;
 };
 
-export type AiSearchInstance = {
+// ============ AI Search Item Types ============
+
+export type AiSearchItemInfo = {
   id: string;
-  enable?: boolean;
-  type?: 'r2' | 'web-crawler';
-  source?: string;
+  key: string;
+  status: 'completed' | 'error' | 'skipped' | 'queued' | 'processing';
+  metadata?: Record<string, unknown>;
   [key: string]: unknown;
 };
 
-// AI Search Instance Service - Instance-level operations
-export declare abstract class AiSearchInstanceService {
+export type AiSearchItemContentResult = {
+  body: ReadableStream;
+  contentType: string;
+  filename: string;
+  size: number;
+};
+
+export type AiSearchUploadItemOptions = {
+  metadata?: Record<string, unknown>;
+};
+
+export type AiSearchListItemsParams = {
+  page?: number;
+  per_page?: number;
+};
+
+export type AiSearchListItemsResponse = {
+  result: AiSearchItemInfo[];
+  result_info?: {
+    count: number;
+    page: number;
+    per_page: number;
+    total_count: number;
+  };
+};
+
+// ============ AI Search Job Types ============
+
+export type AiSearchJobInfo = {
+  id: string;
+  status: 'completed' | 'error' | 'queued' | 'processing';
+  [key: string]: unknown;
+};
+
+export type AiSearchListJobsParams = {
+  page?: number;
+  per_page?: number;
+};
+
+export type AiSearchListJobsResponse = {
+  result: AiSearchJobInfo[];
+  result_info?: {
+    count: number;
+    page: number;
+    per_page: number;
+    total_count: number;
+  };
+};
+
+export type AiSearchJobLogsParams = {
+  page?: number;
+  per_page?: number;
+};
+
+// ============ AI Search Sub-Service Classes ============
+
+/**
+ * Single item service for an AI Search instance.
+ * Provides info, delete, and download operations on a specific item.
+ */
+export declare abstract class AiSearchItem {
+  /** Get metadata about this item. */
+  info(): Promise<AiSearchItemInfo>;
+
+  /** Delete this item from the instance. */
+  delete(): Promise<void>;
+
+  /**
+   * Download the item's content.
+   * @returns Object with body stream, content type, filename, and size.
+   */
+  download(): Promise<AiSearchItemContentResult>;
+}
+
+/**
+ * Items collection service for an AI Search instance.
+ * Provides list, upload, and access to individual items.
+ */
+export declare abstract class AiSearchItems {
+  /** List items in this instance. */
+  list(params?: AiSearchListItemsParams): Promise<AiSearchListItemsResponse>;
+
+  /**
+   * Upload a file as an item.
+   * @param name Filename for the uploaded item.
+   * @param content File content as a ReadableStream, ArrayBuffer, or string.
+   * @param options Optional metadata to attach to the item.
+   * @returns The created item info.
+   */
+  upload(
+    name: string,
+    content: ReadableStream | ArrayBuffer | string,
+    options?: AiSearchUploadItemOptions
+  ): Promise<AiSearchItemInfo>;
+
+  /**
+   * Upload a file and poll until processing completes.
+   * @param name Filename for the uploaded item.
+   * @param content File content as a ReadableStream, ArrayBuffer, or string.
+   * @param options Optional metadata and polling configuration.
+   * @returns The item info after processing completes (or timeout).
+   */
+  uploadAndPoll(
+    name: string,
+    content: ReadableStream | ArrayBuffer | string,
+    options?: AiSearchUploadItemOptions & {
+      pollIntervalMs?: number;
+      timeoutMs?: number;
+    }
+  ): Promise<AiSearchItemInfo>;
+
+  /**
+   * Get an item by ID.
+   * @param itemId The item identifier.
+   * @returns Item service for info, delete, and download operations.
+   */
+  get(itemId: string): AiSearchItem;
+}
+
+/**
+ * Single job service for an AI Search instance.
+ * Provides info and logs for a specific job.
+ */
+export declare abstract class AiSearchJob {
+  /** Get metadata about this job. */
+  info(): Promise<AiSearchJobInfo>;
+
+  /** Get logs for this job. */
+  logs(params?: AiSearchJobLogsParams): Promise<object>;
+}
+
+/**
+ * Jobs collection service for an AI Search instance.
+ * Provides list, create, and access to individual jobs.
+ */
+export declare abstract class AiSearchJobs {
+  /** List jobs for this instance. */
+  list(params?: AiSearchListJobsParams): Promise<AiSearchListJobsResponse>;
+
+  /**
+   * Create a new indexing job.
+   * @param params Optional job parameters.
+   * @returns The created job info.
+   */
+  create(params?: Record<string, unknown>): Promise<AiSearchJobInfo>;
+
+  /**
+   * Get a job by ID.
+   * @param jobId The job identifier.
+   * @returns Job service for info and logs operations.
+   */
+  get(jobId: string): AiSearchJob;
+}
+
+// ============ AI Search Binding Classes ============
+
+/**
+ * Instance-level AI Search service.
+ *
+ * Used as:
+ * - The return type of `AiSearchNamespace.get(name)` (namespace binding)
+ * - The type of `env.BLOG_SEARCH` (single instance binding via `ai_search`)
+ *
+ * Provides search, chat, update, stats, items, and jobs operations.
+ * No delete() — deletion is done via `AiSearchNamespace.delete(name)`.
+ *
+ * @example
+ * ```ts
+ * // Via namespace binding
+ * const instance = env.AI_SEARCH.get("blog");
+ * const results = await instance.search({
+ *   messages: [{ role: "user", content: "How does caching work?" }],
+ * });
+ *
+ * // Via single instance binding
+ * const results = await env.BLOG_SEARCH.search({
+ *   messages: [{ role: "user", content: "How does caching work?" }],
+ * });
+ * ```
+ */
+export declare abstract class AiSearchInstance {
   /**
    * Search the AI Search instance for relevant chunks.
-   * @param params Search request with messages and AI search options
-   * @returns Search response with matching chunks
+   * @param params Search request with messages and optional AI search options.
+   * @returns Search response with matching chunks and search query.
    */
   search(params: AiSearchSearchRequest): Promise<AiSearchSearchResponse>;
 
   /**
    * Generate chat completions with AI Search context.
-   * @param params Chat completions request with optional streaming
-   * @returns Response object (if streaming) or chat completion result
+   * @param params Chat completions request with optional streaming.
+   * @returns ReadableStream if streaming, otherwise a chat completion object.
    */
   chatCompletions(
     params: AiSearchChatCompletionsRequest
-  ): Promise<Response | object>;
+  ): Promise<ReadableStream | object>;
 
   /**
-   * Delete this AI Search instance.
+   * Update the instance configuration.
+   * @param config Partial configuration to update.
+   * @returns Updated instance data.
    */
-  delete(): Promise<void>;
+  update(config: Partial<AiSearchConfig>): Promise<object>;
+
+  /**
+   * Get instance statistics (item count, indexing status, etc.).
+   * @returns Statistics object.
+   */
+  stats(): Promise<object>;
+
+  /** Items collection — list, upload, and manage items in this instance. */
+  get items(): AiSearchItems;
+
+  /** Jobs collection — list, create, and inspect indexing jobs. */
+  get jobs(): AiSearchJobs;
 }
 
-// AI Search Account Service - Account-level operations
-export declare abstract class AiSearchAccountService {
+/**
+ * Namespace-level AI Search service.
+ *
+ * Used as the type of `env.AI_SEARCH` (namespace binding via `ai_search_namespaces`).
+ * Scoped to a single namespace. Provides dynamic instance access, creation, and deletion.
+ *
+ * @example
+ * ```ts
+ * // Access an instance within the namespace
+ * const blog = env.AI_SEARCH.get("blog");
+ * const results = await blog.search({
+ *   messages: [{ role: "user", content: "How does caching work?" }],
+ * });
+ *
+ * // List all instances in the namespace
+ * const instances = await env.AI_SEARCH.list();
+ *
+ * // Create a new instance
+ * const tenant = await env.AI_SEARCH.create({
+ *   id: "tenant-123",
+ *   type: "web-crawler",
+ *   source: "https://example.com",
+ * });
+ *
+ * // Delete an instance
+ * await env.AI_SEARCH.delete("tenant-123");
+ * ```
+ */
+export declare abstract class AiSearchNamespace {
+  /**
+   * Get an instance by name within the bound namespace.
+   * @param name Instance name.
+   * @returns Instance service for search, chat, update, stats, items, and jobs.
+   */
+  get(name: string): AiSearchInstance;
+
   /**
-   * List all AI Search instances in the account.
-   * @returns Array of AI Search instances
+   * List all instances in the bound namespace.
+   * @returns Array of instance metadata.
    */
   list(): Promise<AiSearchListResponse>;
 
   /**
-   * Get an AI Search instance by ID.
-   * @param name Instance ID
-   * @returns Instance service for performing operations
+   * Create a new instance within the bound namespace.
+   * @param config Instance configuration including id, type, and source.
+   * @returns Instance service for the newly created instance.
    */
-  get(name: string): AiSearchInstanceService;
+  create(config: AiSearchConfig): Promise<AiSearchInstance>;
 
   /**
-   * Create a new AI Search instance.
-   * @param config Instance configuration
-   * @returns Instance service for performing operations
+   * Delete an instance from the bound namespace.
+   * @param name Instance name to delete.
    */
-  create(config: AiSearchConfig): Promise<AiSearchInstanceService>;
+  delete(name: string): Promise<void>;
 }