chore: phase 1 nativephp foundation setup

legacy-api-spec.md

@@ -0,0 +1,93 @@
+# Legacy API Spec (Retraced)
+
+This spec is based on:
+- backend code in `../dewemoji-api`
+- extension usage in `../dewemoji-chrome-ext`
+
+## 1) Implemented backend API (`dewemoji-api`)
+
+### `GET /api/emojis`
+- Params supported in backend code:
+  - `query` (search string)
+  - `category`
+  - `subcategory`
+  - `page` (default `1`)
+  - `limit` (default `50`, max `50`)
+  - `key` (optional license key for tier detection)
+- Response:
+```json
+{
+  "items": [],
+  "page": 1,
+  "limit": 50,
+  "total": 0
+}
+```
+- ETag + `Cache-Control: public, max-age=300`
+
+### `GET /api/emoji/{slug}` and `GET /api/emoji?slug=...`
+- Response: single emoji object
+- Not found: `404 {"error":"not_found"}`
+- ETag + `Cache-Control: public, max-age=300`
+
+### `GET /api/categories`
+- Response shape:
+```json
+{
+  "Smileys & Emotion": ["face-smiling", "face-affection"],
+  "People & Body": ["hand-fingers-open", "person"]
+}
+```
+- `Cache-Control: public, max-age=3600`
+
+### Router-level behavior
+- CORS: `*`
+- Methods: `GET, OPTIONS`
+- Rate-limit: ~60 req/min/IP
+- Rate-limit error: `429 {"error":"rate_limited"}`
+
+## 2) Extension-consumed API contract (`dewemoji-chrome-ext`)
+
+Extension points to: `https://api.dewemoji.com/v1`
+
+### `GET /v1/emojis`
+- Params sent by extension:
+  - `q`
+  - `category`
+  - `subcategory`
+  - `page`
+  - `limit` (Free 20 / Pro 50 in client logic)
+- Expected response fields:
+  - top-level: `items`, `total`
+  - per-item: at least `emoji`, `name`, `category`, `subcategory`, `supports_skin_tone`
+- Header read by extension: `X-Dewemoji-Tier`
+
+### `GET /v1/categories`
+Extension accepts two payload styles:
+1) object map `{ "Category": ["sub"] }`
+2) items array `{ "items": [{ "name": "Category", "subcategories": [...] }] }`
+
+### `POST /v1/license/verify`
+- Body sent:
+```json
+{
+  "key": "<license>",
+  "account_id": "<hashed-account-id>",
+  "version": "<extension-version>"
+}
+```
+- Expected minimum response:
+```json
+{ "ok": true }
+```
+or
+```json
+{ "ok": false, "error": "..." }
+```
+
+## 3) Compatibility gaps to handle in rebuild
+
+- Accept both `q` and `query` for search.
+- Keep `/v1/*` contract stable for extension.
+- Return `X-Dewemoji-Tier`.
+- Preserve key item fields used by extension UI and tone logic.