@origingame/origin-asset 0.12.0

package/README.md

@@ -0,0 +1,225 @@
+# origin-asset
+
+TypeScript SDK for the Origin Asset Gateway service. Mirrors the Rust crate of the same name (`origin-asset` on crates.io).
+
+> **Migration note:** This package was previously published as `@doufunao123/assetforge-sdk` (now deprecated). The API surface is unchanged — just update your `package.json` dependency name and import path.
+
+```bash
+npm install @origingame/origin-asset
+```
+
+```ts
+import { AssetForge } from "@origingame/origin-asset";
+
+const forge = new AssetForge({
+  apiKey: "agk_...",
+  baseUrl: "https://asset.origingame.dev",
+});
+```
+
+## Generate
+
+Generation and processing endpoints are durable-job based. The convenience
+methods below submit a job, then wait via SSE with polling fallback; the initial
+HTTP submit request returns immediately and never holds the provider task open.
+
+```ts
+const image = await forge.image("cinematic sci-fi skyline", {
+  size: "1536x1024",
+  transparent: true,
+});
+
+const video = await forge.video({
+  prompt: "slow camera pan",
+  input: image.url!,
+});
+
+const music = await forge.music("uplifting synth theme", { duration: 30 });
+const audio = await forge.audio("explosion sfx", { type: "sfx" });
+const tts = await forge.tts("Hello world", { voice: "Cherry" });
+const model = await forge.model3d("treasure chest");
+const character = await forge.character("medieval knight in plate armor", {
+  format: "fbx",
+  polycount: 30000,
+  pbr: true,
+  hd_texture: true,
+  pose_mode: "t-pose",
+});
+const prop = await forge.prop("ornate treasure chest", {
+  format: "glb",
+  pbr: true,
+  hd_texture: true,
+});
+const sprite = await forge.sprite("knight walk cycle", {
+  animation_type: "walk",
+  duration: 2,
+});
+const world = await forge.world("misty medieval village");
+const text = await forge.text("Write a short fantasy intro");
+```
+
+```ts
+const raw = await forge.generate({
+  asset_type: "image",
+  prompt: "minimal icon set",
+  size: "1024x1024",
+  transparent: true,
+});
+```
+
+## Jobs
+
+```ts
+const jobs = await forge.job.list({ status: "completed", limit: 20 });
+const job = await forge.job.status("job-id");
+await forge.job.cancel("job-id");
+```
+
+## Async Submit + Wait
+
+Pass `async: true` when you want the submit acknowledgement immediately and will
+wait or poll yourself.
+
+```ts
+const ack = await forge.image("cinematic sci-fi skyline", {
+  async: true,
+  idempotencyKey: "skyline-001",
+});
+
+const completed = await forge.job.wait(ack.job_id, {
+  timeoutMs: 120_000,
+  intervalMs: 1_000,
+});
+
+console.log(completed.output_url);
+```
+
+`idempotencyKey` is forwarded as the `Idempotency-Key` header. `job.wait()` uses authenticated fetch-based SSE first and falls back to polling when SSE is unavailable.
+
+## Stream
+
+```ts
+const subscription = forge.stream.job("job-id", (event) => {
+  console.log(event.kind, event.status, event.progress?.progress);
+});
+
+// Later:
+subscription.close();
+```
+
+```ts
+import { subscribeAllJobs } from "@origingame/origin-asset";
+
+const allJobs = subscribeAllJobs(
+  (event) => console.log(event.job_id, event.status),
+  { apiKey: "agk_..." }
+);
+```
+
+## Upload + Assets
+
+```ts
+const uploaded = await forge.upload(file);
+const files = await forge.assets.list();
+await forge.assets.delete(uploaded.filename);
+```
+
+## Library
+
+```ts
+const items = await forge.library.search({
+  query: "sword",
+  mode: "hybrid",
+  style: "pixel",
+});
+
+const ingest = await forge.library.ingest({
+  source: "manual",
+  asset_type: "image",
+  file_url: "https://example.com/fire-sword.png",
+  name: "Fire Sword",
+  user_tags: ["weapon", "fire"],
+});
+
+const ingested = await forge.library.ingestWait(ingest.ingest_job_id);
+
+await forge.library.packsInstall({
+  source: "builtin",
+  id: "hello-world",
+});
+
+const packs = await forge.library.packs();
+
+await forge.library.add({
+  name: "Fire Sword",
+  asset_type: "image",
+  file_url: "https://example.com/fire-sword.png",
+});
+```
+
+## Providers
+
+```ts
+const providers = await forge.providers.list();
+const health = await forge.providers.health();
+const gemini = await forge.providers.health("gemini_image");
+```
+
+## Process
+
+```ts
+const processed = await forge.process({
+  input: image.url!,
+  operations: [
+    { op: "smart_crop", mode: "tightest" },
+    { op: "resize", width: 512, height: 512 },
+  ],
+});
+
+const rigged = await forge.process3d({
+  task_id: "tripo-task-id",
+  operation: "rig",
+});
+```
+
+## Voice
+
+```ts
+await forge.voice.clone({
+  audio_base64: "...",
+  audio_mime: "audio/mpeg",
+  preview_text: "Welcome back.",
+  name: "hero",
+});
+
+const voiceAck = await forge.voice.clone(
+  {
+    audio_base64: "...",
+    audio_mime: "audio/mpeg",
+    preview_text: "Welcome back.",
+    name: "hero",
+  },
+  { async: true }
+);
+
+await forge.voice.design({
+  voice_prompt: "warm documentary narrator",
+  preview_text: "Welcome to AssetForge.",
+  name: "narrator",
+});
+
+const voices = await forge.voice.list({ type: "vc" });
+```
+
+## Errors
+
+```ts
+import { AssetForgeError } from "@origingame/origin-asset";
+
+try {
+  await forge.image("...");
+} catch (error) {
+  const e = error as AssetForgeError;
+  console.error(e.code, e.message);
+}
+```