@se-studio/search 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# @se-studio/search
+
+## 1.0.1
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+- Updated dependencies
+  - @se-studio/contentful-rest-api@1.0.90
+  - @se-studio/core-data-types@1.0.90
+  - @se-studio/markdown-renderer@1.0.54

package/README.md

@@ -0,0 +1,185 @@
+# @se-studio/search
+
+AI-powered site search for Next.js marketing sites using [Upstash Search](https://upstash.com/docs/search/overall/whatisupstashsearch). Combines semantic and full-text search with zero infrastructure to manage.
+
+## Overview
+
+This package provides:
+
+- **Search client** – typed wrapper around `@upstash/search` with automatic batch handling
+- **Content indexing** – extracts searchable text from CMS content using `MarkdownConverter`
+- **Webhook handler** – incremental index updates on Contentful publish/delete
+- **Full rebuild** – enumerates all content and re-indexes in batches
+- **API route factories** – drop-in Next.js route handlers for search and rebuild
+- **Client hook** – `useSearch()` for building search UIs with debouncing
+
+## Setup
+
+### 1. Install
+
+The package is a workspace dependency. Add it to your app's `package.json`:
+
+```json
+{
+  "dependencies": {
+    "@se-studio/search": "workspace:*"
+  }
+}
+```
+
+### 2. Create an Upstash Search database
+
+Go to [console.upstash.com/search](https://console.upstash.com/search) and create a database. Copy the REST URL and token.
+
+### 3. Environment variables
+
+Add to your `.env.local`:
+
+```bash
+UPSTASH_SEARCH_REST_URL=https://your-search-url.upstash.io
+UPSTASH_SEARCH_REST_TOKEN=your-token
+```
+
+### 4. Search config
+
+Create `src/lib/search-config.ts`:
+
+```typescript
+import 'server-only';
+import type { SearchIndexingConfig } from '@se-studio/search';
+
+export const searchIndexingConfig: SearchIndexingConfig = {
+  searchIndex: {
+    connection: {
+      url: process.env.UPSTASH_SEARCH_REST_URL ?? '',
+      token: process.env.UPSTASH_SEARCH_REST_TOKEN ?? '',
+    },
+    publishedIndexName: 'published',
+    previewIndexName: 'preview',
+  },
+  contentTypes: [
+    { type: 'page', enabled: true },
+    { type: 'article', enabled: true },
+    { type: 'person', enabled: false },
+  ],
+  indexComponents: true,
+  respectIndexedFlag: true,
+  respectHiddenFlag: true,
+};
+```
+
+### 5. Search API route
+
+Create `src/app/api/search/route.ts`:
+
+```typescript
+import { createSearchApiHandler } from '@se-studio/search/api';
+import { buildInformation } from '@/lib/converter-context';
+import { searchIndexingConfig } from '@/lib/search-config';
+
+export const GET = createSearchApiHandler({
+  searchConfig: searchIndexingConfig.searchIndex.connection,
+  publishedIndexName: searchIndexingConfig.searchIndex.publishedIndexName,
+  previewIndexName: searchIndexingConfig.searchIndex.previewIndexName,
+  isPreview: buildInformation.preview ?? false,
+});
+```
+
+### 6. Rebuild API route
+
+Create `src/app/api/search/rebuild/route.ts`:
+
+```typescript
+import { createSearchClient } from '@se-studio/search/client';
+import { rebuildSearchIndex } from '@se-studio/search/indexing';
+import { createRebuildApiHandler } from '@se-studio/search/api';
+import { buildOptions, getContentfulConfig } from '@/lib/cms-server';
+import { customerName, license } from '@/lib/constants';
+import { buildInformation, converterContext } from '@/lib/converter-context';
+import { searchIndexingConfig } from '@/lib/search-config';
+import { baseUrl, revalidationSecret } from '@/lib/server-config';
+
+const isPreview = buildInformation.preview ?? false;
+
+export const POST = createRebuildApiHandler({
+  rebuildSecret: revalidationSecret ?? '',
+  isPreview,
+  rebuildFn: () => {
+    const config = getContentfulConfig(isPreview);
+    const client = createSearchClient(searchIndexingConfig.searchIndex.connection);
+    const indexName = isPreview
+      ? searchIndexingConfig.searchIndex.previewIndexName
+      : searchIndexingConfig.searchIndex.publishedIndexName;
+
+    return rebuildSearchIndex({
+      client,
+      indexName,
+      indexingConfig: searchIndexingConfig,
+      converterContext,
+      contentfulConfig: config,
+      fetchOptions: buildOptions({ preview: isPreview }),
+      urlCalculators: converterContext.urlCalculators,
+      siteConfig: { canonicalBaseUrl: baseUrl, source: customerName, license },
+    });
+  },
+});
+```
+
+### 7. Webhook integration
+
+Update your `src/app/api/revalidate/route.ts` to call the search webhook handler after cache revalidation. See the example-brightline app for the full pattern.
+
+### 8. Client-side search
+
+```tsx
+'use client';
+import { useSearch } from '@se-studio/search/hooks';
+
+export function SearchPage() {
+  const { query, setQuery, results, isLoading, error, totalCount } = useSearch();
+
+  return (
+    <div>
+      <input value={query} onChange={(e) => setQuery(e.target.value)} placeholder="Search..." />
+      {isLoading && <p>Searching...</p>}
+      {error && <p>Error: {error}</p>}
+      {results.map((r) => (
+        <a key={r.id} href={r.metadata.href}>
+          <h3>{r.content.title}</h3>
+          <p>{r.content.description}</p>
+        </a>
+      ))}
+    </div>
+  );
+}
+```
+
+## Triggering a full rebuild
+
+```bash
+curl -X POST https://your-site.com/api/search/rebuild \
+  -H "Authorization: Bearer YOUR_REVALIDATION_SECRET"
+```
+
+The index to rebuild (published vs preview) is determined by the app's own `isPreview` flag
+set at initialization time in `createRebuildApiHandler`.
+
+## Architecture
+
+- **Single Upstash database, two indexes**: `published` and `preview`
+- **Text extraction**: Uses `MarkdownConverter` to deeply extract text from page components, then strips markdown formatting
+- **Content truncation**: Body text is truncated to ~4,000 chars (Upstash limit)
+- **Batch upsert**: Documents are upserted in batches of 100 (Upstash API limit)
+- **Webhook-driven**: Incremental updates on Contentful publish/delete events
+- **Flags**: Respects `indexed` and `hidden` fields on content entries
+
+## Subpath Exports
+
+| Import | Purpose |
+|--------|---------|
+| `@se-studio/search` | Types only |
+| `@se-studio/search/client` | `createSearchClient()` |
+| `@se-studio/search/indexing` | `rebuildSearchIndex()`, `buildSearchDocument()` |
+| `@se-studio/search/webhook` | `createSearchWebhookHandler()` |
+| `@se-studio/search/api` | `createSearchApiHandler()`, `createRebuildApiHandler()` |
+| `@se-studio/search/hooks` | `useSearch()` |

package/dist/api/index.d.ts

@@ -0,0 +1,2 @@
+export { createRebuildApiHandler, createSearchApiHandler, deduplicateChunks, type RebuildApiConfig, type SearchApiConfig, } from './route-handler';
+//# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EACtB,iBAAiB,EACjB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,iBAAiB,CAAC"}

package/dist/api/index.js

@@ -0,0 +1,2 @@
+export { createRebuildApiHandler, createSearchApiHandler, deduplicateChunks, } from './route-handler';
+//# sourceMappingURL=index.js.map

package/dist/api/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EACtB,iBAAiB,GAGlB,MAAM,iBAAiB,CAAC"}

package/dist/api/route-handler.d.ts

@@ -0,0 +1,53 @@
+import type { RebuildResult, SearchConfig, SearchResult } from '../types';
+/**
+ * Groups results by base entry ID and keeps the highest-scoring chunk per entry.
+ * Results are returned in score-descending order.
+ */
+export declare function deduplicateChunks(results: SearchResult[]): SearchResult[];
+export interface SearchApiConfig {
+    searchConfig: SearchConfig;
+    publishedIndexName: string;
+    previewIndexName: string;
+    /** When true, queries the preview index instead of published. */
+    isPreview?: boolean;
+}
+/**
+ * Creates a Next.js GET route handler for search queries.
+ *
+ * Query params:
+ * - `q` -- search query (required)
+ * - `limit` -- max results (default: 20)
+ * - `filter` -- Upstash metadata filter expression
+ *
+ * @example
+ * ```ts
+ * // app/api/search/route.ts
+ * import { createSearchApiHandler } from '@se-studio/search/api';
+ * export const GET = createSearchApiHandler({ ... });
+ * ```
+ */
+export declare function createSearchApiHandler(config: SearchApiConfig): (request: Request) => Promise<Response>;
+export interface RebuildApiConfig {
+    /** Secret used to authenticate rebuild requests (typically REVALIDATION_SECRET). */
+    rebuildSecret: string;
+    /** Whether this app instance is running in preview/draft mode. */
+    isPreview: boolean;
+    /** Function that performs the actual rebuild and returns stats. */
+    rebuildFn: () => Promise<RebuildResult>;
+}
+/**
+ * Creates a Next.js POST route handler for triggering a full search index rebuild.
+ * Protected by `Authorization: Bearer <secret>`.
+ *
+ * The index to rebuild (published vs preview) is determined by the app's
+ * own preview state via `isPreview`, not by a query parameter.
+ *
+ * @example
+ * ```ts
+ * // app/api/search/rebuild/route.ts
+ * import { createRebuildApiHandler } from '@se-studio/search/api';
+ * export const POST = createRebuildApiHandler({ ... });
+ * ```
+ */
+export declare function createRebuildApiHandler(config: RebuildApiConfig): (request: Request) => Promise<Response>;
+//# sourceMappingURL=route-handler.d.ts.map

package/dist/api/route-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-handler.d.ts","sourceRoot":"","sources":["../../src/api/route-handler.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAkB,YAAY,EAAE,MAAM,UAAU,CAAC;AAE1F;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,YAAY,EAAE,CAazE;AAED,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,YAAY,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,eAAe,IAGxB,SAAS,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC,CAiFzE;AAED,MAAM,WAAW,gBAAgB;IAC/B,oFAAoF;IACpF,aAAa,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,SAAS,EAAE,OAAO,CAAC;IACnB,mEAAmE;IACnE,SAAS,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;CACzC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,gBAAgB,IACzB,SAAS,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC,CAyB1E"}

package/dist/api/route-handler.js

@@ -0,0 +1,135 @@
+import { createSearchClient } from '../client/search-client';
+import { debugLog } from '../debug';
+import { baseEntryId } from '../indexing/document-builder';
+/**
+ * Groups results by base entry ID and keeps the highest-scoring chunk per entry.
+ * Results are returned in score-descending order.
+ */
+export function deduplicateChunks(results) {
+    const seen = new Map();
+    for (const result of results) {
+        const entryId = baseEntryId(result.id);
+        const existing = seen.get(entryId);
+        if (!existing || result.score > existing.score) {
+            seen.set(entryId, result);
+        }
+    }
+    return [...seen.values()].sort((a, b) => b.score - a.score);
+}
+/**
+ * Creates a Next.js GET route handler for search queries.
+ *
+ * Query params:
+ * - `q` -- search query (required)
+ * - `limit` -- max results (default: 20)
+ * - `filter` -- Upstash metadata filter expression
+ *
+ * @example
+ * ```ts
+ * // app/api/search/route.ts
+ * import { createSearchApiHandler } from '@se-studio/search/api';
+ * export const GET = createSearchApiHandler({ ... });
+ * ```
+ */
+export function createSearchApiHandler(config) {
+    const client = createSearchClient(config.searchConfig);
+    return async function searchHandler(request) {
+        const { searchParams } = new URL(request.url);
+        const query = (searchParams.get('q') ?? '').trim();
+        debugLog('api', `GET /api/search`, { query, params: Object.fromEntries(searchParams) });
+        if (!query) {
+            debugLog('api', 'Empty query, returning empty results');
+            return Response.json({ results: [], query: '', totalCount: 0 }, {
+                status: 200,
+            });
+        }
+        const limit = Math.min(Number(searchParams.get('limit')) || 20, 100);
+        const filter = searchParams.get('filter') ?? undefined;
+        const indexName = config.isPreview ? config.previewIndexName : config.publishedIndexName;
+        // Over-fetch to account for multiple chunks per entry, then deduplicate
+        const fetchLimit = Math.min(limit * 3, 100);
+        debugLog('api', `Querying index "${indexName}"`, {
+            query,
+            limit,
+            fetchLimit,
+            filter,
+            isPreview: config.isPreview,
+        });
+        try {
+            const response = await client.search(indexName, { query, limit: fetchLimit, filter });
+            debugLog('api', `Search returned ${response.totalCount} raw results for "${query}"`);
+            debugLog('api', 'Raw chunks (before dedup)', response.results.map((r) => ({
+                id: r.id,
+                title: r.content.title,
+                type: r.metadata.type,
+                slug: r.metadata.slug,
+                score: r.score,
+                chunkIndex: r.metadata.chunkIndex,
+                bodySnippet: r.content.body.slice(0, 200),
+            })));
+            const deduplicated = deduplicateChunks(response.results);
+            const trimmed = deduplicated.slice(0, limit);
+            debugLog('api', `After dedup: ${deduplicated.length} unique entries, returning ${trimmed.length}`);
+            debugLog('api', 'Final results', trimmed.map((r, i) => ({
+                rank: i + 1,
+                entryId: r.metadata.entryId,
+                title: r.content.title,
+                type: r.metadata.type,
+                slug: r.metadata.slug,
+                score: r.score,
+                description: r.content.description.slice(0, 150),
+            })));
+            const deduped = {
+                results: trimmed,
+                query: response.query,
+                totalCount: deduplicated.length,
+            };
+            return Response.json(deduped, { status: 200 });
+        }
+        catch (err) {
+            console.error('[search] Search query failed:', err);
+            debugLog('api', 'Search query threw an error', { error: String(err) });
+            return Response.json({ error: 'Search failed' }, { status: 500 });
+        }
+    };
+}
+/**
+ * Creates a Next.js POST route handler for triggering a full search index rebuild.
+ * Protected by `Authorization: Bearer <secret>`.
+ *
+ * The index to rebuild (published vs preview) is determined by the app's
+ * own preview state via `isPreview`, not by a query parameter.
+ *
+ * @example
+ * ```ts
+ * // app/api/search/rebuild/route.ts
+ * import { createRebuildApiHandler } from '@se-studio/search/api';
+ * export const POST = createRebuildApiHandler({ ... });
+ * ```
+ */
+export function createRebuildApiHandler(config) {
+    return async function rebuildHandler(request) {
+        debugLog('api', 'POST /api/search/rebuild', { isPreview: config.isPreview });
+        const authHeader = request.headers.get('Authorization');
+        const token = authHeader?.startsWith('Bearer ') ? authHeader.slice(7) : null;
+        if (!token || token !== config.rebuildSecret) {
+            debugLog('api', 'Rebuild: unauthorized (bad or missing token)', {
+                hasAuthHeader: !!authHeader,
+                hasSecret: !!config.rebuildSecret,
+            });
+            return Response.json({ error: 'Unauthorized' }, { status: 401 });
+        }
+        debugLog('api', `Rebuild: authorized, isPreview=${config.isPreview}`);
+        try {
+            const result = await config.rebuildFn();
+            debugLog('api', 'Rebuild complete', result);
+            return Response.json(result, { status: 200 });
+        }
+        catch (err) {
+            console.error('[search] Rebuild failed:', err);
+            debugLog('api', 'Rebuild threw an error', { error: String(err) });
+            return Response.json({ error: 'Rebuild failed' }, { status: 500 });
+        }
+    };
+}
+//# sourceMappingURL=route-handler.js.map

package/dist/api/route-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-handler.js","sourceRoot":"","sources":["../../src/api/route-handler.ts"],"names":[],"mappings":"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"}

package/dist/client/index.d.ts

@@ -0,0 +1,2 @@
+export { createSearchClient, type SearchClient } from './search-client';
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/client/index.js

@@ -0,0 +1,2 @@
+export { createSearchClient } from './search-client';
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAqB,MAAM,iBAAiB,CAAC"}

package/dist/client/search-client.d.ts

@@ -0,0 +1,12 @@
+import type { SearchConfig, SearchDocument, SearchOptions, SearchResponse } from '../types';
+/**
+ * Creates a typed Upstash Search client bound to a single database.
+ * Use separate index names for published vs preview content.
+ */
+export declare function createSearchClient(config: SearchConfig): {
+    search(indexName: string, options: SearchOptions): Promise<SearchResponse>;
+    upsert(indexName: string, documents: SearchDocument[]): Promise<void>;
+    delete(indexName: string, ids: string[]): Promise<void>;
+};
+export type SearchClient = ReturnType<typeof createSearchClient>;
+//# sourceMappingURL=search-client.d.ts.map

package/dist/client/search-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-client.d.ts","sourceRoot":"","sources":["../../src/client/search-client.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,YAAY,EACZ,cAAc,EAEd,aAAa,EACb,cAAc,EAEf,MAAM,UAAU,CAAC;AAOlB;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY;sBAY3B,MAAM,WAAW,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC;sBA8BxD,MAAM,aAAa,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;sBA6BnD,MAAM,OAAO,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;EAQhE;AAED,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/client/search-client.js

@@ -0,0 +1,72 @@
+import { Search } from '@upstash/search';
+import { debugLog } from '../debug';
+const UPSTASH_BATCH_LIMIT = 100;
+/**
+ * Creates a typed Upstash Search client bound to a single database.
+ * Use separate index names for published vs preview content.
+ */
+export function createSearchClient(config) {
+    debugLog('client', 'Creating search client', {
+        url: config.url ? `${config.url.slice(0, 30)}...` : '(empty)',
+        hasToken: !!config.token,
+    });
+    const client = new Search({ url: config.url, token: config.token });
+    function getIndex(indexName) {
+        return client.index(indexName);
+    }
+    return {
+        async search(indexName, options) {
+            debugLog('client', `search("${indexName}")`, {
+                query: options.query,
+                limit: options.limit,
+                filter: options.filter,
+            });
+            const index = getIndex(indexName);
+            const results = await index.search({
+                query: options.query,
+                limit: options.limit ?? 20,
+                filter: options.filter,
+                semanticWeight: options.semanticWeight,
+            });
+            debugLog('client', `search("${indexName}") returned ${results.length} raw results`);
+            const mapped = results.map((r) => ({
+                id: r.id,
+                content: r.content,
+                metadata: r.metadata,
+                score: r.score,
+            }));
+            return {
+                results: mapped,
+                query: options.query,
+                totalCount: mapped.length,
+            };
+        },
+        async upsert(indexName, documents) {
+            const totalBatches = Math.ceil(documents.length / UPSTASH_BATCH_LIMIT);
+            debugLog('client', `upsert("${indexName}"): ${documents.length} docs in ${totalBatches} batch(es)`);
+            const index = getIndex(indexName);
+            for (let i = 0; i < documents.length; i += UPSTASH_BATCH_LIMIT) {
+                const batch = documents.slice(i, i + UPSTASH_BATCH_LIMIT);
+                const batchNum = Math.floor(i / UPSTASH_BATCH_LIMIT) + 1;
+                debugLog('client', `upsert("${indexName}") batch ${batchNum}/${totalBatches}: ${batch.length} docs`, {
+                    ids: batch.map((d) => d.id),
+                });
+                await index.upsert(batch.map((doc) => ({
+                    id: doc.id,
+                    content: doc.content,
+                    metadata: doc.metadata,
+                })));
+                debugLog('client', `upsert("${indexName}") batch ${batchNum}/${totalBatches}: done`);
+            }
+        },
+        async delete(indexName, ids) {
+            if (ids.length === 0)
+                return;
+            debugLog('client', `delete("${indexName}"): ${ids.length} id(s)`, { ids });
+            const index = getIndex(indexName);
+            await index.delete(ids);
+            debugLog('client', `delete("${indexName}"): done`);
+        },
+    };
+}
+//# sourceMappingURL=search-client.js.map

package/dist/client/search-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-client.js","sourceRoot":"","sources":["../../src/client/search-client.ts"],"names":[],"mappings":"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"}

package/dist/debug.d.ts

@@ -0,0 +1,2 @@
+export declare function debugLog(area: string, message: string, data?: unknown): void;
+//# sourceMappingURL=debug.d.ts.map

package/dist/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../src/debug.ts"],"names":[],"mappings":"AAEA,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,QAOrE"}

package/dist/debug.js

@@ -0,0 +1,12 @@
+const isDebug = () => process.env.DEBUG_SEARCH === 'true';
+export function debugLog(area, message, data) {
+    if (!isDebug())
+        return;
+    if (data !== undefined) {
+        console.log(`[search:${area}] ${message}`, JSON.stringify(data, null, 2));
+    }
+    else {
+        console.log(`[search:${area}] ${message}`);
+    }
+}
+//# sourceMappingURL=debug.js.map

package/dist/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.js","sourceRoot":"","sources":["../src/debug.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,KAAK,MAAM,CAAC;AAE1D,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,OAAe,EAAE,IAAc;IACpE,IAAI,CAAC,OAAO,EAAE;QAAE,OAAO;IACvB,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,KAAK,OAAO,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAC5E,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC;IAC7C,CAAC;AACH,CAAC"}

package/dist/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export { type UseSearchOptions, type UseSearchReturn, useSearch } from './useSearch';
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/hooks/index.js

@@ -0,0 +1,2 @@
+export { useSearch } from './useSearch';
+//# sourceMappingURL=index.js.map

package/dist/hooks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+C,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/hooks/useSearch.d.ts

@@ -0,0 +1,26 @@
+import type { SearchResult } from '../types';
+export interface UseSearchOptions {
+    /** Debounce delay in milliseconds. Default: 300. */
+    debounceMs?: number;
+    /** Max results per query. Default: 20. */
+    limit?: number;
+    /** API endpoint path. Default: '/api/search'. */
+    apiPath?: string;
+    /** Seed the query on first render (e.g. from a URL param). Ignored after mount. */
+    initialQuery?: string;
+}
+export interface UseSearchReturn {
+    query: string;
+    setQuery: (q: string) => void;
+    results: SearchResult[];
+    isLoading: boolean;
+    error: string | null;
+    totalCount: number;
+}
+/**
+ * Client-side hook for searching via the app's `/api/search` endpoint.
+ * Manages query state, debouncing, loading, and error handling.
+ * Apps build their own search UI on top of this hook.
+ */
+export declare function useSearch(options?: UseSearchOptions): UseSearchReturn;
+//# sourceMappingURL=useSearch.d.ts.map

package/dist/hooks/useSearch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSearch.d.ts","sourceRoot":"","sources":["../../src/hooks/useSearch.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7D,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mFAAmF;IACnF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,eAAe,CA2ErE"}