Document legacyCompat and add integration test

Author: luandro

README.md

@@ -105,6 +105,8 @@ Example payload:
 }
 ```
 
+Set `metadata.legacyCompat: true` to add a legacy-friendly tag per category. When enabled, each category gets an extra tag keyed by its `id` with value `"yes"`, in addition to the default `{ categoryId: "<id>" }`.
+
 #### Field/type mapping (v2)
 - `select` → `selectOne`
 - `multiselect` → `selectMultiple`
@@ -119,7 +121,7 @@ Example payload:
 - Categories with `track: true` are added to the track list (must not be empty if any track is declared).
 
 #### Limits & validation (v2)
-- JSON body ≤ 1 MB (enforced while streaming parse).
+- JSON body ≤ 10 MB (streaming-validated).
 - SVG icons ≤ 2 MB each; icons can be provided via:
   - `svgData` (inline SVG string)
   - `svgUrl` (remote fetch with 5s timeout and content-type check)

context/api.md

@@ -102,6 +102,51 @@ curl -X POST \
 
 ---
 
+### 3. Build Configuration (JSON, v2)
+
+#### `POST /v2`
+
+Processes a JSON payload and returns a built `.comapeocat` file using `comapeocat@1.1.0` Writer.
+
+**Content-Type**: `application/json`
+
+**Request Body** (required):
+- `metadata`: `{ name: string; version?: string; description?: string; legacyCompat?: boolean }`
+  - `legacyCompat` (optional): when `true`, every category gets an extra tag keyed by its `id` with value `"yes"` (e.g., `{ "mahali-pa-kihistoria": "yes" }`) in addition to the default `{ categoryId: <id> }` tag to support legacy consumers.
+- `categories`: array of categories with `id`, `name`, `appliesTo` (`observation`/`track`), optional `tags`, `fields`, `iconId`, `addTags`, `removeTags`, `terms`, `color`, `track`.
+- `fields`: array of fields with `id`, `type`, optional `name/label/tagKey/options/...` (legacy types are mapped automatically).
+- `icons` (optional): array with `id` plus either `svgData` or `svgUrl` (data URIs allowed).
+- `translations` (optional): object keyed by BCP‑47 locale.
+
+**Default tags**: If a category provides no `tags`, the service sets `{ categoryId: <id> }`. With `legacyCompat: true`, it also adds `{ <id>: "yes" }`.
+
+**Response**: Binary stream of `.comapeocat` file.
+
+**Status Codes**:
+- `200 OK` - file built and validated
+- `400 Bad Request` - validation errors (e.g., size limits, bad schema, path traversal)
+- `422 Unprocessable Entity` - build produced a file but downstream validation timed out/failed
+
+**Examples**:
+```bash
+curl -X POST \
+  -H "Content-Type: application/json" \
+  -d @config.json \
+  --output output.comapeocat \
+  http://localhost:3000/v2
+```
+
+**Implementation**: `src/controllers/settingsController.ts` (dispatch) and `src/services/comapeocatBuilder.ts` (build logic)
+
+**Key validation/limits** (see `src/config/app.ts`):
+- JSON body ≤ 10 MB (streaming enforced in `app.ts` onParse hook)
+- Icons ≤ 2 MB each, 5s fetch timeout
+- Entries (categories + fields + icons + translations + options) ≤ 10,000
+- Locales must be valid BCP‑47 (normalized); path traversal blocked in metadata name/version
+- Legacy field types mapped to Writer equivalents
+
+---
+
 ## CORS Configuration
 
 The API has CORS enabled for all origins using `@elysiajs/cors`.

src/tests/integration/routes.test.ts

@@ -71,6 +71,49 @@ describe('API routes', () => {
     expect(buffer.byteLength).toBeGreaterThan(0); // Expect a non-empty file
   });
 
+  it('adds legacyCompat tag in /v2 output', async () => {
+    const payload = {
+      metadata: { name: 'legacy-test', version: '1.0.0', legacyCompat: true },
+      categories: [
+        {
+          id: 'mahali-pa-kihistoria',
+          name: 'Historic Place',
+          appliesTo: ['observation', 'track'],
+          fields: ['field-1'],
+          track: true,
+        },
+      ],
+      fields: [{ id: 'field-1', name: 'Field', tagKey: 'field-1', type: 'text' }],
+    };
+
+    const res = await app.handle(
+      new Request('http://localhost/v2', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(payload),
+      })
+    );
+
+    expect(res.status).toBe(200);
+    const buffer = Buffer.from(await res.arrayBuffer());
+
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'comapeo-legacy-'));
+    const filePath = path.join(tmpDir, 'out.comapeocat');
+    await fs.writeFile(filePath, buffer);
+
+    const reader = new Reader(filePath);
+    const categories = await reader.categories();
+    const cat = categories.get('mahali-pa-kihistoria');
+
+    expect(cat?.tags).toEqual({
+      categoryId: 'mahali-pa-kihistoria',
+      'mahali-pa-kihistoria': 'yes',
+    });
+
+    await reader.close();
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
   it('returns 422 when comapeocat validation hangs', async () => {
     const payload = {
       metadata: { name: 'timeout-test', version: '1.0.0' },