# 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

```ts
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

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

---

## File layout

```text
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`.