# Purge

O módulo `azion/purge` é a biblioteca da Azion Lib do [Real-Time Purge](/pt-br/documentacao/plataforma/applications/cache/real-time-purge/). As funções dele removem URLs, cache keys e expressões wildcard do cache pela Azion API v4, de modo que a requisição seguinte busca a versão atual na origem. Cada função recebe uma lista de strings e retorna um envelope de resposta em vez de lançar uma exceção.

Instale o pacote:

```bash
npm install azion
```

O pacote `azion` recebe apenas correções de bugs, e a manutenção dele termina em dezembro de 2026.

Todos os exemplos abaixo são módulos ES em TypeScript com `await` de nível superior, executados no Node.js. Os tipos entram por `import type`, então o exemplo ainda carrega depois que as anotações de tipo são removidas.

---

## Autenticação

Cada requisição de purge carrega o seu [personal token](/pt-br/documentacao/fundamentos/personal-tokens/). As funções leem o token da variável de ambiente `AZION_TOKEN`, e um cliente criado com [createClient](#createclient) lê o token do campo `token`.

| Variável      | Descrição                          |
| ------------- | ---------------------------------- |
| `AZION_TOKEN` | Seu personal token da Azion.       |
| `AZION_DEBUG` | Com `true`, ativa o modo de debug. |

Para ver onde cada pacote da Azion Lib procura esses valores, consulte [Como a Azion Lib funciona](/pt-br/documentacao/devtools/azion-lib/como-funciona/).

---

## Envelope de resposta

Toda função retorna um objeto [AzionPurgeResponse](#azionpurgeresponse), `{ data?, error? }`. Em caso de sucesso, `data` contém um objeto [AzionPurge](#azionpurge): `items`, a lista que o purge recebeu, e `state`. Em caso de falha, `error` contém `{ message, operation }`, e `operation` é `post purge`.

Cada função envia uma requisição para a Azion API v4. A API responde com os itens e a camada que purgou, e o envelope mantém apenas `items` e `state`:

| Função                          | Requisição da API                   | Argumento                        |
| ------------------------------- | ----------------------------------- | -------------------------------- |
| [purgeURL](#purgeurl)           | `POST /v4/workspace/purge/url`      | Uma lista de URLs                |
| [purgeCacheKey](#purgecachekey) | `POST /v4/workspace/purge/cachekey` | Uma lista de cache keys          |
| [purgeWildCard](#purgewildcard) | `POST /v4/workspace/purge/wildcard` | Uma lista de expressões wildcard |

As funções não recebem argumento de camada, e a API informa `layer: 'cache'` na resposta. Para as camadas e o número de itens que cada tipo de purge aceita, consulte [Real-Time Purge](/pt-br/documentacao/plataforma/applications/cache/real-time-purge/#tipos-de-purge).

---

## createClient

Cria um cliente que guarda um token e expõe as três funções de purge como métodos.

```typescript
function createClient(config?: Partial<{
  token: string;
  options?: AzionClientOptions;
}>): AzionPurgeClient;
```

| Parâmetro | Tipo                                        | Obrigatório | Descrição                    |
| --------- | ------------------------------------------- | ----------- | ---------------------------- |
| `token`   | `string`                                    | Não         | Seu personal token da Azion. |
| `options` | [`AzionClientOptions`](#azionclientoptions) | Não         | Opções do cliente.           |

Retorna um [AzionPurgeClient](#azionpurgeclient). Os métodos dele recebem a mesma lista que a função correspondente desta página, sem `options`. Para registrar no log a resposta que a API retorna, passe `{ debug: true }` para uma função, como faz o exemplo de [purgeURL](#purgeurl).

Este exemplo cria um cliente e purga uma URL com ele:

```typescript
import { createClient } from 'azion/purge';
import type { AzionPurgeClient, AzionPurgeResponse, AzionPurge } from 'azion/purge';

const client: AzionPurgeClient = createClient({ token: process.env.AZION_TOKEN, options: { debug: true } });

const { data: purgeURLResponse, error }: AzionPurgeResponse<AzionPurge> = await client.purgeURL([
  'http://www.example.com/image.jpg',
]);
if (purgeURLResponse) {
  console.log('Purge successful:', purgeURLResponse);
} else {
  console.error('Purge failed', error);
}
```

Saída:

```text
Purge successful: {
  items: [ 'http://www.example.com/image.jpg' ],
  state: 'executed'
}
```

---

## purgeURL

Purga uma lista de URLs do cache. Apenas as URLs da lista saem do cache.

```typescript
function purgeURL(url: string[], options?: AzionClientOptions): Promise<AzionPurgeResponse<AzionPurge>>;
```

| Parâmetro | Tipo                                        | Obrigatório | Descrição                                                                                       |
| --------- | ------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------- |
| `url`     | `string[]`                                  | Sim         | As URLs a purgar.                                                                               |
| `options` | [`AzionClientOptions`](#azionclientoptions) | Não         | Opções da requisição. Com `debug: true`, a função registra no log a resposta que a API retorna. |

Retorna `data` como um objeto [AzionPurge](#azionpurge) com as URLs purgadas em `items`. Uma URL cujo host não pertence a nenhum domínio da sua conta retorna `error`; a mensagem está em [Erros](#erros).

Este exemplo purga uma URL no modo de debug, então a saída começa com a resposta da API:

```typescript
import { purgeURL } from 'azion/purge';
import type { AzionPurgeResponse, AzionPurge } from 'azion/purge';

const url: string[] = ['http://www.example.com/image.jpg'];
const { data: response, error }: AzionPurgeResponse<AzionPurge> = await purgeURL(url, { debug: true });
if (response) {
  console.log('Purge successful:', response);
} else {
  console.error('Purge failed', error);
}
```

Saída:

```text
Response: {
  state: 'executed',
  data: {
    items: [ 'http://www.example.com/image.jpg' ],
    layer: 'cache'
  }
}
Purge successful: {
  items: [ 'http://www.example.com/image.jpg' ],
  state: 'executed'
}
```

---

## purgeCacheKey

Purga uma lista de cache keys do cache. Uma cache key nomeia uma variação de um objeto em cache.

```typescript
function purgeCacheKey(cacheKey: string[], options?: AzionClientOptions): Promise<AzionPurgeResponse<AzionPurge>>;
```

| Parâmetro  | Tipo                                        | Obrigatório | Descrição                                                                                       |
| ---------- | ------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------- |
| `cacheKey` | `string[]`                                  | Sim         | As cache keys a purgar, sem scheme.                                                             |
| `options`  | [`AzionClientOptions`](#azionclientoptions) | Não         | Opções da requisição. Com `debug: true`, a função registra no log a resposta que a API retorna. |

Retorna `data` como um objeto [AzionPurge](#azionpurge) com as keys purgadas em `items`. Uma key não leva scheme: a forma `host/path` é aceita, e uma key que começa com um scheme, como `http://`, é recusada com `error`. Para o formato de uma key, consulte [Cache keys](/pt-br/documentacao/plataforma/applications/cache/cache-keys/).

Este exemplo purga uma cache key no modo de debug:

```typescript
import { purgeCacheKey } from 'azion/purge';
import type { AzionPurgeResponse, AzionPurge } from 'azion/purge';

const cacheKey: string[] = ['www.example.com/image.jpg'];
const { data: response, error }: AzionPurgeResponse<AzionPurge> = await purgeCacheKey(cacheKey, { debug: true });
if (response) {
  console.log('Purge successful:', response);
} else {
  console.error('Purge failed', error);
}
```

Saída:

```text
Response: {
  state: 'executed',
  data: {
    items: [ 'www.example.com/image.jpg' ],
    layer: 'cache'
  }
}
Purge successful: {
  items: [ 'www.example.com/image.jpg' ],
  state: 'executed'
}
```

---

## purgeWildCard

Purga os objetos em cache que casam com uma expressão wildcard: uma URL com um asterisco (`*`) no path ou na query string.

```typescript
function purgeWildCard(wildcard: string[], options?: AzionClientOptions): Promise<AzionPurgeResponse<AzionPurge>>;
```

| Parâmetro  | Tipo                                        | Obrigatório | Descrição                                                                                       |
| ---------- | ------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------- |
| `wildcard` | `string[]`                                  | Sim         | As expressões wildcard a purgar.                                                                |
| `options`  | [`AzionClientOptions`](#azionclientoptions) | Não         | Opções da requisição. Com `debug: true`, a função registra no log a resposta que a API retorna. |

Retorna `data` como um objeto [AzionPurge](#azionpurge) com a expressão em `items`. O tipo recebe uma lista, e o Real-Time Purge aceita uma expressão wildcard por requisição. Para as expressões que ele aceita, consulte [Purge por wildcard](/pt-br/documentacao/plataforma/applications/cache/real-time-purge/#purge-por-wildcard).

Este exemplo purga todos os objetos em cache sob um prefixo de path:

```typescript
import { purgeWildCard } from 'azion/purge';
import type { AzionPurgeResponse, AzionPurge } from 'azion/purge';

const wildcard: string[] = ['http://www.example.com/images/*'];
const { data: response, error }: AzionPurgeResponse<AzionPurge> = await purgeWildCard(wildcard, { debug: true });
if (response) {
  console.log('Purge successful:', response);
} else {
  console.error('Purge failed', error);
}
```

Saída:

```text
Response: {
  state: 'executed',
  data: {
    items: [ 'http://www.example.com/images/*' ],
    layer: 'cache'
  }
}
Purge successful: {
  items: [ 'http://www.example.com/images/*' ],
  state: 'executed'
}
```

---

## Erros

Um purge recusado retorna `error` apenas com o status HTTP. O motivo que a API informa, como `The Content must be a valid cachekey.`, não chega ao envelope. `error.operation` é `post purge` em todas as funções.

| Mensagem                                       | Causa                                                                                            | O que fazer                                     |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------- |
| `Error: HTTP error! Status: 400 - Bad Request` | Uma cache key passada para [purgeCacheKey](#purgecachekey) começa com um scheme, como `http://`. | Passe a key sem o scheme, na forma `host/path`. |
| `Error: HTTP error! Status: 400 - Bad Request` | O host de uma URL passada para [purgeURL](#purgeurl) não pertence a nenhum domínio da sua conta. | Purgue uma URL de um domínio da sua conta.      |

Para os códigos de erro que a API retorna em cada tipo de purge, consulte [Real-Time Purge](/pt-br/documentacao/plataforma/applications/cache/real-time-purge/#erros).

---

## Tipos

O módulo `azion/purge` exporta estes tipos. Importe-os com `import type`.

### AzionPurgeClient

O objeto que [createClient](#createclient) retorna, com um método por tipo de purge. Cada método recebe uma lista.

| Método          | Argumento             | Retorno                                   |
| --------------- | --------------------- | ----------------------------------------- |
| `purgeURL`      | `urls: string[]`      | `Promise<AzionPurgeResponse<AzionPurge>>` |
| `purgeCacheKey` | `cacheKeys: string[]` | `Promise<AzionPurgeResponse<AzionPurge>>` |
| `purgeWildCard` | `wildcards: string[]` | `Promise<AzionPurgeResponse<AzionPurge>>` |

### CreateAzionPurgeClient

O tipo de [createClient](#createclient).

```typescript
type CreateAzionPurgeClient = (config?: Partial<{
  token: string;
  options?: AzionClientOptions;
}>) => AzionPurgeClient;
```

### AzionClientOptions

Opções de requisição que toda função recebe em `options`.

| Propriedade | Tipo      | Obrigatório | Descrição                                                                     |
| ----------- | --------- | ----------- | ----------------------------------------------------------------------------- |
| `debug`     | `boolean` | Não         | Registra no log a resposta que a API retorna, quando passado para uma função. |
| `force`     | `boolean` | Não         | —                                                                             |

### AzionPurgeResponse

O objeto que cada função de purge retorna. [Envelope de resposta](#envelope-de-resposta) descreve as formas de sucesso e de falha.

| Propriedade | Tipo                                     | Obrigatório | Descrição                                                                        |
| ----------- | ---------------------------------------- | ----------- | -------------------------------------------------------------------------------- |
| `data`      | `T`                                      | Não         | O resultado do purge, definido em caso de sucesso.                               |
| `error`     | `{ message: string; operation: string }` | Não         | A mensagem de falha e o nome da operação que falhou, definidos em caso de falha. |

### AzionPurge

O resultado de um purge.

| Propriedade | Tipo                      | Obrigatório | Descrição                                                       |
| ----------- | ------------------------- | ----------- | --------------------------------------------------------------- |
| `state`     | `'executed' \| 'pending'` | Sim         | O estado da requisição de purge.                                |
| `items`     | `string[]`                | Sim         | As URLs, cache keys ou expressões wildcard que o purge recebeu. |

---

## Recursos relacionados

- [Azion Lib](/pt-br/documentacao/devtools/azion-lib.md): Todas as bibliotecas da Azion Lib, com o pacote npm a instalar para cada uma.
- [Client](/pt-br/documentacao/devtools/azion-lib/client.md): Um único cliente que alcança as funções de purge junto com os módulos dos outros produtos.
- [Real-Time Purge](/pt-br/documentacao/plataforma/applications/cache/real-time-purge.md): Tipos de purge, camadas, limites de requisição e os erros que a API de purge retorna.
- [Cache keys](/pt-br/documentacao/plataforma/applications/cache/cache-keys.md): Como a Azion monta a cache key que um purge por cache key atinge.