@86d-app/search 0.0.4 → 0.0.13

package/src/__tests__/service-impl.test.ts

@@ -63,6 +63,64 @@ describe("createSearchController", () => {
 		});
 	});
 
+	// ── bulkIndex ────────────────────────────────────────────────────────
+
+	describe("bulkIndex", () => {
+		it("indexes multiple items at once", async () => {
+			const result = await controller.bulkIndex([
+				{
+					entityType: "product",
+					entityId: "p1",
+					title: "Item 1",
+					url: "/p1",
+				},
+				{
+					entityType: "product",
+					entityId: "p2",
+					title: "Item 2",
+					url: "/p2",
+				},
+				{
+					entityType: "product",
+					entityId: "p3",
+					title: "Item 3",
+					url: "/p3",
+				},
+			]);
+			expect(result.indexed).toBe(3);
+			expect(result.errors).toBe(0);
+			const count = await controller.getIndexCount();
+			expect(count).toBe(3);
+		});
+
+		it("updates existing items in bulk", async () => {
+			await controller.indexItem({
+				entityType: "product",
+				entityId: "p1",
+				title: "Old Title",
+				url: "/p1",
+			});
+			const result = await controller.bulkIndex([
+				{
+					entityType: "product",
+					entityId: "p1",
+					title: "New Title",
+					url: "/p1",
+				},
+				{
+					entityType: "product",
+					entityId: "p2",
+					title: "Item 2",
+					url: "/p2",
+				},
+			]);
+			expect(result.indexed).toBe(2);
+			expect(result.errors).toBe(0);
+			const count = await controller.getIndexCount();
+			expect(count).toBe(2);
+		});
+	});
+
 	// ── removeFromIndex ─────────────────────────────────────────────────
 
 	describe("removeFromIndex", () => {
@@ -123,7 +181,9 @@ describe("createSearchController", () => {
 		});
 
 		it("returns empty results for non-matching query", async () => {
-			const { results, total } = await controller.search("nonexistent");
+			const { results, total } = await controller.search("nonexistent", {
+				fuzzy: false,
+			});
 			expect(results).toHaveLength(0);
 			expect(total).toBe(0);
 		});
@@ -171,11 +231,215 @@ describe("createSearchController", () => {
 		});
 
 		it("ranks title matches higher than body matches", async () => {
-			// "Red T-Shirt" has "red" in title; "Blue Jeans" does not
 			const { results } = await controller.search("red");
 			expect(results.length).toBeGreaterThan(0);
 			expect(results[0].item.entityId).toBe("prod_1");
 		});
+
+		it("returns facets with results", async () => {
+			const { facets } = await controller.search("clothing");
+			expect(facets.entityTypes.length).toBeGreaterThan(0);
+			expect(facets.entityTypes[0].type).toBe("product");
+			expect(facets.tags.length).toBeGreaterThan(0);
+		});
+
+		it("returns highlights in results", async () => {
+			const { results } = await controller.search("red");
+			expect(results.length).toBeGreaterThan(0);
+			const highlight = results[0].highlights;
+			expect(highlight?.title).toContain("<mark>");
+		});
+	});
+
+	// ── fuzzy search ───────────────────────────────────────────────────
+
+	describe("fuzzy search", () => {
+		beforeEach(async () => {
+			await controller.indexItem({
+				entityType: "product",
+				entityId: "prod_1",
+				title: "Running Shoes",
+				tags: ["footwear", "athletic"],
+				url: "/products/running-shoes",
+			});
+			await controller.indexItem({
+				entityType: "product",
+				entityId: "prod_2",
+				title: "Leather Boots",
+				tags: ["footwear", "winter"],
+				url: "/products/leather-boots",
+			});
+		});
+
+		it("finds results with typos when fuzzy is enabled", async () => {
+			const { results } = await controller.search("runnign", {
+				fuzzy: true,
+			});
+			expect(results.length).toBeGreaterThan(0);
+			expect(results[0].item.entityId).toBe("prod_1");
+		});
+
+		it("does not find typo results when fuzzy is disabled", async () => {
+			const { results } = await controller.search("runnign", {
+				fuzzy: false,
+			});
+			expect(results).toHaveLength(0);
+		});
+
+		it("fuzzy matches short words only with exact match", async () => {
+			// Words <= 3 chars get no fuzzy tolerance
+			const { results } = await controller.search("ren", {
+				fuzzy: true,
+			});
+			// "ren" is too short for fuzzy to match "run" (distance 2)
+			expect(results).toHaveLength(0);
+		});
+
+		it("fuzzy matches medium words with 1 edit distance", async () => {
+			const { results } = await controller.search("shoez", {
+				fuzzy: true,
+			});
+			expect(results.length).toBeGreaterThan(0);
+		});
+
+		it("fuzzy matches longer words with 2 edit distance", async () => {
+			const { results } = await controller.search("leathor", {
+				fuzzy: true,
+			});
+			expect(results.length).toBeGreaterThan(0);
+		});
+	});
+
+	// ── tag filtering ──────────────────────────────────────────────────
+
+	describe("tag filtering", () => {
+		beforeEach(async () => {
+			await controller.indexItem({
+				entityType: "product",
+				entityId: "p1",
+				title: "Red Sneakers",
+				tags: ["shoes", "red", "sport"],
+				url: "/p1",
+			});
+			await controller.indexItem({
+				entityType: "product",
+				entityId: "p2",
+				title: "Red Jacket",
+				tags: ["outerwear", "red", "winter"],
+				url: "/p2",
+			});
+			await controller.indexItem({
+				entityType: "product",
+				entityId: "p3",
+				title: "Blue Sneakers",
+				tags: ["shoes", "blue", "sport"],
+				url: "/p3",
+			});
+		});
+
+		it("filters results by tags", async () => {
+			const { results } = await controller.search("sneakers", {
+				tags: ["red"],
+			});
+			expect(results).toHaveLength(1);
+			expect(results[0].item.entityId).toBe("p1");
+		});
+
+		it("returns all matching results without tag filter", async () => {
+			const { results } = await controller.search("red");
+			expect(results.length).toBeGreaterThanOrEqual(2);
+		});
+
+		it("returns empty when no items match tag filter", async () => {
+			const { results } = await controller.search("sneakers", {
+				tags: ["winter"],
+			});
+			expect(results).toHaveLength(0);
+		});
+	});
+
+	// ── sorting ────────────────────────────────────────────────────────
+
+	describe("sorting", () => {
+		beforeEach(async () => {
+			await controller.indexItem({
+				entityType: "product",
+				entityId: "p1",
+				title: "Alpha Widget",
+				tags: ["widget"],
+				url: "/p1",
+			});
+			// Add a small delay to ensure different timestamps
+			await controller.indexItem({
+				entityType: "product",
+				entityId: "p2",
+				title: "Beta Widget",
+				tags: ["widget"],
+				url: "/p2",
+			});
+			await controller.indexItem({
+				entityType: "product",
+				entityId: "p3",
+				title: "Charlie Widget",
+				tags: ["widget"],
+				url: "/p3",
+			});
+		});
+
+		it("sorts by title ascending", async () => {
+			const { results } = await controller.search("widget", {
+				sort: "title_asc",
+			});
+			expect(results[0].item.title).toBe("Alpha Widget");
+			expect(results[results.length - 1].item.title).toBe("Charlie Widget");
+		});
+
+		it("sorts by title descending", async () => {
+			const { results } = await controller.search("widget", {
+				sort: "title_desc",
+			});
+			expect(results[0].item.title).toBe("Charlie Widget");
+			expect(results[results.length - 1].item.title).toBe("Alpha Widget");
+		});
+
+		it("defaults to relevance sorting", async () => {
+			const { results } = await controller.search("widget");
+			// All have same relevance, so order is stable
+			expect(results.length).toBe(3);
+		});
+	});
+
+	// ── did-you-mean ───────────────────────────────────────────────────
+
+	describe("did-you-mean", () => {
+		beforeEach(async () => {
+			await controller.indexItem({
+				entityType: "product",
+				entityId: "p1",
+				title: "Running Shoes",
+				url: "/p1",
+			});
+			await controller.indexItem({
+				entityType: "product",
+				entityId: "p2",
+				title: "Leather Boots",
+				url: "/p2",
+			});
+		});
+
+		it("suggests correction for misspelled query with zero results", async () => {
+			// "bootes" is close to "boots" (dist 1), won't substring-match "Running Shoes"
+			const { didYouMean } = await controller.search("bootes", {
+				fuzzy: false,
+			});
+			expect(didYouMean).toBeDefined();
+			expect(didYouMean).toBe("boots");
+		});
+
+		it("does not suggest correction when results are found", async () => {
+			const { didYouMean } = await controller.search("running");
+			expect(didYouMean).toBeUndefined();
+		});
 	});
 
 	// ── synonym expansion ───────────────────────────────────────────────
@@ -205,7 +469,6 @@ describe("createSearchController", () => {
 				url: "/products/tee-collection",
 			});
 			const { results } = await controller.search("tshirt");
-			// "tshirt" is a synonym of "tee", so "tee" should also be searched
 			expect(results.length).toBeGreaterThan(0);
 		});
 	});
@@ -226,7 +489,6 @@ describe("createSearchController", () => {
 				title: "Red Sneakers",
 				url: "/products/red-sneakers",
 			});
-			// Record some queries
 			await controller.recordQuery("red t-shirt", 5);
 			await controller.recordQuery("red t-shirt", 3);
 			await controller.recordQuery("red sneakers", 2);
@@ -242,7 +504,6 @@ describe("createSearchController", () => {
 
 		it("prioritizes popular queries over title matches", async () => {
 			const suggestions = await controller.suggest("red");
-			// "red t-shirt" was searched twice, should appear before "red sneakers"
 			expect(suggestions[0].toLowerCase()).toContain("red t-shirt");
 		});
 
@@ -276,6 +537,47 @@ describe("createSearchController", () => {
 		});
 	});
 
+	// ── recordClick ─────────────────────────────────────────────────────
+
+	describe("recordClick", () => {
+		it("records a search result click", async () => {
+			const query = await controller.recordQuery("shoes", 10, "sess_1");
+			const click = await controller.recordClick({
+				queryId: query.id,
+				term: "shoes",
+				entityType: "product",
+				entityId: "prod_1",
+				position: 0,
+			});
+			expect(click.id).toBeDefined();
+			expect(click.queryId).toBe(query.id);
+			expect(click.term).toBe("shoes");
+			expect(click.position).toBe(0);
+			expect(click.clickedAt).toBeInstanceOf(Date);
+		});
+
+		it("records multiple clicks for different positions", async () => {
+			const query = await controller.recordQuery("shoes", 10);
+			const click1 = await controller.recordClick({
+				queryId: query.id,
+				term: "shoes",
+				entityType: "product",
+				entityId: "prod_1",
+				position: 0,
+			});
+			const click2 = await controller.recordClick({
+				queryId: query.id,
+				term: "shoes",
+				entityType: "product",
+				entityId: "prod_2",
+				position: 1,
+			});
+			expect(click1.id).not.toBe(click2.id);
+			expect(click1.position).toBe(0);
+			expect(click2.position).toBe(1);
+		});
+	});
+
 	// ── getRecentQueries ────────────────────────────────────────────────
 
 	describe("getRecentQueries", () => {
@@ -324,7 +626,7 @@ describe("createSearchController", () => {
 			const popular = await controller.getPopularTerms();
 			expect(popular[0].term).toBe("shoes");
 			expect(popular[0].count).toBe(3);
-			expect(popular[0].avgResultCount).toBe(10); // (10+8+12)/3 = 10
+			expect(popular[0].avgResultCount).toBe(10);
 			expect(popular[1].term).toBe("hats");
 			expect(popular[1].count).toBe(2);
 		});
@@ -377,9 +679,11 @@ describe("createSearchController", () => {
 			const analytics = await controller.getAnalytics();
 			expect(analytics.totalQueries).toBe(3);
 			expect(analytics.uniqueTerms).toBe(2);
-			expect(analytics.avgResultCount).toBe(6); // (10+8+0)/3 = 6
+			expect(analytics.avgResultCount).toBe(6);
 			expect(analytics.zeroResultCount).toBe(1);
-			expect(analytics.zeroResultRate).toBe(33); // 1/3 = 33%
+			expect(analytics.zeroResultRate).toBe(33);
+			expect(analytics.clickThroughRate).toBe(0);
+			expect(analytics.avgClickPosition).toBe(0);
 		});
 
 		it("returns zeros when no queries", async () => {
@@ -389,6 +693,35 @@ describe("createSearchController", () => {
 			expect(analytics.avgResultCount).toBe(0);
 			expect(analytics.zeroResultCount).toBe(0);
 			expect(analytics.zeroResultRate).toBe(0);
+			expect(analytics.clickThroughRate).toBe(0);
+			expect(analytics.avgClickPosition).toBe(0);
+		});
+
+		it("computes click-through rate and avg position", async () => {
+			const q1 = await controller.recordQuery("shoes", 10);
+			const q2 = await controller.recordQuery("hats", 5);
+			await controller.recordQuery("bags", 3);
+
+			await controller.recordClick({
+				queryId: q1.id,
+				term: "shoes",
+				entityType: "product",
+				entityId: "p1",
+				position: 0,
+			});
+			await controller.recordClick({
+				queryId: q2.id,
+				term: "hats",
+				entityType: "product",
+				entityId: "p2",
+				position: 2,
+			});
+
+			const analytics = await controller.getAnalytics();
+			// 2 queries with clicks out of 3 queries with results = 67%
+			expect(analytics.clickThroughRate).toBe(67);
+			// avg position: (0 + 2) / 2 = 1
+			expect(analytics.avgClickPosition).toBe(1);
 		});
 	});
 

package/src/admin/components/search-analytics.tsx

@@ -25,9 +25,25 @@ interface Synonym {
 	createdAt: string;
 }
 
+interface SearchSettings {
+	meilisearch: {
+		configured: boolean;
+		host: string | null;
+		apiKey: string | null;
+		indexUid: string;
+	};
+	embeddings: {
+		configured: boolean;
+		provider: "openai" | "openrouter" | null;
+		model: string;
+	};
+	indexCount: number;
+}
+
 function useSearchAdminApi() {
 	const client = useModuleClient();
 	return {
+		settings: client.module("search").admin["/admin/search/settings"],
 		analytics: client.module("search").admin["/admin/search/analytics"],
 		popular: client.module("search").admin["/admin/search/popular"],
 		zeroResults: client.module("search").admin["/admin/search/zero-results"],
@@ -49,12 +65,41 @@ function StatCard({ label, value }: { label: string; value: string | number }) {
 	);
 }
 
+function ConfigBadge({
+	configured,
+	label,
+}: {
+	configured: boolean;
+	label: string;
+}) {
+	return (
+		<span
+			className={`inline-flex items-center gap-1.5 rounded-full px-2.5 py-0.5 font-medium text-xs ${
+				configured
+					? "bg-emerald-100 text-emerald-700 dark:bg-emerald-900/30 dark:text-emerald-400"
+					: "bg-amber-100 text-amber-700 dark:bg-amber-900/30 dark:text-amber-400"
+			}`}
+		>
+			<span
+				className={`inline-block size-1.5 rounded-full ${
+					configured ? "bg-emerald-500" : "bg-amber-500"
+				}`}
+			/>
+			{label}
+		</span>
+	);
+}
+
 export function SearchAnalytics() {
 	const api = useSearchAdminApi();
 	const [newTerm, setNewTerm] = useState("");
 	const [newSynonyms, setNewSynonyms] = useState("");
 	const [error, setError] = useState("");
 
+	const { data: settingsData } = api.settings.useQuery({}) as {
+		data: SearchSettings | undefined;
+	};
+
 	const { data: analyticsData, isLoading: analyticsLoading } =
 		api.analytics.useQuery({}) as {
 			data: { analytics: AnalyticsData } | undefined;
@@ -132,6 +177,81 @@ export function SearchAnalytics() {
 
 	return (
 		<div className="space-y-8">
+			{/* Search engine configuration */}
+			{settingsData && (
+				<div className="rounded-lg border border-border bg-background p-5">
+					<h3 className="mb-4 font-medium text-foreground text-sm">
+						Search Configuration
+					</h3>
+					<div className="grid gap-4 sm:grid-cols-2">
+						<div className="flex flex-col gap-2">
+							<div className="flex items-center justify-between">
+								<span className="text-muted-foreground text-sm">
+									MeiliSearch
+								</span>
+								<ConfigBadge
+									configured={settingsData.meilisearch.configured}
+									label={
+										settingsData.meilisearch.configured
+											? "Connected"
+											: "Not configured"
+									}
+								/>
+							</div>
+							{settingsData.meilisearch.configured ? (
+								<div className="text-muted-foreground text-xs">
+									<p>Host: {settingsData.meilisearch.host}</p>
+									<p>Index: {settingsData.meilisearch.indexUid}</p>
+									<p>Key: {settingsData.meilisearch.apiKey}</p>
+								</div>
+							) : (
+								<p className="text-muted-foreground text-xs">
+									Using local search engine. Configure{" "}
+									<code className="rounded bg-muted px-1 text-[11px]">
+										MEILISEARCH_HOST
+									</code>{" "}
+									and{" "}
+									<code className="rounded bg-muted px-1 text-[11px]">
+										MEILISEARCH_API_KEY
+									</code>{" "}
+									for dedicated search.
+								</p>
+							)}
+						</div>
+						<div className="flex flex-col gap-2">
+							<div className="flex items-center justify-between">
+								<span className="text-muted-foreground text-sm">
+									AI Embeddings
+								</span>
+								<ConfigBadge
+									configured={settingsData.embeddings.configured}
+									label={
+										settingsData.embeddings.configured
+											? settingsData.embeddings.provider === "openai"
+												? "OpenAI"
+												: "OpenRouter"
+											: "Not configured"
+									}
+								/>
+							</div>
+							{settingsData.embeddings.configured ? (
+								<p className="text-muted-foreground text-xs">
+									Model: {settingsData.embeddings.model}
+								</p>
+							) : (
+								<p className="text-muted-foreground text-xs">
+									Semantic search disabled. Configure{" "}
+									<code className="rounded bg-muted px-1 text-[11px]">
+										OPENAI_API_KEY
+									</code>{" "}
+									for AI-powered results.
+								</p>
+							)}
+						</div>
+					</div>
+				</div>
+			)}
+
 			{/* Stats overview */}
 			{analytics && (
 				<div className="grid grid-cols-2 gap-4 md:grid-cols-3 lg:grid-cols-6">

package/src/admin/endpoints/bulk-index.ts

@@ -0,0 +1,34 @@
+import { createAdminEndpoint, z } from "@86d-app/core";
+import type { SearchController } from "../../service";
+
+export const bulkIndex = createAdminEndpoint(
+	"/admin/search/index/bulk",
+	{
+		method: "POST",
+		body: z.object({
+			items: z
+				.array(
+					z.object({
+						entityType: z.string().min(1).max(100),
+						entityId: z.string().min(1).max(200),
+						title: z.string().min(1).max(500),
+						body: z.string().max(10000).optional(),
+						tags: z.array(z.string().max(100)).max(50).optional(),
+						url: z.string().min(1).max(500),
+						image: z.string().max(500).optional(),
+						metadata: z
+							.record(z.string().max(100), z.unknown())
+							.refine((r) => Object.keys(r).length <= 50, "Too many keys")
+							.optional(),
+					}),
+				)
+				.min(1)
+				.max(500),
+		}),
+	},
+	async (ctx) => {
+		const controller = ctx.context.controllers.search as SearchController;
+		const result = await controller.bulkIndex(ctx.body.items);
+		return result;
+	},
+);

package/src/admin/endpoints/click-analytics.ts

@@ -0,0 +1,16 @@
+import { createAdminEndpoint } from "@86d-app/core";
+import type { SearchController } from "../../service";
+
+export const clickAnalyticsEndpoint = createAdminEndpoint(
+	"/admin/search/clicks",
+	{ method: "GET" },
+	async (ctx) => {
+		const controller = ctx.context.controllers.search as SearchController;
+		const analytics = await controller.getAnalytics();
+
+		return {
+			clickThroughRate: analytics.clickThroughRate,
+			avgClickPosition: analytics.avgClickPosition,
+		};
+	},
+);

package/src/admin/endpoints/get-settings.ts

@@ -0,0 +1,56 @@
+import { createAdminEndpoint } from "@86d-app/core";
+import type { SearchController } from "../../service";
+
+function maskKey(key: string): string {
+	if (key.length <= 8) return `${key.slice(0, 2)}••••••`;
+	return `${key.slice(0, 4)}${"•".repeat(Math.min(key.length - 4, 20))}`;
+}
+
+interface SearchModuleOptions {
+	meilisearchHost?: string;
+	meilisearchApiKey?: string;
+	meilisearchIndexUid?: string;
+	openaiApiKey?: string;
+	openrouterApiKey?: string;
+	embeddingModel?: string;
+}
+
+export const getSettings = createAdminEndpoint(
+	"/admin/search/settings",
+	{ method: "GET" },
+	async (ctx) => {
+		const controller = ctx.context.controllers.search as SearchController;
+		const options = ctx.context.options as SearchModuleOptions | undefined;
+
+		const meilisearchConfigured = Boolean(
+			options?.meilisearchHost && options?.meilisearchApiKey,
+		);
+
+		const embeddingConfigured = Boolean(
+			options?.openaiApiKey || options?.openrouterApiKey,
+		);
+
+		const indexCount = await controller.getIndexCount();
+
+		return {
+			meilisearch: {
+				configured: meilisearchConfigured,
+				host: options?.meilisearchHost ?? null,
+				apiKey: options?.meilisearchApiKey
+					? maskKey(options.meilisearchApiKey)
+					: null,
+				indexUid: options?.meilisearchIndexUid ?? "search",
+			},
+			embeddings: {
+				configured: embeddingConfigured,
+				provider: options?.openaiApiKey
+					? "openai"
+					: options?.openrouterApiKey
+						? "openrouter"
+						: null,
+				model: options?.embeddingModel ?? "text-embedding-3-small",
+			},
+			indexCount,
+		};
+	},
+);

package/src/admin/endpoints/index-manage.ts

@@ -13,7 +13,10 @@ export const indexItem = createAdminEndpoint(
 			tags: z.array(z.string().max(100)).max(50).optional(),
 			url: z.string().min(1).max(500),
 			image: z.string().max(500).optional(),
-			metadata: z.record(z.string(), z.unknown()).optional(),
+			metadata: z
+				.record(z.string().max(100), z.unknown())
+				.refine((r) => Object.keys(r).length <= 50, "Too many keys")
+				.optional(),
 		}),
 	},
 	async (ctx) => {