ragpack-js 1.0.0 → 1.1.0

package/README.md

@@ -41,7 +41,7 @@ console.log(answer);
 // Semantic search (without LLM)
 const results = await collection.findSimilar({ query: "how does auth work?", topK: 5 });
 for (const r of results) {
-  console.log(r.similarity, r.chunk_text);
+  console.log(r.vector_similarity, r.chunk_text);
 }
 ```
 
@@ -72,12 +72,15 @@ Returns a `CollectionClient` scoped to that collection.
 | `ingest(file, filename?)`           | Upload a file directly                   |
 | `ingest({ uri, mimeType? })`        | Ingest from a URL or S3 URI, MIME type auto-detected if omitted |
 | `rag(options)`                      | Full RAG pipeline — retrieves chunks and returns an LLM answer |
-| `findSimilar({ query, topK? })`     | Semantic search without LLM, returns ranked chunks |
+| `findSimilar(options)`              | Hybrid (vector + keyword) search without LLM, returns ranked chunks |
 | `jobs.list()`                       | List ingestion jobs for this collection  |
 | `jobs.get(id)`                      | Get a single job by ID                   |
 | `jobs.waitUntilComplete(id)`        | Poll until job is `complete` or `failed` |
 | `documents.list(options?)`          | List indexed documents                   |
+| `documents.get(id)`                 | Get a single document by ID              |
+| `documents.metadata(id)`            | Get a document's typed metadata field values |
 | `documents.rename(id, name)`        | Set the display name of a document       |
+| `documents.update(id, options)`     | Update a document's name, `extraJson`, and/or typed metadata |
 | `documents.delete(id)`              | Delete a document and its chunks         |
 
 #### `rag(options)`
@@ -89,18 +92,54 @@ const { answer, chunks } = await collection.rag({
   query: "How do I reset my password?",
   // All options below are optional
   promptSlug: "basic_rag",   // defaults to "basic_rag" if omitted
-  topK: 5,                   // number of chunks to retrieve (default: 5)
+  topK: 2,                   // number of chunks to retrieve (default: 2)
   model: "gpt-4o",           // LLM model; falls back to server default
   minSimilarity: 70,         // drop chunks below this similarity score (0–100)
+  filters: { mime_type: "application/pdf" },
 });
 
 console.log(answer);
 
 for (const chunk of chunks) {
-  console.log(chunk.similarity, chunk.chunk_text);
+  console.log(chunk.vector_similarity, chunk.chunk_text);
 }
 ```
 
+#### Hybrid (vector + keyword) search
+
+`findSimilar` and `rag` run hybrid search by default: a vector pass and a keyword/BM25 pass are fused server-side via weighted RRF (semantic-favored 7:3). Each result carries `vector_similarity`, `keyword_bm25_score`, `rrf_score`, and `rrf_score_normalized` (0–100, normalized so the batch's top result is always 100).
+
+```ts
+const results = await collection.findSimilar({
+  query: "password reset",
+  vectorSearchOnly: false,          // set true to skip the keyword pass entirely
+  hybridSettings: {
+    semanticWeight: 0.7,
+    fullTextWeight: 0.3,
+    rrfK: 60,
+    fullTextLimit: 200,
+  },
+});
+```
+
+#### Filtering by metadata
+
+Both `findSimilar` and `rag` accept a `filters` option — a MongoDB-style expression compiled server-side into a predicate over a document's built-in (`mime_type`, `source_name`, `file_uri`, `created_at`, `updated_at`, …) and registered metadata fields.
+
+```ts
+await collection.findSimilar({
+  query: "refund policy",
+  filters: {
+    $and: [
+      { mime_type: "application/pdf" },
+      { $or: [{ tags: { $contains: "billing" } }, { created_at: { $gte: "7 days ago" } }] },
+    ],
+  },
+});
+```
+
+Supported operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$exists`, `$like`/`$ilike` (string fields), `$contains`/`$containsAny`/`$containsAll` (array fields), plus `$and`/`$or` for nesting.
+
 #### Prompt templates
 
 Three built-in prompts are always available: `basic_rag`, `rag_with_citations`, and `concise_rag`. List all available prompts (including any you've created in the admin UI) with:

package/dist/index.cjs

@@ -118,6 +118,25 @@ var DocumentsResource = class {
     );
     return r.documents;
   }
+  /**
+   * Get a single document by ID.
+   * @param id - The document ID.
+   */
+  get(id) {
+    return this.req(`/collections/${this.slug}/documents/${id}`);
+  }
+  /**
+   * Get this document's typed metadata field values.
+   * A field is only included if its value is identical across every chunk
+   * of the document — this avoids showing a value that's mid-sync.
+   * @param id - The document ID.
+   */
+  async metadata(id) {
+    const r = await this.req(
+      `/collections/${this.slug}/documents/${id}/metadata`
+    );
+    return r.metadata;
+  }
   /**
    * Rename a document.
    * @param id - The document ID.
@@ -129,6 +148,32 @@ var DocumentsResource = class {
       body: JSON.stringify({ name })
     });
   }
+  /**
+   * Update a document's name, extra_json, and/or typed metadata.
+   * `metadata` keys that aren't registered fields on this collection (or whose
+   * value doesn't match the field's declared type) are silently dropped by
+   * the server — the request still succeeds, with no signal for which keys
+   * landed. Register fields first via the metadata-fields admin API.
+   * @param id - The document ID.
+   *
+   * @example
+   * ```ts
+   * await collection.documents.update(id, {
+   *   metadata: { reviewed: true },
+   *   extraJson: JSON.stringify({ source: "zendesk" }),
+   * });
+   * ```
+   */
+  update(id, options) {
+    return this.req(`/collections/${this.slug}/documents/${id}`, {
+      method: "PATCH",
+      body: JSON.stringify({
+        ...options.name !== void 0 && { name: options.name },
+        ...options.extraJson !== void 0 && { extra_json: options.extraJson },
+        ...options.metadata !== void 0 && { metadata: options.metadata }
+      })
+    });
+  }
   /**
    * Delete a document and all its chunks from this collection.
    * @param id - The document ID.
@@ -140,6 +185,29 @@ var DocumentsResource = class {
   }
 };
 
+// src/hybrid.ts
+function buildHybridBody(options) {
+  const { filters, vectorSearchOnly, hybridSettings } = options;
+  return {
+    ...filters !== void 0 && { filters },
+    ...vectorSearchOnly !== void 0 && { vector_search_only: vectorSearchOnly },
+    ...hybridSettings !== void 0 && {
+      hybrid_settings: {
+        ...hybridSettings.fullTextWeight !== void 0 && {
+          full_text_weight: hybridSettings.fullTextWeight
+        },
+        ...hybridSettings.semanticWeight !== void 0 && {
+          semantic_weight: hybridSettings.semanticWeight
+        },
+        ...hybridSettings.rrfK !== void 0 && { rrf_k: hybridSettings.rrfK },
+        ...hybridSettings.fullTextLimit !== void 0 && {
+          full_text_limit: hybridSettings.fullTextLimit
+        }
+      }
+    }
+  };
+}
+
 // src/resources/query.ts
 var QueryResource = class {
   constructor(req, slug) {
@@ -155,7 +223,11 @@ var QueryResource = class {
       `/collections/${this.slug}/query`,
       {
         method: "POST",
-        body: JSON.stringify({ query: options.query, top_k: options.topK ?? 5 })
+        body: JSON.stringify({
+          query: options.query,
+          top_k: options.topK ?? 5,
+          ...buildHybridBody(options)
+        })
       }
     );
     return r.results;
@@ -215,7 +287,8 @@ var CollectionClient = class {
         top_k: options.topK ?? 5,
         ...options.promptSlug ? { prompt_slug: options.promptSlug } : {},
         ...options.model ? { model: options.model } : {},
-        ...options.minSimilarity != null ? { min_similarity: options.minSimilarity } : {}
+        ...options.minSimilarity != null ? { min_similarity: options.minSimilarity } : {},
+        ...buildHybridBody(options)
       })
     });
   }

package/dist/index.d.cts

@@ -74,7 +74,14 @@ interface RagChunk {
     chunk_index: number;
     chunk_header: string | null;
     chunk_text: string | null;
-    similarity: number;
+    /** Cosine similarity score between 0 and 100. Higher is more relevant. */
+    vector_similarity: number;
+    /** Raw BM25 score from the keyword channel; present only for hybrid results. */
+    keyword_bm25_score?: number;
+    /** Weighted RRF fusion score, normalized so this batch's top result is 100. */
+    rrf_score_normalized?: number;
+    /** Raw RRF fusion score; only comparable within this query's own weights/k. */
+    rrf_score?: number;
 }
 interface RagResult {
     formatted_prompt: string;
@@ -87,13 +94,73 @@ interface QueryResult {
     file_uri: string;
     mime_type: string;
     chunk_index: number;
+    chunk_header: string | null;
     /** The matched text chunk. */
     chunk_text: string | null;
     /** Optional metadata attached at ingest time. */
     extra_json: string | null;
-    distance: number;
-    /** Cosine similarity score between 0 and 1. Higher is more relevant. */
-    similarity: number;
+    /** Typed metadata field values registered for this collection. */
+    metadata?: Record<string, unknown>;
+    vector_distance: number;
+    /** Cosine similarity score between 0 and 100. Higher is more relevant. */
+    vector_similarity: number;
+    /** Raw BM25 score from the keyword channel; present only for hybrid results. */
+    keyword_bm25_score?: number;
+    /** Weighted RRF fusion score, normalized so this batch's top result is 100. */
+    rrf_score_normalized?: number;
+    /** Raw RRF fusion score; only comparable within this query's own weights/k. */
+    rrf_score?: number;
+}
+type FilterValue = string | number | boolean;
+/** Operators usable against a single field in a {@link FilterExpression}. */
+interface FilterOps {
+    $eq?: FilterValue;
+    $ne?: FilterValue;
+    $gt?: FilterValue;
+    $gte?: FilterValue;
+    $lt?: FilterValue;
+    $lte?: FilterValue;
+    $in?: FilterValue[];
+    $nin?: FilterValue[];
+    $exists?: boolean;
+    /** str/timestamp fields only. */
+    $like?: string;
+    /** str fields only. */
+    $ilike?: string;
+    /** arr fields only. */
+    $contains?: string;
+    /** arr fields only. */
+    $containsAny?: string[];
+    /** arr fields only. */
+    $containsAll?: string[];
+}
+/**
+ * MongoDB-style filter expression, compiled server-side into a predicate over
+ * a document's built-in and registered metadata fields.
+ *
+ * @example
+ * ```ts
+ * { mime_type: "application/pdf", score: { $gte: 4 } }
+ * { $or: [{ tags: { $contains: "urgent" } }, { created_at: { $gte: "7 days ago" } }] }
+ * ```
+ */
+type FilterExpression = {
+    $and: FilterExpression[];
+} | {
+    $or: FilterExpression[];
+} | {
+    [field: string]: FilterValue | FilterOps;
+};
+/**
+ * Per-request override of the weighted RRF merge between vector and keyword
+ * search. Unset fields fall back to server defaults (semantic-favored 7:3).
+ */
+interface HybridSettings {
+    fullTextWeight?: number;
+    semanticWeight?: number;
+    rrfK?: number;
+    /** Caps FTS candidates considered before fusion; FTS search has no native limit. */
+    fullTextLimit?: number;
 }
 
 type Requester = <T>(path: string, init?: RequestInit) => Promise<T>;
@@ -133,6 +200,14 @@ declare class JobsResource {
     waitUntilComplete(id: string, options?: WaitOptions): Promise<Job>;
 }
 
+interface UpdateDocumentOptions {
+    /** New display name. */
+    name?: string;
+    /** Replaces the document's freeform extra_json metadata. */
+    extraJson?: string;
+    /** Merges values into the document's typed metadata fields. */
+    metadata?: Record<string, unknown>;
+}
 declare class DocumentsResource {
     private readonly req;
     private readonly slug?;
@@ -146,12 +221,41 @@ declare class DocumentsResource {
         limit?: number;
         offset?: number;
     }): Promise<Document[]>;
+    /**
+     * Get a single document by ID.
+     * @param id - The document ID.
+     */
+    get(id: string): Promise<Document>;
+    /**
+     * Get this document's typed metadata field values.
+     * A field is only included if its value is identical across every chunk
+     * of the document — this avoids showing a value that's mid-sync.
+     * @param id - The document ID.
+     */
+    metadata(id: string): Promise<Record<string, unknown>>;
     /**
      * Rename a document.
      * @param id - The document ID.
      * @param name - The new display name.
      */
     rename(id: string, name: string): Promise<Document>;
+    /**
+     * Update a document's name, extra_json, and/or typed metadata.
+     * `metadata` keys that aren't registered fields on this collection (or whose
+     * value doesn't match the field's declared type) are silently dropped by
+     * the server — the request still succeeds, with no signal for which keys
+     * landed. Register fields first via the metadata-fields admin API.
+     * @param id - The document ID.
+     *
+     * @example
+     * ```ts
+     * await collection.documents.update(id, {
+     *   metadata: { reviewed: true },
+     *   extraJson: JSON.stringify({ source: "zendesk" }),
+     * });
+     * ```
+     */
+    update(id: string, options: UpdateDocumentOptions): Promise<Document>;
     /**
      * Delete a document and all its chunks from this collection.
      * @param id - The document ID.
@@ -159,23 +263,36 @@ declare class DocumentsResource {
     delete(id: string): Promise<void>;
 }
 
+interface FindSimilarOptions {
+    /** The search query text. */
+    query: string;
+    /** Number of results to return. Defaults to 5. */
+    topK?: number;
+    /** Restrict results to chunks whose document matches this filter expression. */
+    filters?: FilterExpression;
+    /** Skip the keyword/BM25 pass and use pure vector search. Hybrid search runs by default. */
+    vectorSearchOnly?: boolean;
+    /** Per-request override of the weighted RRF merge between vector and keyword search. */
+    hybridSettings?: HybridSettings;
+}
+
 interface RagOptions {
     /** Slug of the prompt template to use. Defaults to `"basic_rag"` if omitted. */
     promptSlug?: string;
     /** The user's question. Substituted into `{{question}}`. */
     query: string;
-    /** Number of chunks to retrieve. Defaults to 5. */
+    /** Number of chunks to retrieve. Defaults to 2, since RAG chunks feed an LLM prompt. */
     topK?: number;
     /** LLM model name to use (e.g. `"gpt-4o"`, `"claude-opus-4-8"`). Falls back to server default. */
     model?: string;
     /** Minimum similarity score (0–100) a chunk must meet to be included in context. Omit to include all top_k results. */
     minSimilarity?: number;
-}
-interface FindSimilarOptions {
-    /** The search query text. */
-    query: string;
-    /** Number of results to return. Defaults to 5. */
-    topK?: number;
+    /** Restrict retrieval to chunks whose document matches this filter expression. */
+    filters?: FilterExpression;
+    /** Skip the keyword/BM25 pass and use pure vector search. Hybrid search runs by default. */
+    vectorSearchOnly?: boolean;
+    /** Per-request override of the weighted RRF merge between vector and keyword search. */
+    hybridSettings?: HybridSettings;
 }
 interface IngestUriOptions {
     /** Remote file URI (e.g. `s3://bucket/file.pdf`). */
@@ -355,4 +472,4 @@ declare class RagPack {
     collection(slug: string): CollectionClient;
 }
 
-export { type Collection, type Document, type EmbedderInfo, type FindSimilarOptions, type IngestUriOptions, type Job, type LLMInfo, type Prompt, type QueryResult, type RagChunk, type RagOptions, RagPack, type RagPackConfig, RagPackError, type RagResult };
+export { type Collection, type Document, type EmbedderInfo, type FilterExpression, type FilterOps, type FilterValue, type FindSimilarOptions, type HybridSettings, type IngestUriOptions, type Job, type LLMInfo, type Prompt, type QueryResult, type RagChunk, type RagOptions, RagPack, type RagPackConfig, RagPackError, type RagResult, type UpdateDocumentOptions };

package/dist/index.d.ts

@@ -74,7 +74,14 @@ interface RagChunk {
     chunk_index: number;
     chunk_header: string | null;
     chunk_text: string | null;
-    similarity: number;
+    /** Cosine similarity score between 0 and 100. Higher is more relevant. */
+    vector_similarity: number;
+    /** Raw BM25 score from the keyword channel; present only for hybrid results. */
+    keyword_bm25_score?: number;
+    /** Weighted RRF fusion score, normalized so this batch's top result is 100. */
+    rrf_score_normalized?: number;
+    /** Raw RRF fusion score; only comparable within this query's own weights/k. */
+    rrf_score?: number;
 }
 interface RagResult {
     formatted_prompt: string;
@@ -87,13 +94,73 @@ interface QueryResult {
     file_uri: string;
     mime_type: string;
     chunk_index: number;
+    chunk_header: string | null;
     /** The matched text chunk. */
     chunk_text: string | null;
     /** Optional metadata attached at ingest time. */
     extra_json: string | null;
-    distance: number;
-    /** Cosine similarity score between 0 and 1. Higher is more relevant. */
-    similarity: number;
+    /** Typed metadata field values registered for this collection. */
+    metadata?: Record<string, unknown>;
+    vector_distance: number;
+    /** Cosine similarity score between 0 and 100. Higher is more relevant. */
+    vector_similarity: number;
+    /** Raw BM25 score from the keyword channel; present only for hybrid results. */
+    keyword_bm25_score?: number;
+    /** Weighted RRF fusion score, normalized so this batch's top result is 100. */
+    rrf_score_normalized?: number;
+    /** Raw RRF fusion score; only comparable within this query's own weights/k. */
+    rrf_score?: number;
+}
+type FilterValue = string | number | boolean;
+/** Operators usable against a single field in a {@link FilterExpression}. */
+interface FilterOps {
+    $eq?: FilterValue;
+    $ne?: FilterValue;
+    $gt?: FilterValue;
+    $gte?: FilterValue;
+    $lt?: FilterValue;
+    $lte?: FilterValue;
+    $in?: FilterValue[];
+    $nin?: FilterValue[];
+    $exists?: boolean;
+    /** str/timestamp fields only. */
+    $like?: string;
+    /** str fields only. */
+    $ilike?: string;
+    /** arr fields only. */
+    $contains?: string;
+    /** arr fields only. */
+    $containsAny?: string[];
+    /** arr fields only. */
+    $containsAll?: string[];
+}
+/**
+ * MongoDB-style filter expression, compiled server-side into a predicate over
+ * a document's built-in and registered metadata fields.
+ *
+ * @example
+ * ```ts
+ * { mime_type: "application/pdf", score: { $gte: 4 } }
+ * { $or: [{ tags: { $contains: "urgent" } }, { created_at: { $gte: "7 days ago" } }] }
+ * ```
+ */
+type FilterExpression = {
+    $and: FilterExpression[];
+} | {
+    $or: FilterExpression[];
+} | {
+    [field: string]: FilterValue | FilterOps;
+};
+/**
+ * Per-request override of the weighted RRF merge between vector and keyword
+ * search. Unset fields fall back to server defaults (semantic-favored 7:3).
+ */
+interface HybridSettings {
+    fullTextWeight?: number;
+    semanticWeight?: number;
+    rrfK?: number;
+    /** Caps FTS candidates considered before fusion; FTS search has no native limit. */
+    fullTextLimit?: number;
 }
 
 type Requester = <T>(path: string, init?: RequestInit) => Promise<T>;
@@ -133,6 +200,14 @@ declare class JobsResource {
     waitUntilComplete(id: string, options?: WaitOptions): Promise<Job>;
 }
 
+interface UpdateDocumentOptions {
+    /** New display name. */
+    name?: string;
+    /** Replaces the document's freeform extra_json metadata. */
+    extraJson?: string;
+    /** Merges values into the document's typed metadata fields. */
+    metadata?: Record<string, unknown>;
+}
 declare class DocumentsResource {
     private readonly req;
     private readonly slug?;
@@ -146,12 +221,41 @@ declare class DocumentsResource {
         limit?: number;
         offset?: number;
     }): Promise<Document[]>;
+    /**
+     * Get a single document by ID.
+     * @param id - The document ID.
+     */
+    get(id: string): Promise<Document>;
+    /**
+     * Get this document's typed metadata field values.
+     * A field is only included if its value is identical across every chunk
+     * of the document — this avoids showing a value that's mid-sync.
+     * @param id - The document ID.
+     */
+    metadata(id: string): Promise<Record<string, unknown>>;
     /**
      * Rename a document.
      * @param id - The document ID.
      * @param name - The new display name.
      */
     rename(id: string, name: string): Promise<Document>;
+    /**
+     * Update a document's name, extra_json, and/or typed metadata.
+     * `metadata` keys that aren't registered fields on this collection (or whose
+     * value doesn't match the field's declared type) are silently dropped by
+     * the server — the request still succeeds, with no signal for which keys
+     * landed. Register fields first via the metadata-fields admin API.
+     * @param id - The document ID.
+     *
+     * @example
+     * ```ts
+     * await collection.documents.update(id, {
+     *   metadata: { reviewed: true },
+     *   extraJson: JSON.stringify({ source: "zendesk" }),
+     * });
+     * ```
+     */
+    update(id: string, options: UpdateDocumentOptions): Promise<Document>;
     /**
      * Delete a document and all its chunks from this collection.
      * @param id - The document ID.
@@ -159,23 +263,36 @@ declare class DocumentsResource {
     delete(id: string): Promise<void>;
 }
 
+interface FindSimilarOptions {
+    /** The search query text. */
+    query: string;
+    /** Number of results to return. Defaults to 5. */
+    topK?: number;
+    /** Restrict results to chunks whose document matches this filter expression. */
+    filters?: FilterExpression;
+    /** Skip the keyword/BM25 pass and use pure vector search. Hybrid search runs by default. */
+    vectorSearchOnly?: boolean;
+    /** Per-request override of the weighted RRF merge between vector and keyword search. */
+    hybridSettings?: HybridSettings;
+}
+
 interface RagOptions {
     /** Slug of the prompt template to use. Defaults to `"basic_rag"` if omitted. */
     promptSlug?: string;
     /** The user's question. Substituted into `{{question}}`. */
     query: string;
-    /** Number of chunks to retrieve. Defaults to 5. */
+    /** Number of chunks to retrieve. Defaults to 2, since RAG chunks feed an LLM prompt. */
     topK?: number;
     /** LLM model name to use (e.g. `"gpt-4o"`, `"claude-opus-4-8"`). Falls back to server default. */
     model?: string;
     /** Minimum similarity score (0–100) a chunk must meet to be included in context. Omit to include all top_k results. */
     minSimilarity?: number;
-}
-interface FindSimilarOptions {
-    /** The search query text. */
-    query: string;
-    /** Number of results to return. Defaults to 5. */
-    topK?: number;
+    /** Restrict retrieval to chunks whose document matches this filter expression. */
+    filters?: FilterExpression;
+    /** Skip the keyword/BM25 pass and use pure vector search. Hybrid search runs by default. */
+    vectorSearchOnly?: boolean;
+    /** Per-request override of the weighted RRF merge between vector and keyword search. */
+    hybridSettings?: HybridSettings;
 }
 interface IngestUriOptions {
     /** Remote file URI (e.g. `s3://bucket/file.pdf`). */
@@ -355,4 +472,4 @@ declare class RagPack {
     collection(slug: string): CollectionClient;
 }
 
-export { type Collection, type Document, type EmbedderInfo, type FindSimilarOptions, type IngestUriOptions, type Job, type LLMInfo, type Prompt, type QueryResult, type RagChunk, type RagOptions, RagPack, type RagPackConfig, RagPackError, type RagResult };
+export { type Collection, type Document, type EmbedderInfo, type FilterExpression, type FilterOps, type FilterValue, type FindSimilarOptions, type HybridSettings, type IngestUriOptions, type Job, type LLMInfo, type Prompt, type QueryResult, type RagChunk, type RagOptions, RagPack, type RagPackConfig, RagPackError, type RagResult, type UpdateDocumentOptions };

package/dist/index.js

@@ -91,6 +91,25 @@ var DocumentsResource = class {
     );
     return r.documents;
   }
+  /**
+   * Get a single document by ID.
+   * @param id - The document ID.
+   */
+  get(id) {
+    return this.req(`/collections/${this.slug}/documents/${id}`);
+  }
+  /**
+   * Get this document's typed metadata field values.
+   * A field is only included if its value is identical across every chunk
+   * of the document — this avoids showing a value that's mid-sync.
+   * @param id - The document ID.
+   */
+  async metadata(id) {
+    const r = await this.req(
+      `/collections/${this.slug}/documents/${id}/metadata`
+    );
+    return r.metadata;
+  }
   /**
    * Rename a document.
    * @param id - The document ID.
@@ -102,6 +121,32 @@ var DocumentsResource = class {
       body: JSON.stringify({ name })
     });
   }
+  /**
+   * Update a document's name, extra_json, and/or typed metadata.
+   * `metadata` keys that aren't registered fields on this collection (or whose
+   * value doesn't match the field's declared type) are silently dropped by
+   * the server — the request still succeeds, with no signal for which keys
+   * landed. Register fields first via the metadata-fields admin API.
+   * @param id - The document ID.
+   *
+   * @example
+   * ```ts
+   * await collection.documents.update(id, {
+   *   metadata: { reviewed: true },
+   *   extraJson: JSON.stringify({ source: "zendesk" }),
+   * });
+   * ```
+   */
+  update(id, options) {
+    return this.req(`/collections/${this.slug}/documents/${id}`, {
+      method: "PATCH",
+      body: JSON.stringify({
+        ...options.name !== void 0 && { name: options.name },
+        ...options.extraJson !== void 0 && { extra_json: options.extraJson },
+        ...options.metadata !== void 0 && { metadata: options.metadata }
+      })
+    });
+  }
   /**
    * Delete a document and all its chunks from this collection.
    * @param id - The document ID.
@@ -113,6 +158,29 @@ var DocumentsResource = class {
   }
 };
 
+// src/hybrid.ts
+function buildHybridBody(options) {
+  const { filters, vectorSearchOnly, hybridSettings } = options;
+  return {
+    ...filters !== void 0 && { filters },
+    ...vectorSearchOnly !== void 0 && { vector_search_only: vectorSearchOnly },
+    ...hybridSettings !== void 0 && {
+      hybrid_settings: {
+        ...hybridSettings.fullTextWeight !== void 0 && {
+          full_text_weight: hybridSettings.fullTextWeight
+        },
+        ...hybridSettings.semanticWeight !== void 0 && {
+          semantic_weight: hybridSettings.semanticWeight
+        },
+        ...hybridSettings.rrfK !== void 0 && { rrf_k: hybridSettings.rrfK },
+        ...hybridSettings.fullTextLimit !== void 0 && {
+          full_text_limit: hybridSettings.fullTextLimit
+        }
+      }
+    }
+  };
+}
+
 // src/resources/query.ts
 var QueryResource = class {
   constructor(req, slug) {
@@ -128,7 +196,11 @@ var QueryResource = class {
       `/collections/${this.slug}/query`,
       {
         method: "POST",
-        body: JSON.stringify({ query: options.query, top_k: options.topK ?? 5 })
+        body: JSON.stringify({
+          query: options.query,
+          top_k: options.topK ?? 5,
+          ...buildHybridBody(options)
+        })
       }
     );
     return r.results;
@@ -188,7 +260,8 @@ var CollectionClient = class {
         top_k: options.topK ?? 5,
         ...options.promptSlug ? { prompt_slug: options.promptSlug } : {},
         ...options.model ? { model: options.model } : {},
-        ...options.minSimilarity != null ? { min_similarity: options.minSimilarity } : {}
+        ...options.minSimilarity != null ? { min_similarity: options.minSimilarity } : {},
+        ...buildHybridBody(options)
       })
     });
   }

package/package.json

@@ -1,15 +1,20 @@
 {
   "name": "ragpack-js",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "TypeScript client for the Ragpack self-hosted RAG engine",
-  "main": "./dist/index.js",
-  "module": "./dist/index.mjs",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     }
   },
   "files": [