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​

module:enable​

Enable specific functionality modules.

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

module:disable​

Disable specific functionality modules.

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

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');