api reference

The SDK exposes one object, AgentContext, with four methods: init, getSnapshot, track, and destroy. Every method is safe to call at any time, and none of them throws.

import

import { AgentContext } from '@contextune/sdk';

// Public types — import only what you reference.
import type {
  AgentContextOptions,
  Snapshot,
  BehaviorBlock,
  DeviceInfoBlock,
  MarketingParamsBlock,
  EventLogEntry,
  IdlePeriod,
  RageClickAggregate,
} from '@contextune/sdk';

1 / AgentContext.init(options?)

Initialise the SDK. Idempotent — calling twice returns the existing instance unchanged. Wires DOM listeners, marketing-param capture, and (optionally) an external event source.

init(options?: AgentContextOptions): AgentContextInstance

1 / parameters

2 / returns

An AgentContextInstance with getSnapshot(), track(), and destroy()methods. You typically don't need to hold this reference — the static AgentContext façade delegates to the same singleton.

3 / example

AgentContext.init();                          // defaults
AgentContext.init({ eventSource: 'segment' }); // tap segment
AgentContext.init({                            // privacy-conscious
  blocks: { event_log: false, marketing_params: false },
});

If init() is called a second time with different options, the SDK emits a console.warn and keeps the first call's options. First call wins — call destroy() first to apply new options. See Security > F7 for the rationale.

2 / AgentContext.getSnapshot()

Return a fresh structured snapshot of the user's current behavioural profile. Synchronous, side-effect-free, never throws. Returns {} before init() and after destroy().

getSnapshot(): Snapshot

1 / parameters

None.

2 / returns

A Snapshot object. See Configuration for the per-block shape and defaults.

interface Snapshot {
  behavior?: BehaviorBlock;
  device_info?: DeviceInfoBlock;
  marketing_params?: MarketingParamsBlock;
  event_log?: EventLogEntry[];
}

3 / example

const snapshot = AgentContext.getSnapshot();

// inspect a single block
if (snapshot.behavior) {
  console.debug('session', snapshot.behavior.session_duration_s, 's');
  console.debug('rage clicks', snapshot.behavior.rage_clicks.count);
}

// hand the whole thing to your model
const systemPrompt = `...

<user_behavioural_context>
${JSON.stringify(snapshot, null, 2)}
</user_behavioural_context>`;

Snapshot reads are cheap — call getSnapshot()every time you invoke the model. Don't cache it; a stale snapshot is worse than no snapshot.

3 / AgentContext.track(name, properties?)

Emit a structured custom event. The event lands in event_log with source: 'custom' and goes through the same sanitisation as every other event. No-op before init() and after destroy() — never crashes the host page.

track(name: string, properties?: Record<string, unknown>): void

1 / parameters

2 / returns

void. Fire-and-forget.

3 / example

AgentContext.track('filter-dropdown:applied', { facet: 'size', value: 'M' });
AgentContext.track('checkout-form:submitted', { cart_value: 129 });

// no properties is fine
AgentContext.track('searched');

Custom events coexist with source plugins. See Custom events for when to use them.

4 / AgentContext.destroy()

Tear down all listeners, timers, and monkey-patches. Zero the in-memory snapshot. After destroy(), getSnapshot() returns {} and track() is a no-op.

destroy(): void

1 / parameters

None.

2 / returns

void.

3 / example

// fresh context on a route change
AgentContext.destroy();
AgentContext.init();

// or on logout
onLogout(() => AgentContext.destroy());

destroy() zeroes the captured snapshot — after teardown, nothing can recover the pre-destroy profile. See Security > F8.

5 / public types

All public types are exported from @contextune/sdk. The most useful:

interface AgentContextOptions {
  eventSource?: 'segment' | 'ga4' | 'gtm';
  blocks?: {
    behavior?: boolean;
    device_info?: boolean;
    marketing_params?: boolean;
    event_log?: boolean;
  };
  eventLogSize?: number;
  namespace?: string;
}

interface AgentContextInstance {
  getSnapshot(): Snapshot;
  track(name: string, properties?: Record<string, unknown>): void;
  destroy(): void;
}

For the full per-block shape, see Configuration.