@mframework/layer-search 0.0.1

package/app/composables/useSearchkit.ts

@@ -0,0 +1,218 @@
+import { ref, computed } from 'vue'
+export type SearchHit = Record<string, any>
+import { useNuxtApp } from 'nuxt/app'
+
+export function useSearchkit() {
+  const nuxt = useNuxtApp() as any
+  const client: any = nuxt.$searchClient
+  const indexName: string = (nuxt.$searchIndexName as string) || 'default'
+  const helpers: any = nuxt.$searchHelpers || {}
+
+  const query = ref('')
+  const hits = ref<SearchHit[]>([])
+  const total = ref(0)
+  const loading = ref(false)
+  const page = ref(1)
+  const perPage = ref(12)
+  const sortBy = ref<string | null>(null)
+  const facets = ref<Record<string, any>>({})
+  const geo = ref<{ lat?: number; lon?: number; distanceKm?: number }>({})
+  const semantic = ref(false)
+  const ranking = ref<'relevance' | 'newest' | 'popularity' | 'custom'>('relevance')
+
+  async function search() {
+    if (!client || typeof client.search !== 'function') {
+      throw new Error('Search client is not available or does not implement `search`')
+    }
+
+    loading.value = true
+    const from = (page.value - 1) * perPage.value
+
+    // Build params — aim for compatibility with Searchkit/Elasticsearch via instantsearch client.
+    const params: any = {
+      params: {
+        q: query.value || '*',
+        size: perPage.value,
+        from,
+      },
+    }
+
+    // Sorting strategies
+    if (ranking.value === 'newest') {
+      params.params.sort = 'created_at:desc'
+    } else if (ranking.value === 'popularity') {
+      params.params.sort = 'popularity:desc'
+    } else if (sortBy.value) {
+      params.params.sort = sortBy.value
+    }
+
+    // Geo filter: translate into an Elasticsearch geo_distance filter in body
+    if (geo.value.lat && geo.value.lon && geo.value.distanceKm) {
+      params.body = params.body || {}
+      params.body.query = params.body.query || { bool: { must: [{ match_all: {} }], filter: [] } }
+      const filter = { geo_distance: { distance: `${geo.value.distanceKm}km`, location: { lat: geo.value.lat, lon: geo.value.lon } } }
+      params.body.query.bool.filter.push(filter)
+    }
+
+    // Semantic hint flag — some backends will honour this to run semantic/rerank
+    if (semantic.value) {
+      params.params.semantic = true
+    }
+
+    try {
+      const results = await client.search([{ indexName, ...params }])
+      const res = results && results[0]
+      if (!res) {
+        hits.value = []
+        total.value = 0
+        facets.value = {}
+        return
+      }
+
+      // Best-effort parsing for common instantsearch-style responses
+      const rawHits = (res.hits && res.hits.hits) || (res.hits && res.hits) || res.hits
+      let parsedHits: any[] = []
+      if (Array.isArray(rawHits)) {
+        // ES style hits.hits
+        parsedHits = rawHits.map((h: any) => (h._source ? { ...h._source, _meta: h._id } : h))
+      } else if (res.hits && res.hits.hits) {
+        parsedHits = res.hits.hits.map((h: any) => (h._source ? { ...h._source, _meta: h._id } : h))
+      } else if (res.hits) {
+        parsedHits = res.hits
+      } else {
+        parsedHits = []
+      }
+
+      total.value = (res.hits && (res.hits.total?.value ?? res.hits.total)) || res.nbHits || 0
+
+      // Aggregations / facets parsing (normalize via plugin helper when available)
+      const rawAggs = res.aggregations || res.facets || {}
+      if (helpers && typeof helpers.mapAggregations === 'function') {
+        try {
+          facets.value = helpers.mapAggregations(rawAggs)
+        } catch (e) {
+          facets.value = rawAggs
+        }
+      } else {
+        facets.value = rawAggs
+      }
+
+      // If semantic rerank is enabled, attempt to call the plugin helper to reorder results.
+      if (semantic.value && helpers && typeof helpers.semanticRerank === 'function') {
+        try {
+          const reranked = await helpers.semanticRerank(parsedHits, query.value)
+          hits.value = Array.isArray(reranked) ? reranked : parsedHits
+        } catch (e) {
+          // fallback to parsedHits on error
+          hits.value = parsedHits
+        }
+      } else {
+        hits.value = parsedHits
+      }
+    } finally {
+      loading.value = false
+    }
+  }
+
+  async function autocomplete(input: string, limit = 6) {
+    if (!client) return []
+    try {
+      // Use a small search request to act as suggestions
+      const params = {
+        params: { q: input || '*', size: limit },
+      }
+      const result = await client.search([{ indexName, ...params }])
+      const r = result && result[0]
+      const suggestionHits = (r && ((r.hits && r.hits.hits) || r.hits)) || []
+      return Array.isArray(suggestionHits)
+        ? suggestionHits.map((h: any) => (h._source ? h._source : h))
+        : []
+    } catch (e) {
+      return []
+    }
+  }
+
+  function setPage(p: number) {
+    page.value = p
+    return search()
+  }
+
+  function setPerPage(n: number) {
+    perPage.value = n
+    page.value = 1
+    return search()
+  }
+
+  function setSort(sort: string | null) {
+    sortBy.value = sort
+    return search()
+  }
+
+  function setGeo(lat: number, lon: number, distanceKm = 50) {
+    geo.value = { lat, lon, distanceKm }
+    page.value = 1
+    return search()
+  }
+
+  function setSemantic(enabled: boolean) {
+    semantic.value = enabled
+    return search()
+  }
+
+  const totalPages = computed(() => Math.max(1, Math.ceil((total.value || 0) / perPage.value)))
+
+  // Provide a normalized facets structure for consumers: { facetName: [{ key, doc_count }, ...] }
+  const normalizedFacets = computed(() => {
+    const out: Record<string, Array<{ key: string; doc_count: number }>> = {}
+    try {
+      for (const k of Object.keys(facets.value || {})) {
+        const v = (facets.value as any)[k]
+        if (!v) {
+          out[k] = []
+          continue
+        }
+        if (Array.isArray(v)) {
+          out[k] = v.map((b: any) => ({ key: b.key ?? b.value ?? String(b), doc_count: b.doc_count ?? b.count ?? 0 }))
+        } else if (v.buckets) {
+          out[k] = v.buckets.map((b: any) => ({ key: b.key ?? b.value, doc_count: b.doc_count ?? 0 }))
+        } else if (v.terms) {
+          out[k] = v.terms.map((b: any) => ({ key: b.key ?? b.value, doc_count: b.doc_count ?? 0 }))
+        } else {
+          // generic object — try to map entries
+          out[k] = Object.keys(v).map((kk) => ({ key: kk, doc_count: (v as any)[kk] }))
+        }
+      }
+    } catch (e) {
+      return {}
+    }
+    return out
+  })
+
+  return {
+    // state
+    query,
+    hits,
+    total,
+    loading,
+    page,
+    perPage,
+    sortBy,
+    facets,
+    geo,
+    semantic,
+    ranking,
+    totalPages,
+
+    // actions
+    search,
+    autocomplete,
+    setPage,
+    setPerPage,
+    setSort,
+    setGeo,
+    setSemantic,
+    normalizedFacets,
+  }
+}
+
+export default useSearchkit

package/app/composables/utils/health.ts

@@ -0,0 +1,13 @@
+import type { MeeoviSearchAdapter } from '../adapter/types'
+
+export async function checkAdapterHealth(adapter?: MeeoviSearchAdapter) {
+  if (!adapter) return { ok: false, error: 'no adapter' }
+  try {
+    const res = await adapter.search({ term: '', page: 1, pageSize: 1, filters: {} } as any)
+    return { ok: true, total: res?.total ?? null }
+  } catch (e: any) {
+    return { ok: false, error: e?.message || String(e) }
+  }
+}
+
+export default checkAdapterHealth

package/app/composables/utils/normalizers.ts

@@ -0,0 +1,6 @@
+export function normalizeOpenSearchHit(hit: any) {
+  return {
+    id: hit._id,
+    ...hit._source
+  }
+}

package/app/pages/results.vue

@@ -0,0 +1,85 @@
+<template>
+  <div class="resultsPage">
+    <ais-instant-search :search-client="searchClient" :index-name="indexName">
+      <header class="search-header">
+        <ais-search-box />
+        <ais-stats />
+        <ais-sort-by :items="sortingOptions" />
+      </header>
+
+      <div class="search-body">
+        <aside class="filters">
+          <ais-refinement-list attribute="category" />
+          <ais-refinement-list attribute="brand" />
+          <ais-range-input attribute="price" />
+          <ais-rating-menu attribute="rating_rounded" />
+        </aside>
+
+        <main class="results">
+          <ais-hits>
+            <template #item="{ item }">
+              <article @click="openResult(item)" class="hit">
+                <h3><ais-highlight attribute="title" :hit="item" /></h3>
+                <p><ais-snippet attribute="plot" :hit="item" /></p>
+              </article>
+            </template>
+          </ais-hits>
+
+          <ais-pagination />
+        </main>
+      </div>
+    </ais-instant-search>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { useRouter, useRoute } from 'vue-router'
+import { useRuntimeConfig } from '#imports'
+import Client from '@searchkit/instantsearch-client'
+import { getSearchClient, getIndexName } from '../utils/search/client'
+
+import 'instantsearch.css/themes/satellite-min.css'
+
+// initialize search client using existing helper (falls back safely)
+let searchClient
+let indexName = 'default'
+try {
+  searchClient = getSearchClient()
+  indexName = getIndexName()
+} catch (e) {
+  // fallback placeholder
+  // eslint-disable-next-line no-console
+  console.warn('Search client unavailable:', e.message || e)
+  searchClient = { _client: 'searchkit-fallback' }
+}
+
+const router = useRouter()
+const route = useRoute()
+
+function openResult(item) {
+  const id = item._id ?? item.id ?? ''
+  const title = item.title ?? item.name ?? ''
+  router.push({ path: route.path, query: { ...route.query, id, title } })
+}
+
+const sortingOptions = [
+  { value: indexName, label: 'Featured' },
+  { value: `${indexName}:price:asc`, label: 'Price: Low to High' },
+  { value: `${indexName}:price:desc`, label: 'Price: High to Low' },
+  { value: `${indexName}:rating:desc`, label: 'Rating: High to Low' }
+]
+
+definePageMeta({ layout: 'nolive' })
+useHead({ title: 'Search Results' })
+</script>
+
+<style scoped>
+.search-body {
+  display: flex;
+  gap: 1rem;
+}
+.filters { width: 260px }
+.results { flex: 1 }
+.hit { padding: 0.75rem; border-bottom: 1px solid #eee }
+</style>

package/app/plugins/instantsearch.js

@@ -0,0 +1,35 @@
+import { h } from 'vue'
+import { defineNuxtPlugin } from '#imports'
+import InstantSearch from 'vue-instantsearch/vue3/es'
+
+export default defineNuxtPlugin(nuxtApp => {
+  // Register the original InstantSearch plugin (registers other components)
+  nuxtApp.vueApp.use(InstantSearch)
+  // Capture the original registered component (if the plugin registered it)
+  const OriginalInstantSearch = nuxtApp.vueApp.component('ais-instant-search') || InstantSearch
+
+  // Override `ais-instant-search` with a small wrapper that sets
+  // future.preserveSharedStateOnUnmount = true by default to silence
+  // the deprecation warning and adopt the new behavior.
+  const AisInstantSearchWrapper = {
+    name: 'AisInstantSearch',
+    inheritAttrs: false,
+    setup(_, { attrs, slots }) {
+      const mergedAttrs = {
+        ...attrs,
+        future: {
+          preserveSharedStateOnUnmount: true,
+          ...(attrs.future || {})
+        }
+      }
+      if (process.env.NODE_ENV !== 'production') {
+        // helpful debug when running locally
+        // eslint-disable-next-line no-console
+        console.debug('[instantsearch] merged future options', mergedAttrs.future)
+      }
+      return () => h(OriginalInstantSearch, mergedAttrs, slots)
+    }
+  }
+
+  nuxtApp.vueApp.component('ais-instant-search', AisInstantSearchWrapper)
+})

package/app/plugins/search.js

@@ -0,0 +1,103 @@
+import { defineNuxtPlugin } from '#imports'
+import { getSearchClient, getIndexName } from '../utils/search/client'
+
+export default defineNuxtPlugin((nuxtApp) => {
+  let searchClient
+  let indexName
+  try {
+    searchClient = getSearchClient()
+    indexName = getIndexName()
+  } catch (e) {
+    // fallback placeholder to avoid build/runtime crash when not configured
+    // Provide a clearer validation message to help users wire env vars
+    // eslint-disable-next-line no-console
+    console.warn('Search client not configured:', e.message || e)
+    // Helpful runtime guidance
+    // eslint-disable-next-line no-console
+    console.info('Search layer requires configuring SEARCHKIT_HOST or SEARCHKIT_HOSTNAME/SEARCHKIT_PORT (or their NUXT_PUBLIC_ variants). Example:')
+    // eslint-disable-next-line no-console
+    console.info('  SEARCHKIT_HOST=https://search.example.com')
+    // eslint-disable-next-line no-console
+    console.info('  or:')
+    // eslint-disable-next-line no-console
+    console.info('  SEARCHKIT_PROTOCOL=https')
+    // eslint-disable-next-line no-console
+    console.info('  SEARCHKIT_HOSTNAME=search.example.com')
+    // eslint-disable-next-line no-console
+    console.info('  SEARCHKIT_PORT=9200')
+    searchClient = { _client: 'searchkit-fallback' }
+    indexName = 'default'
+  }
+
+  // Helper: normalize aggregations/ facets into { name: buckets[] }
+  function mapAggregations(aggs) {
+    const mapped = {}
+    if (!aggs) return mapped
+    for (const key of Object.keys(aggs)) {
+      const a = aggs[key]
+      if (!a) continue
+      if (Array.isArray(a)) mapped[key] = a
+      else if (a.buckets) mapped[key] = a.buckets
+      else if (a.terms) mapped[key] = a.terms
+      else mapped[key] = a
+    }
+    return mapped
+  }
+
+  // Basic suggestion helper that performs a small search to return candidate documents
+  async function suggest(q, opts = {}) {
+    if (!searchClient || typeof searchClient.search !== 'function') return []
+    const size = opts.size || 6
+    const params = { params: { q: q || '*', size } }
+    try {
+      const resArr = await searchClient.search([{ indexName, ...params }])
+      const res = resArr && resArr[0]
+      const hits = (res && ((res.hits && res.hits.hits) || res.hits)) || []
+      return Array.isArray(hits) ? hits.map((h) => (h._source ? h._source : h)) : []
+    } catch (e) {
+      // eslint-disable-next-line no-console
+      console.warn('Suggest failed', e && e.message ? e.message : e)
+      return []
+    }
+  }
+
+  // Server-side semantic reranking: call embeddings API if configured, otherwise noop.
+  // Expects an embeddings API that can accept { query, docs } and return either
+  // { ranked: [ids...] } or { scores: [number...] } aligned with docs.
+  async function semanticRerank(hitsArray, queryStr) {
+    const url = process.env.NUXT_PUBLIC_EMBEDDINGS_API_URL || process.env.EMBEDDINGS_API_URL
+    const key = process.env.NUXT_PUBLIC_EMBEDDINGS_API_KEY || process.env.EMBEDDINGS_API_KEY
+    if (!url || !key) return hitsArray
+    try {
+      const docs = hitsArray.slice(0, 100).map((h) => ({ id: h._meta || h.id || h._id, text: h.title || h.name || h.description || '' }))
+      const body = { query: queryStr, docs }
+      const resp = await (globalThis.fetch || fetch)(url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` },
+        body: JSON.stringify(body),
+      })
+      if (!resp.ok) return hitsArray
+      const json = await resp.json()
+      if (Array.isArray(json.ranked)) {
+        const idToHit = new Map(hitsArray.map((h) => [(h._meta || h.id || h._id), h]))
+        const ordered = json.ranked.map((id) => idToHit.get(id)).filter(Boolean)
+        const remaining = hitsArray.filter((h) => !ordered.includes(h))
+        return [...ordered, ...remaining]
+      }
+      if (Array.isArray(json.scores)) {
+        const paired = hitsArray.map((h, i) => ({ h, s: json.scores[i] ?? 0 }))
+        paired.sort((a, b) => b.s - a.s)
+        return paired.map((p) => p.h)
+      }
+      return hitsArray
+    } catch (e) {
+      // eslint-disable-next-line no-console
+      console.warn('semanticRerank failed', e && e.message ? e.message : e)
+      return hitsArray
+    }
+  }
+
+  nuxtApp.provide('searchClient', searchClient)
+  nuxtApp.provide('searchIndexName', indexName)
+  nuxtApp.provide('searchHelpers', { suggest, mapAggregations, semanticRerank })
+})

package/app/plugins/searchClient.ts

@@ -0,0 +1,108 @@
+import { defineNuxtPlugin, useRuntimeConfig } from 'nuxt/app'
+
+export default defineNuxtPlugin(() => {
+  const config = useRuntimeConfig() as any
+  const endpoint: string | undefined = config.search?.endpoint || process.env.SEARCH_ENDPOINT
+  const indexName: string = config.search?.indexName || process.env.SEARCH_INDEX_NAME || 'default'
+
+  // Simple helpers that consumers may rely on
+  const helpers = {
+    mapAggregations(aggs: any) {
+      return aggs || {}
+    },
+    async semanticRerank(hits: any[], _query: string) {
+      // no-op rerank: return input
+      return hits
+    },
+  }
+
+  // HTTP-backed ES-compatible client when endpoint is configured
+  const httpClient = endpoint
+    ? {
+        async search(requests: Array<any>) {
+          const base = endpoint.replace(/\/+$/, '')
+          return Promise.all(
+            requests.map(async (req: any) => {
+              const idx = req.indexName || indexName
+              // Build a basic ES query body from params
+              let body: any = {}
+
+              // If params contains q/size/from, map to simple query_string
+              if (req.params) {
+                const p = req.params
+                const q = (p.q || (p.params && p.params.q)) || '*'
+                const size = p.size || (p.params && p.params.size) || 10
+                const from = p.from || 0
+                if (!req.body) body = {}
+                if (q && q !== '*') {
+                  body.query = { query_string: { query: q } }
+                } else if (!req.body) {
+                  body.query = { match_all: {} }
+                }
+                body.size = size
+                body.from = from
+              }
+
+              if (req.body) {
+                body = { ...body, ...req.body }
+              }
+
+              // fetch with retries and exponential backoff
+              async function fetchWithRetry(url: string, init: RequestInit, retries = 2, backoff = 200): Promise<any> {
+                try {
+                  const res = await fetch(url, init)
+                  if (!res.ok) {
+                    const text = await res.text().catch(() => '')
+                    if (retries > 0) {
+                      await new Promise((r) => setTimeout(r, backoff))
+                      return fetchWithRetry(url, init, retries - 1, backoff * 2)
+                    }
+                    return { hits: [], error: `HTTP ${res.status}: ${text}` }
+                  }
+                  return await res.json()
+                } catch (err) {
+                  if (retries > 0) {
+                    await new Promise((r) => setTimeout(r, backoff))
+                    return fetchWithRetry(url, init, retries - 1, backoff * 2)
+                  }
+                  return { hits: [], error: String(err) }
+                }
+              }
+
+              const resJson = await fetchWithRetry(`${base}/${encodeURIComponent(idx)}/_search`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(body),
+              })
+              // Ensure a consistent shape on error
+              if (!resJson) return { hits: [] }
+              return resJson
+            })
+          )
+        },
+      }
+    : null
+
+  // In-memory fallback client for environments without an endpoint
+  const stubClient = {
+    async search(requests: Array<any>) {
+      return requests.map((req: any) => {
+        const q = (req.params && (req.params.q || (req.params.params && req.params.params.q))) || '*'
+        const hits = [
+          { _source: { title: q && q !== '*' ? `Result for ${q}` : 'Sample result', description: 'Stubbed result' } },
+        ]
+        return { hits: { hits }, aggregations: {}, nbHits: hits.length }
+      })
+    },
+  }
+
+  const client = httpClient || stubClient
+
+  return {
+    provide: {
+      $searchClient: client,
+      $searchIndexName: indexName,
+      $searchHelpers: helpers,
+    },
+  }
+})

package/app/utils/env.ts

@@ -0,0 +1,28 @@
+let shared: any = null
+try {
+	// Try to use the centralized shared helper at runtime when available
+	// Use require to avoid TypeScript resolving the module at compile-time for this layer project
+	// eslint-disable-next-line @typescript-eslint/no-var-requires
+	shared = require('../../../shared/app/utils/env')
+} catch (e) {
+	shared = null
+}
+
+export function getEnv(key: string, fallback?: string): string | undefined {
+	if (shared && typeof shared.getEnv === 'function') return shared.getEnv(key, fallback)
+	if (!key) return fallback
+	const direct = process.env[key]
+	if (direct !== undefined) return direct
+	const publicKey = `NUXT_PUBLIC_${key}`
+	if (process.env[publicKey] !== undefined) return process.env[publicKey]
+	return fallback
+}
+
+export function getEnvBool(key: string, fallback = false): boolean {
+	const v = getEnv(key)
+	if (v === undefined) return fallback
+	const low = String(v).toLowerCase()
+	return ['1', 'true', 'yes', 'on'].includes(low)
+}
+
+export default { getEnv, getEnvBool }

package/app/utils/search/client.ts

@@ -0,0 +1,53 @@
+// Lightweight helper to obtain a search client and index name for InstantSearch
+// This version NEVER throws — it returns null when search is not configured.
+
+import type { SearchClient } from 'instantsearch.js'
+import { getEnv } from '../env'
+
+export function getIndexName(): string {
+  return (
+    process.env.NUXT_PUBLIC_SEARCH_INDEX ||
+    process.env.SEARCH_INDEX ||
+    'default'
+  )
+}
+
+function buildHostFromParts(): string | null {
+  const explicit = getEnv('SEARCHKIT_HOST')
+  if (explicit) return explicit
+
+  const protocol = (getEnv('SEARCHKIT_PROTOCOL') || 'http').replace(/:\/\//, '')
+  const hostname = getEnv('SEARCHKIT_HOSTNAME')
+  const port = getEnv('SEARCHKIT_PORT')
+
+  if (!hostname) return null
+
+  return `${protocol}://${hostname}${port ? `:${port}` : ''}`
+}
+
+export function getSearchClient(): SearchClient | null {
+  const host = buildHostFromParts()
+  if (!host) {
+    console.warn('[search] Searchkit host not configured — search disabled')
+    return null
+  }
+
+  let createClient: any
+  try {
+    createClient = require('@searchkit/instantsearch-client')
+  } catch {
+    console.warn('[search] @searchkit/instantsearch-client not installed — search disabled')
+    return null
+  }
+
+  try {
+    const opts: any = { host }
+    const apiKey = getEnv('SEARCHKIT_API_KEY')
+    if (apiKey) opts.apiKey = apiKey
+
+    return createClient(opts)
+  } catch (e: any) {
+    console.warn('[search] Failed to create Searchkit client:', e?.message || e)
+    return null
+  }
+}

package/nuxt.config.ts

@@ -0,0 +1,11 @@
+import {
+  defineNuxtConfig
+} from 'nuxt/config'
+
+export default defineNuxtConfig({
+  $meta: {
+    name: 'search',
+  },
+
+  runtimeConfig: {}
+})