NodeJS SDK

import {
  Environment,
  KameleoonClient,
  SDKConfigurationType,
  CredentialsType,
} from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';

// -- Mandatory credentials
const credentials: CredentialsType = {
  clientId: 'my_client_id',
  clientSecret: 'my_client_secret',
};

// -- Optional configuration
const configuration: Partial<SDKConfigurationType> = {
  dataFileRefreshInterval: 20,
  environment: Environment.Production,
  cookieDomain: '.example.com',
};

const client = new KameleoonClient({
  siteCode: 'my_site_code',
  credentials,
  configuration,
  externals: {
    visitorCodeManager: new KameleoonVisitorCodeManager(),
    eventSource: new KameleoonEventSource(),
    requester: new KameleoonRequester(),
  },
});

// -- Waiting for the client initialization using `async/await`
async function init(): Promise<void> {
  await client.initialize();
}

init();

// -- Waiting for the client initialization using `Promise.then()`
client
  .initialize()
  .then(() => {})
  .catch((error) => {});

import {
  KameleoonError,
  KameleoonClient,
  KameleoonException,
} from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';

const client = new KameleoonClient({
  siteCode: 'my_site_code',
  credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
  externals: {
    visitorCodeManager: new KameleoonVisitorCodeManager(),
    eventSource: new KameleoonEventSource(),
    requester: new KameleoonRequester(),
  },
});

async function init(): Promise<void> {
  try {
    await client.initialize();

    const customData = new CustomData(0, 'my_data');
    client.addData(visitorCode, customData);
  } catch (error) {
    // -- Type guard for inferring error type, as native JavaScript `catch`
    //    only infers `unknown`
    if (error instanceof KameleoonError) {
      switch (error.type) {
        case KameleoonException.VisitorCodeMaxLength:
          // -- Handle an error
          break;
        case KameleoonException.StorageWrite:
          // -- Handle an error
          break;
        case KameleoonException.Initialization:
          // -- Handle an error
          break;
        default:
          break;
      }
    }
  }
}

init();

import { KameleoonClient, KameleoonLogger, LogLevel } from '@kameleoon/nodejs-sdk';

const client = new KameleoonClient({ siteCode: 'my_site_code', configuration });

// The `NONE` log level does not allow logging.
client.setLogLevel(LogLevel.NONE);
// Or use directly KameleoonLogger
KameleoonLogger.setLogLevel(LogLevel.NONE);


// The `ERROR` log level only allows logging issues that may affect the SDK's main behaviour.
client.setLogLevel(LogLevel.ERROR);
// Or use directly KameleoonLogger
KameleoonLogger.setLogLevel(LogLevel.ERROR);

// The `WARNING` log level allows logging issues which may require additional attention.
// It extends the `ERROR` log level.
// The `WARNING` log level is a default log level.
client.setLogLevel(LogLevel.WARNING);
// Or use KameleoonLogger
KameleoonLogger.setLogLevel(LogLevel.WARNING);

// The `INFO` log level allows logging general information on the SDK's internal processes.
// It extends the `WARNING` log level.
client.setLogLevel(LogLevel.INFO);
// Or use KameleoonLogger
KameleoonLogger.setLogLevel(LogLevel.INFO);

// The `DEBUG` level logs additional details about the SDK’s internal processes and extends the `INFO` level
// with more granular. diagnostic output.
// This information is not intended for end-user interpretation but can be sent to our support team
// to assist with internal troubleshooting.
client.setLogLevel(LogLevel.DEBUG);
// Or use KameleoonLogger
KameleoonLogger.setLogLevel(LogLevel.DEBUG);

import { KameleoonClient, KameleoonLogger, IExternalLogger, LogLevel } from '@kameleoon/nodejs-sdk';

export class CustomLogger implements IExternalLogger {
  // `log` method accepts logs from the SDK
  public log(level: LogLevel, message: string): void {
    // Custom log handling logic here. For example:
    switch (level) {
      case LogLevel.DEBUG:
        console.debug(message);
        break;
      case LogLevel.INFO:
        console.info(message);
        break;
      case LogLevel.WARNING:
        console.warn(message);
        break;
      case LogLevel.ERROR:
        console.error(message);
        break;
    }
  }
}

const client = new KameleoonClient({
  siteCode: 'my_site_code',
  externals: {
    logger: new CustomLogger(),
  },
});

// Log level filtering is applied separately from log handling logic.
// The custom logger will only accept logs that meet or exceed the specified log level.
// Ensure the log level is set correctly.
client.setLogLevel(LogLevel.DEBUG);
// Or use KameleoonLogger
KameleoonLogger.setLogLevel(LogLevel.DEBUG);

import { IExternalStorage, KameleoonClient } from '@kameleoon/nodejs-sdk';

// --- External Storage implementation ---
// - JavaScript `Map` is used as an example storage
const storage = new Map();

class MyStorage<T> implements IExternalStorage<T> {
  public read(key: string): T | null {
    // - Read data using `key`
    const data = storage.get(key);

    // - Return `null` if there's no data
    if (!data) {
      return null;
    }

    // - Return obtained data
    return data;
  }

  public write(key: string, data: T): void {
    // - Write data using `key`
    storage.set(key, data);
  }
}

// --- Create KameleoonClient ---
const client = new KameleoonClient({
  siteCode: 'my_site_code',
  externals: {
    storage: new MyStorage(),
  },
});

import {
  IExternalEventSource,
  KameleoonClient,
  EventSourceOpenParametersType,
} from '@kameleoon/nodejs-sdk';

// --- External EventSource implementation ---
// - Example uses dummy `EventSource` class
class MyEventSource implements IExternalEventSource {
  private eventSource?: EventSource;

  public open({
    eventType,
    onEvent,
    url,
  }: EventSourceOpenParametersType): void {
    // - Initialize `EventSource` (use any event source of your choice here)
    const eventSource = new EventSource(url);

    this.eventSource = eventSource;
    // - Add event listener with provided event type and event callback
    this.eventSource.addEventListener(eventType, onEvent);
  }

  public close(): void {
    // - Clean up open event source
    if (this.eventSource) {
      this.eventSource.close();
    }
  }

  public onError(callback: (error: Event) => void): void {
    // - Set error callback
    if (this.eventSource) {
      this.eventSource.onerror = callback;
    }
  }
}

// --- Create KameleoonClient ---
const client = new KameleoonClient({
  siteCode: 'my_site_code',
  externals: {
    eventSource: new MyEventSource(),
  },
});

import {
  IExternalVisitorCodeManager,
  SetDataParametersType,
  GetDataParametersType,
  KameleoonClient,
  KameleoonUtils,
} from '@kameleoon/nodejs-sdk';

// --- External Visitor Code Manager implementation ---
// - Example uses server `request` and `response`
class MyVisitorCodeManager implements IExternalVisitorCodeManager {
  public getData({ request, key }: GetDataParametersType): string | null {
    // - Get cookie from server request
    const cookieString = request.headers.cookie;

    // - Return `null` if no cookie was found
    if (!cookieString) {
      return null;
    }

    // - Parse cookie using the provided `key`
    return KameleoonUtils.getCookieValue(cookieString, key);
  }

  public setData({
    visitorCode,
    response,
    domain,
    maxAge,
    key,
    path,
  }: SetDataParametersType): void {
    // - Set cookie to request using provided parameters
    let resultCookie = `${key}=${visitorCode}; Max-Age=${maxAge}; Path=${path}`;

    if (domain) {
      resultCookie += `; Domain=${domain}`;
    }

    response.setHeader('Set-Cookie', resultCookie);
  }
}

// --- Create KameleoonClient ---
const client = new KameleoonClient({
  siteCode: 'my_site_code',
  externals: {
    visitorCodeManager: new MyVisitorCodeManager(),
  },
});

import {
  IExternalDenoVisitorCodeManager,
  SetDenoDataParametersType,
  GetDenoDataParametersType,
  KameleoonClient,
  KameleoonUtils,
} from '@kameleoon/nodejs-sdk';

// --- External Visitor Code Manager implementation ---
// - Example uses server `request` and `response`
class MyVisitorCodeManager implements IExternalDenoVisitorCodeManager {
  public getData({ request, key }: GetDenoDataParametersType): string | null {
    // - Get cookie from server request
    const cookieString = request.headers.get('cookie');

    // - Return `null` if no cookie was found
    if (!cookieString) {
      return null;
    }

    // - Parse cookie using the provided `key`
    return KameleoonUtils.getCookieValue(cookieString, key);
  }

  public setData({
    visitorCode,
    response,
    domain,
    maxAge,
    key,
    path,
  }: SetDenoDataParametersType): void {
    // - Set cookie to request using provided parameters
    let resultCookie = `${key}=${visitorCode}; Max-Age=${maxAge}; Path=${path}`;

    if (domain) {
      resultCookie += `; Domain=${domain}`;
    }

    response.headers.set('Set-Cookie', resultCookie);
  }
}

// --- Create KameleoonClient ---
const client = new KameleoonClient({
  siteCode: 'my_site_code',
  externals: {
    visitorCodeManager: new MyVisitorCodeManager(),
  },
});

import {
  IExternalNextJSVisitorCodeManager,
  SetNextJSDataParametersType,
  GetNextJSDataParametersType,
  KameleoonClient,
} from '@kameleoon/nodejs-sdk';

// --- External Visitor Code Manager implementation ---
// - Example uses server `cookies` object imported from "next/headers"
class MyVisitorCodeManager implements IExternalNextJSVisitorCodeManager {
  public getData({ cookies, key }: GetNextJSDataParametersType): string | null {
    // - Get cookie from server request by provided `key`
    const cookie = cookies().get(key);

    if (cookie) {
      return cookie.value;
    }

    // - Return `null` if no cookie was found
    return null;
  }

  public setData({
    visitorCode,
    cookie,
    domain,
    maxAge,
    key,
    path,
  }: SetNextJSDataParametersType): void {
    // - Set cookie to request using provided parameters
    cookies().set(key, visitorCode, {
      path,
      domain,
      maxAge,
    });
  }
}

// --- Create KameleoonClient ---
const client = new KameleoonClient({
  siteCode: 'my_site_code',
  externals: {
    visitorCodeManager: new MyVisitorCodeManager(),
  },
});

import {
  IExternalCustomVisitorCodeManager,
  SetDataCustomParametersType,
  GetDataCustomParametersType,
  KameleoonClient,
} from '@kameleoon/nodejs-sdk';

// --- External Visitor Code Manager implementation ---
// - Example uses custom arbitrary `input` and `output` objects
class MyVisitorCodeManager implements IExternalCustomVisitorCodeManager {
  public getData({ input, key }: GetDataCustomParametersType): string | null {
    // - Get visitor code from `input` object
    //   `input` is of type `unknown`, so you can provide any structure.
    //   In Example, we assume `input` is a `Map` object.
    const visitorCode = input.get(key);

    if (visitorCode) {
      return visitorCode;
    }

    // - Return `null` if no visitor code was found
    return null;
  }

  public setData({
    visitorCode,
    output,
    domain,
    maxAge,
    key,
    path,
  }: SetDataCustomParametersType): void {
    // - Set visitor code as a cookie to `output` object using provided parameters.
    let resultCookie = `${key}=${visitorCode}; Max-Age=${maxAge}; Path=${path}`;

    if (domain) {
      resultCookie += `; Domain=${domain}`;
    }

    // - `output` is of type `unknown`, so you can provide any structure.
    //   In Example, we assume `output` is a `Map` object.
    output.set(key, resultCookie);
  }
}

// --- Create KameleoonClient ---
const client = new KameleoonClient({
  siteCode: 'my_site_code',
  externals: {
    visitorCodeManager: new MyVisitorCodeManager(),
  },
});

import {
  RequestType,
  IExternalRequester,
  KameleoonResponseType,
  SendRequestParametersType,
  KameleoonClient,
} from '@kameleoon/nodejs-sdk';

// --- External Requester Implementation
export class MyRequester implements IExternalRequester {
  public async sendRequest({
    url,
    parameters,
  }: SendRequestParametersType<RequestType>): Promise<KameleoonResponseType> {
    // - Using native NodeJS `fetch` (for v18+)
    return await fetch(url, parameters);
  }
}

// --- Create KameleoonClient ---
const client = new KameleoonClient({
  siteCode: 'my_site_code',
  externals: {
    requester: new MyRequester(),
  },
});

import {
  KameleoonUtils,
  IExternalRequester,
  SendRequestParametersType,
  RequestType,
  KameleoonResponseType,
} from '@kameleoon/nodejs-sdk';

// - Example of `Requester` with disabled tracking
class Requester implements IExternalRequester {
  public async sendRequest({
    url,
    parameters,
    requestType,
  }: SendRequestParametersType<RequestType>): Promise<KameleoonResponseType> {
    if (requestType === RequestType.Tracking) {
      return KameleoonUtils.simulateSuccessRequest<RequestType.Tracking>(
        requestType,
        null,
      );
    }

    return await fetch(url, parameters);
  }
}