Typescript

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, 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

npm install @katla.app/sdk

Creating a client

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.

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.

await client.injectGuard();

onConsentChange

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

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:

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)
`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.

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

Next steps

Static cookies

Pre-fetch cookie data at build time to eliminate runtime requests.

React guide

Use the SDK with React hooks and components.

Next.js guide

Integrate the SDK in a Next.js App Router project.

Getting started

Guides

Reference

Compliance

Prerequisites

Installation

Creating a client

Client methods

getCookies

injectGuard

onConsentChange

Constants

COOKIE_CATEGORIES

Types

Caching

Next steps

Static cookies

React guide

Next.js guide

​Prerequisites

​Installation

​Creating a client

​Client methods

​getCookies

​injectGuard

​onConsentChange

​Constants

​COOKIE_CATEGORIES

​Types

​Caching

​Next steps

Static cookies

React guide

Next.js guide

Prerequisites

Installation

Creating a client

Client methods

getCookies

injectGuard

onConsentChange

Constants

COOKIE_CATEGORIES

Types

Caching

Next steps