@humation/sdk 0.1.0

package/README.md

@@ -0,0 +1,172 @@
+# Humation SDK
+
+Avatar Builder SDK for Humation.
+
+This SDK is for building and previewing Humation avatars. It exposes the concepts designers and product teams actually use: templates, groups, parts, colors, backgrounds, crops, SVG preview, and render URLs.
+
+## Status
+
+This package is in developer preview.
+
+- API host: `https://api.humation.app/v1`
+- Main template: `humation-1`
+- API key: required for template, asset, and render requests
+- Rate limit: `600 requests / minute / key`
+- Package version: `0.x`, breaking changes may still happen
+
+## Install
+
+```sh
+npm install @humation/sdk
+```
+
+For local workspace testing:
+
+```sh
+bun install
+bun run --cwd apps/sdk build
+```
+
+## Get An API Key
+
+Open the developer page and create a free key:
+
+```txt
+https://humation.app/developer
+```
+
+Local development:
+
+```txt
+http://localhost:3000/developer
+```
+
+The raw API key is shown only once. Humation stores only a hash, so copy it when it is created.
+
+Do not commit API keys to Git. Use environment variables:
+
+```sh
+HUMATION_API_KEY=sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+## Quickstart
+
+```ts
+import { createHumationClient } from '@humation/sdk';
+
+const humation = createHumationClient({
+  apiKey: process.env.HUMATION_API_KEY,
+});
+
+const avatar = await humation.loadAvatar('humation-1');
+
+avatar.setPart('hair', '002');
+avatar.setPart('body', '003');
+avatar.setColor('skin', 'F2C7A5');
+avatar.setBackground('transparent');
+avatar.setCrop('avatar');
+
+const svg = avatar.toSvg();
+const renderUrl = avatar.renderUrl();
+```
+
+`toSvg()` is designed for immediate preview. It uses SVG assets already fetched by the SDK, so color picker interactions can update without calling the API on every drag.
+
+`renderUrl()` points to the API render endpoint for confirmed display, export, or save flows. Since the public render API requires an API key, fetch the URL with an Authorization header instead of embedding the key in the URL.
+
+```ts
+const response = await fetch(avatar.renderUrl(), {
+  headers: {
+    Authorization: `Bearer ${process.env.HUMATION_API_KEY}`,
+  },
+});
+
+const renderedSvg = await response.text();
+```
+
+## List Templates
+
+```ts
+const templates = await humation.listTemplates();
+
+console.log(templates.map((template) => template.id));
+```
+
+## Inspect Groups And Parts
+
+```ts
+const avatar = await humation.loadAvatar('humation-1');
+
+for (const group of avatar.getGroups()) {
+  console.log(group.id, group.label);
+  console.log(group.parts.map((part) => part.id));
+}
+```
+
+Groups are the editable slots of the avatar, such as hair, body, face, or other layer groups. Parts are selectable SVG variants inside each group.
+
+Some groups can be linked. For example, selecting a visible part may update a hidden linked layer so the final avatar stacks correctly. Use `setPart()` and let the SDK resolve those links.
+
+## Change Colors
+
+```ts
+for (const color of avatar.getColors()) {
+  console.log(color.id, color.label, color.default);
+}
+
+avatar.setColor('skin', 'F2C7A5');
+```
+
+Colors are six-digit hex values. A leading `#` is optional.
+
+`stroke` means stroke color. It does not mean stroke width.
+
+## Background And Crop
+
+```ts
+avatar.setBackground('transparent');
+avatar.setBackground('F6F5F4');
+
+avatar.setCrop('avatar');
+avatar.setCrop('full');
+```
+
+Use `avatar` for square profile-style output and `full` for the full-body illustration.
+
+## Export PNG
+
+`toPngBlob()` uses `Image`, `document`, and `canvas`, so it is browser-only.
+
+```ts
+const pngBlob = await avatar.toPngBlob();
+```
+
+For server-side PNG generation, render SVG first and convert it using your server image pipeline.
+
+## Error Handling
+
+Non-2xx API responses throw `HumationApiError`.
+
+```ts
+import { HumationApiError, createHumationClient } from '@humation/sdk';
+
+try {
+  await createHumationClient({
+    apiKey: process.env.HUMATION_API_KEY,
+  }).loadAvatar('humation-1');
+} catch (error) {
+  if (error instanceof HumationApiError) {
+    console.log(error.status, error.body);
+  }
+}
+```
+
+## Raw API
+
+Raw OpenAPI-generated functions are available under `raw`, but they are a low-level escape hatch.
+
+```ts
+import { raw } from '@humation/sdk';
+```
+
+Prefer `createHumationClient()` and `AvatarSession` unless you specifically need direct endpoint access.