summa-client-typescript 2.0.0

package/README.md

@@ -0,0 +1,163 @@
+# Summa TypeScript client
+
+Typed Node.js client for the
+[Summa](https://github.com/SpaceFrontiers/summa) gRPC search server.
+
+## Installation
+
+```bash
+pnpm add summa-client-typescript
+```
+
+## Quick start
+
+```typescript
+import { SummaClient } from "summa-client-typescript";
+
+const client = new SummaClient("localhost:50051");
+client.connect();
+
+try {
+  await client.createIndex(
+    "articles",
+    `
+      index articles {
+        field id: text<raw> [primary, stored]
+        field title: text<simple> [indexed, stored]
+        field body: text<simple> [indexed, stored]
+      }
+    `,
+  );
+
+  const [indexedCount, errorCount, errors] = await client.indexDocuments(
+    "articles",
+    [
+      { id: "1", title: "Hello", body: "First article" },
+      { id: "2", title: "Summa", body: "Fast search" },
+    ],
+  );
+  if (errorCount) throw new Error(JSON.stringify(errors));
+  console.log(`Indexed ${indexedCount} documents`);
+
+  await client.commit("articles");
+
+  const results = await client.search("articles", {
+    query: { match: { field: "title", text: "hello" } },
+    fieldsToLoad: ["title", "body"],
+  });
+
+  for (const hit of results.hits) {
+    console.log(hit.address, hit.score, hit.fields);
+  }
+
+  if (results.hits.length > 0) {
+    const document = await client.getDocument(
+      "articles",
+      results.hits[0].address,
+    );
+    console.log(document?.fields);
+  }
+} finally {
+  client.close();
+}
+```
+
+Call `connect()` before the first RPC and `close()` when finished.
+
+## Index management
+
+```typescript
+await client.listIndexes();
+const info = await client.getIndexInfo("articles");
+await client.reorder("articles");
+await client.retrainVectorIndex("articles");
+```
+
+`indexDocuments` returns `[indexedCount, errorCount, errors]`;
+`indexDocumentsStream` takes an async iterable. Inspect errors, then `commit()`
+to publish accepted work. Arrays hold repeated values; flat numeric arrays are
+dense vectors. One sparse vector uses `[[[1, 0.5], [8, 0.25]]]`: the outer array
+is required because `[[1, 0.5], [8, 0.25]]` means two dense vectors.
+
+### Delete and upsert documents
+
+With a text primary key, delete by exact key or supply a complete replacement:
+
+```typescript
+await client.deleteDocument("articles", "2");
+await client.upsertDocument("articles", { id: "1", title: "Updated title" });
+await client.commit("articles");
+```
+
+`deleteDocuments` / `upsertDocuments` return `DocumentMutationResult` with
+`acceptedCount` and `errors: [{index, error}]`. Single-item helpers throw on
+rejection. Missing deletes succeed; upserts insert missing keys. Staged rows can
+be replaced/deleted again before commit; the latest accepted version wins.
+Optional [content hashes](../docs/content-deduplication.md) skip unchanged writes.
+
+Limits: 100,000 deletion keys / 8 MiB key bytes; 1,000 replacements / 32 MiB
+encoded protobuf, or one replacement / 200 MiB including the request envelope.
+Broker commits are atomic per partition. See [mutation semantics](../docs/row-deletion.md).
+
+### Compact deleted rows
+
+```typescript
+await client.forceMerge("articles"); // Retain tombstones.
+await client.forceMerge("articles", undefined, true); // Physically remove deleted rows.
+```
+
+The second argument remains the timeout in milliseconds. Compaction handles
+singletons and may change addresses and BM25 scores. Index info exposes
+`numDocs`, `physicalNumDocs`, `numDeletedDocs`, and `deletedRatio`.
+
+## Searching
+
+`search(indexName, request)` accepts a typed `SearchRequest`. Its `query` selects
+one variant: `term`, `match`, `phrase`, `boolean`, `sparseVector`, `denseVector`,
+`binaryDenseVector`, `boost`, `range`, `prefix`, `all`, or `fusion`.
+See [client types](src/types.ts) and the [protocol](../summa-proto/summa.proto).
+
+```typescript
+const results = await client.search("articles", {
+  query: {
+    boolean: {
+      must: [{ match: { field: "title", text: "search" } }],
+      mustNot: [{ term: { field: "title", term: "draft" } }],
+    },
+  },
+  fieldsToLoad: ["title"],
+});
+```
+
+`getDocument(indexName, hit.address)` uses the full segment/document address
+and returns `null` on `NOT_FOUND`. Use primary keys for durable identity.
+
+## Ranking diagnostics and recall traces
+
+Search options `includeRrfScores: true` and `tracing: true` default to false.
+RRF diagnostics describe organic branch nominations; traces retain bounded
+candidates and query trees, including hits outside the final page. Neither
+changes retrieval depth or ranking. Oversized exports fail explicitly.
+
+For named branches, use `l1: { formula: "0.2 * title + 0.8 * body + 3 * rrf" }`.
+The formula is the only L1 scoring interface; old coefficient fields are removed.
+See [candidate scoring](../docs/candidate-rescoring.md) for backfill, passage
+selection, expression limits, capability versions, and distributed behavior.
+
+## Deadlines
+
+RPCs accept a trailing timeout in milliseconds, overriding the constructor's
+`defaultTimeoutMs`. Expired calls reject with gRPC `DEADLINE_EXCEEDED`.
+An expired mutation may already be staged, and an accepted commit continues
+after disconnection. Resolve the outcome before retrying replacements.
+
+## Development
+
+```bash
+pnpm install --frozen-lockfile
+pnpm check
+```
+
+`check` compiles strict TypeScript and runs converter tests. After
+[protocol changes](../summa-proto/README.md#regeneration-and-validation), run
+`pnpm generate && pnpm check` and include the generated source.

package/dist/client.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Async Summa client implementation.
+ *
+ * Search types mirror the protobuf API. Serialization details live in
+ * converters.ts so this class remains focused on connection and RPC lifecycle.
+ */
+import type { DocAddress, Document, DocumentMutationResult, IndexInfo, SearchRequest, SearchResponse } from "./types";
+export interface SummaClientOptions {
+    /**
+     * Default per-RPC deadline in milliseconds, applied to every call unless
+     * overridden by the call's `timeoutMs` argument. Undefined means no
+     * deadline. Expired calls reject with gRPC DEADLINE_EXCEEDED.
+     */
+    defaultTimeoutMs?: number;
+}
+export declare class SummaClient {
+    private readonly address;
+    private readonly defaultTimeoutMs?;
+    private channel;
+    private indexClient;
+    private searchClient;
+    constructor(address?: string, options?: SummaClientOptions);
+    /** Connect to the server. */
+    connect(): void;
+    /** Close the connection. */
+    close(): void;
+    /** Per-call options with the effective deadline (call override > default). */
+    private callOptions;
+    private ensureConnected;
+    /** Create a new index. */
+    createIndex(indexName: string, schema: string, timeoutMs?: number): Promise<boolean>;
+    /** Delete an index. */
+    deleteIndex(indexName: string, timeoutMs?: number): Promise<boolean>;
+    /** List all indexes on the server. */
+    listIndexes(timeoutMs?: number): Promise<string[]>;
+    /** Get information about an index. */
+    getIndexInfo(indexName: string, timeoutMs?: number): Promise<IndexInfo>;
+    /** Index multiple documents. Returns [indexedCount, errorCount, errors]. */
+    indexDocuments(indexName: string, documents: Record<string, unknown>[], timeoutMs?: number): Promise<[number, number, Array<{
+        index: number;
+        error: string;
+    }>]>;
+    /** Index a single document. */
+    indexDocument(indexName: string, document: Record<string, unknown>, timeoutMs?: number): Promise<void>;
+    /** Stage exact-key deletions of whole documents and all their chunks.
+     * Missing keys are accepted. Inspect errors, then commit accepted work.
+     * Do not blindly retry mutations after an uncertain RPC outcome.
+     */
+    deleteDocuments(indexName: string, primaryKeys: string[], timeoutMs?: number): Promise<DocumentMutationResult>;
+    /** Stage one deletion; throws on rejection. Call commit to publish. */
+    deleteDocument(indexName: string, primaryKey: string, timeoutMs?: number): Promise<void>;
+    /** Stage complete replacements (inserts if absent); inspect errors, then commit.
+     * Each document needs its primary key; commit publishes its latest accepted
+     * replacement, including across calls. This is not a partial patch API.
+     */
+    upsertDocuments(indexName: string, documents: Record<string, unknown>[], timeoutMs?: number): Promise<DocumentMutationResult>;
+    /** Stage one complete replacement; throws on rejection. Commit to publish. */
+    upsertDocument(indexName: string, document: Record<string, unknown>, timeoutMs?: number): Promise<void>;
+    /** Stream documents for indexing. Returns number of indexed documents. */
+    indexDocumentsStream(indexName: string, documents: AsyncIterable<Record<string, unknown>>, timeoutMs?: number): Promise<number>;
+    /** Commit pending changes. Returns total number of documents. */
+    commit(indexName: string, timeoutMs?: number): Promise<number>;
+    /** Merge segments; compact=true physically removes tombstones from final outputs. */
+    forceMerge(indexName: string, timeoutMs?: number, compact?: boolean): Promise<number>;
+    /** Retrain vector index centroids/codebooks from current data. */
+    retrainVectorIndex(indexName: string, timeoutMs?: number): Promise<boolean>;
+    /** Run bounded text, Seismic, and binary ANN layout maintenance. */
+    reorder(indexName: string, timeoutMs?: number): Promise<number>;
+    /**
+     * Search for documents.
+     *
+     * @example
+     * await client.search("articles", {
+     *   query: { match: { field: "title", text: "search engine" } },
+     *   fieldsToLoad: ["title"],
+     * });
+     */
+    search(indexName: string, request: SearchRequest, timeoutMs?: number): Promise<SearchResponse>;
+    /** Get a document by address. Returns null if not found. */
+    getDocument(indexName: string, address: DocAddress, timeoutMs?: number): Promise<Document | null>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAoBH,OAAO,KAAK,EACV,UAAU,EACV,QAAQ,EACR,sBAAsB,EACtB,SAAS,EAET,aAAa,EACb,cAAc,EAEf,MAAM,SAAS,CAAC;AAKjB,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAS;IAC3C,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,YAAY,CAA6B;gBAG/C,OAAO,GAAE,MAA0B,EACnC,OAAO,GAAE,kBAAuB;IAMlC,6BAA6B;IAC7B,OAAO,IAAI,IAAI;IAef,4BAA4B;IAC5B,KAAK,IAAI,IAAI;IASb,8EAA8E;IAC9E,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,eAAe;IAMvB,0BAA0B;IACpB,WAAW,CACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC;IASnB,uBAAuB;IACjB,WAAW,CACf,SAAS,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC;IASnB,sCAAsC;IAChC,WAAW,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IASxD,sCAAsC;IAChC,YAAY,CAChB,SAAS,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,SAAS,CAAC;IAyBrB,4EAA4E;IACtE,cAAc,CAClB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACpC,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IAkBrE,+BAA+B;IACzB,aAAa,CACjB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC;IAIhB;;;OAGG;IACG,eAAe,CACnB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EAAE,EACrB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,sBAAsB,CAAC;IAclC,uEAAuE;IACjE,cAAc,CAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC;IAOhB;;;OAGG;IACG,eAAe,CACnB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACpC,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,sBAAsB,CAAC;IAclC,8EAA8E;IACxE,cAAc,CAClB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC;IAOhB,0EAA0E;IACpE,oBAAoB,CACxB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACjD,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC;IAmBlB,iEAAiE;IAC3D,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IASpE,qFAAqF;IAC/E,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,UAAQ,GAAG,OAAO,CAAC,MAAM,CAAC;IASzF,kEAAkE;IAC5D,kBAAkB,CACtB,SAAS,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC;IASnB,oEAAoE;IAC9D,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IASrE;;;;;;;;OAQG;IACG,MAAM,CACV,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,aAAa,EACtB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,cAAc,CAAC;IA0F1B,4DAA4D;IACtD,WAAW,CACf,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,UAAU,EACnB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;CAkC5B"}

package/dist/client.js

@@ -0,0 +1,312 @@
+"use strict";
+/**
+ * Async Summa client implementation.
+ *
+ * Search types mirror the protobuf API. Serialization details live in
+ * converters.ts so this class remains focused on connection and RPC lifecycle.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SummaClient = void 0;
+const grpc_js_1 = require("@grpc/grpc-js");
+const nice_grpc_1 = require("nice-grpc");
+const nice_grpc_client_middleware_deadline_1 = require("nice-grpc-client-middleware-deadline");
+const converters_1 = require("./converters");
+const summa_1 = require("./generated/summa");
+class SummaClient {
+    constructor(address = "localhost:50051", options = {}) {
+        this.channel = null;
+        this.indexClient = null;
+        this.searchClient = null;
+        this.address = address;
+        this.defaultTimeoutMs = options.defaultTimeoutMs;
+    }
+    /** Connect to the server. */
+    connect() {
+        this.channel = (0, nice_grpc_1.createChannel)(this.address, grpc_js_1.ChannelCredentials.createInsecure(), {
+            // Match Python and fit bounded mutation requests and per-item errors.
+            "grpc.max_receive_message_length": 50 * 1024 * 1024,
+            "grpc.max_send_message_length": 200 * 1024 * 1024,
+        });
+        const factory = (0, nice_grpc_1.createClientFactory)().use(nice_grpc_client_middleware_deadline_1.deadlineMiddleware);
+        this.indexClient = factory.create(summa_1.IndexServiceDefinition, this.channel);
+        this.searchClient = factory.create(summa_1.SearchServiceDefinition, this.channel);
+    }
+    /** Close the connection. */
+    close() {
+        if (this.channel) {
+            this.channel.close();
+            this.channel = null;
+            this.indexClient = null;
+            this.searchClient = null;
+        }
+    }
+    /** Per-call options with the effective deadline (call override > default). */
+    callOptions(timeoutMs) {
+        const milliseconds = timeoutMs ?? this.defaultTimeoutMs;
+        return milliseconds !== undefined && milliseconds > 0
+            ? { deadline: new Date(Date.now() + milliseconds) }
+            : {};
+    }
+    ensureConnected() {
+        if (!this.indexClient || !this.searchClient) {
+            throw new Error("Client not connected. Call connect() first.");
+        }
+    }
+    /** Create a new index. */
+    async createIndex(indexName, schema, timeoutMs) {
+        this.ensureConnected();
+        const response = await this.indexClient.createIndex({ indexName, schema }, this.callOptions(timeoutMs));
+        return response.success;
+    }
+    /** Delete an index. */
+    async deleteIndex(indexName, timeoutMs) {
+        this.ensureConnected();
+        const response = await this.indexClient.deleteIndex({ indexName }, this.callOptions(timeoutMs));
+        return response.success;
+    }
+    /** List all indexes on the server. */
+    async listIndexes(timeoutMs) {
+        this.ensureConnected();
+        const response = await this.indexClient.listIndexes({}, this.callOptions(timeoutMs));
+        return response.indexNames;
+    }
+    /** Get information about an index. */
+    async getIndexInfo(indexName, timeoutMs) {
+        this.ensureConnected();
+        const response = await this.searchClient.getIndexInfo({ indexName }, this.callOptions(timeoutMs));
+        return {
+            indexName: response.indexName,
+            numDocs: response.numDocs,
+            numSegments: response.numSegments,
+            schema: response.schema,
+            physicalNumDocs: response.physicalNumDocs,
+            numDeletedDocs: response.numDeletedDocs,
+            deletedRatio: response.deletedRatio,
+            candidateScoringVersion: response.candidateScoringVersion,
+            unpreparedCandidateFields: response.unpreparedCandidateFields,
+            vectorStats: (response.vectorStats ?? []).map((stats) => ({
+                fieldName: stats.fieldName,
+                vectorType: stats.vectorType,
+                totalVectors: stats.totalVectors,
+                dimension: stats.dimension,
+            })),
+        };
+    }
+    /** Index multiple documents. Returns [indexedCount, errorCount, errors]. */
+    async indexDocuments(indexName, documents, timeoutMs) {
+        this.ensureConnected();
+        const response = await this.indexClient.batchIndexDocuments({
+            indexName,
+            documents: documents.map((document) => ({
+                fields: (0, converters_1.toFieldEntries)(document),
+            })),
+        }, this.callOptions(timeoutMs));
+        const errors = (response.errors ?? []).map((error) => ({
+            index: error.index,
+            error: error.error,
+        }));
+        return [response.indexedCount, response.errorCount, errors];
+    }
+    /** Index a single document. */
+    async indexDocument(indexName, document, timeoutMs) {
+        await this.indexDocuments(indexName, [document], timeoutMs);
+    }
+    /** Stage exact-key deletions of whole documents and all their chunks.
+     * Missing keys are accepted. Inspect errors, then commit accepted work.
+     * Do not blindly retry mutations after an uncertain RPC outcome.
+     */
+    async deleteDocuments(indexName, primaryKeys, timeoutMs) {
+        this.ensureConnected();
+        if (primaryKeys.length > 100000 ||
+            primaryKeys.reduce((sum, key) => sum + Buffer.byteLength(key, "utf8"), 0) > 8 * 1024 * 1024) {
+            throw new Error("deletion request exceeds 100000 keys or 8 MiB of key bytes");
+        }
+        return this.indexClient.deleteDocuments({ indexName, primaryKeys }, this.callOptions(timeoutMs));
+    }
+    /** Stage one deletion; throws on rejection. Call commit to publish. */
+    async deleteDocument(indexName, primaryKey, timeoutMs) {
+        const result = await this.deleteDocuments(indexName, [primaryKey], timeoutMs);
+        if (result.errors.length || result.acceptedCount !== 1) {
+            throw new Error(result.errors[0]?.error ?? "deletion was not accepted");
+        }
+    }
+    /** Stage complete replacements (inserts if absent); inspect errors, then commit.
+     * Each document needs its primary key; commit publishes its latest accepted
+     * replacement, including across calls. This is not a partial patch API.
+     */
+    async upsertDocuments(indexName, documents, timeoutMs) {
+        this.ensureConnected();
+        if (documents.length > 1000) {
+            throw new Error("upsert request exceeds 1000 documents");
+        }
+        return this.indexClient.upsertDocuments({
+            indexName,
+            documents: documents.map((document) => ({ fields: (0, converters_1.toFieldEntries)(document) })),
+        }, this.callOptions(timeoutMs));
+    }
+    /** Stage one complete replacement; throws on rejection. Commit to publish. */
+    async upsertDocument(indexName, document, timeoutMs) {
+        const result = await this.upsertDocuments(indexName, [document], timeoutMs);
+        if (result.errors.length || result.acceptedCount !== 1) {
+            throw new Error(result.errors[0]?.error ?? "upsert was not accepted");
+        }
+    }
+    /** Stream documents for indexing. Returns number of indexed documents. */
+    async indexDocumentsStream(indexName, documents, timeoutMs) {
+        this.ensureConnected();
+        async function* requestIterator() {
+            for await (const document of documents) {
+                yield {
+                    indexName,
+                    fields: (0, converters_1.toFieldEntries)(document),
+                };
+            }
+        }
+        const response = await this.indexClient.indexDocuments(requestIterator(), this.callOptions(timeoutMs));
+        return response.indexedCount;
+    }
+    /** Commit pending changes. Returns total number of documents. */
+    async commit(indexName, timeoutMs) {
+        this.ensureConnected();
+        const response = await this.indexClient.commit({ indexName }, this.callOptions(timeoutMs));
+        return response.numDocs;
+    }
+    /** Merge segments; compact=true physically removes tombstones from final outputs. */
+    async forceMerge(indexName, timeoutMs, compact = false) {
+        this.ensureConnected();
+        const response = await this.indexClient.forceMerge({ indexName, compact }, this.callOptions(timeoutMs));
+        return response.numSegments;
+    }
+    /** Retrain vector index centroids/codebooks from current data. */
+    async retrainVectorIndex(indexName, timeoutMs) {
+        this.ensureConnected();
+        const response = await this.indexClient.retrainVectorIndex({ indexName }, this.callOptions(timeoutMs));
+        return response.success;
+    }
+    /** Run bounded text, Seismic, and binary ANN layout maintenance. */
+    async reorder(indexName, timeoutMs) {
+        this.ensureConnected();
+        const response = await this.indexClient.reorder({ indexName }, this.callOptions(timeoutMs));
+        return response.numSegments;
+    }
+    /**
+     * Search for documents.
+     *
+     * @example
+     * await client.search("articles", {
+     *   query: { match: { field: "title", text: "search engine" } },
+     *   fieldsToLoad: ["title"],
+     * });
+     */
+    async search(indexName, request, timeoutMs) {
+        if (request.l1 && Object.keys(request.l1).some(key => !["formula", "backfill", "missingValues"].includes(key))) {
+            throw new Error("L1 accepts only formula, backfill and missingValues; put coefficients in formula");
+        }
+        this.ensureConnected();
+        const response = await this.searchClient.search({
+            indexName,
+            query: (0, converters_1.buildQuery)(request.query),
+            limit: request.limit ?? 10,
+            offset: request.offset ?? 0,
+            fieldsToLoad: request.fieldsToLoad ?? [],
+            reranker: request.reranker
+                ? (0, converters_1.buildReranker)(request.reranker)
+                : undefined,
+            candidateLimit: request.candidateLimit ?? 0,
+            timeBudgetMs: request.timeBudgetMs ?? 0,
+            textStats: undefined,
+            includeRrfScores: request.includeRrfScores ?? false,
+            tracing: request.tracing ?? false,
+            l1: request.l1 ? {
+                formula: request.l1.formula,
+                backfill: request.l1.backfill,
+                missingValues: request.l1.missingValues ?? {},
+            } : undefined,
+            scoreExport: request.scoreExport ? { passagesPerDocument: request.scoreExport.passagesPerDocument ?? 0, allPassages: request.scoreExport.allPassages ?? false, seedDocumentPassages: request.scoreExport.seedDocumentPassages ?? false } : undefined,
+        }, this.callOptions(timeoutMs));
+        const expectedL1 = "formula_v1";
+        if (request.scoreExport?.seedDocumentPassages && !response.seededDocumentPassages) {
+            throw new Error("Backend did not acknowledge document passage seeding; upgrade the broker and all backends");
+        }
+        if (request.l1 && response.rankingMethod !== expectedL1) {
+            throw new Error(`L1 requires a backend with ${expectedL1} ranking semantics; received ${JSON.stringify(response.rankingMethod)}`);
+        }
+        if (request.tracing && !response.trace) {
+            throw new Error("Backend omitted requested search trace; upgrade Summa");
+        }
+        if (request.includeRrfScores && response.hits.some((hit) => hit.rrfScore === undefined)) {
+            throw new Error("Backend omitted requested RRF diagnostics; upgrade Summa");
+        }
+        const hits = response.hits.map((hit) => ({
+            address: {
+                segmentId: hit.address?.segmentId ?? "",
+                docId: hit.address?.docId ?? 0,
+            },
+            score: hit.score,
+            candidateScores: hit.candidateScores,
+            rrfScore: hit.rrfScore,
+            rrfContributions: hit.rrfContributions,
+            fields: Object.fromEntries(Object.entries(hit.fields).map(([name, value]) => [
+                name,
+                (0, converters_1.fromFieldValueList)(value),
+            ])),
+            ordinalScores: (hit.ordinalScores ?? []).map((score) => ({
+                ordinal: score.ordinal,
+                score: score.score,
+            })),
+        }));
+        const timings = response.timings
+            ? {
+                searchUs: Number(response.timings.searchUs),
+                rerankUs: Number(response.timings.rerankUs),
+                loadUs: Number(response.timings.loadUs),
+                totalUs: Number(response.timings.totalUs),
+                candidateScoringUs: Number(response.timings.candidateScoringUs),
+            }
+            : undefined;
+        return {
+            hits,
+            totalHits: response.totalHits,
+            trace: response.trace,
+            rankingMethod: response.rankingMethod,
+            seededDocumentPassages: response.seededDocumentPassages,
+            fusionCandidates: response.fusionCandidates.map(branch => ({ queryIndex: branch.queryIndex,
+                candidates: branch.candidates.map(hit => ({ address: { segmentId: hit.address?.segmentId ?? "", docId: hit.address?.docId ?? 0 },
+                    score: hit.score, ordinalScores: hit.ordinalScores })) })),
+            truncated: response.truncated,
+            tookMs: response.tookMs,
+            timings,
+        };
+    }
+    /** Get a document by address. Returns null if not found. */
+    async getDocument(indexName, address, timeoutMs) {
+        this.ensureConnected();
+        try {
+            const response = await this.searchClient.getDocument({
+                indexName,
+                address: {
+                    segmentId: address.segmentId,
+                    docId: address.docId,
+                },
+            }, this.callOptions(timeoutMs));
+            return {
+                fields: Object.fromEntries(Object.entries(response.fields).map(([name, value]) => [
+                    name,
+                    (0, converters_1.fromFieldValueList)(value),
+                ])),
+            };
+        }
+        catch (error) {
+            // gRPC NOT_FOUND status code.
+            if (typeof error === "object" &&
+                error !== null &&
+                "code" in error &&
+                error.code === 5) {
+                return null;
+            }
+            throw error;
+        }
+    }
+}
+exports.SummaClient = SummaClient;
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,2CAAmD;AACnD,yCAAgF;AAChF,+FAG8C;AAE9C,6CAKsB;AACtB,6CAG2B;AAyB3B,MAAa,WAAW;IAOtB,YACE,UAAkB,iBAAiB,EACnC,UAA8B,EAAE;QAN1B,YAAO,GAAmB,IAAI,CAAC;QAC/B,gBAAW,GAAuB,IAAI,CAAC;QACvC,iBAAY,GAAwB,IAAI,CAAC;QAM/C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IACnD,CAAC;IAED,6BAA6B;IAC7B,OAAO;QACL,IAAI,CAAC,OAAO,GAAG,IAAA,yBAAa,EAC1B,IAAI,CAAC,OAAO,EACZ,4BAAkB,CAAC,cAAc,EAAE,EACnC;YACE,sEAAsE;YACtE,iCAAiC,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;YACnD,8BAA8B,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI;SAClD,CACF,CAAC;QACF,MAAM,OAAO,GAAG,IAAA,+BAAmB,GAAE,CAAC,GAAG,CAAC,yDAAkB,CAAC,CAAC;QAC9D,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,8BAAsB,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QACxE,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,+BAAuB,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC5E,CAAC;IAED,4BAA4B;IAC5B,KAAK;QACH,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YACrB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;YACpB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;YACxB,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,8EAA8E;IACtE,WAAW,CAAC,SAAkB;QACpC,MAAM,YAAY,GAAG,SAAS,IAAI,IAAI,CAAC,gBAAgB,CAAC;QACxD,OAAO,YAAY,KAAK,SAAS,IAAI,YAAY,GAAG,CAAC;YACnD,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,YAAY,CAAC,EAAE;YACnD,CAAC,CAAC,EAAE,CAAC;IACT,CAAC;IAEO,eAAe;QACrB,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YAC5C,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;QACjE,CAAC;IACH,CAAC;IAED,0BAA0B;IAC1B,KAAK,CAAC,WAAW,CACf,SAAiB,EACjB,MAAc,EACd,SAAkB;QAElB,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,WAAY,CAAC,WAAW,CAClD,EAAE,SAAS,EAAE,MAAM,EAAE,EACrB,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAC5B,CAAC;QACF,OAAO,QAAQ,CAAC,OAAO,CAAC;IAC1B,CAAC;IAED,uBAAuB;IACvB,KAAK,CAAC,WAAW,CACf,SAAiB,EACjB,SAAkB;QAElB,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,WAAY,CAAC,WAAW,CAClD,EAAE,SAAS,EAAE,EACb,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAC5B,CAAC;QACF,OAAO,QAAQ,CAAC,OAAO,CAAC;IAC1B,CAAC;IAED,sCAAsC;IACtC,KAAK,CAAC,WAAW,CAAC,SAAkB;QAClC,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,WAAY,CAAC,WAAW,CAClD,EAAE,EACF,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAC5B,CAAC;QACF,OAAO,QAAQ,CAAC,UAAU,CAAC;IAC7B,CAAC;IAED,sCAAsC;IACtC,KAAK,CAAC,YAAY,CAChB,SAAiB,EACjB,SAAkB;QAElB,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,YAAa,CAAC,YAAY,CACpD,EAAE,SAAS,EAAE,EACb,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAC5B,CAAC;QACF,OAAO;YACL,SAAS,EAAE,QAAQ,CAAC,SAAS;YAC7B,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,WAAW,EAAE,QAAQ,CAAC,WAAW;YACjC,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,eAAe,EAAE,QAAQ,CAAC,eAAe;YACzC,cAAc,EAAE,QAAQ,CAAC,cAAc;YACvC,YAAY,EAAE,QAAQ,CAAC,YAAY;YACnC,uBAAuB,EAAE,QAAQ,CAAC,uBAAuB;YACzD,yBAAyB,EAAE,QAAQ,CAAC,yBAAyB;YAC7D,WAAW,EAAE,CAAC,QAAQ,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;gBACxD,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,UAAU,EAAE,KAAK,CAAC,UAAU;gBAC5B,YAAY,EAAE,KAAK,CAAC,YAAY;gBAChC,SAAS,EAAE,KAAK,CAAC,SAAS;aAC3B,CAAC,CAAC;SACJ,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,KAAK,CAAC,cAAc,CAClB,SAAiB,EACjB,SAAoC,EACpC,SAAkB;QAElB,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,WAAY,CAAC,mBAAmB,CAC1D;YACE,SAAS;YACT,SAAS,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;gBACtC,MAAM,EAAE,IAAA,2BAAc,EAAC,QAAQ,CAAC;aACjC,CAAC,CAAC;SACJ,EACD,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAC5B,CAAC;QACF,MAAM,MAAM,GAAG,CAAC,QAAQ,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YACrD,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,KAAK,EAAE,KAAK,CAAC,KAAK;SACnB,CAAC,CAAC,CAAC;QACJ,OAAO,CAAC,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAC9D,CAAC;IAED,+BAA+B;IAC/B,KAAK,CAAC,aAAa,CACjB,SAAiB,EACjB,QAAiC,EACjC,SAAkB;QAElB,MAAM,IAAI,CAAC,cAAc,CAAC,SAAS,EAAE,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,CAAC;IAC9D,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,eAAe,CACnB,SAAiB,EACjB,WAAqB,EACrB,SAAkB;QAElB,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,IACE,WAAW,CAAC,MAAM,GAAG,MAAO;YAC5B,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,EAC3F,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;QAChF,CAAC;QACD,OAAO,IAAI,CAAC,WAAY,CAAC,eAAe,CACtC,EAAE,SAAS,EAAE,WAAW,EAAE,EAC1B,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAC5B,CAAC;IACJ,CAAC;IAED,uEAAuE;IACvE,KAAK,CAAC,cAAc,CAClB,SAAiB,EACjB,UAAkB,EAClB,SAAkB;QAElB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,SAAS,EAAE,CAAC,UAAU,CAAC,EAAE,SAAS,CAAC,CAAC;QAC9E,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,aAAa,KAAK,CAAC,EAAE,CAAC;YACvD,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,2BAA2B,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,eAAe,CACnB,SAAiB,EACjB,SAAoC,EACpC,SAAkB;QAElB,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,IAAI,SAAS,CAAC,MAAM,GAAG,IAAK,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;QAC3D,CAAC;QACD,OAAO,IAAI,CAAC,WAAY,CAAC,eAAe,CACtC;YACE,SAAS;YACT,SAAS,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,IAAA,2BAAc,EAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;SAC/E,EACD,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAC5B,CAAC;IACJ,CAAC;IAED,8EAA8E;IAC9E,KAAK,CAAC,cAAc,CAClB,SAAiB,EACjB,QAAiC,EACjC,SAAkB;QAElB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,SAAS,EAAE,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,CAAC;QAC5E,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,aAAa,KAAK,CAAC,EAAE,CAAC;YACvD,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,yBAAyB,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;IAED,0EAA0E;IAC1E,KAAK,CAAC,oBAAoB,CACxB,SAAiB,EACjB,SAAiD,EACjD,SAAkB;QAElB,IAAI,CAAC,eAAe,EAAE,CAAC;QAEvB,KAAK,SAAS,CAAC,CAAC,eAAe;YAC7B,IAAI,KAAK,EAAE,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;gBACvC,MAAM;oBACJ,SAAS;oBACT,MAAM,EAAE,IAAA,2BAAc,EAAC,QAAQ,CAAC;iBACjC,CAAC;YACJ,CAAC;QACH,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,WAAY,CAAC,cAAc,CACrD,eAAe,EAAE,EACjB,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAC5B,CAAC;QACF,OAAO,QAAQ,CAAC,YAAY,CAAC;IAC/B,CAAC;IAED,iEAAiE;IACjE,KAAK,CAAC,MAAM,CAAC,SAAiB,EAAE,SAAkB;QAChD,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,WAAY,CAAC,MAAM,CAC7C,EAAE,SAAS,EAAE,EACb,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAC5B,CAAC;QACF,OAAO,QAAQ,CAAC,OAAO,CAAC;IAC1B,CAAC;IAED,qFAAqF;IACrF,KAAK,CAAC,UAAU,CAAC,SAAiB,EAAE,SAAkB,EAAE,OAAO,GAAG,KAAK;QACrE,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,WAAY,CAAC,UAAU,CACjD,EAAE,SAAS,EAAE,OAAO,EAAE,EACtB,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAC5B,CAAC;QACF,OAAO,QAAQ,CAAC,WAAW,CAAC;IAC9B,CAAC;IAED,kEAAkE;IAClE,KAAK,CAAC,kBAAkB,CACtB,SAAiB,EACjB,SAAkB;QAElB,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,WAAY,CAAC,kBAAkB,CACzD,EAAE,SAAS,EAAE,EACb,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAC5B,CAAC;QACF,OAAO,QAAQ,CAAC,OAAO,CAAC;IAC1B,CAAC;IAED,oEAAoE;IACpE,KAAK,CAAC,OAAO,CAAC,SAAiB,EAAE,SAAkB;QACjD,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,WAAY,CAAC,OAAO,CAC9C,EAAE,SAAS,EAAE,EACb,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAC5B,CAAC;QACF,OAAO,QAAQ,CAAC,WAAW,CAAC;IAC9B,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,MAAM,CACV,SAAiB,EACjB,OAAsB,EACtB,SAAkB;QAElB,IAAI,OAAO,CAAC,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,eAAe,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YAC/G,MAAM,IAAI,KAAK,CAAC,kFAAkF,CAAC,CAAC;QACtG,CAAC;QACD,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,YAAa,CAAC,MAAM,CAC9C;YACE,SAAS;YACT,KAAK,EAAE,IAAA,uBAAU,EAAC,OAAO,CAAC,KAAK,CAAC;YAChC,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,EAAE;YAC1B,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,CAAC;YAC3B,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,EAAE;YACxC,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBACxB,CAAC,CAAC,IAAA,0BAAa,EAAC,OAAO,CAAC,QAAQ,CAAC;gBACjC,CAAC,CAAC,SAAS;YACb,cAAc,EAAE,OAAO,CAAC,cAAc,IAAI,CAAC;YAC3C,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,CAAC;YACvC,SAAS,EAAE,SAAS;YACpB,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,IAAI,KAAK;YACnD,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,KAAK;YACjC,EAAE,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;gBACf,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC,OAAO;gBAC3B,QAAQ,EAAE,OAAO,CAAC,EAAE,CAAC,QAAQ;gBAC7B,aAAa,EAAE,OAAO,CAAC,EAAE,CAAC,aAAa,IAAI,EAAE;aAC9C,CAAC,CAAC,CAAC,SAAS;YACb,WAAW,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,mBAAmB,EAAE,OAAO,CAAC,WAAW,CAAC,mBAAmB,IAAI,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,CAAC,WAAW,IAAI,KAAK,EAAE,oBAAoB,EAAE,OAAO,CAAC,WAAW,CAAC,oBAAoB,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS;SACrP,EACD,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAC5B,CAAC;QAEF,MAAM,UAAU,GAAG,YAAY,CAAC;QAChC,IAAI,OAAO,CAAC,WAAW,EAAE,oBAAoB,IAAI,CAAC,QAAQ,CAAC,sBAAsB,EAAE,CAAC;YAClF,MAAM,IAAI,KAAK,CAAC,2FAA2F,CAAC,CAAC;QAC/G,CAAC;QACD,IAAI,OAAO,CAAC,EAAE,IAAI,QAAQ,CAAC,aAAa,KAAK,UAAU,EAAE,CAAC;YACxD,MAAM,IAAI,KAAK,CAAC,8BAA8B,UAAU,gCAAgC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;QACpI,CAAC;QAED,IAAI,OAAO,CAAC,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;QAC3E,CAAC;QACD,IAAI,OAAO,CAAC,gBAAgB,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,EAAE,CAAC;YACxF,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;QAC9E,CAAC;QACD,MAAM,IAAI,GAAgB,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YACpD,OAAO,EAAE;gBACP,SAAS,EAAE,GAAG,CAAC,OAAO,EAAE,SAAS,IAAI,EAAE;gBACvC,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,KAAK,IAAI,CAAC;aAC/B;YACD,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,eAAe,EAAE,GAAG,CAAC,eAAe;YACpC,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,gBAAgB,EAAE,GAAG,CAAC,gBAAgB;YACtC,MAAM,EAAE,MAAM,CAAC,WAAW,CACxB,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC;gBAChD,IAAI;gBACJ,IAAA,+BAAkB,EAAC,KAAK,CAAC;aAC1B,CAAC,CACH;YACD,aAAa,EAAE,CAAC,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;gBACvD,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,KAAK,EAAE,KAAK,CAAC,KAAK;aACnB,CAAC,CAAC;SACJ,CAAC,CAAC,CAAC;QAEJ,MAAM,OAAO,GAA8B,QAAQ,CAAC,OAAO;YACzD,CAAC,CAAC;gBACE,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC;gBAC3C,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC;gBAC3C,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC;gBACvC,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC;gBACzC,kBAAkB,EAAE,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,kBAAkB,CAAC;aAChE;YACH,CAAC,CAAC,SAAS,CAAC;QAEd,OAAO;YACL,IAAI;YACJ,SAAS,EAAE,QAAQ,CAAC,SAAS;YAC7B,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,aAAa,EAAE,QAAQ,CAAC,aAAa;YACrC,sBAAsB,EAAE,QAAQ,CAAC,sBAAsB;YACvD,gBAAgB,EAAE,QAAQ,CAAC,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU;gBACxF,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,OAAO,EAAE,SAAS,IAAI,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,KAAK,IAAI,CAAC,EAAE;oBAC9H,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,CAAC,aAAa,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;YAC9D,SAAS,EAAE,QAAQ,CAAC,SAAS;YAC7B,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,OAAO;SACR,CAAC;IACJ,CAAC;IAED,4DAA4D;IAC5D,KAAK,CAAC,WAAW,CACf,SAAiB,EACjB,OAAmB,EACnB,SAAkB;QAElB,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,YAAa,CAAC,WAAW,CACnD;gBACE,SAAS;gBACT,OAAO,EAAE;oBACP,SAAS,EAAE,OAAO,CAAC,SAAS;oBAC5B,KAAK,EAAE,OAAO,CAAC,KAAK;iBACrB;aACF,EACD,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAC5B,CAAC;YACF,OAAO;gBACL,MAAM,EAAE,MAAM,CAAC,WAAW,CACxB,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC;oBACrD,IAAI;oBACJ,IAAA,+BAAkB,EAAC,KAAK,CAAC;iBAC1B,CAAC,CACH;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,8BAA8B;YAC9B,IACE,OAAO,KAAK,KAAK,QAAQ;gBACzB,KAAK,KAAK,IAAI;gBACd,MAAM,IAAI,KAAK;gBACf,KAAK,CAAC,IAAI,KAAK,CAAC,EAChB,CAAC;gBACD,OAAO,IAAI,CAAC;YACd,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;CACF;AA9aD,kCA8aC"}

package/dist/converters.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pure conversion helpers between the ergonomic client API and generated
+ * protobuf types. Keeping them free of channel state makes them easy to test
+ * and keeps SummaClient focused on RPC orchestration.
+ */
+import { FieldEntry as PbFieldEntry, FieldValueList as PbFieldValueList, Query as PbQuery, Reranker as PbReranker } from "./generated/summa";
+import type { Query, Reranker } from "./types";
+export declare function buildQuery(q: Query): PbQuery;
+export declare function buildReranker(reranker: Reranker): PbReranker;
+export declare function toFieldEntries(document: Record<string, unknown>): PbFieldEntry[];
+export declare function fromFieldValueList(valueList: PbFieldValueList): unknown;
+//# sourceMappingURL=converters.d.ts.map

package/dist/converters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"converters.d.ts","sourceRoot":"","sources":["../src/converters.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAEL,UAAU,IAAI,YAAY,EAE1B,cAAc,IAAI,gBAAgB,EAIlC,KAAK,IAAI,OAAO,EAChB,QAAQ,IAAI,UAAU,EAEvB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAY,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAiBzD,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,GAAG,OAAO,CAgK5C;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,UAAU,CAY5D;AA+CD,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,YAAY,EAAE,CAgChB;AA0DD,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAGvE"}