# `CmsEngine`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

`CmsEngine` is the headless content-management core for
`@suaveplan/api-plugin-cms`. It manages flexible content models,
content entries with a `draft → review → published → archived` status
lifecycle, slug uniqueness within a model, and a per-entry version
trail. The engine is in-memory by design — three `Map`s back its
state — so it is suitable for development, testing, and small-scale
single-process deployments. Production-scale persistence is a downstream
concern; the engine ships a stable surface that a future Surreal-backed
storage port can wrap without modifying any caller code.

State changes flow through a typed `EventBus<CmsEventMap>` and an
OpenTelemetry counter bundle so observability is free at the call site.
Two abstractions are injectable for determinism: `Clock` drives every
timestamp and `IdGenerator` drives every persisted identifier. Both
default to the upstream Suaveplan main behaviour, so test fixtures
captured against main remain byte-reproducible against this port.

## Features

- Content-model CRUD (`createModel`, `getModel`, `listModels`,
  `deleteModel`) with referential-integrity guard against orphaning
  entries.
- Content-entry CRUD (`createContent`, `getContent`, `queryContent`,
  `updateContent`, `deleteContent`) with `(modelId, slug)` uniqueness
  and `validateContentData` enforcement on create and update.
- `queryContent` supports filter by `modelId`, `status`, `locale`,
  case-insensitive `search` over `title`/`slug`, sort by an arbitrary
  field with `asc`/`desc`, and `offset`/`limit` paging.
- Status transitions consult `VALID_STATUS_TRANSITIONS` and emit one
  of `content.published` / `content.drafted` / `content.archived` /
  fallback `content.updated`.
- Version history retained per entry; `getVersions` returns the full
  trail, deletion drops it.
- OTel counters fire from every mutating method.

## Usage: Basic

```ts
import { CmsEngine } from "@suaveplan/api-plugin-cms";

const engine = new CmsEngine();
const model = engine.createModel({
    name: "Blog post",
    slug: "post",
    contentType: "post",
    fields: [
        { name: "title", type: "text", label: "Title", required: true },
        { name: "body", type: "richtext", label: "Body" },
    ],
});
const entry = engine.createContent({
    modelId: model.id,
    title: "Hello world",
    data: { title: "Hello world", body: "Welcome." },
});
engine.transitionStatus(entry.id, "published");
console.log(engine.queryContent({ status: "published" }));
```

## Usage: Advanced

Inject a `Clock` and `IdGenerator` for deterministic test fixtures, and
subscribe to the typed event bus to fan-out into downstream systems
(audit log, search indexer, webhook dispatcher):

```ts
import { CmsEngine } from "@suaveplan/api-plugin-cms";
import { EventBus } from "@suaveplan/events";

let n = 0;
const engine = new CmsEngine({
    clock: () => 1_700_000_000_000,
    idGenerator: () => `ulid_${++n}`,
    events: new EventBus(),
});
engine.events.on("content.published", (entry) => {
    queueWebhook("content.published", entry);
});
```

## API Reference

| Member | Description |
|---|---|
| `new CmsEngine(options?)` | Construct the engine. Optional `clock`, `idGenerator`, `events`. |
| `engine.events` | The underlying `EventBus<CmsEventMap>` — subscribe with `.on(...)`. |
| `createModel(input)` | Register a new model. Emits `model.created`. |
| `getModel(id)` | Look up by id. Throws `CMS.MODEL_NOT_FOUND` on miss. |
| `listModels()` | Snapshot of every registered model. |
| `deleteModel(id)` | Remove a model. Throws `CMS.MODEL_IN_USE` if entries exist. |
| `createContent(input)` | Validate + persist + version + emit `content.created`. |
| `getContent(id)` | Look up entry. Throws `CMS.CONTENT_NOT_FOUND` on miss. |
| `queryContent(query?)` | Filter / sort / page entries. |
| `updateContent(id, input)` | Merge data; re-validate; version; emit `content.updated`. |
| `transitionStatus(id, target)` | Status FSM step. Throws `CMS.INVALID_TRANSITION` on illegal edge. |
| `deleteContent(id)` | Drop entry + versions; emit `content.deleted`. |
| `getVersions(entryId)` | Full version trail. |

## Implementation Notes

The engine uses three `Map`s (`models`, `entries`, `versions`). The
default `IdGenerator` produces `cms_<n>_<clock()>` strings — verbatim
from upstream so byte-level test fixtures survive. The default `Clock`
is `() => Date.now()`. `EventBus<CmsEventMap>` adapts to the
single-payload suaveplan convention (`Record<string, unknown>`); upstream
used tuple events, but the listener-side argument shape is identical.
OTel counters are resolved lazily inside `getCmsInstruments()` so test
harnesses installing a custom `MeterProvider` first capture every
observation.