Skip to main content
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',
});
OptionTypeDefaultDescription
siteIdstring—Your site’s UUID (required)
baseUrlstringhttps://dist.katla.appOverride the CDN base URL

​
Client methods

MethodReturnsDescription
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)() => voidListen 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

An array of all cookie category strings: 
import { COOKIE_CATEGORIES } from '@katla.app/sdk';
// ['functional', 'personalization', 'analytics', 'marketing', 'security', 'unknown']

​
Types

TypeDescription
KatlaClientClient instance returned by createKatlaClient
KatlaClientOptionsOptions for createKatlaClient
CookieDataCookie data response with site, cookies, and jsUrl
CookieInfoIndividual cookie with name, domain, platform, description, etc.
CookieCategory'functional' | 'personalization' | 'analytics' | 'marketing' | 'security' | 'unknown'
ConsentStateRecord<CookieCategory, boolean> — consent per category
ConsentChangeCallback(consent: ConsentState) => void
ManifestSite manifest with site and resources URLs
KatlaConsentAPIThe window.KatlaConsent API shape (see JavaScript API)
ConsentManagerStateReturn type of the useConsentManager() hook
ManageableCategory'personalization' | 'analytics' | 'marketing' | 'security' — categories the visitor can toggle
CookieBannerPropsProps for the <CookieBanner> component
CookieCatalogPropsProps 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.