@docslurp/contrib-search-compat 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 DocSlurp, Inc. and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSES/Apache-2.0.txt

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Support. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 DocSlurp, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,12 @@
+DocSlurp
+Copyright 2025-2026 DocSlurp, Inc. and contributors
+
+Earlier versions were distributed under the Apache License, Version 2.0.
+Existing license grants remain in effect for those versions. Retain applicable
+upstream copyright, patent, license and attribution notices when redistributing
+code from those versions. The accompanying Apache-2.0 text preserves the
+previous repository notice and supplies the future license for SSPL versions.
+
+Third-party components retain their own licenses. DocSlurp's license does not
+relicense dependencies, models, fonts, assets or separately licensed files.
+See THIRD_PARTY_NOTICES.md in the repository for the compatibility review.

package/README.md

@@ -1,3 +1,105 @@
-# Temporary Holding Version
+# @docslurp/contrib-search-compat
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[Package docs](https://docslurp.io/docs/packages/contrib-search-compat) · [GitHub](https://github.com/DocSlurp/docslurp-oss/tree/main/packages/contrib-search-compat) · [npm](https://www.npmjs.com/package/@docslurp/contrib-search-compat)
+
+Keep your existing search calls and get DocSlurp results with citations. One package, one subpath per client:
+
+| Subpath | Replaces | Entry point |
+| --- | --- | --- |
+| `@docslurp/contrib-search-compat/algolia` | Algolia (Lite-style and `initIndex()`) | `docslurpAlgoliaClient()` |
+| `@docslurp/contrib-search-compat/meilisearch` | Meilisearch | `createDocSlurpMeilisearchClient()` |
+| `@docslurp/contrib-search-compat/typesense` | Typesense | `createDocSlurpTypesenseClient()` |
+| `@docslurp/contrib-search-compat/pagefind` | Pagefind | `createDocSlurpPagefind()` |
+
+Requires `@docslurp/sdk` 0.4.0 or newer. The Meilisearch, Typesense and Pagefind subpaths are the same adapters you can import from `@docslurp/sdk/search-adapters`. In the browser, pass a browser key as `clientKey`. Workspace references (`indexName`, `index(...)`, `collections(...)`, `workspace`) accept a workspace ID, slug or `default`; the `workspace` option also accepts a name.
+
+Renamed from `@docslurp/compat-algolia`, `@docslurp/compat-meilisearch`, `@docslurp/compat-typesense` and `@docslurp/compat-pagefind`; see [`docs/releases.md`](https://github.com/DocSlurp/docslurp-oss/blob/main/docs/releases.md) for the migration.
+
+## Algolia
+
+Move Algolia search code to DocSlurp without rewriting your calls. This client keeps the current Lite-style methods (`searchSingleIndex`, `search`, `searchForFacetValues`) and the legacy `initIndex()` surface, plus settings, synonym and rule sync, click and conversion events, and imports. Results come from DocSlurp retrieval and keep their citations.
+
+### Search from the browser
+
+```ts
+import { docslurpAlgoliaClient } from "@docslurp/contrib-search-compat/algolia";
+
+const client = docslurpAlgoliaClient({
+  apiUrl: process.env.PUBLIC_DOCSLURP_API_URL!,
+  clientKey: process.env.PUBLIC_DOCSLURP_CLIENT_KEY!, // A browser key: search-only, limited to your allowed websites.
+  glossary: { ml: ["machine learning"] } // Optional synonyms, expanded locally before each query.
+});
+
+// indexName is a workspace slug, UUID or "default".
+const res = await client.searchSingleIndex({
+  indexName: "product-manuals",
+  searchParams: { query: "ml models", hitsPerPage: 10 }
+});
+console.log(res.hits);
+
+const facets = await client.searchForFacetValues({
+  indexName: "product-manuals",
+  facetName: "filename",
+  searchForFacetValuesRequest: { facetQuery: "invoice" }
+});
+console.log(facets.facetHits);
+
+// Report a click on a result.
+await client.clickedObjectIDsAfterSearch({ indexName: "product-manuals", queryID: res.queryID, objectIDs: ["doc-1:0"] });
+```
+
+### Sync settings, synonyms and rules from your server
+
+Reads such as `getSettings` work with a browser key. Writes (`setSettings`, `saveSynonyms`, `saveRules`, `importIndex`) need a server key with the `workspaces:manage` scope, which only organization owners and admins can grant, and the key owner must be able to edit the workspace. Run them from a backend job or migration script, never in the browser:
+
+```ts
+const admin = docslurpAlgoliaClient({
+  apiUrl: "https://docslurp.io",
+  clientKey: process.env.DOCSLURP_API_KEY!, // A server key with the workspaces:manage scope. The option is named clientKey.
+});
+
+const settings = await admin.getSettings({ indexName: "product-manuals" });
+await admin.saveSynonyms({ indexName: "product-manuals", synonymHit: [{ type: "synonym", synonyms: ["invoice", "bill"] }] });
+await admin.saveRules({ indexName: "product-manuals", rules: [{ objectID: "rule-1", condition: { pattern: "invoice" } }] });
+```
+
+[`@docslurp/contrib-algolia-server`](https://docslurp.io/docs/packages/contrib-algolia-server) wraps these writes with server-side helper names.
+
+### Supported call shapes
+
+- Legacy `index.search("query", { hitsPerPage: 10 })` and `index.search({ query: "query", hitsPerPage: 10 })` both work.
+- InstantSearch-style `client.search([{ indexName, params: { query } }])` is converted to the API's flat request shape. The current `{ requests }` form works too, with up to 10 requests.
+- The client follows common Algolia request and response shapes, but ranking comes from DocSlurp retrieval, not Algolia's ranking.
+- `filters` and `facetFilters` support `tags`, `mime_type`, `filename` (exact, case-sensitive match), `filenameContains` (case-insensitive literal substring), `language`, `heading`, `documentId` and `runId` clauses joined with `AND`. `OR` works only between values of one `tags` or `mime_type` attribute, for example `(tags:a OR tags:b)` or `facetFilters: [["tags:a", "tags:b"]]`, because DocSlurp matches any of the listed values; each attribute may appear in one `AND` clause. `numericFilters` (and numeric clauses in `filters`) support `page` with `=`, `<`, `<=`, `>`, `>=` and `page:1 TO 5`.
+- Any parameter that narrows results and is outside that subset is rejected, never ignored, so a filter you rely on for scoping cannot silently stop applying. That covers other attributes, `NOT` and `-` negation, `!=`, mixed `AND`/`OR` without parentheses, nested groups, malformed syntax, non-empty `tagFilters`, geo parameters, `restrictSearchableAttributes`, `ruleContexts`, `distinct`, `offset`/`length`, `advancedSyntax`, the URL-encoded `params` string and any unknown or misspelled key (such as `facetfilters`). Limits: `filters` up to 8 KB, 100 clauses in total, 1 KB per clause, 255 characters per filename value, 100 entries per `facetFilters`/`numericFilters` array, arrays nested at most two levels deep and a 1 MB request body.
+- Ranking, presentation and analytics parameters that never change which hits match are accepted with any value and ignored: `analytics`, `analyticsTags`, `clickAnalytics`, `getRankingInfo`, `userToken`, `enablePersonalization`, `personalizationImpact`, `enableABTest`, `enableReRanking`, `percentileComputation`, `attributesToHighlight`, `attributesToSnippet`, `snippetEllipsisText`, `restrictHighlightAndSnippetArrays`, `responseFields`, `maxValuesPerFacet`, `sortFacetValuesBy`, `facetingAfterDistinct`, `optionalFilters`, `sumOrFiltersScores` and `aroundPrecision`. `type` is accepted as `"default"` on every route.
+- Query-matching parameters change how many hits match, and DocSlurp does not apply them, so they are accepted only with Algolia's default or a more permissive value: `typoTolerance: true`, `allowTyposOnNumericTokens: true`, `decompoundQuery: true`, `minWordSizefor1Typo` up to 4, `minWordSizefor2Typos` up to 8, and any boolean or language list for `ignorePlurals`, `removeStopWords`, `queryLanguages` and `naturalLanguages`. Restrictive values, such as `typoTolerance: false`, `"min"` or `"strict"`, and a non-empty `keepDiacriticsOnCharacters`, are rejected. Empty or disabled defaults such as `tagFilters: ""` and `aroundLatLngViaIP: false` are accepted, so standard InstantSearch requests work.
+- Rejections are HTTP 400 with `code: "UNSUPPORTED_SEARCH_OPTION"` and a message naming the clause or parameter, returned before any retrieval runs; in a batched `search()` one bad request rejects the whole batch. The client throws a `SearchCompatibilityError` (exported from this subpath) for these responses, and also for legacy `{ indexName, params }` entries whose `params` is not a plain object.
+- Facet counts and `searchForFacetValues` cover `filename` only, counted within the retrieved results. Highlight tags return the passage text without match markup.
+- `searchSingleIndex` with an empty `query` returns HTTP 400; batched requests with an empty query or an unknown index name return zero hits.
+
+## Meilisearch
+
+`createDocSlurpMeilisearchClient()` supports `index(workspace).search(q, params)`.
+
+```ts
+import { createDocSlurpMeilisearchClient } from "@docslurp/contrib-search-compat/meilisearch";
+```
+
+## Typesense
+
+`createDocSlurpTypesenseClient()` supports `collections(workspace).documents().search(params)` and `multiSearch.perform()` (up to 10 searches).
+
+```ts
+import { createDocSlurpTypesenseClient } from "@docslurp/contrib-search-compat/typesense";
+```
+
+## Pagefind
+
+`createDocSlurpPagefind()` supports `search(term)` with lazy `data()` results. It requires `workspace` and a `resolveUrl` function that maps each citation to a public page URL.
+
+```ts
+import { createDocSlurpPagefind } from "@docslurp/contrib-search-compat/pagefind";
+```
+
+See the [search integrations guide](https://docslurp.io/docs/search-integrations) for contract limits, source routing, CMS and platform setup, and agent handoffs.

package/dist/algolia.d.ts

@@ -0,0 +1,190 @@
+import { SearchCompatibilityError } from "@docslurp/sdk/search-adapters";
+export { SearchCompatibilityError };
+export type AlgoliaSearchRequest = {
+    query: string;
+    page?: number;
+    hitsPerPage?: number;
+    filters?: string;
+    facetFilters?: string[] | string[][];
+    numericFilters?: string[] | string[][];
+    facets?: string[];
+    attributesToRetrieve?: string[];
+    highlightPreTag?: string;
+    highlightPostTag?: string;
+};
+export type AlgoliaMultipleQueriesRequest = {
+    requests: Array<AlgoliaSearchRequest & {
+        indexName: string;
+    }>;
+};
+export type AlgoliaLegacyQueries = Array<{
+    indexName: string;
+    params: AlgoliaSearchRequest;
+}>;
+export type AlgoliaSearchSingleIndexRequest = {
+    indexName: string;
+    searchParams: AlgoliaSearchRequest;
+};
+export type AlgoliaSearchForFacetValuesRequest = {
+    indexName: string;
+    facetName: string;
+    searchForFacetValuesRequest: {
+        facetQuery: string;
+        query?: string;
+        filters?: string;
+        facetFilters?: string[] | string[][];
+        numericFilters?: string[] | string[][];
+        maxFacetHits?: number;
+    };
+};
+export type AlgoliaHit = Record<string, unknown> & {
+    objectID: string;
+};
+export type AlgoliaSearchResponse = {
+    hits: AlgoliaHit[];
+    page: number;
+    nbHits: number;
+    nbPages: number;
+    hitsPerPage: number;
+    processingTimeMS: number;
+    query: string;
+    queryID?: string;
+    params: string;
+    facets?: Record<string, Record<string, number>>;
+    exhaustiveNbHits?: boolean;
+};
+export type AlgoliaCompatSettings = Record<string, unknown>;
+export type AlgoliaSynonymEntry = {
+    objectID?: string;
+    type?: "synonym" | "oneWaySynonym";
+    synonyms?: string[];
+    input?: string;
+};
+export type AlgoliaRuleEntry = Record<string, unknown>;
+export type AlgoliaFacetHit = {
+    value: string;
+    highlighted: string;
+    count: number;
+};
+export interface DocSlurpAlgoliaClientOptions {
+    apiUrl: string;
+    clientKey: string;
+    glossary?: Record<string, string[]>;
+    fetch?: typeof globalThis.fetch;
+}
+export declare function docslurpAlgoliaClient(opts: DocSlurpAlgoliaClientOptions): {
+    initIndex: (indexName: string) => {
+        search: (query: string | AlgoliaSearchRequest, params?: Omit<AlgoliaSearchRequest, "query">) => Promise<AlgoliaSearchResponse>;
+        getSettings: () => Promise<AlgoliaCompatSettings>;
+        setSettings: (settings: AlgoliaCompatSettings) => Promise<{
+            ok: boolean;
+            settings: AlgoliaCompatSettings;
+        }>;
+        searchSynonyms: () => Promise<{
+            hits: AlgoliaSynonymEntry[];
+        }>;
+        saveSynonyms: (synonyms: AlgoliaSynonymEntry[]) => Promise<{
+            updatedAt: string;
+            count: number;
+        }>;
+        searchRules: () => Promise<{
+            hits: AlgoliaRuleEntry[];
+        }>;
+        saveRules: (rules: AlgoliaRuleEntry[]) => Promise<{
+            updatedAt: string;
+            count: number;
+        }>;
+        searchForFacetValues: (facetName: string, requestBody: Omit<AlgoliaSearchForFacetValuesRequest["searchForFacetValuesRequest"], "facetName">) => Promise<{
+            facetHits: AlgoliaFacetHit[];
+            exhaustiveFacetsCount: boolean;
+        }>;
+        getAnalytics: () => Promise<{
+            queries: number;
+            zeroResults: number;
+            clicks: number;
+            conversions: number;
+        }>;
+        clickedObjectIDsAfterSearch: (payload: {
+            queryID?: string;
+            objectIDs: string[];
+            positions?: number[];
+        }) => Promise<{
+            status: string;
+        }>;
+        convertedObjectIDsAfterSearch: (payload: {
+            queryID?: string;
+            objectIDs: string[];
+            eventName?: string;
+        }) => Promise<{
+            status: string;
+        }>;
+    };
+    searchSingleIndex: (requestBody: AlgoliaSearchSingleIndexRequest) => Promise<AlgoliaSearchResponse>;
+    searchForFacetValues: (requestBody: AlgoliaSearchForFacetValuesRequest) => Promise<{
+        facetHits: AlgoliaFacetHit[];
+        exhaustiveFacetsCount: boolean;
+    }>;
+    getSettings: (requestBody: {
+        indexName: string;
+    }) => Promise<AlgoliaCompatSettings>;
+    setSettings: (requestBody: {
+        indexName: string;
+        indexSettings: AlgoliaCompatSettings;
+    }) => Promise<{
+        ok: boolean;
+        settings: AlgoliaCompatSettings;
+    }>;
+    searchSynonyms: (requestBody: {
+        indexName: string;
+    }) => Promise<{
+        hits: AlgoliaSynonymEntry[];
+    }>;
+    saveSynonyms: (requestBody: {
+        indexName: string;
+        synonymHit: AlgoliaSynonymEntry[];
+    }) => Promise<{
+        updatedAt: string;
+        count: number;
+    }>;
+    searchRules: (requestBody: {
+        indexName: string;
+    }) => Promise<{
+        hits: AlgoliaRuleEntry[];
+    }>;
+    saveRules: (requestBody: {
+        indexName: string;
+        rules: AlgoliaRuleEntry[];
+    }) => Promise<{
+        updatedAt: string;
+        count: number;
+    }>;
+    getAnalytics: (requestBody: {
+        indexName: string;
+    }) => Promise<{
+        queries: number;
+        zeroResults: number;
+        clicks: number;
+        conversions: number;
+    }>;
+    clickedObjectIDsAfterSearch: (requestBody: {
+        indexName: string;
+        queryID?: string;
+        objectIDs: string[];
+        positions?: number[];
+    }) => Promise<{
+        status: string;
+    }>;
+    convertedObjectIDsAfterSearch: (requestBody: {
+        indexName: string;
+        queryID?: string;
+        objectIDs: string[];
+        eventName?: string;
+    }) => Promise<{
+        status: string;
+    }>;
+    search: (requestBody: AlgoliaMultipleQueriesRequest | AlgoliaLegacyQueries) => Promise<{
+        results: AlgoliaSearchResponse[];
+    }>;
+    importIndex: (payload: Record<string, unknown>) => Promise<unknown>;
+};
+export default docslurpAlgoliaClient;

package/dist/algolia.js

@@ -0,0 +1,220 @@
+import { SearchCompatibilityError, unsupportedSearchOptionMessage } from "@docslurp/sdk/search-adapters";
+export { SearchCompatibilityError };
+function expandQuery(query, glossary) {
+    if (!glossary || Object.keys(glossary).length === 0)
+        return query;
+    const norm = {};
+    for (const [k, v] of Object.entries(glossary))
+        norm[k.toLowerCase()] = v;
+    const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
+    const out = [];
+    let i = 0;
+    const alt = (t) => `(${[t, ...(norm[t] ?? [])].join(" OR ")})`;
+    while (i < tokens.length) {
+        if (i + 2 < tokens.length) {
+            const tri = `${tokens[i]} ${tokens[i + 1]} ${tokens[i + 2]}`;
+            if (norm[tri]) {
+                out.push(alt(tri));
+                i += 3;
+                continue;
+            }
+        }
+        if (i + 1 < tokens.length) {
+            const bi = `${tokens[i]} ${tokens[i + 1]}`;
+            if (norm[bi]) {
+                out.push(alt(bi));
+                i += 2;
+                continue;
+            }
+        }
+        out.push(norm[tokens[i]] ? alt(tokens[i]) : tokens[i]);
+        i++;
+    }
+    return out.join(" ");
+}
+/**
+ * Legacy `{ indexName, params }` entries must carry a plain object. Spreading a
+ * URL-encoded params string or a URLSearchParams would drop its filters silently.
+ */
+function plainParams(params) {
+    if (params === undefined)
+        return {};
+    const prototype = params !== null && typeof params === "object" ? Object.getPrototypeOf(params) : undefined;
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new SearchCompatibilityError("Algolia request params must be a plain object; URL-encoded params strings are not supported.");
+    }
+    return params;
+}
+export function docslurpAlgoliaClient(opts) {
+    const { apiUrl, clientKey, glossary } = opts;
+    // Server keys (dslp_priv_…) must never ship to a browser; client keys are dslp_pub_….
+    if (typeof window !== "undefined" && typeof document !== "undefined" && clientKey.startsWith("dslp_priv_")) {
+        throw new Error("DocSlurp server keys (dslp_priv_…) must never be used in browser code. Use a search-only, domain-restricted client key (dslp_pub_…).");
+    }
+    const fetchImpl = opts.fetch ?? globalThis.fetch;
+    const base = apiUrl.replace(/\/$/, "");
+    if (!fetchImpl) {
+        throw new Error("A fetch implementation is required.");
+    }
+    async function request(pathname, init) {
+        const res = await fetchImpl(`${base}${pathname}`, {
+            ...init,
+            headers: {
+                ...(init?.body ? { "Content-Type": "application/json" } : {}),
+                ...(init?.headers ?? {}),
+                Authorization: `Bearer ${clientKey}`
+            }
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            // Unsupported filters and options are rejected with HTTP 400 rather than ignored.
+            const unsupported = unsupportedSearchOptionMessage(res.status, text);
+            if (unsupported)
+                throw new SearchCompatibilityError(unsupported);
+            throw new Error(`DocSlurp Algolia-compat request failed: ${res.status} ${text}`);
+        }
+        return await res.json();
+    }
+    async function searchSingleIndex(requestBody) {
+        return await request(`/compat/algolia/1/indexes/${encodeURIComponent(requestBody.indexName)}/query`, {
+            method: "POST",
+            body: JSON.stringify({
+                ...requestBody.searchParams,
+                query: expandQuery(requestBody.searchParams.query, glossary)
+            })
+        });
+    }
+    async function searchForFacetValues(requestBody) {
+        return await request(`/compat/algolia/1/indexes/${encodeURIComponent(requestBody.indexName)}/facets/${encodeURIComponent(requestBody.facetName)}/query`, {
+            method: "POST",
+            body: JSON.stringify(requestBody.searchForFacetValuesRequest)
+        });
+    }
+    async function getSettings(requestBody) {
+        return await request(`/compat/algolia/1/indexes/${encodeURIComponent(requestBody.indexName)}/settings`);
+    }
+    async function setSettings(requestBody) {
+        return await request(`/compat/algolia/1/indexes/${encodeURIComponent(requestBody.indexName)}/settings`, {
+            method: "PUT",
+            body: JSON.stringify(requestBody.indexSettings)
+        });
+    }
+    async function searchSynonyms(requestBody) {
+        return await request(`/compat/algolia/1/indexes/${encodeURIComponent(requestBody.indexName)}/synonyms`);
+    }
+    async function saveSynonyms(requestBody) {
+        return await request(`/compat/algolia/1/indexes/${encodeURIComponent(requestBody.indexName)}/synonyms/batch`, {
+            method: "POST",
+            body: JSON.stringify({ synonyms: requestBody.synonymHit })
+        });
+    }
+    async function searchRules(requestBody) {
+        return await request(`/compat/algolia/1/indexes/${encodeURIComponent(requestBody.indexName)}/rules`);
+    }
+    async function saveRules(requestBody) {
+        return await request(`/compat/algolia/1/indexes/${encodeURIComponent(requestBody.indexName)}/rules/batch`, {
+            method: "POST",
+            body: JSON.stringify({ rules: requestBody.rules })
+        });
+    }
+    async function getAnalytics(requestBody) {
+        return await request(`/compat/algolia/1/indexes/${encodeURIComponent(requestBody.indexName)}/analytics/summary`);
+    }
+    async function clickedObjectIDsAfterSearch(requestBody) {
+        return await request(`/compat/algolia/1/indexes/${encodeURIComponent(requestBody.indexName)}/analytics/click`, {
+            method: "POST",
+            body: JSON.stringify({
+                queryID: requestBody.queryID,
+                objectIDs: requestBody.objectIDs,
+                positions: requestBody.positions
+            })
+        });
+    }
+    async function convertedObjectIDsAfterSearch(requestBody) {
+        return await request(`/compat/algolia/1/indexes/${encodeURIComponent(requestBody.indexName)}/analytics/conversion`, {
+            method: "POST",
+            body: JSON.stringify({
+                queryID: requestBody.queryID,
+                objectIDs: requestBody.objectIDs,
+                eventName: requestBody.eventName
+            })
+        });
+    }
+    function initIndex(indexName) {
+        return {
+            search: async (query, params = {}) => {
+                return await searchSingleIndex({
+                    indexName,
+                    searchParams: typeof query === "string" ? { ...params, query } : query
+                });
+            },
+            getSettings: async () => {
+                return await getSettings({ indexName });
+            },
+            setSettings: async (settings) => {
+                return await setSettings({ indexName, indexSettings: settings });
+            },
+            searchSynonyms: async () => {
+                return await searchSynonyms({ indexName });
+            },
+            saveSynonyms: async (synonyms) => {
+                return await saveSynonyms({ indexName, synonymHit: synonyms });
+            },
+            searchRules: async () => {
+                return await searchRules({ indexName });
+            },
+            saveRules: async (rules) => {
+                return await saveRules({ indexName, rules });
+            },
+            searchForFacetValues: async (facetName, requestBody) => {
+                return await searchForFacetValues({
+                    indexName,
+                    facetName,
+                    searchForFacetValuesRequest: requestBody
+                });
+            },
+            getAnalytics: async () => {
+                return await getAnalytics({ indexName });
+            },
+            clickedObjectIDsAfterSearch: async (payload) => {
+                return await clickedObjectIDsAfterSearch({ indexName, ...payload });
+            },
+            convertedObjectIDsAfterSearch: async (payload) => {
+                return await convertedObjectIDsAfterSearch({ indexName, ...payload });
+            }
+        };
+    }
+    return {
+        initIndex,
+        searchSingleIndex,
+        searchForFacetValues,
+        getSettings,
+        setSettings,
+        searchSynonyms,
+        saveSynonyms,
+        searchRules,
+        saveRules,
+        getAnalytics,
+        clickedObjectIDsAfterSearch,
+        convertedObjectIDsAfterSearch,
+        search: async (requestBody) => {
+            const requests = Array.isArray(requestBody) ? requestBody.map(({ indexName, params }) => ({ indexName, ...plainParams(params) })) : requestBody.requests;
+            return await request(`/compat/algolia/1/indexes/*/queries`, {
+                method: "POST",
+                body: JSON.stringify({
+                    requests: requests.map((entry) => ({
+                        ...entry,
+                        query: expandQuery(entry.query, glossary)
+                    }))
+                })
+            });
+        },
+        importIndex: async (payload) => {
+            return await request(`/compat/algolia/1/import`, {
+                method: "POST",
+                body: JSON.stringify(payload)
+            });
+        }
+    };
+}
+export default docslurpAlgoliaClient;

package/dist/meilisearch.d.ts

@@ -0,0 +1,2 @@
+export { createDocSlurpMeilisearchClient, createDocSlurpMeilisearchClient as default, SearchCompatibilityError } from "@docslurp/sdk/search-adapters";
+export type { SearchAdapterOptions } from "@docslurp/sdk/search-adapters";

package/dist/meilisearch.js

@@ -0,0 +1 @@
+export { createDocSlurpMeilisearchClient, createDocSlurpMeilisearchClient as default, SearchCompatibilityError } from "@docslurp/sdk/search-adapters";

package/dist/pagefind.d.ts

@@ -0,0 +1,2 @@
+export { createDocSlurpPagefind, createDocSlurpPagefind as default, SearchCompatibilityError } from "@docslurp/sdk/search-adapters";
+export type { SearchAdapterOptions } from "@docslurp/sdk/search-adapters";

package/dist/pagefind.js

@@ -0,0 +1 @@
+export { createDocSlurpPagefind, createDocSlurpPagefind as default, SearchCompatibilityError } from "@docslurp/sdk/search-adapters";

package/dist/typesense.d.ts

@@ -0,0 +1,2 @@
+export { createDocSlurpTypesenseClient, createDocSlurpTypesenseClient as default, SearchCompatibilityError } from "@docslurp/sdk/search-adapters";
+export type { SearchAdapterOptions } from "@docslurp/sdk/search-adapters";

package/dist/typesense.js

@@ -0,0 +1 @@
+export { createDocSlurpTypesenseClient, createDocSlurpTypesenseClient as default, SearchCompatibilityError } from "@docslurp/sdk/search-adapters";

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@docslurp/contrib-search-compat",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.4.0",
+  "description": "Drop-in Algolia, Meilisearch, Typesense and Pagefind search clients backed by DocSlurp retrieval, one package with a subpath per client.",
+  "license": "MIT",
+  "homepage": "https://docslurp.io/docs/packages/contrib-search-compat",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DocSlurp/docslurp-oss.git",
+    "directory": "packages/contrib-search-compat"
+  },
+  "bugs": {
+    "url": "https://github.com/DocSlurp/docslurp-oss/issues"
+  },
+  "type": "module",
+  "exports": {
+    "./algolia": {
+      "types": "./dist/algolia.d.ts",
+      "import": "./dist/algolia.js"
+    },
+    "./meilisearch": {
+      "types": "./dist/meilisearch.d.ts",
+      "import": "./dist/meilisearch.js"
+    },
+    "./typesense": {
+      "types": "./dist/typesense.d.ts",
+      "import": "./dist/typesense.js"
+    },
+    "./pagefind": {
+      "types": "./dist/pagefind.d.ts",
+      "import": "./dist/pagefind.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "LICENSES"
+  ],
+  "dependencies": {
+    "@docslurp/sdk": "^0.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "typescript": "^7.0.2",
+    "typescript-compiler-api": "npm:typescript@6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm build && node ../../scripts/node-test.mjs test/*.test.mjs"
+  }
 }