# API Reference

> Complete API reference for Zest cookie consent toolkit

Source: https://zest.freshjuice.dev/docs/api/

## Global Object

All Zest methods are available on the global `Zest` object.

## Initialization

### `Zest.init(config)`

Manually initialize Zest with a configuration object. Only needed if `autoInit` is set to `false`.

```javascript
Zest.init({
  position: 'bottom-right',
  theme: 'dark'
});
```

## UI Control

### `Zest.show()`

Show the consent banner.

```javascript
Zest.show();
```

### `Zest.hide()`

Hide the consent banner.

```javascript
Zest.hide();
```

### `Zest.showSettings()`

Open the settings modal where users can customize their preferences.

```javascript
Zest.showSettings();
```

### `Zest.hideSettings()`

Close the settings modal.

```javascript
Zest.hideSettings();
```

### `Zest.reset()`

Clear all consent data and show the banner again. Useful for "reset preferences" buttons.

```javascript
Zest.reset();
```

## Consent Management

### `Zest.getConsent()`

Get the current consent state for all categories.

```javascript
const consent = Zest.getConsent();
// Returns: { essential: true, functional: false, analytics: false, marketing: false }
```

### `Zest.hasConsent(category)`

Check if a specific category has consent.

```javascript
if (Zest.hasConsent('analytics')) {
  // Initialize analytics tracking
  initAnalytics();
}
```

### `Zest.hasConsentDecision()`

Check if the user has made any consent decision (accept or reject).

```javascript
if (!Zest.hasConsentDecision()) {
  // User hasn't decided yet
  console.log('Waiting for consent...');
}
```

### `Zest.acceptAll()`

Programmatically accept all consent categories.

```javascript
Zest.acceptAll();
```

### `Zest.rejectAll()`

Programmatically reject all non-essential categories.

```javascript
Zest.rejectAll();
```

### `Zest.getConsentProof()`

Get consent proof data for compliance records.

```javascript
const proof = Zest.getConsentProof();
// Returns: {
//   version: "1.0",
//   timestamp: 1234567890,
//   categories: { essential: true, ... }
// }
```

### `Zest.updateConsent(selections)`

_Since v2.0.0._

Save an arbitrary set of category selections. Useful when building a custom UI (especially with the [headless entry](/docs/getting-started/#npm-headless-bring-your-own-ui)) — pass the checkbox state from your own form.

```javascript
Zest.updateConsent({
  analytics: true,
  marketing: false,
  functional: true
});
```

Categories you don't include keep their previous state. Unknown keys are ignored. The cookie is written and the usual `zest:change` / `zest:consent` events are dispatched.

## Privacy Detection

### `Zest.isDoNotTrackEnabled()`

Check if Do Not Track (DNT) or Global Privacy Control (GPC) is enabled.

```javascript
if (Zest.isDoNotTrackEnabled()) {
  console.log('User has privacy signals enabled');
}
```

### `Zest.getDNTDetails()`

Get details about which privacy signal is enabled.

```javascript
const dnt = Zest.getDNTDetails();
// Returns: { enabled: true, source: 'gpc' }
// source can be: 'dnt', 'gpc', or null
```

## Configuration

### `Zest.getConfig()`

Get the current Zest configuration.

```javascript
const config = Zest.getConfig();
console.log(config.position); // 'bottom-right'
```

## Events

### `Zest.on(event, callback)`

_Since v2.0.0._

Subscribe to a Zest event. Returns an **unsubscribe** function.

```javascript
const unsubscribe = Zest.on('consent', (consent) => {
  if (consent.analytics) initAnalytics();
});

// Later — stop listening
unsubscribe();
```

The event name can be passed with or without the `zest:` prefix (`'consent'` and `'zest:consent'` are equivalent). Use `Zest.EVENTS` for constants.

### `Zest.once(event, callback)`

_Since v2.0.0._

Same as `Zest.on()`, but the callback fires at most once and then auto-unsubscribes.

```javascript
Zest.once('ready', (consent) => {
  console.log('Zest is ready with:', consent);
});
```

### `Zest.EVENTS`

Object containing all event names for reference.

```javascript
console.log(Zest.EVENTS);
// {
//   READY: 'zest:ready',
//   CONSENT: 'zest:consent',
//   REJECT: 'zest:reject',
//   CHANGE: 'zest:change',
//   SHOW: 'zest:show',
//   HIDE: 'zest:hide'
// }

// Use constants with on()/once()
Zest.on(Zest.EVENTS.CHANGE, handleChange);
```

## Practical Examples

### Conditional Script Loading

```javascript
document.addEventListener('zest:consent', (e) => {
  if (e.detail.consent.analytics) {
    // Load Google Analytics
    const script = document.createElement('script');
    script.src = 'https://www.googletagmanager.com/gtag/js?id=GA-XXXXX';
    document.head.appendChild(script);
  }
});
```

### Cookie Preferences Button

```html
<button onclick="Zest.showSettings()">Cookie Preferences</button>
```

### Reset Consent Link

```html
<a href="#" onclick="Zest.reset(); return false;">Reset Cookie Settings</a>
```

### Check Before Tracking

```javascript
function trackEvent(name, data) {
  if (Zest.hasConsent('analytics')) {
    gtag('event', name, data);
  }
}
```

### Wait for Consent

```javascript
async function waitForAnalyticsConsent() {
  return new Promise((resolve) => {
    if (Zest.hasConsent('analytics')) {
      resolve(true);
      return;
    }

    document.addEventListener('zest:consent', (e) => {
      if (e.detail.consent.analytics) {
        resolve(true);
      }
    });

    document.addEventListener('zest:reject', () => {
      resolve(false);
    });
  });
}

// Usage
const hasAnalytics = await waitForAnalyticsConsent();
if (hasAnalytics) {
  initAnalytics();
}
```