# Azion `Domains` library

import DocButton from '~/components/webkit/DocButton.vue';

Azion **Domains** library provides a simple interface to interact with the **Edge Domains** API, allowing you to create, list, get, update, and delete domains.

<DocButton href="/en/documentation/products/azion-lib/overview/" label="Go to Azion Libraries Overview" kind="secondary" size="medium" />

You can interact with the API using a `client` or calling the methods directly from the library. When making direct calls, you can use the environment variables to configure the `client` without passing the token and debug parameters directly.

This is an example of how a `.env` file with your environment variables may look like:

```sh
AZION_TOKEN=<your-api-token>
AZION_DEBUG=true
```

| Variable | Description |
|----------|-------------|
| `AZION_TOKEN` | Your Azion API token. |
| `AZION_DEBUG` | Enable debug mode (true/false). |

:::tip
Setting `AZION_DEBUG` to `true` enables **Debug mode**. This mode provides detailed logging of the API requests and responses.
:::

If you want to create a specific `client` for interacting with **Domains**, create one by calling the `createClient` method from the library:

```typescript
import { createClient } from 'azion/domains';
import type { AzionDomain, AzionDomainsClient } from 'azion/domains';

const client: AzionDomainsClient = createClient({ token: 'your-api-token', { debug: true } });

const { data: newDomain, error }: AzionDomainsResponse<AzionDomain> = await client.createDomain({ name: 'example domain', edgeApplicationId: 123 });
if (newDomain) {
  console.log(`Domain created with ID: ${newDomain.id}`);
}
```

The `createClient` method has the following **parameters** and **return value**:

**Parameters**:

| Parameter | Type | Description |
|-----------|------|-------------|
| `config` | `Partial<{ token: string; options?: OptionsParams }>` | Configuration options for the Domain client. |

**Returns**:

| Return Type | Description |
|-------------|-------------|
| `AzionDomainsClient` | An object with methods to interact with Domains. |

:::note
In the following examples, the methods are called directly without the creation of a `client`. For more information on how to interact with services and products using a `client`, check the [Azion Lib Client documentation](/en/documentation/products/azion-lib/client/).
:::

---

## Usage

### `createDomain`

This method creates a new domain. For example:

```typescript
import { createDomain } from 'azion/domains';
import type { AzionDomain, AzionDomainsResponse } from 'azion/domains';

const { data: domain, error }: AzionDomainsResponse<AzionDomain> = await createDomain({
  name: 'example domain',
  edgeApplicationId: 123,
});
if (domain) {
  console.log(`Domain created with ID: ${domain.id}`);
} else {
  console.error('Failed to create domain', error);
}
```

**Parameters**:

| Parameter | Type | Description |
|-----------|------|-------------|
| `domain` | `AzionCreateDomain` | The domain object containing domain configuration. |
| `options` | `{ debug?: boolean }` | Optional. The object containing a debug flag to enable detailed logging. |

**Returns**:

| Return Type | Description |
|-------------|-------------|
| `Promise<AzionDomainsResponse<AzionDomain>>` | The created domain object or error if failed. |

### `getDomains`

This method lists all domains. Example:

```typescript
import { getDomains } from 'azion/domains';
import type { AzionDomainCollection, AzionDomainsResponse } from 'azion/domains';

const { data: domains, error }: AzionDomainsResponse<AzionDomainCollection> = await getDomains();

if (domains) {
  console.log(`Found ${domains.count} domains`);
} else {
  console.error('Failed to list domains', error);
}
```

**Parameters**:

| Parameter | Type | Description |
|-----------|------|-------------|
| `options` | `{ debug?: boolean }` | Optional. The object containing a debug flag to enable detailed logging. |
| `queryParams` | `{ pageSize?: number; page?: number; order?: 'id' \| 'name'; sort?: 'asc' \| 'desc' }` | Optional. Query parameters for pagination and sorting. |

**Returns**:

| Return Type | Description |
|-------------|-------------|
| `Promise<AzionDomainsResponse<AzionDomainCollection>>` | An array of domain objects or error if failed. |

### `getDomain`

Use this method to get a domain by its ID.

```typescript
import { getDomain } from 'azion/domains';
import type { AzionDomain, AzionDomainsResponse } from 'azion/domains';

const domainId = 123;
const { data: domain, error }: AzionDomainsResponse<AzionDomain> = await getDomain(domainId);

if (domain) {
  console.log(`Found domain with name: ${domain.name}`);
} else {
  console.error('Failed to get domain', error);
}
```

**Parameters**:

| Parameter | Type | Description |
|-----------|------|-------------|
| `domainId` | `number` | The domain ID. |
| `options` | `{ debug?: boolean }` | Optional. The object containing a debug flag to enable detailed logging. |

### `updateDomain`

This method updates a domain.

```typescript
import { updateDomain } from 'azion/domains';
import type { AzionDomain, AzionDomainsResponse } from 'azion/domains';

const domainId = 123;
const { data: domain, error }: AzionDomainsResponse<AzionDomain> = await updateDomain(domainId, {
  name: 'new domain name',
  edgeApplicationId: 456,
});

if (domain) {
  console.log(`Updated domain with name: ${domain.name}`);
} else {
  console.error('Failed to update domain', error);
}
```

**Parameters**:

| Parameter | Type | Description |
|-----------|------|-------------|
| `domainId` | `number` | The domain ID. |
| `domain` | `AzionUpdateDomain` | The domain object to update. |
| `options` | `{ debug?: boolean }` | Optional. The object containing a debug flag to enable detailed logging. |

**Returns**:

| Type | Description |
|------|-------------|
| `Promise<AzionDomainsResponse<AzionDomain>>` | The updated domain object or state failed. |

### `deleteDomain`

This method deletes a domain specified by its ID.

```typescript
import { deleteDomain } from 'azion/domains';
import type { AzionDomain, AzionDomainsResponse } from 'azion/domains';

const domainId = 123;
const { data: deletedDomain, error }: AzionDomainsResponse<AzionDomain> = await deleteDomain(domainId);

if (deletedDomain) {
  console.log(`Deleted domain with ID: ${deletedDomain.id}`);
} else {
  console.error('Failed to delete domain', error);
}
```

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `domainId` | `number` | The domain ID. |
| `options` | `{ debug?: boolean }` | Optional. The object containing a debug flag to enable detailed logging. |

**Returns**:

| Type | Description |
|------|-------------|
| `Promise<AzionDomainsResponse<AzionDeletedDomain>>` | The deleted domain id or state failed. |

## Types

If you're using **TypeScript**, you'll need to import and use the appropriate types for the parameters and return values. Here you can see a list of all the types used by the **Domains** library:

### `AzionDomainsClient`

Configuration options for the Azion Domains client.

| Parameter | Type | Description |
|-----------|------|-------------|
| `token` | `string` | Optional. Your Azion API token. |
| `options` | `OptionsParams` | Optional. Object options params. |
| `debug` | `boolean` | Optional. Enable debug mode for detailed logging. |

### `AzionDomainsResponse<T>`

Generic response type returned by all **Domains** methods.

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | `T` | Optional. The response data. |
| `error` | `{ message: string; operation: string; }` | Optional. The error object. |

### `AzionDomain`

Represents a domain configuration with its properties.

| Parameter | Type | Description |
|-----------|------|-------------|
| `state` | `'pending' \| 'executed' \| 'failed'` | The state of the domain. |
| `id` | `number` | Optional. The domain ID. |
| `name` | `string` | The domain name. |
| `url` | `string` | Optional. The domain URL. |
| `environment` | `string` | Optional. The domain environment. |
| `edgeApplicationId` | `number` | The application ID. |
| `active` | `boolean` | The domain status. |
| `cnameAccessOnly` | `boolean` | Optional. CNAME access only. |
| `cnames` | `string[]` | List of CNAMEs. |
| `edgeFirewallId` | `number` | Optional. The firewall ID. |
| `digitalCertificateId` | `number \| string \| null` | the digital certificate ID. |
| `mtls` | `object \| null` | Optional. Mutual TLS configuration. |
| `mtls.verification` | `string` | Verification method: enforce or permissive. |
| `mtls.trustedCaCertificateId` | `number` | The trusted CA certificate ID. |
| `mtls.crlList` | `number[]` | The list of CRL IDs. |

### `AzionDomainCollection`

Represents a collection of domains with their current state and pagination details.

| Parameter | Type | Description |
|-----------|------|-------------|
| `state` | `'pending' \| 'executed' \| 'failed'` | The state of the domain list. |
| `pages` | `number` | Number of pages. |
| `count` | `number` | Number of domains. |
| `results` | `AzionDomain[]` | Array of domain objects. |

### `AzionDeleteDomain`

Represents the parameters required to delete a domain.

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | `number` | The domain ID. |
| `state` | `'pending' \| 'executed' \| 'failed'` | The state of the domain deletion. |