> ## Documentation Index
> Fetch the complete documentation index at: https://docs.katla.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Typescript

> Build custom consent integrations with the Katla SDK.

The `@katla.app/sdk` package gives you programmatic access to your site's cookie data and consent state. Use it to build custom consent UIs instead of the default [widget](/widget), or to integrate cookie data into your application.

## Prerequisites

* A Katla account with a verified site
* At least one completed scan
* Node.js 18+

## Installation

```bash theme={null}
npm install @katla.app/sdk
```

## Creating a client

```typescript theme={null}
import { createKatlaClient } from '@katla.app/sdk';

const client = createKatlaClient({
  siteId: 'your-site-id',
});
```

| Option    | Type     | Default                  | Description                 |
| --------- | -------- | ------------------------ | --------------------------- |
| `siteId`  | `string` | —                        | Your site's UUID (required) |
| `baseUrl` | `string` | `https://dist.katla.app` | Override the CDN base URL   |

## Client methods

| Method                      | Returns               | Description                                                 |
| --------------------------- | --------------------- | ----------------------------------------------------------- |
| `getCookies()`              | `Promise<CookieData>` | Fetch all cookies grouped by category                       |
| `getManifest()`             | `Promise<Manifest>`   | Fetch the site manifest with resource URLs                  |
| `getGuardScript()`          | `Promise<string>`     | Fetch the guard script source as a string                   |
| `injectGuard()`             | `Promise<void>`       | Inject the guard script into the current page               |
| `onConsentChange(callback)` | `() => void`          | Listen for consent changes; returns an unsubscribe function |

### getCookies

Returns cookie data for your site, grouped by category.

```typescript theme={null}
const data = await client.getCookies();

for (const [category, cookies] of Object.entries(data.cookies)) {
  console.log(`${category}: ${cookies.length} cookies`);
}
```

### injectGuard

Injects the cookie guard script into the page. The guard intercepts `document.cookie` writes and blocks non-consented cookies.

```typescript theme={null}
await client.injectGuard();
```

### onConsentChange

Subscribes to consent state changes. The callback fires whenever the visitor updates their preferences.

```typescript theme={null}
const unsubscribe = client.onConsentChange((consent) => {
  console.log('analytics allowed:', consent.analytics);
});

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

## Constants

### COOKIE\_CATEGORIES

An array of all cookie category strings:

```typescript theme={null}
import { COOKIE_CATEGORIES } from '@katla.app/sdk';
// ['functional', 'personalization', 'analytics', 'marketing', 'security', 'unknown']
```

## Types

| Type                    | Description                                                                                         |
| ----------------------- | --------------------------------------------------------------------------------------------------- |
| `KatlaClient`           | Client instance returned by `createKatlaClient`                                                     |
| `KatlaClientOptions`    | Options for `createKatlaClient`                                                                     |
| `CookieData`            | Cookie data response with `site`, `cookies`, and `jsUrl`                                            |
| `CookieInfo`            | Individual cookie with `name`, `domain`, `platform`, `description`, etc.                            |
| `CookieCategory`        | `'functional' \| 'personalization' \| 'analytics' \| 'marketing' \| 'security' \| 'unknown'`        |
| `ConsentState`          | `Record<CookieCategory, boolean>` — consent per category                                            |
| `ConsentChangeCallback` | `(consent: ConsentState) => void`                                                                   |
| `Manifest`              | Site manifest with `site` and `resources` URLs                                                      |
| `KatlaConsentAPI`       | The `window.KatlaConsent` API shape (see [JavaScript API](/javascript-api))                         |
| `ConsentManagerState`   | Return type of the `useConsentManager()` hook                                                       |
| `ManageableCategory`    | `'personalization' \| 'analytics' \| 'marketing' \| 'security'` — categories the visitor can toggle |
| `CookieBannerProps`     | Props for the `<CookieBanner>` component                                                            |
| `CookieCatalogProps`    | Props for the `<CookieCatalog>` component                                                           |

## Caching

Even without static cookies, the SDK caches intelligently:

* **Client-side (React):** `getCookies()` deduplicates in-flight requests. Multiple components mounting simultaneously share a single fetch.
* **Server-side (Next.js):** Use `getCachedCookies()` from `@katla.app/sdk/next/server` — it wraps React's `cache()` to deduplicate across Server Components in the same render pass.

```tsx theme={null}
// Server Component — cached and deduplicated
import { getCachedCookies } from '@katla.app/sdk/next/server';
const cookies = await getCachedCookies({ siteId: 'your-site-id' });
```

## Next steps

<CardGroup cols={2}>
  <Card title="Static cookies" icon="database" href="/sdk-static-cookies">
    Pre-fetch cookie data at build time to eliminate runtime requests.
  </Card>

  <Card title="React guide" icon="atom" href="/react">
    Use the SDK with React hooks and components.
  </Card>

  <Card title="Next.js guide" icon="globe" href="/nextjs">
    Integrate the SDK in a Next.js App Router project.
  </Card>
</CardGroup>