tryiton 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TryItOn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# TryItOn Node.js SDK — AI Virtual Try-On API for JavaScript & TypeScript
+
+Official Node.js and TypeScript client for the [TryItOn](https://tryiton.now) virtual try-on API. Add photoreal AI virtual try-on for clothing, accessories, hairstyles, and tattoos to your JavaScript or TypeScript application with a few lines of code.
+
+- Virtual clothing try-on and accessory try-on (eyewear, footwear, headwear, jewelry)
+- Hairstyle and tattoo try-on
+- Fully typed, zero runtime dependencies (uses the native `fetch` API)
+- Built-in job polling helper
+
+Full API reference: [docs.tryiton.now](https://docs.tryiton.now) · Get an API key: [tryiton.now/app/developer](https://tryiton.now/app/developer)
+
+## Installation
+
+```bash
+npm install tryiton
+```
+
+Requires Node.js 18 or later (or any runtime with a global `fetch`, such as Bun, Deno, or modern browsers). TypeScript types are bundled.
+
+## Quickstart: run a virtual try-on
+
+Submit a garment and a model photo, then wait for the generated result image.
+
+```ts
+import { TryItOn } from "tryiton";
+
+const client = new TryItOn({ apiKey: process.env.TRYITON_API_KEY });
+
+// Submit a clothing try-on
+const jobId = await client.tryOnClothes({
+  modelImage: "https://example.com/model.jpg",
+  garmentImage: "https://example.com/tshirt.jpg",
+  category: "clothing",
+  subcategory: "tops",
+});
+
+// Poll until the job completes and return the output image URL(s)
+const [resultUrl] = await client.waitForResult(jobId);
+console.log(resultUrl); // CDN URL, available for 72 hours
+```
+
+Image inputs accept a public URL or a base64 data URL (`data:image/png;base64,...`).
+
+## Core parameters
+
+`tryOnClothes` covers clothing and accessory try-on. The most important parameters:
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `modelImage` | string | Yes | URL or base64 data URL of the person. |
+| `garmentImage` | string | Yes | URL or base64 data URL of the garment or accessory. |
+| `category` | string | No | Item type: `auto`, `clothing`, `eyewear`, `footwear`, `headwear`, `jewelry`, `accessories`, or `others`. `auto` detects it for you. |
+| `subcategory` | string | No | Required for `clothing` (`tops`, `bottoms`, `dresses`), `jewelry`, and `accessories`. |
+
+Additional clothing options (`mode`, `numSamples`, `outputFormat`, `seed`) are documented in the [API reference](https://docs.tryiton.now).
+
+## Other endpoints
+
+```ts
+// Hairstyle try-on (see the HAIRCUTS export for all supported values)
+await client.tryOnHairstyle({ faceImage, haircut: "BuzzCut", hairColor: "ash blonde" });
+
+// Tattoo try-on
+await client.tryOnTattoo({ bodyImage, designImage, placement: "on the right forearm, small" });
+
+// Poll a job manually, or check your credit balance
+const status = await client.getStatus(jobId);   // { status, output, error }
+const credits = await client.getCredits();        // { on_demand, subscription, purchased, reserved }
+```
+
+## Error handling
+
+All failures throw `TryItOnError`, which carries the HTTP status code and the API error name.
+
+```ts
+import { TryItOn, TryItOnError } from "tryiton";
+
+try {
+  await client.tryOnClothes({ /* ... */ });
+} catch (err) {
+  if (err instanceof TryItOnError) {
+    console.error(err.status, err.errorName, err.message); // e.g. 429, "OutOfCredits"
+  }
+}
+```
+
+## Notes
+
+- Output image URLs expire 72 hours after completion. Download any results you want to keep.
+- Failed jobs are never charged.
+
+## Documentation
+
+Full documentation, parameter reference, and guides: [docs.tryiton.now](https://docs.tryiton.now)
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,221 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  HAIRCUTS: () => HAIRCUTS,
+  TryItOn: () => TryItOn,
+  TryItOnError: () => TryItOnError,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var DEFAULT_BASE_URL = "https://tryiton.now/api/v1";
+var HAIRCUTS = [
+  "Afro",
+  "BobCut",
+  "BowlCut",
+  "BoxBraids",
+  "BuzzCut",
+  "Chignon",
+  "CombOver",
+  "CornrowBraids",
+  "CurlyBob",
+  "CurlyShag",
+  "DoubleBun",
+  "Dreadlocks",
+  "FauxHawk",
+  "FishtailBraid",
+  "LongCurly",
+  "LongHairTiedUp",
+  "LongHimeCut",
+  "LongStraight",
+  "LongTwintails",
+  "LongWavy",
+  "LongWavyCurtainBangs",
+  "ManBun",
+  "MessyTousled",
+  "PixieCut",
+  "Pompadour",
+  "Ponytail",
+  "ShortCurlyPixie",
+  "ShortTwintails",
+  "ShoulderLengthHair",
+  "Spiky",
+  "TexturedFringe",
+  "TwinBraids",
+  "Updo",
+  "WavyShag"
+];
+var TryItOnError = class _TryItOnError extends Error {
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = "TryItOnError";
+    this.status = opts.status ?? null;
+    this.errorName = opts.errorName ?? null;
+    Object.setPrototypeOf(this, _TryItOnError.prototype);
+  }
+};
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(new TryItOnError("Aborted.", { errorName: "Aborted" }));
+    const t = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(t);
+        reject(new TryItOnError("Aborted.", { errorName: "Aborted" }));
+      },
+      { once: true }
+    );
+  });
+}
+var TryItOn = class {
+  constructor(options) {
+    if (!options || !options.apiKey) throw new TryItOnError("An apiKey is required.", { errorName: "ConfigError" });
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeoutMs = options.timeoutMs ?? 6e4;
+    const f = options.fetch ?? globalThis.fetch;
+    if (!f) {
+      throw new TryItOnError(
+        "No fetch implementation found. Use Node 18+, or pass `fetch` in options.",
+        { errorName: "ConfigError" }
+      );
+    }
+    this.fetchImpl = f;
+  }
+  /** Put a garment or accessory on a person. Returns the job id. */
+  async tryOnClothes(params) {
+    const body = {
+      model_image: params.modelImage,
+      garment_image: params.garmentImage,
+      category: params.category,
+      subcategory: params.subcategory,
+      mode: params.mode,
+      num_samples: params.numSamples,
+      output_format: params.outputFormat,
+      seed: params.seed,
+      segmentation_free: params.segmentationFree,
+      garment_photo_type: params.garmentPhotoType,
+      moderation_level: params.moderationLevel
+    };
+    const res = await this.request("POST", "/tryon/clothes", body);
+    return res.jobId;
+  }
+  /** Restyle a person's hair. Returns the job id. */
+  async tryOnHairstyle(params) {
+    const body = { face_image: params.faceImage, haircut: params.haircut, hair_color: params.hairColor };
+    const res = await this.request("POST", "/tryon/hairstyle", body);
+    return res.jobId;
+  }
+  /** Ink a design onto skin. Returns the job id. */
+  async tryOnTattoo(params) {
+    const body = { body_image: params.bodyImage, design_image: params.designImage, placement: params.placement };
+    const res = await this.request("POST", "/tryon/tattoo", body);
+    return res.jobId;
+  }
+  /** Fetch the current status of a job. */
+  async getStatus(jobId) {
+    return this.request("GET", `/status/${encodeURIComponent(jobId)}`);
+  }
+  /** Fetch your current credit balance. */
+  async getCredits() {
+    const res = await this.request("GET", "/credits");
+    return res.credits;
+  }
+  /**
+   * Poll a job until it completes, then resolve with the output image URLs.
+   * Throws a TryItOnError if the job fails or the timeout is reached.
+   */
+  async waitForResult(jobId, opts = {}) {
+    const pollInterval = opts.pollIntervalMs ?? 2e3;
+    const timeout = opts.timeoutMs ?? 12e4;
+    const start = Date.now();
+    for (; ; ) {
+      const res = await this.getStatus(jobId);
+      if (res.status === "completed") return res.output ?? [];
+      if (res.status === "failed") {
+        throw new TryItOnError(res.error?.message ?? "Try-on failed.", {
+          errorName: res.error?.name ?? "ProcessingError"
+        });
+      }
+      if (Date.now() - start > timeout) {
+        throw new TryItOnError(`Timed out waiting for job ${jobId} after ${timeout}ms.`, { errorName: "Timeout" });
+      }
+      await sleep(pollInterval, opts.signal);
+    }
+  }
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let res;
+    try {
+      res = await this.fetchImpl(url, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          ...body !== void 0 ? { "Content-Type": "application/json" } : {}
+        },
+        body: body !== void 0 ? JSON.stringify(stripUndefined(body)) : void 0,
+        signal: controller.signal
+      });
+    } catch (err) {
+      clearTimeout(timer);
+      if (err?.name === "AbortError") {
+        throw new TryItOnError(`Request timed out after ${this.timeoutMs}ms.`, { errorName: "Timeout" });
+      }
+      throw new TryItOnError(`Network error: ${err?.message ?? String(err)}`, { errorName: "NetworkError" });
+    } finally {
+      clearTimeout(timer);
+    }
+    const text = await res.text();
+    let data = {};
+    if (text) {
+      try {
+        data = JSON.parse(text);
+      } catch {
+        if (!res.ok) throw new TryItOnError(text || `HTTP ${res.status}`, { status: res.status });
+      }
+    }
+    if (!res.ok) {
+      throw new TryItOnError(data?.message ?? `HTTP ${res.status}`, {
+        status: res.status,
+        errorName: data?.error ?? null
+      });
+    }
+    return data;
+  }
+};
+function stripUndefined(obj) {
+  if (obj === null || typeof obj !== "object") return obj;
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== void 0) out[k] = v;
+  }
+  return out;
+}
+var index_default = TryItOn;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HAIRCUTS,
+  TryItOn,
+  TryItOnError
+});

package/dist/index.d.cts

@@ -0,0 +1,127 @@
+/**
+ * TryItOn — official JavaScript / TypeScript SDK.
+ *
+ * Wraps the TryItOn virtual try-on REST API (https://docs.tryiton.now).
+ * Requires a runtime with a global `fetch` (Node 18+, Bun, Deno, browsers) or a
+ * `fetch` implementation passed via options.
+ */
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+interface TryItOnOptions {
+    /** Your API key from https://tryiton.now/app/developer */
+    apiKey: string;
+    /** Override the API base URL. Defaults to https://tryiton.now/api/v1 */
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds. Defaults to 60000. */
+    timeoutMs?: number;
+    /** Custom fetch implementation (e.g. node-fetch on older Node). */
+    fetch?: FetchLike;
+}
+type JobStatus = "processing" | "completed" | "failed";
+interface JobError {
+    name: string;
+    message: string;
+}
+interface StatusResponse {
+    ok: boolean;
+    status: JobStatus;
+    /** CDN URLs of the result image(s); present when completed. Expire after 72h. */
+    output?: string[];
+    error?: JobError | null;
+}
+interface Credits {
+    on_demand: number;
+    subscription: number;
+    purchased: number;
+    reserved: number;
+}
+type Category = "auto" | "clothing" | "eyewear" | "footwear" | "headwear" | "jewelry" | "accessories" | "others";
+type Mode = "performance" | "balanced" | "quality";
+interface TryOnClothesParams {
+    /** URL or base64 data URL of the person. */
+    modelImage: string;
+    /** URL or base64 data URL of the garment/accessory. */
+    garmentImage: string;
+    /** What the item is. `auto` detects it for you. */
+    category?: Category;
+    /** Required for `clothing`, `jewelry`, `accessories` (e.g. "tops"). */
+    subcategory?: string;
+    /** Quality/speed trade-off (clothing only). */
+    mode?: Mode;
+    /** Number of output images, 1–4 (clothing only). Charged per image. */
+    numSamples?: number;
+    /** "png" or "jpeg" (clothing only). */
+    outputFormat?: "png" | "jpeg";
+    /** Fixes randomness (clothing only). */
+    seed?: number;
+    /** Advanced (clothing only). */
+    segmentationFree?: boolean;
+    /** Advanced hint: "auto" | "model" | "flat-lay" (clothing only). */
+    garmentPhotoType?: "auto" | "model" | "flat-lay";
+    /** Advanced (clothing only). */
+    moderationLevel?: string;
+}
+interface TryOnHairstyleParams {
+    /** URL or base64 data URL of the person's face. */
+    faceImage: string;
+    /** One of the supported haircut values (see HAIRCUTS). */
+    haircut: string;
+    /** Optional free-text color, e.g. "ash blonde". Omit to keep current color. */
+    hairColor?: string;
+}
+interface TryOnTattooParams {
+    /** URL or base64 data URL — a close-up of bare skin. */
+    bodyImage: string;
+    /** URL or base64 data URL of the tattoo design on its own. */
+    designImage: string;
+    /** Optional free-text placement/size, max 140 chars. */
+    placement?: string;
+}
+interface WaitOptions {
+    /** How often to poll, in ms. Default 2000. */
+    pollIntervalMs?: number;
+    /** Give up after this many ms. Default 120000. */
+    timeoutMs?: number;
+    /** Abort the wait. */
+    signal?: AbortSignal;
+}
+/** The supported `haircut` values for hairstyle try-on. */
+declare const HAIRCUTS: readonly ["Afro", "BobCut", "BowlCut", "BoxBraids", "BuzzCut", "Chignon", "CombOver", "CornrowBraids", "CurlyBob", "CurlyShag", "DoubleBun", "Dreadlocks", "FauxHawk", "FishtailBraid", "LongCurly", "LongHairTiedUp", "LongHimeCut", "LongStraight", "LongTwintails", "LongWavy", "LongWavyCurtainBangs", "ManBun", "MessyTousled", "PixieCut", "Pompadour", "Ponytail", "ShortCurlyPixie", "ShortTwintails", "ShoulderLengthHair", "Spiky", "TexturedFringe", "TwinBraids", "Updo", "WavyShag"];
+/**
+ * Raised for any API-level error (bad request, auth, rate limit, out of credits,
+ * server error) and for runtime failures surfaced while polling a job.
+ */
+declare class TryItOnError extends Error {
+    /** HTTP status code, or null for a runtime (job) failure. */
+    readonly status: number | null;
+    /** The API error name, e.g. "OutOfCredits" or "ProcessingError". */
+    readonly errorName: string | null;
+    constructor(message: string, opts?: {
+        status?: number | null;
+        errorName?: string | null;
+    });
+}
+declare class TryItOn {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(options: TryItOnOptions);
+    /** Put a garment or accessory on a person. Returns the job id. */
+    tryOnClothes(params: TryOnClothesParams): Promise<string>;
+    /** Restyle a person's hair. Returns the job id. */
+    tryOnHairstyle(params: TryOnHairstyleParams): Promise<string>;
+    /** Ink a design onto skin. Returns the job id. */
+    tryOnTattoo(params: TryOnTattooParams): Promise<string>;
+    /** Fetch the current status of a job. */
+    getStatus(jobId: string): Promise<StatusResponse>;
+    /** Fetch your current credit balance. */
+    getCredits(): Promise<Credits>;
+    /**
+     * Poll a job until it completes, then resolve with the output image URLs.
+     * Throws a TryItOnError if the job fails or the timeout is reached.
+     */
+    waitForResult(jobId: string, opts?: WaitOptions): Promise<string[]>;
+    private request;
+}
+
+export { type Category, type Credits, type FetchLike, HAIRCUTS, type JobError, type JobStatus, type Mode, type StatusResponse, TryItOn, TryItOnError, type TryItOnOptions, type TryOnClothesParams, type TryOnHairstyleParams, type TryOnTattooParams, type WaitOptions, TryItOn as default };

package/dist/index.d.ts

@@ -0,0 +1,127 @@
+/**
+ * TryItOn — official JavaScript / TypeScript SDK.
+ *
+ * Wraps the TryItOn virtual try-on REST API (https://docs.tryiton.now).
+ * Requires a runtime with a global `fetch` (Node 18+, Bun, Deno, browsers) or a
+ * `fetch` implementation passed via options.
+ */
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+interface TryItOnOptions {
+    /** Your API key from https://tryiton.now/app/developer */
+    apiKey: string;
+    /** Override the API base URL. Defaults to https://tryiton.now/api/v1 */
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds. Defaults to 60000. */
+    timeoutMs?: number;
+    /** Custom fetch implementation (e.g. node-fetch on older Node). */
+    fetch?: FetchLike;
+}
+type JobStatus = "processing" | "completed" | "failed";
+interface JobError {
+    name: string;
+    message: string;
+}
+interface StatusResponse {
+    ok: boolean;
+    status: JobStatus;
+    /** CDN URLs of the result image(s); present when completed. Expire after 72h. */
+    output?: string[];
+    error?: JobError | null;
+}
+interface Credits {
+    on_demand: number;
+    subscription: number;
+    purchased: number;
+    reserved: number;
+}
+type Category = "auto" | "clothing" | "eyewear" | "footwear" | "headwear" | "jewelry" | "accessories" | "others";
+type Mode = "performance" | "balanced" | "quality";
+interface TryOnClothesParams {
+    /** URL or base64 data URL of the person. */
+    modelImage: string;
+    /** URL or base64 data URL of the garment/accessory. */
+    garmentImage: string;
+    /** What the item is. `auto` detects it for you. */
+    category?: Category;
+    /** Required for `clothing`, `jewelry`, `accessories` (e.g. "tops"). */
+    subcategory?: string;
+    /** Quality/speed trade-off (clothing only). */
+    mode?: Mode;
+    /** Number of output images, 1–4 (clothing only). Charged per image. */
+    numSamples?: number;
+    /** "png" or "jpeg" (clothing only). */
+    outputFormat?: "png" | "jpeg";
+    /** Fixes randomness (clothing only). */
+    seed?: number;
+    /** Advanced (clothing only). */
+    segmentationFree?: boolean;
+    /** Advanced hint: "auto" | "model" | "flat-lay" (clothing only). */
+    garmentPhotoType?: "auto" | "model" | "flat-lay";
+    /** Advanced (clothing only). */
+    moderationLevel?: string;
+}
+interface TryOnHairstyleParams {
+    /** URL or base64 data URL of the person's face. */
+    faceImage: string;
+    /** One of the supported haircut values (see HAIRCUTS). */
+    haircut: string;
+    /** Optional free-text color, e.g. "ash blonde". Omit to keep current color. */
+    hairColor?: string;
+}
+interface TryOnTattooParams {
+    /** URL or base64 data URL — a close-up of bare skin. */
+    bodyImage: string;
+    /** URL or base64 data URL of the tattoo design on its own. */
+    designImage: string;
+    /** Optional free-text placement/size, max 140 chars. */
+    placement?: string;
+}
+interface WaitOptions {
+    /** How often to poll, in ms. Default 2000. */
+    pollIntervalMs?: number;
+    /** Give up after this many ms. Default 120000. */
+    timeoutMs?: number;
+    /** Abort the wait. */
+    signal?: AbortSignal;
+}
+/** The supported `haircut` values for hairstyle try-on. */
+declare const HAIRCUTS: readonly ["Afro", "BobCut", "BowlCut", "BoxBraids", "BuzzCut", "Chignon", "CombOver", "CornrowBraids", "CurlyBob", "CurlyShag", "DoubleBun", "Dreadlocks", "FauxHawk", "FishtailBraid", "LongCurly", "LongHairTiedUp", "LongHimeCut", "LongStraight", "LongTwintails", "LongWavy", "LongWavyCurtainBangs", "ManBun", "MessyTousled", "PixieCut", "Pompadour", "Ponytail", "ShortCurlyPixie", "ShortTwintails", "ShoulderLengthHair", "Spiky", "TexturedFringe", "TwinBraids", "Updo", "WavyShag"];
+/**
+ * Raised for any API-level error (bad request, auth, rate limit, out of credits,
+ * server error) and for runtime failures surfaced while polling a job.
+ */
+declare class TryItOnError extends Error {
+    /** HTTP status code, or null for a runtime (job) failure. */
+    readonly status: number | null;
+    /** The API error name, e.g. "OutOfCredits" or "ProcessingError". */
+    readonly errorName: string | null;
+    constructor(message: string, opts?: {
+        status?: number | null;
+        errorName?: string | null;
+    });
+}
+declare class TryItOn {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(options: TryItOnOptions);
+    /** Put a garment or accessory on a person. Returns the job id. */
+    tryOnClothes(params: TryOnClothesParams): Promise<string>;
+    /** Restyle a person's hair. Returns the job id. */
+    tryOnHairstyle(params: TryOnHairstyleParams): Promise<string>;
+    /** Ink a design onto skin. Returns the job id. */
+    tryOnTattoo(params: TryOnTattooParams): Promise<string>;
+    /** Fetch the current status of a job. */
+    getStatus(jobId: string): Promise<StatusResponse>;
+    /** Fetch your current credit balance. */
+    getCredits(): Promise<Credits>;
+    /**
+     * Poll a job until it completes, then resolve with the output image URLs.
+     * Throws a TryItOnError if the job fails or the timeout is reached.
+     */
+    waitForResult(jobId: string, opts?: WaitOptions): Promise<string[]>;
+    private request;
+}
+
+export { type Category, type Credits, type FetchLike, HAIRCUTS, type JobError, type JobStatus, type Mode, type StatusResponse, TryItOn, TryItOnError, type TryItOnOptions, type TryOnClothesParams, type TryOnHairstyleParams, type TryOnTattooParams, type WaitOptions, TryItOn as default };

package/dist/index.js

@@ -0,0 +1,194 @@
+// src/index.ts
+var DEFAULT_BASE_URL = "https://tryiton.now/api/v1";
+var HAIRCUTS = [
+  "Afro",
+  "BobCut",
+  "BowlCut",
+  "BoxBraids",
+  "BuzzCut",
+  "Chignon",
+  "CombOver",
+  "CornrowBraids",
+  "CurlyBob",
+  "CurlyShag",
+  "DoubleBun",
+  "Dreadlocks",
+  "FauxHawk",
+  "FishtailBraid",
+  "LongCurly",
+  "LongHairTiedUp",
+  "LongHimeCut",
+  "LongStraight",
+  "LongTwintails",
+  "LongWavy",
+  "LongWavyCurtainBangs",
+  "ManBun",
+  "MessyTousled",
+  "PixieCut",
+  "Pompadour",
+  "Ponytail",
+  "ShortCurlyPixie",
+  "ShortTwintails",
+  "ShoulderLengthHair",
+  "Spiky",
+  "TexturedFringe",
+  "TwinBraids",
+  "Updo",
+  "WavyShag"
+];
+var TryItOnError = class _TryItOnError extends Error {
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = "TryItOnError";
+    this.status = opts.status ?? null;
+    this.errorName = opts.errorName ?? null;
+    Object.setPrototypeOf(this, _TryItOnError.prototype);
+  }
+};
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(new TryItOnError("Aborted.", { errorName: "Aborted" }));
+    const t = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(t);
+        reject(new TryItOnError("Aborted.", { errorName: "Aborted" }));
+      },
+      { once: true }
+    );
+  });
+}
+var TryItOn = class {
+  constructor(options) {
+    if (!options || !options.apiKey) throw new TryItOnError("An apiKey is required.", { errorName: "ConfigError" });
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeoutMs = options.timeoutMs ?? 6e4;
+    const f = options.fetch ?? globalThis.fetch;
+    if (!f) {
+      throw new TryItOnError(
+        "No fetch implementation found. Use Node 18+, or pass `fetch` in options.",
+        { errorName: "ConfigError" }
+      );
+    }
+    this.fetchImpl = f;
+  }
+  /** Put a garment or accessory on a person. Returns the job id. */
+  async tryOnClothes(params) {
+    const body = {
+      model_image: params.modelImage,
+      garment_image: params.garmentImage,
+      category: params.category,
+      subcategory: params.subcategory,
+      mode: params.mode,
+      num_samples: params.numSamples,
+      output_format: params.outputFormat,
+      seed: params.seed,
+      segmentation_free: params.segmentationFree,
+      garment_photo_type: params.garmentPhotoType,
+      moderation_level: params.moderationLevel
+    };
+    const res = await this.request("POST", "/tryon/clothes", body);
+    return res.jobId;
+  }
+  /** Restyle a person's hair. Returns the job id. */
+  async tryOnHairstyle(params) {
+    const body = { face_image: params.faceImage, haircut: params.haircut, hair_color: params.hairColor };
+    const res = await this.request("POST", "/tryon/hairstyle", body);
+    return res.jobId;
+  }
+  /** Ink a design onto skin. Returns the job id. */
+  async tryOnTattoo(params) {
+    const body = { body_image: params.bodyImage, design_image: params.designImage, placement: params.placement };
+    const res = await this.request("POST", "/tryon/tattoo", body);
+    return res.jobId;
+  }
+  /** Fetch the current status of a job. */
+  async getStatus(jobId) {
+    return this.request("GET", `/status/${encodeURIComponent(jobId)}`);
+  }
+  /** Fetch your current credit balance. */
+  async getCredits() {
+    const res = await this.request("GET", "/credits");
+    return res.credits;
+  }
+  /**
+   * Poll a job until it completes, then resolve with the output image URLs.
+   * Throws a TryItOnError if the job fails or the timeout is reached.
+   */
+  async waitForResult(jobId, opts = {}) {
+    const pollInterval = opts.pollIntervalMs ?? 2e3;
+    const timeout = opts.timeoutMs ?? 12e4;
+    const start = Date.now();
+    for (; ; ) {
+      const res = await this.getStatus(jobId);
+      if (res.status === "completed") return res.output ?? [];
+      if (res.status === "failed") {
+        throw new TryItOnError(res.error?.message ?? "Try-on failed.", {
+          errorName: res.error?.name ?? "ProcessingError"
+        });
+      }
+      if (Date.now() - start > timeout) {
+        throw new TryItOnError(`Timed out waiting for job ${jobId} after ${timeout}ms.`, { errorName: "Timeout" });
+      }
+      await sleep(pollInterval, opts.signal);
+    }
+  }
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let res;
+    try {
+      res = await this.fetchImpl(url, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          ...body !== void 0 ? { "Content-Type": "application/json" } : {}
+        },
+        body: body !== void 0 ? JSON.stringify(stripUndefined(body)) : void 0,
+        signal: controller.signal
+      });
+    } catch (err) {
+      clearTimeout(timer);
+      if (err?.name === "AbortError") {
+        throw new TryItOnError(`Request timed out after ${this.timeoutMs}ms.`, { errorName: "Timeout" });
+      }
+      throw new TryItOnError(`Network error: ${err?.message ?? String(err)}`, { errorName: "NetworkError" });
+    } finally {
+      clearTimeout(timer);
+    }
+    const text = await res.text();
+    let data = {};
+    if (text) {
+      try {
+        data = JSON.parse(text);
+      } catch {
+        if (!res.ok) throw new TryItOnError(text || `HTTP ${res.status}`, { status: res.status });
+      }
+    }
+    if (!res.ok) {
+      throw new TryItOnError(data?.message ?? `HTTP ${res.status}`, {
+        status: res.status,
+        errorName: data?.error ?? null
+      });
+    }
+    return data;
+  }
+};
+function stripUndefined(obj) {
+  if (obj === null || typeof obj !== "object") return obj;
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== void 0) out[k] = v;
+  }
+  return out;
+}
+var index_default = TryItOn;
+export {
+  HAIRCUTS,
+  TryItOn,
+  TryItOnError,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "tryiton",
+  "version": "0.1.0",
+  "description": "Official JavaScript/TypeScript SDK for the TryItOn virtual try-on API.",
+  "keywords": [
+    "tryiton",
+    "virtual-try-on",
+    "tryon",
+    "fashion",
+    "ai",
+    "sdk"
+  ],
+  "homepage": "https://docs.tryiton.now",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tryiton-now/tryiton-node.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tryiton-now/tryiton-node/issues"
+  },
+  "license": "MIT",
+  "author": "TryItOn",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,298 @@
+/**
+ * TryItOn — official JavaScript / TypeScript SDK.
+ *
+ * Wraps the TryItOn virtual try-on REST API (https://docs.tryiton.now).
+ * Requires a runtime with a global `fetch` (Node 18+, Bun, Deno, browsers) or a
+ * `fetch` implementation passed via options.
+ */
+
+const DEFAULT_BASE_URL = "https://tryiton.now/api/v1";
+
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+export interface TryItOnOptions {
+  /** Your API key from https://tryiton.now/app/developer */
+  apiKey: string;
+  /** Override the API base URL. Defaults to https://tryiton.now/api/v1 */
+  baseUrl?: string;
+  /** Per-request timeout in milliseconds. Defaults to 60000. */
+  timeoutMs?: number;
+  /** Custom fetch implementation (e.g. node-fetch on older Node). */
+  fetch?: FetchLike;
+}
+
+export type JobStatus = "processing" | "completed" | "failed";
+
+export interface JobError {
+  name: string;
+  message: string;
+}
+
+export interface StatusResponse {
+  ok: boolean;
+  status: JobStatus;
+  /** CDN URLs of the result image(s); present when completed. Expire after 72h. */
+  output?: string[];
+  error?: JobError | null;
+}
+
+export interface Credits {
+  on_demand: number;
+  subscription: number;
+  purchased: number;
+  reserved: number;
+}
+
+export type Category =
+  | "auto"
+  | "clothing"
+  | "eyewear"
+  | "footwear"
+  | "headwear"
+  | "jewelry"
+  | "accessories"
+  | "others";
+
+export type Mode = "performance" | "balanced" | "quality";
+
+export interface TryOnClothesParams {
+  /** URL or base64 data URL of the person. */
+  modelImage: string;
+  /** URL or base64 data URL of the garment/accessory. */
+  garmentImage: string;
+  /** What the item is. `auto` detects it for you. */
+  category?: Category;
+  /** Required for `clothing`, `jewelry`, `accessories` (e.g. "tops"). */
+  subcategory?: string;
+  /** Quality/speed trade-off (clothing only). */
+  mode?: Mode;
+  /** Number of output images, 1–4 (clothing only). Charged per image. */
+  numSamples?: number;
+  /** "png" or "jpeg" (clothing only). */
+  outputFormat?: "png" | "jpeg";
+  /** Fixes randomness (clothing only). */
+  seed?: number;
+  /** Advanced (clothing only). */
+  segmentationFree?: boolean;
+  /** Advanced hint: "auto" | "model" | "flat-lay" (clothing only). */
+  garmentPhotoType?: "auto" | "model" | "flat-lay";
+  /** Advanced (clothing only). */
+  moderationLevel?: string;
+}
+
+export interface TryOnHairstyleParams {
+  /** URL or base64 data URL of the person's face. */
+  faceImage: string;
+  /** One of the supported haircut values (see HAIRCUTS). */
+  haircut: string;
+  /** Optional free-text color, e.g. "ash blonde". Omit to keep current color. */
+  hairColor?: string;
+}
+
+export interface TryOnTattooParams {
+  /** URL or base64 data URL — a close-up of bare skin. */
+  bodyImage: string;
+  /** URL or base64 data URL of the tattoo design on its own. */
+  designImage: string;
+  /** Optional free-text placement/size, max 140 chars. */
+  placement?: string;
+}
+
+export interface WaitOptions {
+  /** How often to poll, in ms. Default 2000. */
+  pollIntervalMs?: number;
+  /** Give up after this many ms. Default 120000. */
+  timeoutMs?: number;
+  /** Abort the wait. */
+  signal?: AbortSignal;
+}
+
+/** The supported `haircut` values for hairstyle try-on. */
+export const HAIRCUTS = [
+  "Afro", "BobCut", "BowlCut", "BoxBraids", "BuzzCut", "Chignon", "CombOver",
+  "CornrowBraids", "CurlyBob", "CurlyShag", "DoubleBun", "Dreadlocks", "FauxHawk",
+  "FishtailBraid", "LongCurly", "LongHairTiedUp", "LongHimeCut", "LongStraight",
+  "LongTwintails", "LongWavy", "LongWavyCurtainBangs", "ManBun", "MessyTousled",
+  "PixieCut", "Pompadour", "Ponytail", "ShortCurlyPixie", "ShortTwintails",
+  "ShoulderLengthHair", "Spiky", "TexturedFringe", "TwinBraids", "Updo", "WavyShag",
+] as const;
+
+/**
+ * Raised for any API-level error (bad request, auth, rate limit, out of credits,
+ * server error) and for runtime failures surfaced while polling a job.
+ */
+export class TryItOnError extends Error {
+  /** HTTP status code, or null for a runtime (job) failure. */
+  readonly status: number | null;
+  /** The API error name, e.g. "OutOfCredits" or "ProcessingError". */
+  readonly errorName: string | null;
+
+  constructor(message: string, opts: { status?: number | null; errorName?: string | null } = {}) {
+    super(message);
+    this.name = "TryItOnError";
+    this.status = opts.status ?? null;
+    this.errorName = opts.errorName ?? null;
+    Object.setPrototypeOf(this, TryItOnError.prototype);
+  }
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(new TryItOnError("Aborted.", { errorName: "Aborted" }));
+    const t = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(t);
+        reject(new TryItOnError("Aborted.", { errorName: "Aborted" }));
+      },
+      { once: true },
+    );
+  });
+}
+
+export class TryItOn {
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+  private readonly timeoutMs: number;
+  private readonly fetchImpl: FetchLike;
+
+  constructor(options: TryItOnOptions) {
+    if (!options || !options.apiKey) throw new TryItOnError("An apiKey is required.", { errorName: "ConfigError" });
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeoutMs = options.timeoutMs ?? 60000;
+    const f = options.fetch ?? (globalThis.fetch as FetchLike | undefined);
+    if (!f) {
+      throw new TryItOnError(
+        "No fetch implementation found. Use Node 18+, or pass `fetch` in options.",
+        { errorName: "ConfigError" },
+      );
+    }
+    this.fetchImpl = f;
+  }
+
+  /** Put a garment or accessory on a person. Returns the job id. */
+  async tryOnClothes(params: TryOnClothesParams): Promise<string> {
+    const body = {
+      model_image: params.modelImage,
+      garment_image: params.garmentImage,
+      category: params.category,
+      subcategory: params.subcategory,
+      mode: params.mode,
+      num_samples: params.numSamples,
+      output_format: params.outputFormat,
+      seed: params.seed,
+      segmentation_free: params.segmentationFree,
+      garment_photo_type: params.garmentPhotoType,
+      moderation_level: params.moderationLevel,
+    };
+    const res = await this.request<{ jobId: string }>("POST", "/tryon/clothes", body);
+    return res.jobId;
+  }
+
+  /** Restyle a person's hair. Returns the job id. */
+  async tryOnHairstyle(params: TryOnHairstyleParams): Promise<string> {
+    const body = { face_image: params.faceImage, haircut: params.haircut, hair_color: params.hairColor };
+    const res = await this.request<{ jobId: string }>("POST", "/tryon/hairstyle", body);
+    return res.jobId;
+  }
+
+  /** Ink a design onto skin. Returns the job id. */
+  async tryOnTattoo(params: TryOnTattooParams): Promise<string> {
+    const body = { body_image: params.bodyImage, design_image: params.designImage, placement: params.placement };
+    const res = await this.request<{ jobId: string }>("POST", "/tryon/tattoo", body);
+    return res.jobId;
+  }
+
+  /** Fetch the current status of a job. */
+  async getStatus(jobId: string): Promise<StatusResponse> {
+    return this.request<StatusResponse>("GET", `/status/${encodeURIComponent(jobId)}`);
+  }
+
+  /** Fetch your current credit balance. */
+  async getCredits(): Promise<Credits> {
+    const res = await this.request<{ credits: Credits }>("GET", "/credits");
+    return res.credits;
+  }
+
+  /**
+   * Poll a job until it completes, then resolve with the output image URLs.
+   * Throws a TryItOnError if the job fails or the timeout is reached.
+   */
+  async waitForResult(jobId: string, opts: WaitOptions = {}): Promise<string[]> {
+    const pollInterval = opts.pollIntervalMs ?? 2000;
+    const timeout = opts.timeoutMs ?? 120000;
+    const start = Date.now();
+    for (;;) {
+      const res = await this.getStatus(jobId);
+      if (res.status === "completed") return res.output ?? [];
+      if (res.status === "failed") {
+        throw new TryItOnError(res.error?.message ?? "Try-on failed.", {
+          errorName: res.error?.name ?? "ProcessingError",
+        });
+      }
+      if (Date.now() - start > timeout) {
+        throw new TryItOnError(`Timed out waiting for job ${jobId} after ${timeout}ms.`, { errorName: "Timeout" });
+      }
+      await sleep(pollInterval, opts.signal);
+    }
+  }
+
+  private async request<T>(method: "GET" | "POST", path: string, body?: unknown): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    let res: Response;
+    try {
+      res = await this.fetchImpl(url, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+        },
+        body: body !== undefined ? JSON.stringify(stripUndefined(body)) : undefined,
+        signal: controller.signal,
+      });
+    } catch (err) {
+      clearTimeout(timer);
+      if ((err as Error)?.name === "AbortError") {
+        throw new TryItOnError(`Request timed out after ${this.timeoutMs}ms.`, { errorName: "Timeout" });
+      }
+      throw new TryItOnError(`Network error: ${(err as Error)?.message ?? String(err)}`, { errorName: "NetworkError" });
+    } finally {
+      clearTimeout(timer);
+    }
+
+    const text = await res.text();
+    let data: any = {};
+    if (text) {
+      try {
+        data = JSON.parse(text);
+      } catch {
+        if (!res.ok) throw new TryItOnError(text || `HTTP ${res.status}`, { status: res.status });
+      }
+    }
+
+    if (!res.ok) {
+      throw new TryItOnError(data?.message ?? `HTTP ${res.status}`, {
+        status: res.status,
+        errorName: data?.error ?? null,
+      });
+    }
+
+    return data as T;
+  }
+}
+
+function stripUndefined(obj: unknown): unknown {
+  if (obj === null || typeof obj !== "object") return obj;
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj as Record<string, unknown>)) {
+    if (v !== undefined) out[k] = v;
+  }
+  return out;
+}
+
+export default TryItOn;