emojistry 1.0.0

package/README.md

@@ -0,0 +1,151 @@
+# emojistry
+
+[![NPM Version](https://img.shields.io/npm/v/emojistry)](https://www.npmjs.com/package/emojistry)
+[![API health](https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.emojistry.kfiros.com%2Fhealth%2Fbadge)](https://api.emojistry.kfiros.com/health)
+
+App-friendly emoji data, search helpers, and a hosted REST API backed by Unicode emoji data.
+
+Emojistry provides a versioned emoji registry with normalized names, codepoints, Unicode groups, app categories, keywords, skin-tone metadata, and sequence metadata.
+
+## Install
+
+```bash
+npm install emojistry
+```
+
+```bash
+bun add emojistry
+```
+
+## Package Usage
+
+Use the generated registry data directly from the package:
+
+```ts
+import snapshot from "emojistry/data";
+import { groupByCategory, searchEmojis } from "emojistry";
+
+const hearts = searchEmojis(snapshot.emojis, "heart");
+const faces = groupByCategory(snapshot.emojis).faces;
+```
+
+Find a single emoji by emoji, slug, exact name, or codepoint:
+
+```ts
+import snapshot from "emojistry/data";
+import { findEmoji } from "emojistry";
+
+const rocket = findEmoji(snapshot.emojis, "rocket");
+const grinning = findEmoji(snapshot.emojis, "U+1F600");
+```
+
+Parse and normalize Unicode `emoji-test.txt` data:
+
+```ts
+import { normalizeEmojiEntries, parseEmojiTest } from "emojistry";
+
+const source = await fetch("https://unicode.org/Public/emoji/latest/emoji-test.txt").then((res) =>
+	res.text(),
+);
+const emojis = normalizeEmojiEntries(parseEmojiTest(source));
+```
+
+## Data Shape
+
+```ts
+interface EmojiRecord {
+	emoji: string;
+	codepoints: string[];
+	qualification: "fully-qualified" | "minimally-qualified" | "unqualified" | "component";
+	emojiVersion: string;
+	name: string;
+	group: string;
+	subgroup: string;
+	slug: string;
+	category: EmojiCategory;
+	keywords: string[];
+	hasSkinTone: boolean;
+	isSequence: boolean;
+}
+```
+
+## REST API
+
+Hosted API:
+
+```text
+https://api.emojistry.kfiros.com
+```
+
+### Endpoints
+
+```http
+GET /health
+GET /health/badge
+GET /v1
+GET /v1/emojis
+GET /v1/emojis/:emoji-or-slug-or-codepoint
+GET /v1/search?q=heart
+GET /v1/categories
+GET /v1/categories/:category/emojis
+```
+
+List endpoints support:
+
+```text
+limit=100
+offset=0
+```
+
+`GET /v1/emojis` also supports:
+
+```text
+q=heart
+category=faces
+group=Smileys%20%26%20Emotion
+subgroup=face-smiling
+```
+
+### Examples
+
+```bash
+curl https://api.emojistry.kfiros.com/health
+```
+
+```bash
+curl https://api.emojistry.kfiros.com/health/badge
+```
+
+```bash
+curl "https://api.emojistry.kfiros.com/v1/search?q=heart&limit=3"
+```
+
+```bash
+curl https://api.emojistry.kfiros.com/v1/emojis/grinning-face
+```
+
+## Categories
+
+Emojistry maps Unicode groups to app-friendly categories:
+
+```text
+faces
+people
+animals-nature
+food-drink
+travel-places
+activities
+objects
+symbols
+flags
+components
+other
+```
+
+## Development
+
+Project setup, data generation, package publishing, and deployment notes live in [docs/development.md](docs/development.md) and [docs/deployment.md](docs/deployment.md).
+
+## License
+
+MIT