# IMGDRIVE API (v2)

Base URL: **https://drive.suaads.com**

## Autenticação
- Header: `x-imgdrive-key`
- Variável sugerida: `IMGDRIVE_KEY`
- ⚠️ Nunca exponha a chave no front público. Use server-side (API/Server Actions).

## Variáveis de ambiente (exemplo)
```bash
END_POINT_DRIVE=https://drive.suaads.com
IMGDRIVE_KEY=******** (NÃO use NEXT_PUBLIC)
```

---

## Upload (Create/Update)
**POST** `https://drive.suaads.com/v2/projects/:project/upload`  
Content-Type: `multipart/form-data`

Campos:
- `file` (obrigatório)
- `scope` (opcional, default `global`) — ex: `loja_9a7f`
- `key` (recomendado) — ex: `products/sku123/front.jpg`

### Exemplo (curl)
```bash
curl -X POST "https://drive.suaads.com/v2/projects/suastore/upload" \
  -H "x-imgdrive-key: $IMGDRIVE_KEY" \
  -F "scope=loja_9a7f" \
  -F "key=products/sku123/front.jpg" \
  -F "file=@/caminho/front.jpg"
```

### Exemplo (Node/Next server-side)
```js
const fd = new FormData();
fd.append("file", fileBlobOrBuffer);
fd.append("scope", "loja_9a7f");
fd.append("key", "products/sku123/front.jpg");

const r = await fetch(`${process.env.END_POINT_DRIVE}/v2/projects/suastore/upload`, {
  method: "POST",
  headers: { "x-imgdrive-key": process.env.IMGDRIVE_KEY },
  body: fd,
});
const data = await r.json();
// data.url (com hash) e data.version (sha256)
```

✅ **Cache-busting garantido**: a URL muda quando a imagem muda (hash).

---

## Resolve (Read URL atual)
**GET** `https://drive.suaads.com/v2/projects/:project/resolve?scope=...&key=...`

```bash
curl "https://drive.suaads.com/v2/projects/suastore/resolve?scope=loja_9a7f&key=products%2Fsku123%2Ffront.jpg"
```

---

## Item (Read completo)
**GET** `https://drive.suaads.com/v2/projects/:project/item?scope=...&key=...`

Retorna metadados (bytes, mimetype, createdAt/updatedAt etc) — bom pra painel.

---

## List (Read lista paginada)
**GET** `https://drive.suaads.com/v2/projects/:project/list?scope=...&prefix=...&limit=50&cursor=0`

- `prefix`: filtra por “pasta lógica” (ex: `products/`)
- `cursor`: paginação (id)

---

## Rename (Update key)
**PATCH** `https://drive.suaads.com/v2/projects/:project/rename`  
Content-Type: `application/json`

```js
await fetch(`${process.env.END_POINT_DRIVE}/v2/projects/suastore/rename`, {
  method: "PATCH",
  headers: {
    "content-type": "application/json",
    "x-imgdrive-key": process.env.IMGDRIVE_KEY,
  },
  body: JSON.stringify({
    scope: "loja_9a7f",
    fromKey: "products/sku123/front.jpg",
    toKey: "products/sku123/1.jpg",
    overwrite: true
  }),
});
```

---

## Move Scope (Update scope)
**PATCH** `https://drive.suaads.com/v2/projects/:project/move-scope`  
Ex: quando `storeId` muda.

---

## Delete (Delete 1 item)
**DELETE** `https://drive.suaads.com/v2/projects/:project/item?scope=...&key=...`

Remove do DB e apaga o arquivo físico **somente se ficar sem referências**.

---

## Purge por prefix (Delete em lote)
**DELETE** `https://drive.suaads.com/v2/projects/:project/purge?scope=...&prefix=...&limit=200&cursor=0`

Repita usando `nextCursor` até vir `null`.

---

## Stats
**GET** `https://drive.suaads.com/v2/projects/:project/stats?scope=...&prefix=...`

Retorna `count` e `bytes` por scope/prefix.

---

## Stats by Scope (Admin)
**GET** `https://drive.suaads.com/v2/projects/:project/stats/by-scope?prefix=...&limit=50&cursor=`

---

## Scopes (Admin)
**GET** `https://drive.suaads.com/v2/projects/:project/scopes?limit=100&cursor=`

---

## GC de órfãos (Admin)
**POST** `https://drive.suaads.com/v2/projects/:project/gc/orphans`

> GC leve por shard: você informa `shardA` e `shardB` (ex: `ab` + `cd`)

```bash
curl -X POST "https://drive.suaads.com/v2/projects/suastore/gc/orphans" \
  -H "x-imgdrive-key: $IMGDRIVE_KEY" \
  -H "content-type: application/json" \
  -d '{"scope":"loja_9a7f","shardA":"ab","shardB":"cd","dryRun":true,"limit":500}'
```

---

## Static (CDN / Nginx)
As URLs retornadas em `data.url` apontam para:
`https://drive.suaads.com/static/<project>/<scope>/<ab>/<cd>/<sha256>.<ext>`

✅ Perfeito para Bunny CDN (Origin Pull) + cache `immutable`.