django-cookie-consent/lib/cookiebar.d.ts

Frontend code for django-cookie-consent

/**
 * Cookiebar functionality, as a TS/JS module.
 *
 * About modules: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules
 *
 * The code is organized here in a way to make the templates work with Django's page
 * cache. This means that anything user-specific (so different django session and even
 * cookie consent cookies) cannot be baked into the templates, as that breaks caches.
 *
 * The cookie bar operates on the following principles:
 *
 * - The developer using the library includes the desired template in their django
 *   templates, using the HTML <template> element. This contains the content for the
 *   cookie bar.
 * - The developer is responsible for loading some Javascript that loads this script.
 * - The main export of this script needs to be called (showCookieBar), with the
 *   appropriate options.
 * - The options include the backend URLs where the retrieve data, which selectors/DOM
 *   nodes to use for various functionality and the hooks to tap into the accept/decline
 *   life-cycle.
 * - When a user accepts or declines (all) cookies, the call to the backend is made via
 *   a fetch request, bypassing any page caches and preventing full-page reloads.
 */
/**
 * A serialized cookie group.
 *
 * See the backend model method `CookieGroup.as_json()`.
 */
export interface CookieGroup {
    varname: string;
    name: string;
    description: string;
    is_required: boolean;
}
export interface Options {
    statusUrl: string;
    templateSelector: string;
    /**
     * DOM selector to the (script) tag holding the JSON-serialized cookie groups.
     *
     * This is typically rendered in a template with a template tag, e.g.
     *
     * ```django
     * {% all_cookie_groups 'cookie-consent__cookie-groups' %}
     * ```
     *
     * resulting in the selector: `'#cookie-consent__cookie-groups'`.
     */
    cookieGroupsSelector: string;
    acceptSelector: string;
    declineSelector: string;
    /**
     * Either a string (selector), DOMNode or null.
     *
     * If null, the bar is appended to the body. If provided, the node is used or looked
     * up.
     */
    insertBefore: string | HTMLElement | null;
    /**
     * Optional callback for when the cookie bar is being shown.
     *
     * You can use this to add a CSS class name to the body, for example.
     */
    onShow?: () => void;
    /**
     * Optional callback called when cookies are accepted.
     */
    onAccept?: (acceptedGroups: CookieGroup[], event?: MouseEvent) => void;
    /**
     * Optional callback called when cookies are accepted.
     */
    onDecline?: (declinedGroups: CookieGroup[], event?: MouseEvent) => void;
    /**
     * Name of the header to use for the CSRF token.
     *
     * If needed, this can be read/set via `settings.CSRF_HEADER_NAME` in the backend.
     */
    csrfHeaderName: string;
}
export interface CookieStatus {
    csrftoken: string;
    /**
     * Backend endpoint to POST to to accept the cookie groups.
     */
    acceptUrl: string;
    /**
     * Backend endpoint to POST to to decline the cookie groups.
     */
    declineUrl: string;
    /**
     * Array of accepted cookie group varnames.
     */
    acceptedCookieGroups: string[];
    /**
     * Array of declined cookie group varnames.
     */
    declinedCookieGroups: string[];
    /**
     * Array of undecided cookie group varnames.
     */
    notAcceptedOrDeclinedCookieGroups: string[];
}
/**
 * A simple wrapper around window.fetch that understands the django-cookie-consent
 * backend endpoints.
 *
 * @private - while exported, use at your own risk. This class is not part of the
 * public API covered by SemVer.
 */
export declare class FetchClient {
    protected statusUrl: string;
    protected csrfHeaderName: string;
    protected cookieStatus: CookieStatus | null;
    constructor(statusUrl: string, csrfHeaderName: string);
    getCookieStatus(): Promise<CookieStatus>;
    saveCookiesStatusBackend(urlProperty: 'acceptUrl' | 'declineUrl'): Promise<void>;
}
/**
 * Read the JSON script node contents and parse the content as JSON.
 *
 * The result is the list of available/configured cookie groups.
 * Use the status URL to get the accepted/declined status for an individual user.
 */
export declare const loadCookieGroups: (selector: string) => CookieGroup[];
export declare const showCookieBar: (options?: Partial<Options>) => Promise<void>;