# SDK JavaScript/TypeScript

Un petit client sans dépendance, entièrement typé en TypeScript. Fonctionne avec Node 18+, Deno, Bun et les runtimes edge. **Côté serveur uniquement.**

## Installation

Le paquet est en cours de préparation pour npm. En attendant, téléchargez le fichier unique dans votre projet :

```bash
curl -o tryoncloud.mjs https://www.tryoncloud.com/sdk/tryoncloud.mjs
```

> **Astuce :** un simple `fetch` fonctionne tout aussi bien. Le SDK vous évite seulement de construire le formulaire, d'analyser les erreurs et de lire les en-têtes. Voir [Générer un essai](/docs/generate).

## Utilisation

```js
import { readFile, writeFile } from "node:fs/promises"
import { TryOnCloud, TryOnCloudError } from "./tryoncloud.mjs"

const client = new TryOnCloud() // reads TRYONCLOUD_API_KEY

try {
  const result = await client.generate({
    garment: { url: "https://cdn.yourstore.com/shirt.jpg" },
    person: { data: await readFile("person.jpg"), filename: "person.jpg" },
    customerId: "shopper_123",          // optional, your own end-user id
    idempotencyKey: crypto.randomUUID(), // optional, a retry is never charged twice
  })
  await writeFile("result.png", result.image)
  console.log("free credit?", result.creditWasFree, "request", result.requestId)
} catch (e) {
  if (e instanceof TryOnCloudError && e.code === "NO_CREDITS") {
    console.log("Out of credits, top up in the dashboard")
  } else if (e instanceof TryOnCloudError && e.code === "KEY_LIMIT_REACHED") {
    console.log("This key used its monthly limit", e.details) // { used, limit }
  } else throw e
}
```

## API

| Méthode | Renvoie | Endpoint |
|---|---|---|
| `new TryOnCloud({ apiKey?, baseUrl?, timeoutMs? })` | client |  |
| `generate({ garment, person, mock?, customerId?, idempotencyKey? })` | `{ image, contentType, resultId, creditWasFree, mock, requestId }` | `POST /generate` |
| `createGeneration({ garment, person, mock?, customerId?, metadata?, webhookUrl?, idempotencyKey? })` | la tâche (`status: "queued"`) | `POST /generations` |
| `getGeneration(id)` | la tâche | `GET /generations/:id` |
| `waitForGeneration(id, { intervalMs?, timeoutMs? })` | la tâche terminée (interrogation) | `GET /generations/:id` |
| `createBatch({ items, webhookUrl?, mock? })` | le lot | `POST /batches` |
| `getBatch(id)` | le lot avec chaque élément | `GET /batches/:id` |
| `cancelBatch(id)` | le lot, avec `cancelled_now` et `refunded_credits` | `DELETE /batches/:id` |
| `getResult(resultId)` | les octets de l'image | `GET /results/:id` |
| `deleteResult(resultId)` | rien | `DELETE /results/:id` |
| `deleteCustomer(customerId)` | `{ results_deleted, records_cleared, webhook_events_deleted }` | `DELETE /customers/:id` |
| `credits()` | `{ credits_remaining, purchased_remaining, purchased_total, free_remaining, spends_from }` | `GET /credits` |
| `TryOnCloud.verifyWebhook(rawBody, headers, secret)` | `true` ou `false` |  |

Images en entrée :

- `{ url }` : une URL d'image https publique (le vêtement, ou la personne dans `createGeneration`)
- `{ base64 }` : une chaîne base64
- `{ data, filename? }` : un `Blob`, `ArrayBuffer`, `Uint8Array` ou un `Buffer` Node

Les erreurs sont levées sous forme de `TryOnCloudError`, avec `status`, `code` (voir [Erreurs](/docs/errors)), `requestId`, `details` (champs supplémentaires comme `used` et `limit`) et `retryAfter` en cas de `429`.

## Tâches asynchrones et lots

```js
// One async try-on, result fetched when ready
const job = await client.createGeneration({ garment, person, customerId: "shopper_123" })
const done = await client.waitForGeneration(job.id) // or receive a webhook instead
if (done.status === "completed") await writeFile("look.png", await client.getResult(done.result_id))

// A catalogue batch, notified by webhook
const batch = await client.createBatch({
  items: skus.map((s) => ({ garment_url: s.imageUrl, person_url: modelUrl, customer_id: s.sku })),
  webhookUrl: "https://example.com/hooks/tryoncloud",
})
```

Voir [Tâches asynchrones, lots et webhooks](/docs/async) pour les limites et les événements.

## Vérifier les webhooks

Passez le corps brut de la requête, les en-têtes et votre secret de signature (**API Keys > Webhooks**) :

```js
// Next.js route handler
export async function POST(request) {
  const raw = await request.text()
  if (!(await TryOnCloud.verifyWebhook(raw, request.headers, process.env.TRYONCLOUD_WEBHOOK_SECRET))) {
    return new Response("bad signature", { status: 401 })
  }
  const { event, data } = JSON.parse(raw)
  // event: generation.completed | generation.failed | batch.completed | webhook.test
  return new Response("ok")
}
```

Les livraisons de plus de 5 minutes sont rejetées, donc une livraison interceptée ne peut pas être rejouée.

## Mode test

```js
const preview = await client.generate({ garment, person, mock: true }) // free, returns the person image
const testJob = await client.createGeneration({ garment, person, mock: true }) // free, completes without a render
```
