endee 1.7.1 → 1.8.0-dev.2

package/dist/collection.js

@@ -0,0 +1,755 @@
+/**
+ * Collection client for Endee-DB (v2 Collections API).
+ *
+ * A collection holds objects, each carrying values for one or more named, typed
+ * fields (dense `vector`, `sparse`, or `multi_vector`). Obtain a Collection via
+ * `Endee.getCollection()` (or after `Endee.createCollection()`).
+ */
+import axios from 'axios';
+import { encode, decode } from '@msgpack/msgpack';
+import { jsonZip, jsonUnzip } from './crypto.js';
+import { raiseException } from './exceptions.js';
+import { DEFAULT_EF_SEARCH, DEFAULT_FILTER_BOOST_PERCENTAGE, DEFAULT_PREFILTER_THRESHOLD, DEFAULT_TOP_K, MAX_EF_SEARCH_ALLOWED, MAX_FILTER_BOOST_PERCENTAGE, MAX_KEY_BYTES, MAX_PREFILTER_THRESHOLD, MAX_TOP_K_ALLOWED, MAX_VALUE_BYTES, MAX_VECTORS_PER_BATCH, MIN_PREFILTER_THRESHOLD, NORM_EPSILON, } from './constants.js';
+/**
+ * Reserved meta key. For cosine fields the client sends unit vectors (the server
+ * stores no norms), so we stash each vector's norm here at upsert time;
+ * `getObjects` multiplies the unit vector by it to reconstruct the original
+ * vector. The key is stripped from the meta the user gets back.
+ */
+const NORMS_KEY = 'internal_';
+// ── result decode helpers ─────────────────────────────────────────────────────
+/** Best-effort decode of a result's meta (zlib+JSON bytes, plain JSON, or object). */
+function decodeMeta(m) {
+    if (m === null || m === undefined || m === '')
+        return {};
+    if (m instanceof Uint8Array || Buffer.isBuffer(m)) {
+        if (m.length === 0)
+            return {};
+        const buf = Buffer.isBuffer(m) ? m : Buffer.from(m);
+        try {
+            return jsonUnzip(buf); // zlib + JSON (matches jsonZip on upsert)
+        }
+        catch {
+            try {
+                return JSON.parse(buf.toString('utf-8'));
+            }
+            catch {
+                return {};
+            }
+        }
+    }
+    if (typeof m === 'string') {
+        try {
+            return JSON.parse(m);
+        }
+        catch {
+            return {};
+        }
+    }
+    return m; // already a dict
+}
+/** Decode a result filter (JSON string/bytes) into an object. */
+function decodeFilter(f) {
+    if (!f)
+        return {};
+    let s = f;
+    if (s instanceof Uint8Array || Buffer.isBuffer(s)) {
+        s = Buffer.from(s).toString('utf-8');
+    }
+    if (typeof s === 'string') {
+        try {
+            return JSON.parse(s);
+        }
+        catch {
+            return {};
+        }
+    }
+    return s;
+}
+/**
+ * The objects map in a SearchResult is keyed by integer (internal) ids. Depending
+ * on the msgpack decoder it comes back as a `Map` or a plain object (numeric keys
+ * coerced to strings). This normalizes both into a lookup by integer id.
+ */
+function lookupObject(objectsMap, intId) {
+    if (objectsMap instanceof Map) {
+        return (objectsMap.get(intId) ?? objectsMap.get(String(intId)));
+    }
+    if (objectsMap && typeof objectsMap === 'object') {
+        return objectsMap[String(intId)];
+    }
+    return undefined;
+}
+/**
+ * Decode one ObjectMeta entry from the SearchResult objects map.
+ * Wire layout: ObjectMeta = [strId, metaBytes, filterStr].
+ */
+function decodeObjectMeta(intId, objectsMap) {
+    const obj = lookupObject(objectsMap, intId);
+    if (obj === undefined) {
+        return { id: String(intId), meta: {}, filter: {}, similarity: 0 };
+    }
+    const meta = obj.length > 1 ? decodeMeta(obj[1]) : {};
+    delete meta[NORMS_KEY]; // search results never expose the internal norms key
+    return {
+        id: obj[0],
+        meta,
+        filter: obj.length > 2 ? decodeFilter(obj[2]) : {},
+        similarity: 0,
+    };
+}
+/** Decode a field's ranked hits ([[intId, score], ...]) into result objects. */
+function decodeFieldHits(hits, objectsMap, limit) {
+    const out = [];
+    for (const hit of (hits || []).slice(0, limit)) {
+        const d = decodeObjectMeta(hit[0], objectsMap);
+        d.similarity = Number(hit[1]);
+        out.push(d);
+    }
+    return out;
+}
+/**
+ * Decode one full object from a get-objects ObjectBatch.
+ * Wire layout: Object = [id, meta, filter, vectors, sparses, multi_vectors].
+ *
+ * For cosine fields the server stores unit vectors; we multiply them by the
+ * norms stashed in meta (`internal_`) at upsert time to return the original
+ * vectors. The `internal_` entry is then stripped from the returned meta.
+ */
+function decodeFullObject(obj) {
+    const meta = obj.length > 1 ? decodeMeta(obj[1]) : {};
+    const norms = (meta[NORMS_KEY] ?? {});
+    const vectorsRaw = (obj.length > 3 ? obj[3] : {});
+    const sparsesRaw = (obj.length > 4 ? obj[4] : {});
+    const multiRaw = (obj.length > 5 ? obj[5] : {});
+    // Rebuild originals: unit_vector * norm (cosine fields only; others have no norm).
+    const vectors = {};
+    for (const [k, v] of mapEntries(vectorsRaw)) {
+        const vec = Array.from(v);
+        const n = norms[k];
+        vectors[k] = typeof n === 'number' && Number.isFinite(n) ? vec.map((x) => x * n) : vec;
+    }
+    const sparses = {};
+    for (const [k, v] of mapEntries(sparsesRaw)) {
+        sparses[k] = { indices: Array.from(v[0]), values: Array.from(v[1]) };
+    }
+    const multi_vectors = {};
+    for (const [k, v] of mapEntries(multiRaw)) {
+        const ns = norms[k];
+        multi_vectors[k] = v.map((member, i) => {
+            const row = Array.from(member);
+            if (Array.isArray(ns) && i < ns.length)
+                return row.map((x) => x * ns[i]);
+            return row;
+        });
+    }
+    delete meta[NORMS_KEY]; // hide the internal norms key from the user
+    return {
+        id: obj[0],
+        meta,
+        filter: obj.length > 2 ? decodeFilter(obj[2]) : {},
+        vectors,
+        sparses,
+        multi_vectors,
+    };
+}
+function mapEntries(m) {
+    if (!m)
+        return [];
+    if (m instanceof Map)
+        return Array.from(m.entries());
+    return Object.entries(m);
+}
+// ── normalization helpers (cosine-only, mirrors the Python client) ─────────────
+/** L2-normalize a dense vector for cosine; returns [vector, norm]. */
+function normalizeDense(vec, spaceType) {
+    for (const v of vec) {
+        if (typeof v !== 'number' || !Number.isFinite(v)) {
+            throw new Error('dense vector contains NaN or infinity');
+        }
+    }
+    if (spaceType !== 'cosine')
+        return [vec.slice(), 1.0];
+    let sum = 0;
+    for (const v of vec)
+        sum += v * v;
+    const norm = Math.max(Math.sqrt(sum), NORM_EPSILON);
+    return [vec.map((v) => v / norm), norm];
+}
+/** L2-normalize each sub-vector for cosine; returns [vectors, norms]. */
+function normalizeMulti(vectors, spaceType) {
+    if (!Array.isArray(vectors) || vectors.length === 0 || !Array.isArray(vectors[0])) {
+        throw new Error('multi_vector field must be a list of equal-length vectors');
+    }
+    for (const row of vectors) {
+        for (const v of row) {
+            if (typeof v !== 'number' || !Number.isFinite(v)) {
+                throw new Error('multi_vector contains NaN or infinity');
+            }
+        }
+    }
+    if (spaceType !== 'cosine')
+        return [vectors.map((r) => r.slice()), vectors.map(() => 1.0)];
+    const out = [];
+    const norms = [];
+    for (const row of vectors) {
+        let sum = 0;
+        for (const v of row)
+            sum += v * v;
+        const norm = Math.max(Math.sqrt(sum), NORM_EPSILON);
+        out.push(row.map((v) => v / norm));
+        norms.push(norm);
+    }
+    return [out, norms];
+}
+/** Accept {indices/values}, {sparse_indices/sparse_values}, or {position/values}. */
+function extractSparse(data) {
+    if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+        throw new Error('sparse field expects a dict with indices and values');
+    }
+    const indicesRaw = data.indices ?? data.sparse_indices ?? data.position ?? [];
+    const valuesRaw = data.values ?? data.sparse_values ?? [];
+    const indices = indicesRaw.map((i) => Math.trunc(i));
+    const values = valuesRaw.map((v) => Number(v));
+    if (indices.length !== values.length) {
+        throw new Error(`sparse indices and values must match in length (${indices.length} vs ${values.length})`);
+    }
+    return [indices, values];
+}
+/** Filter key/value size guards (mirrors the Python client). */
+function validateFilter(flt) {
+    if (typeof flt !== 'object' || flt === null || Array.isArray(flt))
+        return;
+    for (const [key, value] of Object.entries(flt)) {
+        if (Buffer.byteLength(String(key), 'utf8') > MAX_KEY_BYTES) {
+            throw new Error(`Filter key must be <= ${MAX_KEY_BYTES} bytes: ${key}`);
+        }
+        const valuesToCheck = Array.isArray(value) ? value : [value];
+        for (const v of valuesToCheck) {
+            if (typeof v === 'string' && Buffer.byteLength(v, 'utf8') > MAX_VALUE_BYTES) {
+                throw new Error(`Filter value must be <= ${MAX_VALUE_BYTES} bytes`);
+            }
+        }
+    }
+}
+function isConfigDict(x) {
+    return typeof x === 'object' && x !== null && !Array.isArray(x) && 'query' in x;
+}
+/**
+ * Resolve a field's `limit` (max hits to return for this field). A missing
+ * limit defaults to `DEFAULT_TOP_K`; the value must be in [1, MAX_TOP_K_ALLOWED].
+ */
+function resolveFieldLimit(fieldName, limit) {
+    if (limit === undefined || limit === null)
+        return DEFAULT_TOP_K;
+    if (typeof limit !== 'number' ||
+        !Number.isInteger(limit) ||
+        limit < 1 ||
+        limit > MAX_TOP_K_ALLOWED) {
+        throw new Error(`Search field '${fieldName}': limit must be an integer between 1 and ${MAX_TOP_K_ALLOWED}.`);
+    }
+    return limit;
+}
+/**
+ * Build one entry for the `fields` array sent to the server from the unified
+ * per-field config: `{ query, limit?, ef_search? }`. `query` is required.
+ * Returns `[entry, fieldLimit]` so the caller can truncate decoded hits to the
+ * same per-field limit.
+ */
+function buildFieldSearchEntry(fieldName, fieldData, efSearch) {
+    if (!isConfigDict(fieldData)) {
+        throw new Error(`Search field '${fieldName}' must be an object of the form { query, limit?, ef_search? }.`);
+    }
+    const { query, limit, ef_search, ...rest } = fieldData;
+    const fieldLimit = resolveFieldLimit(fieldName, limit);
+    const cfg = {
+        ...rest,
+        query,
+        limit: fieldLimit,
+        ef_search: ef_search === undefined ? efSearch : ef_search,
+    };
+    return [{ [fieldName]: cfg }, fieldLimit];
+}
+export class Collection {
+    name;
+    token;
+    v2Url;
+    fields;
+    createdAt;
+    layoutVersion;
+    http;
+    constructor(name, token, v2Url, metadata, http) {
+        this.name = name;
+        this.token = token;
+        this.v2Url = v2Url;
+        this.fields = metadata.fields ?? [];
+        this.createdAt = metadata.created_at;
+        this.layoutVersion = metadata.layout_version ?? 1;
+        this.http = http ?? axios.create();
+    }
+    toString() {
+        return this.name;
+    }
+    /** name → { type, space_type, dimension } from the collection metadata. */
+    fieldIndex() {
+        const idx = {};
+        for (const f of this.fields) {
+            const params = f.params ?? {};
+            idx[f.name] = {
+                type: f.type ?? 'vector',
+                space_type: params.space_type ?? 'cosine',
+                dimension: params.dimension ?? 0,
+            };
+        }
+        return idx;
+    }
+    authHeaders(extra = {}) {
+        return { Authorization: this.token, ...extra };
+    }
+    // ── upsert ───────────────────────────────────────────────────────────────
+    /**
+     * Insert or update objects. Cosine `vector`/`multi_vector` values are
+     * L2-normalized client-side; the batch is serialized as msgpack into the
+     * server ObjectBatch layout and POSTed as `application/msgpack`.
+     *
+     * Wire layout (maps keyed by field name):
+     *   ObjectBatch   = [ objects ]
+     *   Object        = [ id, meta, filter, vectors, sparses, multi_vectors ]
+     *   vectors       = { fieldName: [float, ...] }
+     *   sparses       = { fieldName: [indices, values] }
+     *   multi_vectors = { fieldName: [[float, ...], ...] }
+     *
+     * Returns `{ upserted: <count> }`.
+     */
+    async upsert(objects) {
+        if (!Array.isArray(objects)) {
+            throw new Error('objects must be an array');
+        }
+        if (objects.length > MAX_VECTORS_PER_BATCH) {
+            throw new Error(`Cannot upsert more than ${MAX_VECTORS_PER_BATCH} objects at a time (got ${objects.length})`);
+        }
+        const fieldIdx = this.fieldIndex();
+        const wireObjects = [];
+        const seenIds = new Set();
+        for (const obj of objects) {
+            const oid = String(obj.id ?? '');
+            if (!oid)
+                throw new Error('object id must be a non-empty string');
+            if (seenIds.has(oid))
+                throw new Error(`Duplicate id in batch: ${oid}`);
+            seenIds.add(oid);
+            // filter → JSON string ("" when absent)
+            const flt = obj.filter;
+            let filterStr;
+            if (flt === null || flt === undefined) {
+                filterStr = '';
+            }
+            else if (typeof flt === 'string') {
+                filterStr = flt;
+            }
+            else {
+                validateFilter(flt);
+                filterStr = JSON.stringify(flt);
+            }
+            // For cosine fields we also collect the per-vector norm(s) to stash in
+            // meta so getObjects can reconstruct the original (non-unit) vectors.
+            const vectors = {};
+            const sparses = {};
+            const multiVectors = {};
+            const norms = {};
+            for (const [fname, fdata] of Object.entries(obj.fields ?? {})) {
+                const cfg = fieldIdx[fname];
+                if (cfg === undefined) {
+                    throw new Error(`Unknown field '${fname}'. Collection fields: ${Object.keys(fieldIdx).join(', ')}`);
+                }
+                const dim = cfg.dimension || 0;
+                const space = cfg.space_type ?? 'cosine';
+                if (cfg.type === 'vector') {
+                    const [vec, norm] = normalizeDense(fdata, space);
+                    if (dim && vec.length !== dim) {
+                        throw new Error(`Field '${fname}': expected dimension ${dim}, got ${vec.length}`);
+                    }
+                    vectors[fname] = vec;
+                    if (space === 'cosine')
+                        norms[fname] = norm;
+                }
+                else if (cfg.type === 'sparse') {
+                    const [indices, values] = extractSparse(fdata);
+                    sparses[fname] = [indices, values];
+                }
+                else if (cfg.type === 'multi_vector') {
+                    const [vecs, mnorms] = normalizeMulti(fdata, space);
+                    if (dim && vecs.some((v) => v.length !== dim)) {
+                        throw new Error(`Field '${fname}': every multi_vector must have dimension ${dim}`);
+                    }
+                    multiVectors[fname] = vecs;
+                    if (space === 'cosine')
+                        norms[fname] = mnorms; // one norm per member
+                }
+                else {
+                    throw new Error(`Field '${fname}' has unknown type '${cfg.type}'`);
+                }
+            }
+            // meta → zlib(JSON(...)) bytes. Stash cosine norms under the reserved
+            // `internal_` key so getObjects can rebuild the original vectors.
+            // Pre-encoded bytes meta is sent as-is and cannot carry norms.
+            const rawMeta = obj.meta;
+            let metaBytes;
+            if (rawMeta instanceof Uint8Array || Buffer.isBuffer(rawMeta)) {
+                metaBytes = Buffer.from(rawMeta);
+            }
+            else {
+                const metaDict = {
+                    ...(rawMeta ?? {}),
+                };
+                if (Object.keys(norms).length > 0)
+                    metaDict[NORMS_KEY] = norms;
+                metaBytes = jsonZip(metaDict);
+            }
+            // Object = [id, meta, filter, vectors, sparses, multi_vectors]
+            wireObjects.push([oid, metaBytes, filterStr, vectors, sparses, multiVectors]);
+        }
+        // ObjectBatch = [objects]  (single-element array)
+        const payload = encode([wireObjects], { forceFloat32: true });
+        let response;
+        try {
+            response = await this.http.post(`${this.v2Url}/collections/${this.name}/objects`, payload, {
+                headers: this.authHeaders({ 'Content-Type': 'application/msgpack' }),
+                responseType: 'arraybuffer',
+            });
+        }
+        catch (err) {
+            if (axios.isAxiosError(err) && err.response) {
+                raiseException(err.response.status, err.response.data);
+            }
+            throw err;
+        }
+        return parseJsonResponse(response.data, { status: 'ok' });
+    }
+    // ── search ───────────────────────────────────────────────────────────────
+    /**
+     * Search the collection across one or more fields in a single request.
+     *
+     * Each field is queried with the unified config `{ query, limit?, ef_search? }`,
+     * where `limit` is the max number of hits to return for that field (defaults
+     * to `DEFAULT_TOP_K`). The result is always one ranked list per field:
+     * `{ results: { [field]: SearchHit[] } }`. Use `rerank()` to fuse these into a
+     * single ranked list.
+     *
+     * For filtered searches, `prefilterCardinalityThreshold` and
+     * `filterBoostPercentage` tune the speed/recall trade-off; when either is
+     * set they're sent to the server as `filter_params`.
+     */
+    async search(options) {
+        const { fields, filter = null, efSearch = DEFAULT_EF_SEARCH, prefilterCardinalityThreshold, filterBoostPercentage, } = options;
+        const fieldNames = Object.keys(fields ?? {});
+        if (fieldNames.length === 0)
+            throw new Error('search requires at least one field');
+        if (!(efSearch > 0 && efSearch <= MAX_EF_SEARCH_ALLOWED)) {
+            throw new Error(`ef_search must be between 1 and ${MAX_EF_SEARCH_ALLOWED}`);
+        }
+        // Optional filter-tuning params (filtered search only). Validate the ranges
+        // up front; they're only sent to the server when explicitly provided.
+        if (prefilterCardinalityThreshold !== undefined) {
+            const t = prefilterCardinalityThreshold;
+            if (!Number.isFinite(t) || t < MIN_PREFILTER_THRESHOLD || t > MAX_PREFILTER_THRESHOLD) {
+                throw new Error(`prefilterCardinalityThreshold must be between ${MIN_PREFILTER_THRESHOLD} and ${MAX_PREFILTER_THRESHOLD}`);
+            }
+        }
+        if (filterBoostPercentage !== undefined) {
+            const b = filterBoostPercentage;
+            if (!Number.isFinite(b) || b < 0 || b > MAX_FILTER_BOOST_PERCENTAGE) {
+                throw new Error(`filterBoostPercentage must be between 0 and ${MAX_FILTER_BOOST_PERCENTAGE}`);
+            }
+        }
+        // L2-normalize query vectors for cosine fields (mirrors upsert).
+        const fieldIdx = this.fieldIndex();
+        const fieldsArray = [];
+        const fieldLimits = {};
+        for (const fname of fieldNames) {
+            const fieldData = fields[fname];
+            if (!isConfigDict(fieldData)) {
+                throw new Error(`Search field '${fname}' must be an object of the form { query, limit?, ef_search? }.`);
+            }
+            const normalized = { ...fieldData };
+            let q = fieldData.query;
+            const cfg = fieldIdx[fname];
+            if (cfg) {
+                const spaceType = cfg.space_type ?? 'cosine';
+                if (cfg.type === 'vector' && spaceType === 'cosine') {
+                    if (Array.isArray(q) && q.length > 0 && !Array.isArray(q[0])) {
+                        [q] = normalizeDense(q, spaceType);
+                    }
+                }
+                else if (cfg.type === 'multi_vector' && spaceType === 'cosine') {
+                    if (Array.isArray(q) && q.length > 0 && Array.isArray(q[0])) {
+                        [q] = normalizeMulti(q, spaceType);
+                    }
+                }
+            }
+            normalized.query = q;
+            const [entry, fieldLimit] = buildFieldSearchEntry(fname, normalized, efSearch);
+            fieldsArray.push(entry);
+            fieldLimits[fname] = fieldLimit;
+        }
+        const payload = { fields: fieldsArray };
+        if (filter !== null)
+            payload.filter = filter;
+        // Filter tuning: send filter_params only when the caller tunes at least one
+        // knob, defaulting the other so the server gets a complete object.
+        if (prefilterCardinalityThreshold !== undefined || filterBoostPercentage !== undefined) {
+            payload.filter_params = {
+                prefilter_threshold: prefilterCardinalityThreshold ?? DEFAULT_PREFILTER_THRESHOLD,
+                boost_percentage: filterBoostPercentage ?? DEFAULT_FILTER_BOOST_PERCENTAGE,
+            };
+        }
+        let response;
+        try {
+            response = await this.http.post(`${this.v2Url}/collections/${this.name}/search`, payload, {
+                headers: this.authHeaders({ 'Content-Type': 'application/json' }),
+                responseType: 'arraybuffer',
+            });
+        }
+        catch (err) {
+            if (axios.isAxiosError(err) && err.response) {
+                raiseException(err.response.status, err.response.data);
+            }
+            throw err;
+        }
+        // SearchResult: [objectsMap, resultsMap]
+        //   objectsMap = { intId → ObjectMeta }
+        //   resultsMap = { fieldName → [[intId, score], ...] }
+        const raw = decode(new Uint8Array(response.data));
+        const objectsMap = raw[0];
+        const resultsMap = raw[1];
+        const getField = (name) => {
+            if (resultsMap instanceof Map)
+                return (resultsMap.get(name) ?? []);
+            return (resultsMap?.[name] ?? []);
+        };
+        // Always per-field results, unfused. Each field is truncated to its own
+        // limit (already applied server-side via the per-field limit).
+        const perField = {};
+        for (const fname of fieldNames) {
+            perField[fname] = decodeFieldHits(getField(fname), objectsMap, fieldLimits[fname]);
+        }
+        return { results: perField };
+    }
+    // ── object operations ──────────────────────────────────────────────────────
+    /** Delete a single object by id. Returns `{ deleted: "<id>" }`. */
+    async deleteObject(id) {
+        let response;
+        try {
+            response = await this.http.delete(`${this.v2Url}/collections/${this.name}/objects/${id}`, {
+                headers: this.authHeaders(),
+            });
+        }
+        catch (err) {
+            if (axios.isAxiosError(err) && err.response) {
+                raiseException(err.response.status, err.response.data);
+            }
+            throw err;
+        }
+        return response.data;
+    }
+    /**
+     * Fetch full objects (meta, filter, and stored vectors) by id. Ids that don't
+     * exist are skipped by the server.
+     */
+    async getObjects(ids) {
+        if (!Array.isArray(ids) || ids.length === 0) {
+            throw new Error('getObjects requires a non-empty array of ids');
+        }
+        let response;
+        try {
+            response = await this.http.post(`${this.v2Url}/collections/${this.name}/objects/query`, { ids: ids.map((i) => String(i)) }, {
+                headers: this.authHeaders({ 'Content-Type': 'application/json' }),
+                responseType: 'arraybuffer',
+            });
+        }
+        catch (err) {
+            if (axios.isAxiosError(err) && err.response) {
+                raiseException(err.response.status, err.response.data);
+            }
+            throw err;
+        }
+        // ObjectBatch = [objects]
+        const batch = decode(new Uint8Array(response.data));
+        let objects = [];
+        if (Array.isArray(batch)) {
+            objects = batch[0] ?? [];
+        }
+        else if (batch && typeof batch === 'object') {
+            objects = batch.objects ?? [];
+        }
+        return (objects || []).map((o) => decodeFullObject(o));
+    }
+    /**
+     * Delete all objects matching a filter. Returns `{ deleted: <count> }`.
+     * `filter` uses the array format, e.g. `[{ category: { $eq: 'news' } }]`.
+     */
+    async deleteByFilter(filter) {
+        if (!Array.isArray(filter)) {
+            throw new Error('filter must be an array, e.g. [{ field: { $op: value } }]');
+        }
+        let response;
+        try {
+            response = await this.http.delete(`${this.v2Url}/collections/${this.name}/objects`, {
+                headers: this.authHeaders({ 'Content-Type': 'application/json' }),
+                data: { filter },
+            });
+        }
+        catch (err) {
+            if (axios.isAxiosError(err) && err.response) {
+                raiseException(err.response.status, err.response.data);
+            }
+            throw err;
+        }
+        return response.data;
+    }
+    /**
+     * Update filter tags on existing objects (no re-upsert of vectors).
+     * Returns `{ updated: <count> }`. `updates` is a list of `{ id, filter }`.
+     */
+    async updateFilters(updates) {
+        if (!Array.isArray(updates) || updates.length === 0) {
+            throw new Error('updates must be a non-empty array of { id, filter } objects');
+        }
+        let response;
+        try {
+            response = await this.http.post(`${this.v2Url}/collections/${this.name}/filters`, { updates }, { headers: this.authHeaders({ 'Content-Type': 'application/json' }) });
+        }
+        catch (err) {
+            if (axios.isAxiosError(err) && err.response) {
+                raiseException(err.response.status, err.response.data);
+            }
+            throw err;
+        }
+        return response.data;
+    }
+    // ── maintenance ──────────────────────────────────────────────────────────
+    /** Return collection metadata: `{ name, fields, created_at, layout_version }`. */
+    async describe() {
+        let response;
+        try {
+            response = await this.http.get(`${this.v2Url}/collections/${this.name}`, {
+                headers: this.authHeaders(),
+            });
+        }
+        catch (err) {
+            if (axios.isAxiosError(err) && err.response) {
+                raiseException(err.response.status, err.response.data);
+            }
+            throw err;
+        }
+        return response.data;
+    }
+    /**
+     * Rebuild a vector field's HNSW graph with new M / ef_con (async).
+     * Only M/ef_con may change; dimension/space_type/precision are immutable.
+     * Poll progress with `rebuildStatus()`.
+     */
+    async rebuild(options) {
+        const { field, m, efCon } = options;
+        if (!field)
+            throw new Error('rebuild requires the vector field name');
+        const body = { field };
+        if (m !== undefined)
+            body.M = m;
+        if (efCon !== undefined)
+            body.ef_con = efCon;
+        let response;
+        try {
+            response = await this.http.post(`${this.v2Url}/collections/${this.name}/rebuild`, body, {
+                headers: this.authHeaders({ 'Content-Type': 'application/json' }),
+            });
+        }
+        catch (err) {
+            if (axios.isAxiosError(err) && err.response) {
+                raiseException(err.response.status, err.response.data);
+            }
+            throw err;
+        }
+        return response.data;
+    }
+    /** Poll rebuild progress. */
+    async rebuildStatus() {
+        let response;
+        try {
+            response = await this.http.get(`${this.v2Url}/collections/${this.name}/rebuild/status`, {
+                headers: this.authHeaders(),
+            });
+        }
+        catch (err) {
+            if (axios.isAxiosError(err) && err.response) {
+                raiseException(err.response.status, err.response.data);
+            }
+            throw err;
+        }
+        return response.data;
+    }
+    /** Defragment the collection's storage in place. */
+    async shrink() {
+        let response;
+        try {
+            response = await this.http.post(`${this.v2Url}/collections/${this.name}/shrink`, undefined, {
+                headers: this.authHeaders(),
+            });
+        }
+        catch (err) {
+            if (axios.isAxiosError(err) && err.response) {
+                raiseException(err.response.status, err.response.data);
+            }
+            throw err;
+        }
+        return response.data;
+    }
+    /**
+     * Start an async backup of this collection. Returns
+     * `{ backup_name, status: "in_progress" }`. Poll `Endee.activeBackup()` /
+     * `Endee.listBackups()` for completion.
+     */
+    async createBackup(name) {
+        if (!name)
+            throw new Error('backup name is required');
+        let response;
+        try {
+            response = await this.http.post(`${this.v2Url}/collections/${this.name}/backups`, { name }, { headers: this.authHeaders({ 'Content-Type': 'application/json' }) });
+        }
+        catch (err) {
+            if (axios.isAxiosError(err) && err.response) {
+                raiseException(err.response.status, err.response.data);
+            }
+            throw err;
+        }
+        return response.data;
+    }
+}
+/** Parse a possibly-empty arraybuffer/JSON response body, with a fallback. */
+function parseJsonResponse(data, fallback) {
+    let text;
+    if (data instanceof ArrayBuffer) {
+        text = new TextDecoder().decode(data);
+    }
+    else if (data instanceof Uint8Array || Buffer.isBuffer(data)) {
+        text = Buffer.from(data).toString('utf-8');
+    }
+    else if (typeof data === 'string') {
+        text = data;
+    }
+    else if (data && typeof data === 'object') {
+        return data;
+    }
+    else {
+        return fallback;
+    }
+    if (!text)
+        return fallback;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { status: text };
+    }
+}
+//# sourceMappingURL=collection.js.map