JavaScript API

The JavaScript API lets your own code read and change consent. The same API is available in two ways:

• The global Cookiesh object, created by the script tag. Use it in plain HTML pages and from the browser console.
• The @cookiesh/js package, a typed wrapper around the global for bundled apps. It works the same way and includes TypeScript definitions.

npm install @cookiesh/js

import { cookiesh } from '@cookiesh/js';

The package does not load a second copy of Cookiesh. It waits for the script tag and calls the global object. All the examples below use the package, but Cookiesh.ready() and cookiesh.ready() behave identically.

Consent state

Most methods return or receive a ConsentState object:

interface ConsentState {
  necessary: true;
  preferences: boolean;
  analytics: boolean;
  marketing: boolean;
  /** How the current state came about. */
  method: 'default' | 'banner' | 'preferences' | 'api' | 'gpc';
  /** Random ID of the stored consent record, or null before the first choice. */
  consentId: string | null;
  /** ISO 8601 time of the choice, or null before the first choice. */
  timestamp: string | null;
  bannerVersion: string;
  /** Region the rule matched, such as "FR" or "US-CA". */
  region: string;
}

Before the visitor makes a choice, method is default and the categories reflect the region’s default state. In opt-in regions, that means everything except necessary is false.

Reading consent

ready()

ready(): Promise<ConsentState>

Resolves as soon as Cookiesh knows the consent state: immediately for returning visitors, and after region detection for new ones. It does not wait for the visitor to click the banner. Use it to start code that depends on consent:

const consent = await cookiesh.ready();
if (consent.analytics) initAnalytics();

getConsent()

getConsent(): ConsentState | null

Returns the current state synchronously, or null if Cookiesh has not finished loading yet. Prefer ready() unless you are sure the script has loaded.

hasConsent(category)

hasConsent(category: 'necessary' | 'preferences' | 'analytics' | 'marketing'): boolean

A shortcut for checking one category. Returns false until Cookiesh has loaded.

Changing consent

These methods store a new consent record, exactly as if the visitor had used the banner. Call them only in response to a clear action by the visitor, such as a click on your own settings page.

acceptAll(): Promise<ConsentState>
rejectAll(): Promise<ConsentState>
setConsent(choices: Partial<Record<'preferences' | 'analytics' | 'marketing', boolean>>): Promise<ConsentState>

// A custom toggle on your account settings page
await cookiesh.setConsent({ analytics: event.target.checked });

Categories you leave out keep their current value. necessary cannot be changed.

Showing the UI

showBanner(): void
openPreferences(): void
close(): void

showBanner() shows the first-layer banner again, even if the visitor has already chosen. openPreferences() opens the preference center with per-category toggles and the cookie declaration. close() closes either one without saving.

Logged-in users

By default, consent is stored per browser. In logged-in products, link it to your user ID so that the choice follows the user across devices:

identify(userId: string): Promise<ConsentState>
reset(): void

// After sign-in
await cookiesh.identify(session.user.id);

// After sign-out
cookiesh.reset();

identify() looks up the user’s latest choice. If one exists, Cookiesh applies it on this device and skips the banner. If the visitor made a choice before signing in, that choice is saved for the user. Cookiesh stores only a salted hash of the ID you pass, never the ID itself. Use an opaque internal ID, not an email address.

reset() removes the link to the user, but keeps the current choice on this device.

Script tag attributes

You configure the script tag with data- attributes:

Attribute	Default	Description
data-site-id	Required	Your site ID, such as ck_live_8f2a91
data-language	Auto	Forces the banner language (see Banner customization)
data-auto-block	true	Set to false to block only the scripts you tag yourself
data-nonce	None	CSP nonce applied to the scripts Cookiesh unblocks
data-consent-mode	true	Set to false to stop sending Google Consent Mode signals

Debugging

Cookiesh.debug(): void

Run it in the browser console to print the detected region, the rule that matched, the banner version, each blocked script and the current state of every category. It is available on the global object only.