Coach SDK

MeltingSpot's contextual guidance SDK. It displays the AI coach (proactive conversations and content such as courses, lives, documents and learning paths) directly inside your web application, triggered by user interactions and the current URL.

Coach relies on hover + fine-pointer interactions and is skipped on touch-only devices.

Installation

Via <script> (CDN)

The standalone bundle is self-contained: it exposes window.MeltingSpot.Coach and injects its styles automatically (no separate stylesheet to load).

<script
  crossorigin
  src="https://cdn.jsdelivr.net/npm/@meltingspot/coach"
></script>

Via npm

npm install @meltingspot/coach

import { Coach } from '@meltingspot/coach';

Authentication (authToken)

authToken is the current user's MeltingSpot SSO token. Provide it to re-authenticate the user at start; omit it to rely on an existing authenticated session. Activate SSO on your spot to obtain these tokens.

With autoJoin: true (requires authToken), the SDK additionally attempts to join and validate the member on the spot right after the SSO authentication. The final member status follows the backend transition rules for the member's current state (e.g. a rejected or deactivated member stays blocked). With the default autoJoin: false, authentication only establishes a session; joining the spot must be handled separately.

Quick start

// Start the coach for your spot.
await Coach.start({
  spotId: 'YOUR_SPOT_ID',
  authToken: 'CURRENT_USER_SSO_TOKEN',
  // Auto-join and validate the member on the spot at SSO auth (default false).
  autoJoin: true,
});

// Stop and tear down the coach.
await Coach.stop();

When loaded via the CDN <script>, start the coach once the DOM is ready:

<script>
  window.addEventListener('DOMContentLoaded', function () {
    window.MeltingSpot.Coach.start({
      spotId: 'YOUR_SPOT_ID',
      authToken: 'CURRENT_USER_SSO_TOKEN',
    });
  });
</script>

Start options

| Option | Type | Required | Default | Description | | ----------------- | ------------------------------------------------------------------------------ | -------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | spotId | string | Yes | n/a | Target spot id. | | authToken | string | No | none (reuse existing session) | Current user's MeltingSpot SSO token. | | autoJoin | boolean | No | false | Attempt auto-join after SSO auth (requires authToken); final status follows backend transition rules. | | autoRefresh | AutoRefreshOptions | No | see AutoRefreshOptions | Fine-tune which browser events trigger a re-evaluation. | | initialPosition | 'left' \| 'center' \| 'right' \| \${number}%` | `${number}px` | number| No |'center' | Initial horizontal position of the coach. See [initialPosition](#initialposition). | | translations |CoachTranslationsOverrides | No | built-in strings | Override built-in conversation UI strings (see below). | |url |string | No | current location | Forces the URL evaluated at startup. | |domain |string | No | none (default MeltingSpot domain) | Custom domain key of your spot. See [domain](#domain). | | theme |CoachThemeOverride | No | built-in brand accent | Visual theming overrides (accent color). See [theme](#theme). | | debug |boolean | No |false` | Verbose logging. |

initialPosition

Where the coach sits horizontally when it first appears. It accepts a named position or an explicit offset, whose sign designates the edge it is measured from: positive from the left, negative from the right.

| Value | Meaning | | --------------------------------- | -------------------------------------------------------- | | 'left' / 'center' / 'right' | Named positions ('center' is the default). | | '25%' | 25% of the way from the left edge towards the right one. | | '-25%' | 25% of the way from the right edge towards the left one. | | 120 or '120px' | A 120 pixel gap between the left edge and the coach. | | -120 or '-120px' | A 120 pixel gap between the right edge and the coach. |

MeltingSpot.Coach.start({
  spotId: 'your-spot-id',
  // Keep the coach 120px away from the right edge of the screen
  initialPosition: '-120px',
});

The two units do not measure the same thing:

• A percentage places the coach along its travel range, so it lines up with the named positions — '0%' = 'left' (flush against the left edge), '50%' = 'center', '100%' = 'right'. It keeps that relative placement when the window is resized.
• A pixel offset is a gap between the edge and the coach, like a CSS left / right distance. That gap stays constant when the window is resized.

The position is always clamped so the coach stays fully visible, and the user can still drag it: once dragged, its placement takes over from this option. Unsupported values fall back to 'center'.

domain

The custom domain key of your spot. It is forwarded to the link-generating API calls and to the widgets the coach opens, so the internal links the Coach, its widgets and beacon cards display point to your custom domain instead of the default MeltingSpot one. It does not affect which playbooks apply on the current page (that scoping stays based on the page hostname).

See the "Multi-domains" section of the embed guide for details.

theme

Visual theming overrides, letting you align the coach with your host branding.

MeltingSpot.Coach.start({
  spotId: 'your-spot-id',
  theme: {
    accentColor: '#24aace',
  },
});

| Field | Type | Default | Description | | ------------- | -------- | --------------------- | ------------------------------------------------- | | accentColor | string | built-in brand accent | Accent color of the mascot and the hotspot icons. |

accentColor accepts standard CSS color literals (hex, rgb()/rgba(), hsl()/hsla(), or a keyword such as red). Values that are not well-formed color literals are ignored and the built-in accent is used instead.

AutoRefreshOptions

Controls which browser signals make the coach re-evaluate playbooks. All fields are optional booleans:

| Field | Default | Description | | ----------------- | ------- | ---------------------------------------------------- | | onHistoryChange | true | Re-evaluate on pushState / replaceState. | | onPopState | true | Re-evaluate on back/forward navigation (popstate). | | onLoad | true | Re-evaluate on the load event. | | onHashChange | true | Re-evaluate on hashchange. | | onDomMutation | false | Re-evaluate on relevant DOM mutations. |

CoachTranslationsOverrides

Override the built-in UI strings (merged on top of the language resolved from lang). Every field is optional:

await Coach.start({
  spotId: 'YOUR_SPOT_ID',
  lang: 'fr',
  translations: {
    conversation: {
      resetConversation: 'Réinitialiser la conversation',
      inputPlaceholder: 'Posez votre question…',
      welcomeMessage: 'Bonjour 👋',
      agentThinking: 'Réflexion…',
      // backToConversation, later, errorFallback, expiredFallback, retryLabel,
      // copyMessage, messageCopied also available
    },
    // mutedHand, autoDismiss groups are also overridable
  },
});

All groups are optional; any omitted string keeps its built-in translation.

| Group | Type | Default | Description | | -------------- | ----------------------------------- | ---------------- | -------------------------------------------- | | conversation | Partial<ConversationTranslations> | built-in strings | Conversation UI strings (input, welcome, …). | | mutedHand | Partial<MutedHandTranslations> | built-in strings | Muted-hand re-entry prompt strings. | | autoDismiss | Partial<AutoDismissTranslations> | built-in strings | Auto-dismiss accessibility strings. | | mute | Partial<MuteTranslations> | built-in strings | Coach mute control: button, durations, menu. |

mute.presets is a record keyed by CoachMutePreset, merged key by key — you can override a single duration label without restating the other five.

Muting the coach

Members mute the coach from a control in its header, which the SDK renders on its own when the spot has the feature enabled. Nothing has to be wired for that.

The engine also exposes the same operations for a headless integration:

| Member | Returns | Description | | ------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | CoachEngine.isCoachMuted() | boolean | Whether the coach is muted for this member on this spot right now, expiry included. Safe to read at any time. | | CoachEngine.muteCoach(preset) | Promise<Result<Nullable<string>, CoachMuteError>> | Mutes the coach. Resolves with the server-computed deadline (ISO 8601), or null for the Always preset. | | CoachEngine.unmuteCoach() | Promise<Result<void, CoachMuteError>> | Resumes the coach. Idempotent. |

Neither call throws: a failure comes back as a CoachMuteError whose reason is 'forbidden' (the server refused the write — the feature is off for the spot, or the session is a preview) or 'network' (the request did not land — retrying is worth it). The original failure is kept as the error's cause.

Both writes are optimistic: the local state changes — and the coach:mute:changed runtime event fires — before the server answers, and a failed write rolls back and re-emits. Drive your own UI from that event rather than from the returned promise, or it will disagree with the engine after a failure.

import { CoachMutePreset } from '@meltingspot/core';
import { CoachEngine } from '@meltingspot/coach';

const result = await CoachEngine.muteCoach(CoachMutePreset.Mute1Hour);
result.match(
  (mutedUntil) => console.info('muted until', mutedUntil ?? 'further notice'),
  (error) => console.warn(error.reason),
);

See the MeltingSpot helpdesk for the full integration guide.

Breaking changes

1.4.0

The coach now renders inside a Shadow DOM and injects its own scoped styles automatically, so the separate stylesheet is gone:

• Removed the @meltingspot/coach/stylesheet.css subpath export and the package style field.
• Migration: delete any import '@meltingspot/coach/stylesheet.css'; (or a <link> pointing to it). It no longer resolves and is no longer needed — styles load automatically on Coach.start().