@nikala-ui/folio-algolia 0.1.0

package/README.md

@@ -0,0 +1,148 @@
+# @nikala-ui/folio-algolia
+
+Algolia search adapter for [Folio](https://github.com/nikala-ui/folio)
+documentation sites.
+
+The package connects Folio's search contract to an Algolia index. It keeps
+site configuration in `docs.config.ts`, sends only search requests from the
+browser, and maps Algolia hits back to the canonical pages already known by
+Folio.
+
+## Requirements
+
+- Folio `0.13.2` or newer;
+- an Algolia index containing the same page URLs used by Folio;
+- an Algolia Search-Only API key.
+
+Never expose an Algolia Admin API key or a key that can write/delete records
+in a browser application.
+
+## Installation
+
+```bash
+bun add @nikala-ui/folio @nikala-ui/folio-algolia
+```
+
+The package also works with npm, pnpm, and yarn.
+
+## Configuration
+
+Keep the adapter import and provider selection in `docs.config.ts`:
+
+```ts
+import { algoliaAdapter } from "@nikala-ui/folio-algolia";
+
+export default {
+  search: {
+    enabled: true,
+    provider: algoliaAdapter,
+  },
+};
+```
+
+The adapter implements Folio's `SearchAdapter` contract. The configuration
+contains no Algolia request logic and no indexing code.
+
+## Environment variables
+
+Create a `.env` file in the documentation project:
+
+```bash
+VITE_ALGOLIA_APP_ID=your_application_id
+VITE_ALGOLIA_SEARCH_KEY=your_search_only_key
+VITE_ALGOLIA_INDEX=your_index_name
+```
+
+The adapter also accepts the equivalent server/runtime names:
+
+```bash
+ALGOLIA_APP_ID=your_application_id
+ALGOLIA_SEARCH_KEY=your_search_only_key
+ALGOLIA_INDEX=your_index_name
+```
+
+`VITE_*` variables are required when the adapter runs in the browser. They
+are public by design; use only a Search-Only key.
+
+## Index records
+
+Use the Folio page URL as Algolia's stable object ID. The helper preserves the
+page metadata needed by Folio:
+
+```ts
+import { toAlgoliaRecord } from "@nikala-ui/folio-algolia";
+
+const record = toAlgoliaRecord(page);
+```
+
+The generated record contains `objectID`, `url`, `slug`, `title`,
+`description`, `metadata` (frontmatter), and `headings` (table-of-contents
+text).
+
+Indexing is intentionally not part of this package. Run indexing from a
+separate trusted server or CI job with an Algolia Admin key.
+
+## Manual adapter construction
+
+Use the factory when credentials come from another runtime configuration
+system:
+
+```ts
+import { createAlgoliaAdapter } from "@nikala-ui/folio-algolia";
+
+const adapter = createAlgoliaAdapter({
+  appId: "your_application_id",
+  apiKey: "your_search_only_key",
+  indexName: "your_index_name",
+});
+```
+
+For environment-based setup, the equivalent factory is available:
+
+```ts
+import { createAlgoliaAdapterFromEnv } from "@nikala-ui/folio-algolia";
+
+const adapter = createAlgoliaAdapterFromEnv();
+```
+
+Most Folio sites should use the exported `algoliaAdapter` instance instead.
+
+## Matching behavior
+
+Folio passes the query and its local page catalog to the adapter. Algolia
+performs the remote search, then the adapter matches returned hits by
+`objectID`, `url`, or `slug`. Hits that do not belong to the current Folio
+site are ignored, preventing an index from displaying routes that do not exist
+in the running documentation project.
+
+The empty query never makes a network request and returns Folio's current page
+catalog.
+
+## Errors
+
+Remote failures throw `AlgoliaSearchError`, which includes the HTTP status when
+one is available:
+
+```ts
+import { AlgoliaSearchError } from "@nikala-ui/folio-algolia";
+```
+
+Folio owns the UI behavior for displaying or handling search failures.
+
+## Development
+
+```bash
+bun install
+bun run typecheck
+bun test tests
+bun run build
+```
+
+The package contains the Folio adapter contract, Algolia query client,
+environment resolution, and record mapping. Index creation, crawling, admin
+credentials, and deployment belong in the consuming project or a separate
+indexing service.
+
+## License
+
+MIT

package/dist/adapter.d.ts

@@ -0,0 +1,4 @@
+import type { AlgoliaAdapterOptions, FolioSearchAdapter } from "./types.js";
+export declare function createAlgoliaAdapter(options: AlgoliaAdapterOptions): FolioSearchAdapter;
+export declare function createAlgoliaAdapterFromEnv(): FolioSearchAdapter;
+export declare const algoliaAdapter: FolioSearchAdapter;

package/dist/adapter.js

@@ -0,0 +1,22 @@
+import { getAlgoliaEnv } from "./env.js";
+import { searchAlgolia } from "./client.js";
+export function createAlgoliaAdapter(options) {
+    return {
+        name: "algolia",
+        async search({ query, pages }) {
+            const normalizedQuery = query.trim();
+            if (!normalizedQuery)
+                return pages;
+            return searchAlgolia(options, normalizedQuery, pages);
+        },
+    };
+}
+export function createAlgoliaAdapterFromEnv() {
+    return createAlgoliaAdapter(getAlgoliaEnv());
+}
+export const algoliaAdapter = {
+    name: "algolia",
+    search(context) {
+        return createAlgoliaAdapterFromEnv().search(context);
+    },
+};

package/dist/client.d.ts

@@ -0,0 +1,6 @@
+import type { AlgoliaAdapterOptions, FolioPage } from "./types.js";
+export declare class AlgoliaSearchError extends Error {
+    readonly status?: number;
+    constructor(message: string, status?: number);
+}
+export declare function searchAlgolia(options: Required<Pick<AlgoliaAdapterOptions, "appId" | "apiKey" | "indexName">> & Pick<AlgoliaAdapterOptions, "endpoint" | "hitsPerPage" | "fetch">, query: string, pages: FolioPage[]): Promise<FolioPage[]>;

package/dist/client.js

@@ -0,0 +1,47 @@
+import { findFolioPage } from "./records.js";
+export class AlgoliaSearchError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = "AlgoliaSearchError";
+        this.status = status;
+    }
+}
+function createSearchUrl(endpoint, indexName) {
+    return `${endpoint.replace(/\/$/, "")}/1/indexes/${encodeURIComponent(indexName)}/query`;
+}
+export async function searchAlgolia(options, query, pages) {
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const endpoint = options.endpoint ?? `https://${options.appId}-dsn.algolia.net`;
+    const response = await fetchImpl(createSearchUrl(endpoint, options.indexName), {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "X-Algolia-Application-Id": options.appId,
+            "X-Algolia-API-Key": options.apiKey,
+        },
+        body: JSON.stringify({
+            params: new URLSearchParams({
+                query,
+                hitsPerPage: String(options.hitsPerPage ?? 20),
+            }).toString(),
+        }),
+    });
+    if (!response.ok) {
+        throw new AlgoliaSearchError(`Algolia search failed with status ${response.status}`, response.status);
+    }
+    const data = await response.json();
+    if (!Array.isArray(data.hits)) {
+        throw new AlgoliaSearchError("Algolia search returned an invalid response");
+    }
+    const results = [];
+    const seen = new Set();
+    for (const hit of data.hits) {
+        const page = findFolioPage(hit, pages);
+        if (page && !seen.has(page.url)) {
+            seen.add(page.url);
+            results.push(page);
+        }
+    }
+    return results;
+}

package/dist/env.d.ts

@@ -0,0 +1,6 @@
+export declare function requiredEnv(...names: string[]): string;
+export declare function getAlgoliaEnv(): {
+    appId: string;
+    apiKey: string;
+    indexName: string;
+};

package/dist/env.js

@@ -0,0 +1,22 @@
+function getRuntimeEnv() {
+    const runtime = globalThis;
+    return runtime.process?.env
+        ?? runtime.Bun?.env
+        ?? import.meta.env
+        ?? {};
+}
+export function requiredEnv(...names) {
+    const env = getRuntimeEnv();
+    for (const name of names) {
+        if (env[name])
+            return env[name];
+    }
+    throw new Error(`Missing required environment variable: ${names.join(" or ")}`);
+}
+export function getAlgoliaEnv() {
+    return {
+        appId: requiredEnv("ALGOLIA_APP_ID", "VITE_ALGOLIA_APP_ID"),
+        apiKey: requiredEnv("ALGOLIA_SEARCH_KEY", "VITE_ALGOLIA_SEARCH_KEY"),
+        indexName: requiredEnv("ALGOLIA_INDEX", "VITE_ALGOLIA_INDEX"),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { algoliaAdapter, createAlgoliaAdapter, createAlgoliaAdapterFromEnv } from "./adapter.js";
+export { AlgoliaSearchError, searchAlgolia } from "./client.js";
+export { getAlgoliaEnv, requiredEnv } from "./env.js";
+export { findFolioPage, toAlgoliaRecord } from "./records.js";
+export type { AlgoliaAdapterOptions, AlgoliaHit, AlgoliaSearchResponse, FolioPage, FolioSearchAdapter, FolioSearchContext, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { algoliaAdapter, createAlgoliaAdapter, createAlgoliaAdapterFromEnv } from "./adapter.js";
+export { AlgoliaSearchError, searchAlgolia } from "./client.js";
+export { getAlgoliaEnv, requiredEnv } from "./env.js";
+export { findFolioPage, toAlgoliaRecord } from "./records.js";

package/dist/records.d.ts

@@ -0,0 +1,3 @@
+import type { AlgoliaHit, FolioPage } from "./types.js";
+export declare function toAlgoliaRecord(page: FolioPage): Record<string, unknown>;
+export declare function findFolioPage(hit: AlgoliaHit, pages: FolioPage[]): FolioPage | undefined;

package/dist/records.js

@@ -0,0 +1,17 @@
+export function toAlgoliaRecord(page) {
+    return {
+        objectID: page.url,
+        slug: page.slug,
+        url: page.url,
+        title: page.title,
+        description: page.description,
+        metadata: page.frontmatter,
+        headings: page.toc.map((item) => item.text),
+    };
+}
+export function findFolioPage(hit, pages) {
+    const identifier = hit.objectID ?? hit.url ?? hit.slug;
+    if (!identifier)
+        return undefined;
+    return pages.find((page) => page.url === identifier || page.slug === identifier);
+}

package/dist/types.d.ts

@@ -0,0 +1,26 @@
+import type { PageData } from "@nikala-ui/folio";
+export interface AlgoliaAdapterOptions {
+    appId: string;
+    apiKey: string;
+    indexName: string;
+    endpoint?: string;
+    hitsPerPage?: number;
+    fetch?: typeof globalThis.fetch;
+}
+export interface AlgoliaHit {
+    objectID?: string;
+    slug?: string;
+    url?: string;
+}
+export interface AlgoliaSearchResponse {
+    hits?: AlgoliaHit[];
+}
+export interface FolioSearchContext {
+    query: string;
+    pages: PageData[];
+}
+export interface FolioSearchAdapter {
+    name: string;
+    search: (context: FolioSearchContext) => PageData[] | Promise<PageData[]>;
+}
+export type FolioPage = PageData;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@nikala-ui/folio-algolia",
+  "version": "0.1.0",
+  "description": "Algolia search adapter for Folio documentation sites",
+  "license": "MIT",
+  "type": "module",
+  "keywords": ["folio", "algolia", "search", "documentation", "solidjs"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nikala-ui/folio-algolia.git"
+  },
+  "homepage": "https://github.com/nikala-ui/folio-algolia#readme",
+  "bugs": {
+    "url": "https://github.com/nikala-ui/folio-algolia/issues"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test tests",
+    "check": "bun run typecheck && bun run test && bun run build",
+    "package:check": "bun run check && npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@nikala-ui/folio": ">=0.13.2"
+  },
+  "devDependencies": {
+    "@nikala-ui/folio": "^0.13.2",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}