@delali/narsil 0.2.2 → 0.2.3-next.32

package/dist/client-DQHB_swQ.d.ts

@@ -0,0 +1,793 @@
+import { e as TaskRecord, b as ImportResult, H as HttpIndexConfig, c as TaskListQuery, T as TaskListPage } from './tasks-CnMLpfk-.js';
+import { P as PartitionConfig, A as AnyDocument, a as InsertOptions } from './schema-emTQfEiX.js';
+import { V as VectorMaintenanceResult, M as MemoryStats, B as BatchResult, L as ListParams, g as ListResult, I as IndexInfo, f as IndexStats, P as PartitionStatsResult, Q as QueryParams, e as QueryResult, h as PreflightResult, i as SuggestParams, j as SuggestResult } from './search-CQ-9bKxo.js';
+
+/**
+ * This is the `fetch` implementation the client sends every request through.
+ *
+ * It matches the global `fetch`, so pass one only to add a proxy agent, a retry
+ * wrapper, or a stub in a test.
+ *
+ * @public
+ */
+type FetchFunction = (input: string, init: RequestInit) => Promise<Response>;
+/**
+ * These are the settings {@link createNarsilClient} accepts.
+ *
+ * Only `url` is required. A client built from the address alone sends no
+ * credentials, and it gives every request 30 seconds to answer.
+ *
+ * @public
+ */
+interface NarsilClientOptions {
+    /**
+     * The server answers at this address. Pass an absolute URL such as
+     * `https://search.example.com`, or a path such as `/search-api` when a
+     * browser reaches the server through its own origin.
+     */
+    url: string;
+    /**
+     * The client sends this key as `authorization: Bearer <key>`, which a server
+     * reads in its `onRequest` hook. For any other scheme, set the header
+     * yourself through {@link NarsilClientOptions.headers}.
+     */
+    apiKey?: string;
+    /** The client sends these headers with every request, and a per-call header of the same name replaces one. */
+    headers?: Record<string, string>;
+    /**
+     * The client waits this many milliseconds for an answer before it fails with
+     * `CLIENT_REQUEST_TIMEOUT`, and it waits 30000 unless you say otherwise. Pass
+     * 0 so that it waits for as long as the server takes. Three routes carry a
+     * corpus or a whole index, so {@link BulkOperations.importDocuments},
+     * {@link AdminOperations.snapshot}, and {@link AdminOperations.restore} set no
+     * deadline of their own until this one arrives.
+     */
+    timeoutMs?: number;
+    /** The client sends every request through this instead of the global `fetch`. */
+    fetch?: FetchFunction;
+    /**
+     * The client stops reading an answer once it passes this many bytes, and
+     * fails with `CLIENT_INVALID_RESPONSE` rather than holding the rest. Set it
+     * where the client runs somewhere a runaway answer would matter, such as a
+     * browser tab, and leave it out to read whatever the server sends. A
+     * snapshot download reads the whole index, so give it its own ceiling
+     * through {@link RequestOptions.maxResponseBytes} or none at all.
+     */
+    maxResponseBytes?: number;
+}
+/**
+ * These settings change the one request a method sends.
+ *
+ * Every client method takes them as its last argument.
+ *
+ * @public
+ */
+interface RequestOptions {
+    /** Aborting this stops the request, which then fails with `CLIENT_REQUEST_ABORTED`. */
+    signal?: AbortSignal;
+    /** The client waits this many milliseconds for this one answer, and 0 waits for as long as the server takes. */
+    timeoutMs?: number;
+    /** The client adds these headers to this request, and one of the same name replaces what it would otherwise send. */
+    headers?: Record<string, string>;
+    /** The client stops reading this one answer past this many bytes, and 0 reads whatever the server sends. */
+    maxResponseBytes?: number;
+}
+
+/**
+ * These methods run the operations that maintain an index: checkpoints,
+ * snapshots, vector maintenance, partitioning, and analysis rebuilds.
+ *
+ * Four of them can run for minutes, so each answers with a {@link TaskRecord}
+ * while the work carries on, and you follow it with
+ * {@link TaskOperations.waitForTask}. The {@link Narsil} methods they mirror
+ * return nothing and finish before they resolve, which is the one place this
+ * client parts from the engine.
+ *
+ * @public
+ */
+interface AdminOperations {
+    /**
+     * Writes everything an index holds to durable storage, so recovery starts
+     * from this point instead of replaying the log from the previous one.
+     *
+     * @param indexName - This names the index to checkpoint.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     */
+    checkpoint(indexName: string, options?: RequestOptions): Promise<void>;
+    /**
+     * Downloads one index as a portable `.nrsl` file, which any Narsil
+     * implementation can read back.
+     *
+     * The whole index crosses the network, so this call sets no deadline of its
+     * own and waits for as long as the download takes until
+     * {@link NarsilClientOptions.timeoutMs} or a per-call `timeoutMs` sets one.
+     *
+     * @param indexName - This names the index to serialise.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The bytes make up the file.
+     */
+    snapshot(indexName: string, options?: RequestOptions): Promise<Uint8Array>;
+    /**
+     * Replaces an index with the contents of a `.nrsl` file, dropping whatever
+     * the index held.
+     *
+     * The load runs as a task, so this resolves once the server has read the
+     * bytes, and the index comes back afterwards.
+     *
+     * @param indexName - This names the index to replace.
+     * @param data - These are the file's bytes.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The record is the task to follow.
+     * @throws A `NarsilError` with `DOC_VALIDATION_FAILED` or an `ENVELOPE_`
+     * code, reported on the task, when the bytes hold no readable snapshot.
+     */
+    restore(indexName: string, data: Uint8Array, options?: RequestOptions): Promise<TaskRecord>;
+    /**
+     * Reports the state of each vector field, and what maintenance would cost.
+     *
+     * @param indexName - This names the index to describe.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns Each vector field appears once.
+     */
+    vectorMaintenanceStatus(indexName: string, options?: RequestOptions): Promise<VectorMaintenanceResult[]>;
+    /**
+     * Reclaims the space removed vectors left behind, which a search would
+     * otherwise scan past.
+     *
+     * @param indexName - This names the index to compact.
+     * @param fieldName - This names one vector field, and omitting it covers
+     * every one.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     */
+    compactVectors(indexName: string, fieldName?: string, options?: RequestOptions): Promise<void>;
+    /**
+     * Rebuilds the vector graphs as a task, so searches run at full speed again.
+     *
+     * @param indexName - This names the index to optimise.
+     * @param fieldName - This names one vector field, and omitting it covers
+     * every one.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The record is the task to follow.
+     */
+    optimizeVectors(indexName: string, fieldName?: string, options?: RequestOptions): Promise<TaskRecord>;
+    /**
+     * Spreads an index across a different number of partitions, as a task.
+     *
+     * The server holds the writes that arrive while it runs and replays them in
+     * order, so an index stays writable throughout.
+     *
+     * @param indexName - This names the index to reshape.
+     * @param targetPartitionCount - The index ends up with this many partitions.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The record is the task to follow.
+     */
+    rebalance(indexName: string, targetPartitionCount: number, options?: RequestOptions): Promise<TaskRecord>;
+    /**
+     * Changes when an index splits into another partition, and how far it may
+     * grow.
+     *
+     * @param indexName - This names the index to reconfigure.
+     * @param partitionConfig - These are the settings to change, and the rest
+     * stay as they are.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @throws A `NarsilError` with `PARTITION_CAPACITY_EXCEEDED` when the new
+     * ceiling falls below what the index already holds.
+     */
+    updatePartitionConfig(indexName: string, partitionConfig: Partial<PartitionConfig>, options?: RequestOptions): Promise<void>;
+    /**
+     * Reanalyses every document in an index, as a task. An index analysed by an
+     * earlier revision of its language module must run this before its terms
+     * match again.
+     *
+     * A result with `analysisStale: true` says the index is due one.
+     *
+     * @param indexName - This names the index to reanalyse.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The record is the task to follow.
+     */
+    rebuildAnalysis(indexName: string, options?: RequestOptions): Promise<TaskRecord>;
+    /**
+     * Reports the server process's heap usage, its estimate of what the indexes
+     * hold, and each worker's heap.
+     *
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The figures are what you size a host from.
+     */
+    getMemoryStats(options?: RequestOptions): Promise<MemoryStats>;
+}
+
+/**
+ * This is a corpus, in whichever form you already hold it.
+ *
+ * The client encodes documents as NDJSON. It sends a string or a byte array
+ * unchanged, so NDJSON read from a file needs no re-encoding.
+ *
+ * @public
+ */
+type ImportSource = AnyDocument[] | string | Uint8Array;
+/**
+ * These methods write and read many documents in one request.
+ *
+ * A batch reports every document's outcome, so one refusal leaves the rest
+ * written. An import streams a whole corpus instead, which the server writes in
+ * bounded batches.
+ *
+ * @public
+ */
+interface BulkOperations {
+    /**
+     * Adds many documents in one request and reports each one's outcome.
+     *
+     * A document the server rejects appears in `failed` under the error that
+     * rejected it, while every other document is still written.
+     *
+     * @param indexName - This names the index that receives the documents.
+     * @param documents - Each document carries its own id, or leaves the server
+     * to generate one.
+     * @param insertOptions - These per-write settings reach the server, and apply
+     * to every document.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The result lists the ids written, and each rejection with its
+     * error.
+     */
+    insertBatch(indexName: string, documents: AnyDocument[], insertOptions?: InsertOptions, options?: RequestOptions): Promise<BatchResult>;
+    /**
+     * Replaces many documents in one request and reports each one's outcome.
+     *
+     * @param indexName - This names the index holding the documents.
+     * @param updates - Each entry names the document to replace and holds its
+     * replacement.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The result lists the ids replaced, and each failure with its
+     * error.
+     */
+    updateBatch(indexName: string, updates: Array<{
+        docId: string;
+        document: AnyDocument;
+    }>, options?: RequestOptions): Promise<BatchResult>;
+    /**
+     * Removes many documents in one request and reports each one's outcome.
+     *
+     * @param indexName - This names the index holding the documents.
+     * @param docIds - These name the documents to remove.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The result lists the ids removed, and each failure with its error.
+     */
+    removeBatch(indexName: string, docIds: string[], options?: RequestOptions): Promise<BatchResult>;
+    /**
+     * Reads many documents by id in one request.
+     *
+     * The result leaves out an id the index does not hold while the call still
+     * succeeds, so compare the size against what you asked for.
+     *
+     * @param indexName - This names the index holding the documents.
+     * @param docIds - These are the ids to read.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The map holds every document found, keyed by id.
+     */
+    getMultiple(indexName: string, docIds: string[], options?: RequestOptions): Promise<Map<string, AnyDocument>>;
+    /**
+     * Pages through the stored documents without searching, in document-id order
+     * until the parameters name a sort.
+     *
+     * @typeParam T - This is the shape of the stored documents.
+     * @param indexName - This names the index to page through.
+     * @param params - These set the page size, the cursor, and any filter, sort,
+     * or projection.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The page holds the documents, and the cursor that reaches the next
+     * one.
+     */
+    listDocuments<T = AnyDocument>(indexName: string, params?: ListParams, options?: RequestOptions): Promise<ListResult<T>>;
+    /**
+     * Loads a corpus in one request and answers once the whole load has finished.
+     *
+     * The server writes the documents in bounded batches, so one bad record never
+     * abandons the rest. Where a load would outlast a proxy's response timeout,
+     * reach for {@link BulkOperations.startImport}, which answers straight away
+     * and reports progress through a task.
+     *
+     * This call sets no deadline of its own, so it waits for as long as the load
+     * takes until {@link NarsilClientOptions.timeoutMs} or a per-call `timeoutMs`
+     * sets one.
+     *
+     * @param indexName - This names the index that receives the corpus.
+     * @param source - These are the documents, or the NDJSON you already hold.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The result counts what the server accepted and refused, and lists
+     * the first refusals.
+     * @throws A `NarsilError` with `PAYLOAD_TOO_LARGE` when the corpus passes the
+     * server's import limit, which defaults to 100 MB.
+     */
+    importDocuments(indexName: string, source: ImportSource, options?: RequestOptions): Promise<ImportResult>;
+    /**
+     * Starts a corpus load as a task, and answers once the server has read the
+     * body. A load longer than a request timeout runs this way.
+     *
+     * Follow the returned record with {@link TaskOperations.waitForTask}, which
+     * reports the bytes read as the load runs. Stop the load with
+     * {@link TaskOperations.cancelTask}.
+     *
+     * This call sets no deadline of its own, so it waits for the server to read
+     * the body until {@link NarsilClientOptions.timeoutMs} or a per-call
+     * `timeoutMs` sets one.
+     *
+     * @param indexName - This names the index that receives the corpus.
+     * @param source - These are the documents, or the NDJSON you already hold.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The record is the task to poll.
+     * @throws A `NarsilError` with `NOT_FOUND` when the server predates the
+     * asynchronous import, which {@link ServerOperations.supports} reports before
+     * you call.
+     */
+    startImport(indexName: string, source: ImportSource, options?: RequestOptions): Promise<TaskRecord>;
+}
+
+/**
+ * This says what an upsert did, which is how {@link DocumentOperations.put}
+ * reports whether the id already held a document.
+ *
+ * @public
+ */
+interface PutResult {
+    /** The document is stored under this id. */
+    id: string;
+    /** This is true when the id held nothing before, and false when the write replaced a document. */
+    created: boolean;
+}
+/**
+ * These methods write and read one document at a time over HTTP.
+ *
+ * Each one has the name of the {@link Narsil} method it mirrors. Reach for
+ * {@link BulkOperations} to load a corpus, because a document per request would
+ * cost a round trip each.
+ *
+ * @public
+ */
+interface DocumentOperations {
+    /**
+     * Adds one document to an index and returns the id it is stored under.
+     *
+     * The id comes from the `docId` argument when you pass one, otherwise from
+     * the document's own `id` field, and otherwise the server generates it.
+     *
+     * @param indexName - This names the index that receives the document.
+     * @param document - Its fields must match the types the schema declares.
+     * @param docId - Pass an id to control it yourself, or omit it and read the
+     * returned value.
+     * @param insertOptions - These per-write settings reach the server, such as
+     * skipping the defensive copy.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The document is stored under this id.
+     */
+    insert(indexName: string, document: AnyDocument, docId?: string, insertOptions?: InsertOptions, options?: RequestOptions): Promise<string>;
+    /**
+     * Reads one stored document back.
+     *
+     * @param indexName - This names the index holding the document.
+     * @param docId - This names the document to read.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The stored document comes back, and `undefined` says the index
+     * holds no such id.
+     * @throws A `NarsilError` with `INDEX_NOT_FOUND` for an unknown index.
+     */
+    get(indexName: string, docId: string, options?: RequestOptions): Promise<AnyDocument | undefined>;
+    /**
+     * Reports whether an index holds a document under an id, without returning
+     * the document itself.
+     *
+     * @param indexName - This names the index to look in.
+     * @param docId - This is the id to look for.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns This is true when the id holds a document.
+     */
+    has(indexName: string, docId: string, options?: RequestOptions): Promise<boolean>;
+    /**
+     * Writes a document at an id, whether or not one is already there, which
+     * suits an application that assigns its own identifiers.
+     *
+     * @param indexName - This names the index that receives the document.
+     * @param docId - This is the id to write at.
+     * @param document - Its fields must match the types the schema declares.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The result names the id, and says whether the write created the
+     * document or replaced one.
+     */
+    put(indexName: string, docId: string, document: AnyDocument, options?: RequestOptions): Promise<PutResult>;
+    /**
+     * Replaces the stored document at an id.
+     *
+     * @param indexName - This names the index holding the document.
+     * @param docId - This names the document to replace.
+     * @param document - This replacement goes through the same schema validation
+     * an insert would.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @throws A `NarsilError` with `DOC_NOT_FOUND` when the index holds no such
+     * document.
+     */
+    update(indexName: string, docId: string, document: AnyDocument, options?: RequestOptions): Promise<void>;
+    /**
+     * Removes one document.
+     *
+     * @param indexName - This names the index holding the document.
+     * @param docId - This names the document to remove.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @throws A `NarsilError` with `DOC_NOT_FOUND` when the index holds no such
+     * document.
+     */
+    remove(indexName: string, docId: string, options?: RequestOptions): Promise<void>;
+    /**
+     * Counts the documents in an index.
+     *
+     * @param indexName - This names the index to count.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The count covers every document the index holds.
+     */
+    countDocuments(indexName: string, options?: RequestOptions): Promise<number>;
+}
+
+/**
+ * These methods create, list, describe, and drop indexes over HTTP.
+ *
+ * Each one has the name of the {@link Narsil} method it mirrors, so a call
+ * written against an embedded engine works against a server.
+ *
+ * @public
+ */
+interface IndexOperations {
+    /**
+     * Creates an index you can insert documents into and query.
+     *
+     * The configuration covers whatever JSON can express of the engine's own. A
+     * custom tokeniser, a stop-word function, and an embedding adapter are all
+     * functions, so name a language and a server-registered adapter instead.
+     *
+     * @param name - Every later call uses this name to reach the index.
+     * @param config - This holds the schema, the language, and the partitioning
+     * and scoring settings, in the form JSON can express.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @throws A `NarsilError` with `INDEX_ALREADY_EXISTS` when the name is taken,
+     * and with `CONFIG_INVALID` when the server refuses the settings.
+     */
+    createIndex(name: string, config: HttpIndexConfig, options?: RequestOptions): Promise<void>;
+    /**
+     * Lists every index the server holds, with its size and its language.
+     *
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns Each index appears once, in creation order.
+     */
+    listIndexes(options?: RequestOptions): Promise<IndexInfo[]>;
+    /**
+     * Removes an index and everything it holds. The documents do not come back.
+     *
+     * @param name - This names the index to drop.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     */
+    dropIndex(name: string, options?: RequestOptions): Promise<void>;
+    /**
+     * Returns one index's document count, partition count, memory estimate,
+     * language, and schema.
+     *
+     * @param indexName - This names the index to describe.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The figures describe the index as it stands now.
+     * @throws A `NarsilError` with `INDEX_NOT_FOUND` for an unknown name.
+     */
+    getStats(indexName: string, options?: RequestOptions): Promise<IndexStats>;
+    /**
+     * Returns per-partition figures for one index, which is where you look when
+     * an index fills unevenly.
+     *
+     * @param indexName - This names the index to describe.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns Each partition appears once, in partition order.
+     */
+    getPartitionStats(indexName: string, options?: RequestOptions): Promise<PartitionStatsResult[]>;
+    /**
+     * Removes every document from an index while the index itself stays, with its
+     * schema and its settings.
+     *
+     * @param indexName - This names the index to empty.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     */
+    clear(indexName: string, options?: RequestOptions): Promise<void>;
+}
+
+/**
+ * These methods search an index over HTTP.
+ *
+ * Each one has the name of the {@link Narsil} method it mirrors and takes the
+ * same parameters, so a query written against an embedded engine runs against a
+ * server unchanged.
+ *
+ * @public
+ */
+interface SearchOperations {
+    /**
+     * Runs a search and returns the ranked hits.
+     *
+     * The parameters hold the text, the filters, the sort, the facets, the
+     * grouping, and the vector or hybrid settings, exactly as the engine takes
+     * them. Where a vector search names `text` instead of a vector, the server
+     * must hold the embedding adapter the index was created with.
+     *
+     * @typeParam T - This is the shape of the stored documents, which flows
+     * through to each hit's `document`.
+     * @param indexName - This names the index to search.
+     * @param params - These carry everything the search asks for.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The result holds the hits, the total match count, and whatever
+     * else the query asked for.
+     * @throws A `NarsilError` with `SEARCH_RESULT_WINDOW_EXCEEDED` when `offset`
+     * plus `limit` passes the server's result window, which the cursor pages
+     * beyond.
+     */
+    query<T = AnyDocument>(indexName: string, params: QueryParams, options?: RequestOptions): Promise<QueryResult<T>>;
+    /**
+     * Counts what a search would match, without building or ranking a single hit,
+     * which is enough to show a result count beside a filter.
+     *
+     * @param indexName - This names the index to count in.
+     * @param params - These are the parameters {@link SearchOperations.query}
+     * takes.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The result holds the match count and how long it took.
+     */
+    preflight(indexName: string, params: QueryParams, options?: RequestOptions): Promise<PreflightResult>;
+    /**
+     * Completes a prefix from the terms the index holds, ready to offer as
+     * you-type suggestions.
+     *
+     * @param indexName - This names the index to complete from.
+     * @param params - These set the prefix and how many completions to return.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The completions run most widely used first.
+     */
+    suggest(indexName: string, params: SuggestParams, options?: RequestOptions): Promise<SuggestResult>;
+}
+
+/**
+ * This is what a server reports about the build it runs, so you can tie a
+ * result or an incident to the exact code that produced it.
+ *
+ * The values are whatever the build stamped in, so an unstamped build reports
+ * nulls.
+ *
+ * @public
+ */
+interface ServerVersion {
+    /** This names the product, and is always `narsil`. */
+    name: string;
+    /** The server was built from this package version. */
+    version: string | null;
+    /** The server was built from this git commit. */
+    gitSha: string | null;
+    /** This is true when the working tree held uncommitted changes at build time. */
+    dirty: boolean;
+}
+/**
+ * These methods ask a server what it is and what it serves, before you ask it
+ * for any work.
+ *
+ * Every route behind them answers without credentials, so a probe or a health
+ * check reaches them without a key.
+ *
+ * @public
+ */
+interface ServerOperations {
+    /**
+     * Reports the build the server runs.
+     *
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The report names the package version and the commit the server was
+     * built from.
+     */
+    version(options?: RequestOptions): Promise<ServerVersion>;
+    /**
+     * Lists the optional routes and modes this server serves.
+     *
+     * A server that predates a capability leaves it out, while one that predates
+     * the whole endpoint reports an empty list and the call still succeeds.
+     *
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The list names each capability the server announces.
+     */
+    capabilities(options?: RequestOptions): Promise<string[]>;
+    /**
+     * Reports whether the server serves one optional capability, such as
+     * `ASYNC_IMPORT_CAPABILITY`.
+     *
+     * The client reads the answer once and keeps it for its own lifetime, because
+     * a server cannot take on a capability without restarting.
+     *
+     * @param capability - This names the capability to ask about.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * the one request that reads the answer.
+     * @returns This is true when the server announced it.
+     */
+    supports(capability: string, options?: RequestOptions): Promise<boolean>;
+    /**
+     * Reports whether the server answers HTTP at all.
+     *
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns This is true when the liveness probe answered.
+     * @throws A `NarsilError` with `CLIENT_CONNECTION_FAILED` when the client
+     * cannot reach the server, which is a different failure from a server that
+     * answers and reports itself unready.
+     */
+    isAlive(options?: RequestOptions): Promise<boolean>;
+    /**
+     * Reports whether the server is ready to take work, which turns false while
+     * it starts up and again once it starts draining.
+     *
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns This is true when the readiness probe answered ready.
+     * @throws A `NarsilError` with `CLIENT_CONNECTION_FAILED` when the client
+     * cannot reach the server.
+     */
+    isReady(options?: RequestOptions): Promise<boolean>;
+}
+
+/**
+ * These settings say how {@link TaskOperations.waitForTask} follows a task.
+ *
+ * `timeoutMs` bounds each poll request, as it does everywhere else, while
+ * `waitTimeoutMs` bounds the whole wait.
+ *
+ * @public
+ */
+interface WaitForTaskOptions extends RequestOptions {
+    /**
+     * The client asks the server again this often, and every 250 ms unless you
+     * say otherwise, which is how often a running import writes its progress.
+     */
+    pollIntervalMs?: number;
+    /**
+     * The wait fails with `CLIENT_TASK_TIMEOUT` after this many milliseconds
+     * while the task keeps running. It waits for as long as the task takes unless
+     * you set this.
+     */
+    waitTimeoutMs?: number;
+    /**
+     * The client calls this each time the record changes, which is what a
+     * progress bar renders. It calls it for the terminal record as well, and
+     * never twice for the same figures.
+     */
+    onProgress?: (record: TaskRecord) => void;
+}
+/**
+ * These methods follow the long-running operations: an import, a restore, a
+ * rebalance, a vector optimisation, and an analysis rebuild.
+ *
+ * Each of those answers straight away with a task record, so these methods
+ * read, follow, and stop the work behind it.
+ *
+ * @public
+ */
+interface TaskOperations {
+    /**
+     * Reads one task record back.
+     *
+     * @param taskId - This names the task to read.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The record comes back, and `null` says the server holds no such
+     * task, which is also the answer once a record has gone.
+     */
+    getTask(taskId: string, options?: RequestOptions): Promise<TaskRecord | null>;
+    /**
+     * Lists task records, newest first.
+     *
+     * @param query - This says which records to keep and where the page starts.
+     * Omit it for the newest 20 records the server still holds.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The page holds the records, the total the filters matched, and the
+     * offset the next page starts at.
+     */
+    listTasks(query?: TaskListQuery, options?: RequestOptions): Promise<TaskListPage>;
+    /**
+     * Asks a running task to stop.
+     *
+     * The work stops between units, so the task reaches `cancelled` only once it
+     * has stopped, and a request that comes too late leaves it `succeeded`.
+     * Whatever the task had already written stays written.
+     *
+     * @param taskId - This names the task to stop.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The record shows the task as it stood when the cancel arrived.
+     * @throws A `NarsilError` with `TASK_NOT_FOUND` for an unknown task,
+     * `TASK_NOT_CANCELLABLE` for one that has already finished, and
+     * `TASK_OWNED_BY_ANOTHER_INSTANCE` when another server instance runs it.
+     */
+    cancelTask(taskId: string, options?: RequestOptions): Promise<TaskRecord>;
+    /**
+     * Polls a task until it finishes, reporting each step on the way.
+     *
+     * A failed task comes back with `status: 'failed'` and its `error` set while
+     * this method throws nothing, because a part-finished import still reports
+     * what it indexed. Read the status you get back.
+     *
+     * @param taskId - This names the task to follow.
+     * @param options - These set the poll interval, the overall deadline, the
+     * progress callback, and the signal, per-request deadline, and headers.
+     * @returns The record shows the task at whichever terminal status it reached.
+     * @throws A `NarsilError` with `CLIENT_TASK_TIMEOUT` when the wait passes
+     * `waitTimeoutMs`, and with `TASK_NOT_FOUND` when the record expires before
+     * the task finishes.
+     */
+    waitForTask(taskId: string, options?: WaitForTaskOptions): Promise<TaskRecord>;
+}
+
+/**
+ * This client reaches one Narsil server, and it runs every operation that
+ * server serves.
+ *
+ * Every method has the name the embedded engine uses, so a call written against
+ * {@link Narsil} works here. HTTP forces two differences: every method takes
+ * per-call request settings as its last argument, and the operations that can
+ * run for minutes answer with a task record while the work carries on.
+ *
+ * The client sends through `fetch` alone, so it runs in a browser, in Node, and
+ * in an edge function.
+ *
+ * @public
+ */
+interface NarsilClient extends IndexOperations, DocumentOperations, BulkOperations, SearchOperations, TaskOperations, AdminOperations, ServerOperations {
+}
+/**
+ * Builds a client for one Narsil server.
+ *
+ * The client opens no connection, and it holds no state beyond the
+ * capabilities it has read, so nothing needs closing. Keep one client for the
+ * application's lifetime.
+ *
+ * @param options - These set the server address, the credentials, and the
+ * defaults every request inherits.
+ * @returns The client is ready to use.
+ * @throws A `NarsilError` with `CONFIG_INVALID` when it cannot read the address
+ * as a URL.
+ *
+ * @public
+ */
+declare function createNarsilClient(options: NarsilClientOptions): NarsilClient;
+
+export { type AdminOperations as A, type BulkOperations as B, type DocumentOperations as D, type FetchFunction as F, type ImportSource as I, type NarsilClient as N, type PutResult as P, type RequestOptions as R, type SearchOperations as S, type TaskOperations as T, type WaitForTaskOptions as W, type IndexOperations as a, type NarsilClientOptions as b, type ServerOperations as c, type ServerVersion as d, createNarsilClient as e };