@se-studio/search 1.0.55 → 1.0.58

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @se-studio/search
 
+## 1.0.58
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+- Updated dependencies
+  - @se-studio/contentful-rest-api@1.0.154
+  - @se-studio/core-data-types@1.0.147
+  - @se-studio/markdown-renderer@1.0.111
+
+## 1.0.57
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+- Updated dependencies
+  - @se-studio/contentful-rest-api@1.0.153
+  - @se-studio/core-data-types@1.0.146
+  - @se-studio/markdown-renderer@1.0.110
+
+## 1.0.56
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+- Updated dependencies
+  - @se-studio/contentful-rest-api@1.0.152
+  - @se-studio/core-data-types@1.0.145
+  - @se-studio/markdown-renderer@1.0.109
+
 ## 1.0.55
 
 ### Patch Changes

package/docs/llms.md

@@ -0,0 +1,114 @@
+# @se-studio/search — LLM Reference
+
+AI-powered site search using Upstash Search (vector + keyword hybrid). Indexes Contentful pages, articles, persons, and custom types. Provides Next.js API route handlers for search queries and index rebuilds.
+
+## Required Environment Variables
+
+```bash
+UPSTASH_SEARCH_REST_URL=https://...
+UPSTASH_SEARCH_REST_TOKEN=...
+```
+
+## Key Types
+
+```ts
+import type {
+  SearchConfig,           // { url, token } — Upstash connection
+  SearchIndexConfig,      // { connection, publishedIndexName, previewIndexName }
+  SearchIndexingConfig,   // full config passed to rebuildSearchIndex / webhook handler
+  SearchableContentType,  // 'page' | 'article' | 'person' | 'articleType' | 'customType'
+  ContentTypeIndexConfig, // { type, enabled, includeComponents? }
+  SearchDocument,         // { id, content: { title, description, body }, metadata }
+  SearchDocumentMetadata, // { type, slug, href, tags?, date?, imageUrl?, entryId, ... }
+  SearchResult,           // SearchDocument + score
+  SearchResponse,         // { results, query, totalCount }
+  SearchOptions,          // { query, limit?, filter?, semanticWeight? }
+  RebuildResult,          // { indexed, skipped, errors }
+} from '@se-studio/search';
+```
+
+## Full Index Rebuild
+
+Rebuilds the entire published (or preview) search index from Contentful:
+
+```ts
+import { rebuildSearchIndex } from '@se-studio/search';
+
+const result = await rebuildSearchIndex({
+  contentfulConfig,   // ContentfulConfig from @se-studio/contentful-rest-api
+  indexingConfig,     // SearchIndexingConfig
+  preview: false,     // true to rebuild the preview index
+});
+// result: { indexed: number, skipped: number, errors: string[] }
+```
+
+## Incremental Updates via Webhook
+
+Creates a handler for Contentful webhooks to update the index on content changes:
+
+```ts
+import { createSearchWebhookHandler } from '@se-studio/search';
+
+const handler = createSearchWebhookHandler({
+  contentfulConfig,
+  indexingConfig,
+  secret: process.env.WEBHOOK_SECRET!,
+});
+
+// In a Next.js API route:
+export const POST = handler.handle;
+```
+
+## Search API Route Handlers
+
+```ts
+import { createSearchApiHandler, createRebuildApiHandler } from '@se-studio/search';
+
+// Search endpoint (GET /api/search?q=...)
+export const GET = createSearchApiHandler({
+  searchConfig: { url: process.env.UPSTASH_SEARCH_REST_URL!, token: process.env.UPSTASH_SEARCH_REST_TOKEN! },
+  publishedIndexName: 'published',
+  previewIndexName: 'preview',
+});
+
+// Rebuild endpoint (POST /api/search/rebuild)
+export const POST = createRebuildApiHandler({
+  contentfulConfig,
+  indexingConfig,
+  secret: process.env.REBUILD_SECRET!,
+});
+```
+
+## SearchIndexingConfig Shape
+
+```ts
+const indexingConfig: SearchIndexingConfig = {
+  searchIndex: {
+    connection: { url: '...', token: '...' },
+    publishedIndexName: 'my-site-published',
+    previewIndexName: 'my-site-preview',
+  },
+  contentTypes: [
+    { type: 'page', enabled: true },
+    { type: 'article', enabled: true },
+    { type: 'person', enabled: false },
+  ],
+  indexComponents: true,       // extract text from nested components (default: true)
+  respectIndexedFlag: true,    // skip entries with indexed === false (default: true)
+  respectHiddenFlag: true,     // skip entries with hidden === true (default: true)
+  documentTransformer: (doc, contentData) => {
+    // optionally patch doc.metadata before upsert, or return null to drop
+    return doc;
+  },
+};
+```
+
+## Deduplication
+
+Search results can contain multiple chunks from the same entry. Use `deduplicateChunks` to collapse them:
+
+```ts
+import { deduplicateChunks } from '@se-studio/search';
+
+const deduped = deduplicateChunks(results); // keeps highest-score chunk per entry
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/search",
-  "version": "1.0.55",
+  "version": "1.0.58",
   "description": "AI-powered site search with Upstash Search for Next.js marketing sites",
   "repository": {
     "type": "git",
@@ -39,13 +39,14 @@
   },
   "files": [
     "dist",
-    "*.md"
+    "*.md",
+    "docs"
   ],
   "dependencies": {
     "@upstash/search": "^0.1.7",
-    "@se-studio/contentful-rest-api": "1.0.151",
-    "@se-studio/core-data-types": "1.0.144",
-    "@se-studio/markdown-renderer": "1.0.108"
+    "@se-studio/contentful-rest-api": "1.0.154",
+    "@se-studio/core-data-types": "1.0.147",
+    "@se-studio/markdown-renderer": "1.0.111"
   },
   "peerDependencies": {
     "next": ">=15.5.0",