@brew-cms/api 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './errors.js';
+export * from './idempotency.js';
+export * from './validators.js';
+export * from './router.js';
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@brew-cms/api",
+  "version": "0.1.0",
+  "description": "REST API router, OpenAPI spec, idempotency, and request validation for BrewCMS",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@brew-cms/content": "0.1.0",
+    "@brew-cms/core": "0.1.0",
+    "@brew-cms/intelligence": "0.1.0",
+    "@brew-cms/policy": "0.1.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@brew-cms/db": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "rimraf dist"
+  }
+}

package/src/__tests__/api.test.ts

@@ -0,0 +1,416 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { handleApiRequest, type ApiContext } from '../router.js';
+import { InMemoryIdempotencyStore } from '../idempotency.js';
+import {
+  DocumentService,
+  WorkflowService,
+  AgentService,
+  AuditService,
+  TaxonomyService,
+  type Actor,
+  type Clock,
+  type IdGenerator,
+} from '@brew-cms/core';
+import { PolicyEngine } from '@brew-cms/policy';
+import {
+  createDatabaseConnection,
+  seedInitialData,
+  SQLiteDocumentRepository,
+  SQLiteRevisionRepository,
+  SQLiteTaxonomyRepository,
+  SQLiteAuditEventRepository,
+  SQLiteAgentRepository,
+  SQLiteMediaAssetRepository,
+} from '@brew-cms/db';
+import {
+  DefaultSourceRegistry,
+  DeterministicMockEmbeddingProvider,
+  MemorySemanticIndexAdapter,
+  MockContentSourceAdapter,
+  IndexingService,
+  HybridRetrievalService,
+  CanonicalSourceResolver,
+} from '@brew-cms/intelligence';
+
+describe('REST API /api/v1 and Router', () => {
+  let ctx: ApiContext;
+  const adminActor: Actor = {
+    id: 'usr_admin_default',
+    type: 'human',
+    role: 'Admin',
+  };
+
+  beforeEach(() => {
+    const db = createDatabaseConnection({ filePath: ':memory:' });
+    seedInitialData(db);
+
+    const docRepo = new SQLiteDocumentRepository(db);
+    const revRepo = new SQLiteRevisionRepository(db);
+    const taxRepo = new SQLiteTaxonomyRepository(db);
+    const auditRepo = new SQLiteAuditEventRepository(db);
+    const agentRepo = new SQLiteAgentRepository(db);
+
+    const policy = new PolicyEngine();
+    const clock: Clock = { now: () => new Date('2026-09-12T12:00:00Z') };
+    let idCounter = 1;
+    const idGen: IdGenerator = { generate: (p = 'id') => `${p}_${idCounter++}` };
+
+    const documentService = new DocumentService(docRepo, revRepo, auditRepo, policy, clock, idGen);
+    const workflowService = new WorkflowService(docRepo, revRepo, auditRepo, policy, clock, idGen);
+    const agentService = new AgentService(agentRepo, auditRepo, policy, clock, idGen);
+    const auditService = new AuditService(auditRepo);
+    const taxonomyService = new TaxonomyService(taxRepo);
+
+    const mediaRepo = new SQLiteMediaAssetRepository(db);
+
+    ctx = {
+      documentService,
+      workflowService,
+      agentService,
+      auditService,
+      taxonomyService,
+      revisionRepo: revRepo,
+      mediaRepo,
+      agentRepo,
+      idempotencyStore: new InMemoryIdempotencyStore(),
+    };
+  });
+
+  it('serves health endpoints', async () => {
+    const live = await handleApiRequest(
+      { method: 'GET', path: '/api/health/live', actor: adminActor },
+      ctx
+    );
+    expect(live.status).toBe(200);
+    expect((live.body as any).status).toBe('live');
+
+    const ready = await handleApiRequest(
+      { method: 'GET', path: '/api/health/ready', actor: adminActor },
+      ctx
+    );
+    expect(ready.status).toBe(200);
+    expect((ready.body as any).status).toBe('ready');
+  });
+
+  it('creates and publishes a document via REST endpoints', async () => {
+    // 1. Create document
+    const createRes = await handleApiRequest(
+      {
+        method: 'POST',
+        path: '/api/v1/documents',
+        actor: adminActor,
+        body: {
+          type: 'post',
+          slug: 'rest-intro',
+          title: 'REST Architecture in BrewCMS',
+          sourceMarkdown: '# REST Architecture\n\nContent operating system REST APIs.',
+        },
+      },
+      ctx
+    );
+
+    expect(createRes.status).toBe(201);
+    const doc = (createRes.body as any).document;
+    expect(doc.id).toBeDefined();
+    expect(doc.status).toBe('DRAFT');
+
+    // 2. Publish document
+    const publishRes = await handleApiRequest(
+      {
+        method: 'POST',
+        path: `/api/v1/documents/${doc.id}/publish`,
+        actor: adminActor,
+        body: {},
+      },
+      ctx
+    );
+
+    expect(publishRes.status).toBe(200);
+    expect((publishRes.body as any).document.status).toBe('PUBLISHED');
+  });
+
+  it('enforces idempotency using Idempotency-Key header', async () => {
+    const key = 'idem_unique_key_123';
+
+    // First mutation
+    const req1 = await handleApiRequest(
+      {
+        method: 'POST',
+        path: '/api/v1/documents',
+        headers: { 'idempotency-key': key },
+        actor: adminActor,
+        body: {
+          type: 'post',
+          slug: 'idempotent-doc',
+          title: 'Idempotency Post',
+          sourceMarkdown: '# Test',
+        },
+      },
+      ctx
+    );
+
+    expect(req1.status).toBe(201);
+    const initialId = (req1.body as any).document.id;
+
+    // Second identical request with same key
+    const req2 = await handleApiRequest(
+      {
+        method: 'POST',
+        path: '/api/v1/documents',
+        headers: { 'idempotency-key': key },
+        actor: adminActor,
+        body: {
+          type: 'post',
+          slug: 'idempotent-doc',
+          title: 'Idempotency Post',
+          sourceMarkdown: '# Test',
+        },
+      },
+      ctx
+    );
+
+    expect(req2.status).toBe(201);
+    expect(req2.headers?.['X-Cache-Lookup']).toBe('HIT');
+    expect((req2.body as any).document.id).toBe(initialId);
+  });
+
+  it('returns standard machine-readable error envelope on validation failure', async () => {
+    const res = await handleApiRequest(
+      {
+        method: 'POST',
+        path: '/api/v1/documents',
+        actor: adminActor,
+        headers: { 'x-request-id': 'req_xyz' },
+        body: {
+          type: 'invalid_type',
+        },
+      },
+      ctx
+    );
+
+    expect(res.status).toBeGreaterThanOrEqual(400);
+    const body = res.body as any;
+    expect(body.error).toBeDefined();
+    expect(body.error.code).toBeDefined();
+    expect(body.error.requestId).toBe('req_xyz');
+  });
+
+  it('handles full editorial lifecycle: submit -> approve -> publish -> unpublish -> restore', async () => {
+    // 1. Create draft
+    const createRes = await handleApiRequest(
+      {
+        method: 'POST',
+        path: '/api/v1/documents',
+        actor: adminActor,
+        body: {
+          type: 'post',
+          slug: 'lifecycle-test',
+          title: 'Lifecycle Post',
+          sourceMarkdown: '# Lifecycle Test\n\nInitial version.',
+        },
+      },
+      ctx
+    );
+    expect(createRes.status).toBe(201);
+    const docId = (createRes.body as any).document.id;
+    const initialRevId = (createRes.body as any).revision.id;
+
+    // 2. Submit for review
+    const submitRes = await handleApiRequest(
+      {
+        method: 'POST',
+        path: `/api/v1/documents/${docId}/submit`,
+        actor: adminActor,
+        body: {},
+      },
+      ctx
+    );
+    expect(submitRes.status).toBe(200);
+    expect((submitRes.body as any).status).toBe('IN_REVIEW');
+
+    // 3. Approve
+    const approveRes = await handleApiRequest(
+      {
+        method: 'POST',
+        path: `/api/v1/documents/${docId}/approve`,
+        actor: adminActor,
+        body: {},
+      },
+      ctx
+    );
+    expect(approveRes.status).toBe(200);
+    expect((approveRes.body as any).status).toBe('APPROVED');
+
+    // 4. Publish
+    const publishRes = await handleApiRequest(
+      {
+        method: 'POST',
+        path: `/api/v1/documents/${docId}/publish`,
+        actor: adminActor,
+        body: {},
+      },
+      ctx
+    );
+    expect(publishRes.status).toBe(200);
+    expect((publishRes.body as any).document.status).toBe('PUBLISHED');
+
+    // 5. Unpublish
+    const unpublishRes = await handleApiRequest(
+      {
+        method: 'POST',
+        path: `/api/v1/documents/${docId}/unpublish`,
+        actor: adminActor,
+        body: {},
+      },
+      ctx
+    );
+    expect(unpublishRes.status).toBe(200);
+    expect((unpublishRes.body as any).status).toBe('DRAFT');
+
+    // 6. Restore initial revision
+    const restoreRes = await handleApiRequest(
+      {
+        method: 'POST',
+        path: `/api/v1/documents/${docId}/restore`,
+        actor: adminActor,
+        body: { revisionId: initialRevId },
+      },
+      ctx
+    );
+    expect(restoreRes.status).toBe(200);
+    expect((restoreRes.body as any).restoredRevision).toBeDefined();
+    expect((restoreRes.body as any).restoredRevision.sourceMarkdown).toBe('# Lifecycle Test\n\nInitial version.');
+  });
+
+  it('manages media and agent endpoints', async () => {
+    // Media list and create
+    const mediaCreate = await handleApiRequest(
+      {
+        method: 'POST',
+        path: '/api/v1/media',
+        actor: adminActor,
+        body: {
+          filename: 'banner.png',
+          mimeType: 'image/png',
+          sizeBytes: 1024,
+          altText: 'Banner Image',
+        },
+      },
+      ctx
+    );
+    expect(mediaCreate.status).toBe(201);
+    expect((mediaCreate.body as any).id).toBeDefined();
+
+    const mediaList = await handleApiRequest(
+      {
+        method: 'GET',
+        path: '/api/v1/media',
+        actor: adminActor,
+      },
+      ctx
+    );
+    expect(mediaList.status).toBe(200);
+    expect((mediaList.body as any).items.length).toBeGreaterThan(0);
+
+    // Agent list
+    const agentList = await handleApiRequest(
+      {
+        method: 'GET',
+        path: '/api/v1/agents',
+        actor: adminActor,
+      },
+      ctx
+    );
+    expect(agentList.status).toBe(200);
+    expect(Array.isArray((agentList.body as any).items)).toBe(true);
+  });
+
+  it('exposes intelligence status, indexing, and hybrid retrieval endpoints', async () => {
+    // Set up intelligence services
+    const registry = new DefaultSourceRegistry();
+    const mockSource = new MockContentSourceAdapter('brew-sqlite', [
+      {
+        sourceId: 'brew-sqlite',
+        contentId: 'doc-ai-1',
+        revisionId: 'rev-1',
+        title: 'Distributed Enterprise Intelligence',
+        canonicalUrl: '/posts/distributed-enterprise-intelligence',
+        summary: 'How AI agents work with governed content workflows.',
+        body: '# Distributed Enterprise Intelligence\n\nHow AI agents work with governed content workflows and retrieval.',
+        publishedAt: '2026-09-12T00:00:00Z',
+      },
+    ]);
+    registry.register(mockSource);
+
+    const embeddingProvider = new DeterministicMockEmbeddingProvider();
+    const semanticIndex = new MemorySemanticIndexAdapter();
+    const indexingService = new IndexingService(registry, embeddingProvider, semanticIndex);
+    const retrievalService = new HybridRetrievalService(embeddingProvider, semanticIndex);
+    const canonicalResolver = new CanonicalSourceResolver(registry);
+
+    const intelligenceCtx: ApiContext = {
+      ...ctx,
+      sourceRegistry: registry,
+      indexingService,
+      retrievalService,
+      canonicalResolver,
+    };
+
+    // 1. Status endpoint
+    const statusRes = await handleApiRequest(
+      { method: 'GET', path: '/api/v1/intelligence/status', actor: adminActor },
+      intelligenceCtx
+    );
+    expect(statusRes.status).toBe(200);
+    expect((statusRes.body as any).status).toBe('operational');
+    expect((statusRes.body as any).sources.length).toBe(1);
+    expect((statusRes.body as any).sources[0].id).toBe('brew-sqlite');
+
+    // 2. Trigger Indexing
+    const indexRes = await handleApiRequest(
+      {
+        method: 'POST',
+        path: '/api/v1/intelligence/index',
+        actor: adminActor,
+        body: { sourceId: 'brew-sqlite' },
+      },
+      intelligenceCtx
+    );
+    expect(indexRes.status).toBe(200);
+    expect((indexRes.body as any).summary.indexed).toBe(1);
+
+    // 3. Search endpoint (references only)
+    const searchRes = await handleApiRequest(
+      {
+        method: 'GET',
+        path: '/api/v1/intelligence/search',
+        actor: adminActor,
+        query: { q: 'enterprise intelligence' },
+      },
+      intelligenceCtx
+    );
+    expect(searchRes.status).toBe(200);
+    expect((searchRes.body as any).total).toBeGreaterThan(0);
+    const item = (searchRes.body as any).items[0];
+    expect(item.contentId).toBe('doc-ai-1');
+    expect(item.sourceId).toBe('brew-sqlite');
+    // Content body must NOT be in search reference result
+    expect(item.markdown).toBeUndefined();
+
+    // 4. Search with resolve=true (canonical resolution)
+    const resolvedSearchRes = await handleApiRequest(
+      {
+        method: 'GET',
+        path: '/api/v1/intelligence/search',
+        actor: adminActor,
+        query: { q: 'enterprise intelligence', resolve: 'true' },
+      },
+      intelligenceCtx
+    );
+    expect(resolvedSearchRes.status).toBe(200);
+    const resolvedItem = (resolvedSearchRes.body as any).items[0];
+    expect(resolvedItem.reference.contentId).toBe('doc-ai-1');
+    expect(resolvedItem.canonical.title).toBe('Distributed Enterprise Intelligence');
+    expect(resolvedItem.canonical.body).toContain('governed content workflows');
+  });
+});

package/src/errors.ts

@@ -0,0 +1,42 @@
+import { DomainError } from '@brew-cms/core';
+
+export interface ApiErrorEnvelope {
+  error: {
+    code: string;
+    message: string;
+    requestId?: string;
+    details?: unknown;
+  };
+}
+
+export function formatErrorResponse(
+  err: unknown,
+  requestId?: string
+): { status: number; body: ApiErrorEnvelope } {
+  if (err instanceof DomainError) {
+    return {
+      status: err.statusCode,
+      body: {
+        error: {
+          code: err.code,
+          message: err.message,
+          requestId,
+          details: err.details,
+        },
+      },
+    };
+  }
+
+  // Fallback for unexpected internal errors: NEVER expose raw stack traces or internal SQL details
+  const fallbackMessage = err instanceof Error ? err.message : 'An unexpected internal error occurred.';
+  return {
+    status: 500,
+    body: {
+      error: {
+        code: 'INTERNAL_ERROR',
+        message: fallbackMessage,
+        requestId,
+      },
+    },
+  };
+}

package/src/idempotency.ts

@@ -0,0 +1,41 @@
+export interface IdempotencyRecord {
+  key: string;
+  actorId: string;
+  responseStatus: number;
+  responseBody: unknown;
+  expiresAt: Date;
+}
+
+export class InMemoryIdempotencyStore {
+  private cache = new Map<string, IdempotencyRecord>();
+
+  get(key: string, actorId: string): IdempotencyRecord | null {
+    const compositeKey = `${actorId}:${key}`;
+    const record = this.cache.get(compositeKey);
+    if (!record) return null;
+
+    if (record.expiresAt < new Date()) {
+      this.cache.delete(compositeKey);
+      return null;
+    }
+    return record;
+  }
+
+  set(
+    key: string,
+    actorId: string,
+    responseStatus: number,
+    responseBody: unknown,
+    ttlSeconds: number = 3600
+  ): void {
+    const compositeKey = `${actorId}:${key}`;
+    const expiresAt = new Date(Date.now() + ttlSeconds * 1000);
+    this.cache.set(compositeKey, {
+      key,
+      actorId,
+      responseStatus,
+      responseBody,
+      expiresAt,
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './errors.js';
+export * from './idempotency.js';
+export * from './validators.js';
+export * from './router.js';

package/src/router.ts

@@ -0,0 +1,538 @@
+import type {
+  Actor,
+  DocumentService,
+  WorkflowService,
+  AgentService,
+  AuditService,
+  TaxonomyService,
+  RevisionRepository,
+  MediaProvider,
+  MediaAssetRepository,
+  AgentRepository,
+} from '@brew-cms/core';
+import type {
+  SourceRegistry,
+  IndexingService,
+  HybridRetrievalService,
+  CanonicalSourceResolver,
+} from '@brew-cms/intelligence';
+import { compileContent } from '@brew-cms/content';
+import { formatErrorResponse } from './errors.js';
+import { InMemoryIdempotencyStore } from './idempotency.js';
+import {
+  CreateDocumentRequestSchema,
+  UpdateDocumentRequestSchema,
+  PublishDocumentRequestSchema,
+  ScheduleDocumentRequestSchema,
+  CreateTopicRequestSchema,
+  CreateTagRequestSchema,
+  CreateSeriesRequestSchema,
+} from './validators.js';
+
+export interface ApiRequest {
+  method: string;
+  path: string;
+  query?: Record<string, string | undefined>;
+  headers?: Record<string, string | undefined>;
+  body?: unknown;
+  actor: Actor;
+}
+
+export interface ApiResponse {
+  status: number;
+  headers?: Record<string, string>;
+  body: unknown;
+}
+
+export interface ApiContext {
+  documentService: DocumentService;
+  workflowService: WorkflowService;
+  agentService: AgentService;
+  auditService: AuditService;
+  taxonomyService: TaxonomyService;
+  revisionRepo: RevisionRepository;
+  mediaProvider?: MediaProvider;
+  mediaRepo?: MediaAssetRepository;
+  agentRepo?: AgentRepository;
+  idempotencyStore?: InMemoryIdempotencyStore;
+  sourceRegistry?: SourceRegistry;
+  indexingService?: IndexingService;
+  retrievalService?: HybridRetrievalService;
+  canonicalResolver?: CanonicalSourceResolver;
+}
+
+export async function handleApiRequest(
+  req: ApiRequest,
+  ctx: ApiContext
+): Promise<ApiResponse> {
+  const idempotencyKey = req.headers?.['idempotency-key'];
+  const idempotencyStore = ctx.idempotencyStore;
+
+  // 1. Idempotency Check for mutations
+  if (idempotencyKey && req.method !== 'GET' && idempotencyStore) {
+    const cached = idempotencyStore.get(idempotencyKey, req.actor.id);
+    if (cached) {
+      return {
+        status: cached.responseStatus,
+        headers: { 'X-Cache-Lookup': 'HIT', 'Idempotency-Key': idempotencyKey },
+        body: cached.responseBody,
+      };
+    }
+  }
+
+  try {
+    const response = await dispatchRoute(req, ctx);
+
+    // Save in idempotency store if mutation
+    if (idempotencyKey && req.method !== 'GET' && idempotencyStore && response.status < 400) {
+      idempotencyStore.set(idempotencyKey, req.actor.id, response.status, response.body);
+    }
+
+    return response;
+  } catch (err: any) {
+    const errorFormatted = formatErrorResponse(err, req.headers?.['x-request-id']);
+    return {
+      status: errorFormatted.status,
+      headers: { 'Content-Type': 'application/json' },
+      body: errorFormatted.body,
+    };
+  }
+}
+
+async function dispatchRoute(req: ApiRequest, ctx: ApiContext): Promise<ApiResponse> {
+  const { path: rawPath, method, actor } = req;
+  const urlPath = rawPath.replace(/\/$/, '');
+
+  // 1. Health Endpoints
+  if (urlPath === '/api/health/live' && method === 'GET') {
+    return { status: 200, body: { status: 'live', timestamp: new Date().toISOString() } };
+  }
+  if (urlPath === '/api/health/ready' && method === 'GET') {
+    return { status: 200, body: { status: 'ready', database: 'connected', timestamp: new Date().toISOString() } };
+  }
+
+  // 2. Documents
+  if (urlPath === '/api/v1/documents') {
+    if (method === 'GET') {
+      const result = await ctx.documentService.listDocuments({
+        type: req.query?.type as any,
+        status: req.query?.status as any,
+        query: req.query?.q,
+        limit: req.query?.limit ? Number(req.query.limit) : undefined,
+      });
+      return { status: 200, body: result };
+    }
+
+    if (method === 'POST') {
+      const validated = CreateDocumentRequestSchema.parse(req.body);
+      const compiled = compileContent(validated.sourceMarkdown, {
+        frontmatterDefaults: validated.frontmatter,
+      });
+
+      const res = await ctx.documentService.createDraft(actor, {
+        type: validated.type,
+        slug: validated.slug,
+        title: validated.title,
+        excerpt: validated.excerpt,
+        sourceMarkdown: compiled.sourceMarkdown,
+        frontmatter: compiled.frontmatter,
+        contentIr: compiled.contentIr,
+        contentHash: compiled.contentHash,
+        compilerVersion: compiled.compilerVersion,
+        wordCount: compiled.wordCount,
+        readingTimeSeconds: compiled.readingTimeSeconds,
+        seo: validated.seo,
+      });
+
+      return { status: 201, body: res };
+    }
+  }
+
+  // Document by ID: /api/v1/documents/:id
+  const docIdMatch = urlPath.match(/^\/api\/v1\/documents\/([^/]+)$/);
+  if (docIdMatch) {
+    const id = docIdMatch[1];
+    if (method === 'GET') {
+      const doc = await ctx.documentService.getDocument(id);
+      return { status: 200, body: doc };
+    }
+    if (method === 'PUT') {
+      const validated = UpdateDocumentRequestSchema.parse(req.body);
+      let compiled: ReturnType<typeof compileContent> | undefined;
+      if (validated.sourceMarkdown !== undefined) {
+        compiled = compileContent(validated.sourceMarkdown, {
+          frontmatterDefaults: validated.frontmatter,
+        });
+      }
+
+      const res = await ctx.documentService.updateDraft(actor, id, {
+        title: validated.title,
+        slug: validated.slug,
+        excerpt: validated.excerpt,
+        sourceMarkdown: compiled?.sourceMarkdown,
+        frontmatter: compiled?.frontmatter,
+        contentIr: compiled?.contentIr,
+        contentHash: compiled?.contentHash,
+        compilerVersion: compiled?.compilerVersion,
+        wordCount: compiled?.wordCount,
+        readingTimeSeconds: compiled?.readingTimeSeconds,
+        seo: validated.seo,
+        changeSummary: validated.changeSummary,
+      });
+
+      return { status: 200, body: res };
+    }
+    if (method === 'DELETE') {
+      await ctx.documentService.deleteDocument(actor, id);
+      return { status: 200, body: { success: true, id } };
+    }
+  }
+
+  // Revisions for document: /api/v1/documents/:id/revisions
+  const revMatch = urlPath.match(/^\/api\/v1\/documents\/([^/]+)\/revisions$/);
+  if (revMatch && method === 'GET') {
+    const id = revMatch[1];
+    const revisions = await ctx.revisionRepo.listByDocumentId(id);
+    return { status: 200, body: { revisions } };
+  }
+
+  // Publish: /api/v1/documents/:id/publish
+  const publishMatch = urlPath.match(/^\/api\/v1\/documents\/([^/]+)\/publish$/);
+  if (publishMatch && method === 'POST') {
+    const id = publishMatch[1];
+    const validated = PublishDocumentRequestSchema.parse(req.body || {});
+    const res = await ctx.workflowService.publish(actor, id, validated.revisionId);
+    return { status: 200, body: res };
+  }
+
+  // Submit for review: /api/v1/documents/:id/submit
+  const submitMatch = urlPath.match(/^\/api\/v1\/documents\/([^/]+)\/submit$/);
+  if (submitMatch && method === 'POST') {
+    const id = submitMatch[1];
+    const revisionId = (req.body as any)?.revisionId;
+    const res = await ctx.workflowService.submitForReview(actor, id, revisionId);
+    return { status: 200, body: res };
+  }
+
+  // Approve: /api/v1/documents/:id/approve
+  const approveMatch = urlPath.match(/^\/api\/v1\/documents\/([^/]+)\/approve$/);
+  if (approveMatch && method === 'POST') {
+    const id = approveMatch[1];
+    const revisionId = (req.body as any)?.revisionId;
+    const res = await ctx.workflowService.approve(actor, id, revisionId);
+    return { status: 200, body: res };
+  }
+
+  // Request Changes: /api/v1/documents/:id/request-changes
+  const reqChangesMatch = urlPath.match(/^\/api\/v1\/documents\/([^/]+)\/request-changes$/);
+  if (reqChangesMatch && method === 'POST') {
+    const id = reqChangesMatch[1];
+    const reason = (req.body as any)?.reason;
+    const res = await ctx.workflowService.requestChanges(actor, id, reason);
+    return { status: 200, body: res };
+  }
+
+  // Unpublish: /api/v1/documents/:id/unpublish
+  const unpublishMatch = urlPath.match(/^\/api\/v1\/documents\/([^/]+)\/unpublish$/);
+  if (unpublishMatch && method === 'POST') {
+    const id = unpublishMatch[1];
+    const res = await ctx.workflowService.unpublish(actor, id);
+    return { status: 200, body: res };
+  }
+
+  // Archive: /api/v1/documents/:id/archive
+  const archiveMatch = urlPath.match(/^\/api\/v1\/documents\/([^/]+)\/archive$/);
+  if (archiveMatch && method === 'POST') {
+    const id = archiveMatch[1];
+    const res = await ctx.workflowService.archive(actor, id);
+    return { status: 200, body: res };
+  }
+
+  // Restore Revision: /api/v1/documents/:id/restore
+  const restoreMatch = urlPath.match(/^\/api\/v1\/documents\/([^/]+)\/restore$/);
+  if (restoreMatch && method === 'POST') {
+    const id = restoreMatch[1];
+    const targetRevId = (req.body as any)?.revisionId;
+    const changeSummary = (req.body as any)?.changeSummary;
+    const res = await ctx.workflowService.restoreRevision(actor, id, targetRevId, changeSummary);
+    return { status: 200, body: res };
+  }
+
+  // Schedule: /api/v1/documents/:id/schedule
+  const scheduleMatch = urlPath.match(/^\/api\/v1\/documents\/([^/]+)\/schedule$/);
+  if (scheduleMatch && method === 'POST') {
+    const id = scheduleMatch[1];
+    const validated = ScheduleDocumentRequestSchema.parse(req.body);
+    const res = await ctx.workflowService.schedule(
+      actor,
+      id,
+      new Date(validated.scheduledAt),
+      validated.revisionId
+    );
+    return { status: 200, body: res };
+  }
+
+  // Taxonomies: Topics
+  if (urlPath === '/api/v1/topics') {
+    if (method === 'GET') {
+      const items = await ctx.taxonomyService.listTopics();
+      return { status: 200, body: { items } };
+    }
+    if (method === 'POST') {
+      const validated = CreateTopicRequestSchema.parse(req.body);
+      const res = await ctx.taxonomyService.createTopic({
+        id: `top_${validated.slug}`,
+        ...validated,
+      });
+      return { status: 201, body: res };
+    }
+  }
+
+  // Taxonomies: Tags
+  if (urlPath === '/api/v1/tags') {
+    if (method === 'GET') {
+      const items = await ctx.taxonomyService.listTags();
+      return { status: 200, body: { items } };
+    }
+    if (method === 'POST') {
+      const validated = CreateTagRequestSchema.parse(req.body);
+      const res = await ctx.taxonomyService.createTag({
+        id: `tag_${validated.slug}`,
+        ...validated,
+      });
+      return { status: 201, body: res };
+    }
+  }
+
+  // Taxonomies: Series
+  if (urlPath === '/api/v1/series') {
+    if (method === 'GET') {
+      const items = await ctx.taxonomyService.listSeries();
+      return { status: 200, body: { items } };
+    }
+    if (method === 'POST') {
+      const validated = CreateSeriesRequestSchema.parse(req.body);
+      const res = await ctx.taxonomyService.createSeries({
+        id: `ser_${validated.slug}`,
+        ...validated,
+      });
+      return { status: 201, body: res };
+    }
+  }
+
+  // Media: /api/v1/media
+  if (urlPath === '/api/v1/media') {
+    if (method === 'GET') {
+      const items = ctx.mediaRepo
+        ? await ctx.mediaRepo.list({
+            mimeType: req.query?.mimeType,
+            limit: req.query?.limit ? Number(req.query.limit) : 50,
+          })
+        : [];
+      return { status: 200, body: { items } };
+    }
+    if (method === 'POST') {
+      const body = req.body as any;
+      if (!ctx.mediaRepo) {
+        return { status: 500, body: { error: { code: 'NO_MEDIA_REPO', message: 'Media repository not configured.' } } };
+      }
+      let stored: any = null;
+      if (ctx.mediaProvider && body.contentBase64) {
+        stored = await ctx.mediaProvider.put({
+          filename: body.filename,
+          mimeType: body.mimeType,
+          content: Buffer.from(body.contentBase64, 'base64'),
+          prefix: body.prefix,
+        });
+      }
+      const asset = await ctx.mediaRepo.create({
+        id: body.id || `med_${Date.now()}`,
+        provider: stored?.provider || 'local',
+        providerKey: stored?.providerKey || body.providerKey || body.filename,
+        mimeType: body.mimeType || 'application/octet-stream',
+        sizeBytes: stored?.sizeBytes || body.sizeBytes || 0,
+        width: body.width ?? null,
+        height: body.height ?? null,
+        altText: body.altText ?? null,
+        caption: body.caption ?? null,
+        metadata: body.metadata ?? null,
+        createdBy: actor.id,
+      });
+      return { status: 201, body: asset };
+    }
+  }
+
+  // Audit Events
+  if (urlPath === '/api/v1/audit' && method === 'GET') {
+    const events = await ctx.auditService.listEvents({
+      resourceType: req.query?.resourceType,
+      resourceId: req.query?.resourceId,
+      actorId: req.query?.actorId,
+      limit: req.query?.limit ? Number(req.query.limit) : 50,
+    });
+    return { status: 200, body: { items: events } };
+  }
+
+  // Agents: /api/v1/agents
+  if (urlPath === '/api/v1/agents') {
+    if (method === 'GET') {
+      const agents = await ctx.agentService.listAgents();
+      return { status: 200, body: { items: agents } };
+    }
+    if (method === 'POST') {
+      const body = req.body as any;
+      const agent = await ctx.agentService.registerAgent(actor, {
+        id: body.id,
+        name: body.name,
+        description: body.description,
+        scopes: body.scopes || [],
+      });
+      return { status: 201, body: agent };
+    }
+  }
+
+  // Agent Action Runs: /api/v1/agent/runs
+  if (urlPath === '/api/v1/agent/runs') {
+    if (method === 'GET') {
+      const runs = ctx.agentRepo
+        ? await ctx.agentRepo.listActionRuns({ limit: req.query?.limit ? Number(req.query.limit) : 50 })
+        : [];
+      return { status: 200, body: { items: runs } };
+    }
+  }
+
+  // Agent Action Run Approval: /api/v1/agent/runs/:id/approve
+  const approveRunMatch = urlPath.match(/^\/api\/v1\/agent\/runs\/([^/]+)\/approve$/);
+  if (approveRunMatch && method === 'POST') {
+    const runId = approveRunMatch[1];
+    const res = await ctx.agentService.approveActionRun(actor, runId, (req.body as any)?.reason);
+    return { status: 200, body: res };
+  }
+
+  // Agent Action Run Rejection: /api/v1/agent/runs/:id/reject
+  const rejectRunMatch = urlPath.match(/^\/api\/v1\/agent\/runs\/([^/]+)\/reject$/);
+  if (rejectRunMatch && method === 'POST') {
+    const runId = rejectRunMatch[1];
+    const res = await ctx.agentService.rejectActionRun(actor, runId, (req.body as any)?.reason);
+    return { status: 200, body: res };
+  }
+
+  // Intelligence: Status / Sources
+  if (urlPath === '/api/v1/intelligence/status' && method === 'GET') {
+    const registry = ctx.sourceRegistry ?? ctx.indexingService?.registry;
+    return {
+      status: 200,
+      body: {
+        status: 'operational',
+        hasIndexingService: Boolean(ctx.indexingService),
+        hasRetrievalService: Boolean(ctx.retrievalService),
+        hasCanonicalResolver: Boolean(ctx.canonicalResolver),
+        sources: registry
+          ? registry.list().map((s) => ({
+              id: s.sourceId,
+              capabilities: s.capabilities,
+            }))
+          : [],
+      },
+    };
+  }
+
+  // Intelligence: Hybrid Retrieval
+  if (urlPath === '/api/v1/intelligence/search' && method === 'GET') {
+    if (!ctx.retrievalService) {
+      return {
+        status: 503,
+        body: {
+          error: {
+            code: 'INTELLIGENCE_UNAVAILABLE',
+            message: 'Retrieval service is not configured.',
+          },
+        },
+      };
+    }
+    const q = req.query?.q;
+    if (!q || typeof q !== 'string') {
+      return {
+        status: 400,
+        body: {
+          error: {
+            code: 'INVALID_QUERY',
+            message: "Query parameter 'q' is required.",
+          },
+        },
+      };
+    }
+    const limit = req.query?.limit ? Number(req.query.limit) : 10;
+    const minScore = req.query?.minScore ? Number(req.query.minScore) : undefined;
+    const sourceId = req.query?.sourceId;
+
+    const results = await ctx.retrievalService.search({
+      query: q,
+      limit,
+      minScore,
+      sourceId,
+    });
+
+    const shouldResolve = req.query?.resolve === 'true' && ctx.canonicalResolver;
+    if (shouldResolve && ctx.canonicalResolver) {
+      const resolved = await ctx.canonicalResolver.resolveMany(results);
+      return {
+        status: 200,
+        body: {
+          query: q,
+          total: results.length,
+          items: resolved.map((r) => ({
+            reference: r.reference,
+            canonical: r.content,
+            error: r.error,
+          })),
+        },
+      };
+    }
+
+    return {
+      status: 200,
+      body: {
+        query: q,
+        total: results.length,
+        items: results,
+      },
+    };
+  }
+
+  // Intelligence: Indexing
+  if (urlPath === '/api/v1/intelligence/index' && method === 'POST') {
+    if (!ctx.indexingService) {
+      return {
+        status: 503,
+        body: {
+          error: {
+            code: 'INTELLIGENCE_UNAVAILABLE',
+            message: 'Indexing service is not configured.',
+          },
+        },
+      };
+    }
+    const body = (req.body || {}) as { sourceId?: string; contentId?: string; revisionId?: string };
+    if (body.sourceId && body.contentId) {
+      const result = await ctx.indexingService.indexDocument(body.sourceId, body.contentId, body.revisionId);
+      return { status: 200, body: { success: true, result } };
+    } else if (body.sourceId) {
+      const summary = await ctx.indexingService.syncSource(body.sourceId);
+      return { status: 200, body: { success: true, summary } };
+    } else {
+      const summaries = await ctx.indexingService.syncAll();
+      return { status: 200, body: { success: true, summaries } };
+    }
+  }
+
+  return {
+    status: 404,
+    body: {
+      error: {
+        code: 'ROUTE_NOT_FOUND',
+        message: `Endpoint '${method} ${urlPath}' was not found.`,
+      },
+    },
+  };
+}

package/src/validators.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+
+export const CreateDocumentRequestSchema = z.object({
+  type: z.enum(['post', 'page']),
+  slug: z.string().min(1),
+  title: z.string().min(1),
+  excerpt: z.string().optional().nullable(),
+  sourceMarkdown: z.string(),
+  frontmatter: z.record(z.unknown()).optional(),
+  seo: z
+    .object({
+      metaTitle: z.string().optional(),
+      metaDescription: z.string().optional(),
+      ogImage: z.string().optional(),
+      noIndex: z.boolean().optional(),
+    })
+    .optional()
+    .nullable(),
+});
+
+export const UpdateDocumentRequestSchema = z.object({
+  title: z.string().optional(),
+  slug: z.string().optional(),
+  excerpt: z.string().optional().nullable(),
+  sourceMarkdown: z.string().optional(),
+  frontmatter: z.record(z.unknown()).optional(),
+  seo: z
+    .object({
+      metaTitle: z.string().optional(),
+      metaDescription: z.string().optional(),
+      ogImage: z.string().optional(),
+      noIndex: z.boolean().optional(),
+    })
+    .optional()
+    .nullable(),
+  changeSummary: z.string().optional().nullable(),
+});
+
+export const PublishDocumentRequestSchema = z.object({
+  revisionId: z.string().optional(),
+});
+
+export const ScheduleDocumentRequestSchema = z.object({
+  scheduledAt: z.string().datetime(),
+  revisionId: z.string().optional(),
+});
+
+export const CreateTopicRequestSchema = z.object({
+  slug: z.string().min(1),
+  name: z.string().min(1),
+  description: z.string().optional().nullable(),
+});
+
+export const CreateTagRequestSchema = z.object({
+  slug: z.string().min(1),
+  name: z.string().min(1),
+});
+
+export const CreateSeriesRequestSchema = z.object({
+  slug: z.string().min(1),
+  name: z.string().min(1),
+  description: z.string().optional().nullable(),
+});

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "references": [
+    { "path": "../core" },
+    { "path": "../content" },
+    { "path": "../policy" },
+    { "path": "../intelligence" }
+  ],
+  "include": ["src/**/*"]
+}