OpenSpec Change: enterprise-api-plugin-search

Change ID: enterprise-api-plugin-search
Package: @suaveplan/api-plugin-search
Category: api/data
Target path: api/data/api-plugin-search
Status: PROPOSED
Date: 2026-04-24
Reference spec: /mnt/s/web/suaveplan/enterprise/api-plugin-search.md

Summary

Deliver @suaveplan/api-plugin-search on the genesis branch from scratch at enterprise quality. Full-text and structured search plugin with pluggable backend adapters (SurrealDB built-in FTS, Meilisearch, Typesense, Elasticsearch). SearchAdapter port abstracts the backend; SearchService indexes documents and queries with filters, facets, pagination, and typo-tolerance. Routes under /search. Typed bus events: search:indexed, search:reindexed. Consumed by @suaveplan/api-plugin-cms, contacts, analytics, and others.

Available workspace deps on genesis

Package	Role
`@suaveplan/api` (`workspace:^`)	`definePlugin`
`@suaveplan/api-shared` (`workspace:^`)	Helpers
`@suaveplan/api-plugin-auth` (`workspace:^`)	`requireAuth`
`@suaveplan/api-plugin-database` (`workspace:^`)	SurrealDB default FTS
`@suaveplan/events` (`workspace:^`)	Event bus
`@suaveplan/error` (`workspace:^`)	`SearchError` hierarchy
`@suaveplan/rate-limiter` (`workspace:^`)	Rate limits
`hono` + `@hono/zod-openapi` + `zod`	Routes
`@opentelemetry/api`	OTel

Public API surface

function createSearchPlugin(adapter?: SearchAdapter, config?: SearchPluginConfig): PluginDescriptor

interface SearchAdapter {
  index(collection: string, doc: SearchDocument): Promise<void>
  indexMany(collection: string, docs: SearchDocument[]): Promise<void>
  delete(collection: string, id: string): Promise<void>
  search(collection: string, query: SearchQuery): Promise<SearchResult>
  reindex(collection: string): Promise<void>
}

interface SearchDocument { id: string; [key: string]: unknown }
interface SearchQuery { q: string; filters?: Record<string, unknown>; facets?: string[]; page?: number; pageSize?: number }
interface SearchResult { hits: SearchDocument[]; total: number; facets?: Record<string, FacetValue[]>; took: number }

Error codes

type SearchErrorCode =
  | "SEARCH_ADAPTER_ERROR"
  | "SEARCH_COLLECTION_NOT_FOUND"
  | "SEARCH_INDEX_FAILED"
  | "SEARCH_QUERY_INVALID"

File layout

api/data/api-plugin-search/
  package.json  tsconfig.json  vitest.config.ts
  src/
    index.ts  events.ts  types/  errors/
    adapters/search-adapter.port.ts  adapters/surrealdb-search.ts
    services/search/
    routes/search/
  tests/integration.test.ts

Impact

Prerequisites: @suaveplan/api, @suaveplan/api-plugin-auth, @suaveplan/api-plugin-database.

2.8 KiB Raw Permalink Blame History