Skip to main content

Client API Reference

These are all the methods that are available in the Cartesian function. You can use either:

  1. The snippet provided: window.Cartesian

or

  1. The npm module:
import { Cartesian } from '@cartesianio/agent-sdk';

Event Subscription​

The Cartesian event system allows you to subscribe to various system events using the 'subscribe' method. This enables you to respond to important state changes and lifecycle events within the Cartesian agent.

window.Cartesian('subscribe', event, callback);

Parameters

  • event (string): The name of the event to subscribe to
  • callback (Function): The function to execute when the event occurs

Available Events:​

load​

Triggered when the agent Javascript is fully loaded and initialized.

load: () => void;

ready​

Triggered when the agent is ready to start or is already running (if autoStart is true).

ready: () => void;

stopped​

Triggered when the agent stops, including optional error information.

stopped: (error?: Error) => void;

app-drawer:visibility-changed​

Triggered when the app drawer visibility state changes.

'app-drawer:visibility-changed': (isVisible: boolean) => void;

offerings:received​

Triggered when the agent receives new offerings.

'offerings:received': (offerings: OfferingDetails[]) => void;

OfferingDetails type​

The OfferingDetails object has the following shape:

type OfferingDetails = {
  id: string;
  offeringId: string;
  title: string;
};

Offering Events​

offering:clicked​

Triggered when an offering card is clicked.

'offering:clicked': (offering: OfferingDetails) => void;

offering:detail-viewed​

Triggered when an offering detail page is viewed.

'offering:detail-viewed': (offering: OfferingDetails) => void;

offerings:expanded​

Triggered when the "Show more" button is clicked to expand the offerings list.

'offerings:expanded': () => void;

Offering Lifecycle Events​

offering:install-started​

Triggered when an offering install operation starts.

'offering:install-started': (payload: { offering: OfferingDetails }) => void;

offering:installed​

Triggered when an offering is successfully installed.

'offering:installed': (payload: { offering: OfferingDetails }) => void;

offering:install-failed​

Triggered when an offering install operation fails.

'offering:install-failed': (payload: { offering: OfferingDetails; error: Error }) => void;

offering:activate-started​

Triggered when an offering activate operation starts.

'offering:activate-started': (payload: { offering: OfferingDetails }) => void;

offering:activated​

Triggered when an offering is successfully activated.

'offering:activated': (payload: { offering: OfferingDetails }) => void;

offering:activate-failed​

Triggered when an offering activate operation fails.

'offering:activate-failed': (payload: { offering: OfferingDetails; error: Error }) => void;

offering:installed-and-activated​

Triggered when an offering is successfully installed and activated.

'offering:installed-and-activated': (payload: { offering: OfferingDetails }) => void;

offering:requested​

Triggered when a user requests an offering they cannot install or activate (e.g. due to insufficient permissions). Use this event to capture demand signals and take appropriate action, such as notifying an administrator.

'offering:requested': (payload: { offering: OfferingDetails }) => void;

Agent Management​

agent-id:get​

Retrieve the current agent identifier.

const agentId = window.Cartesian('agent-id:get');

agent-id:set​

Configure the agent identifier.

window.Cartesian('agent-id:set', agentId);

Settings Management​

settings:get​

Retrieve specific setting values. Currently supports autoStart.

const autoStart = window.Cartesian('settings:get', 'autoStart');

settings:set​

Configure agent settings. Accepts partial settings objects.

window.Cartesian('settings:set', {
  autoStart: true,
});

Telemetry Configuration​

telemetry:set​

Control whether OpenTelemetry instrumentation is enabled for the agent. By default, telemetry is enabled. You can disable it by calling this method with false.

By default, the Agent sends operational telemetry data to Cartesian to help us improve the service and provide better support. This includes performance metrics, usage patterns, and diagnostic information. No sensitive customer data is included in telemetry.

info

This method must be called before the agent loads to take effect. Place it in your initialization code, before or immediately after the agent snippet.

// Optionally disable telemetry
window.Cartesian('telemetry:set', false);

Parameters:

  • enabled (boolean): true to enable telemetry, false to disable it

Default behavior:

  • If you don't call this method, telemetry is enabled by default
  • You only need to call this method if you want to explicitly disable telemetry

Module Control​

Every module:* command takes a single module identifier — 'recommendations' or 'user-tracking' — and rejects anything else with Unknown module <value>. See Working with Modules.

module:enable​

Enable specific functionality modules.

window.Cartesian('module:enable', 'moduleName');

Returns a promise. It rejects while the agent is stopping, and the module is not enabled — see Enabling a module while the agent is stopping. Enabling a module that is already running does nothing.

module:disable​

Disable specific functionality modules.

window.Cartesian('module:disable', 'moduleName');

Returns a promise that resolves once the module has torn itself down. Disabling a module that is not running does nothing.

module:settings:get​

Read the effective settings a module runs with: the agent's defaults, overlaid with the values configured in the Agent Settings screen, overlaid with the overrides you stored through module:settings:set. This is not a read-back of the payload you last passed to module:settings:set — fields you never set are present too, carrying their default or configured value.

const settings = window.Cartesian('module:settings:get', 'user-tracking');

module:settings:set​

Store your overrides for a module and restart it so it picks them up. The payload is merged into the overrides already stored rather than replacing them: a field you leave out keeps the value it has, passing undefined does not clear one, and an array replaces the array it lands on.

window.Cartesian('module:settings:set', 'user-tracking', {
  trackingRules: [],
});

Returns a promise. The restart is refused while the agent is stopping, and a shutdown that begins while the restart is under way refuses it too — the settings are stored either way, and the module picks them up the next time it starts. See Enabling a module while the agent is stopping.

modules:get​

List the modules the agent currently has running. A module is listed from the moment its start begins to the moment its stop begins, so it is there while it is still mounting and gone while it is still tearing down. A module whose start failed is not listed.

const running = window.Cartesian('modules:get');

User Authentication​

user:login​

Configure user authentication with optional status callback. See Authentication for more information.

window.Cartesian('user:login',
	() => Promise<string>,
	(error?: Error) => void
);

Agent Lifecycle Control​

start​

Initialize and start the agent. This will throw an error if the agent is already running or if the 'user:login' callback is not set.

window.Cartesian('start');

stop​

Terminate agent operations.

window.Cartesian('stop');