@mintlify/assistant-core

@mintlify/assistant-core

Framework-independent state and transport for Mintlify Assistant. Use this package when your application owns the UI or when Assistant runs in a non-DOM workflow.

The core does not import browser APIs, React, React DOM, @mintlify/assistant-web, or the maintained widget renderer. Network and persistence behavior are injected through typed transport and storage adapters.

Create a client

import { createAssistantCore, type AssistantTransport } from '@mintlify/assistant-core';

const transport: AssistantTransport = createYourTransport();
const assistant = createAssistantCore({
  transport,
  metadata: {
    surface: 'headless',
    entryPoint: 'support-workflow',
  },
  onEvent(event) {
    recordAssistantEvent(event);
  },
});

const unsubscribe = assistant.subscribe((snapshot) => {
  renderCustomerOwnedUI(snapshot);
});

await assistant.send({ content: 'How do I configure authentication?' });

unsubscribe();
assistant.destroy();

See examples/vanilla-js.mjs for a runnable dependency-free consumer that exercises every public operation. examples/workflow.mjs shows how to isolate a non-DOM workflow around an injected production transport.

Public client contract

Operation	Behavior
getSnapshot()	Returns the current immutable-by-contract state snapshot.
subscribe(listener)	Observes coherent snapshots and returns an unsubscribe function.
send(input)	Adds a user message and resolves after the transport finishes, aborts, or fails.
abort()	Cancels pending transport work and retains a partial response as aborted.
retry()	Regenerates the last user message with its original surface and entry point.
submitFeedback(input)	Sends feedback using the server-issued message ID and original attribution.
newThread()	Aborts pending work, clears continuation state, and keeps the current context.
setContext(context)	Replaces the default context used by later sends.
destroy()	Aborts pending work, removes subscriptions, and destroys the injected transport.

destroy() is idempotent. Other mutating operations throw an AssistantError with code destroyed after cleanup. send, retry, and submitFeedback reject with AssistantError for invalid input, invalid state, transport failures, and normalized Assistant unavailability. Inspect error.code, error.retryable, and assistant.getSnapshot().unavailable instead of parsing error messages.

Context and attribution

The default metadata identifies the integration. A send can override surface and entryPoint when one client serves more than one interaction, such as a floating composer and a custom trigger. Retry, feedback, and lifecycle telemetry retain the resolved attribution for the original message.

Context supports selection/code items plus currentPath, version, language, and product. These values are delivered to the injected transport. The current Assistant widget HTTP endpoint accepts only items and currentPath; browser transports must deliberately omit the other three fields until the server contract supports them.

Do not place secrets, raw identity tokens, or arbitrary personally identifiable attributes in context.

Sessions and storage

The optional AssistantStorageAdapter persists threadId and threadKey continuation values. newThread() clears them. The embedding application owns sign-out and account-switch handling and must call newThread() or clear the old client before another user can send.

Storage and transport implementations are environment-specific. A Node workflow can keep continuation in memory or an encrypted server-side store; a browser integration should use the session adapter maintained by @mintlify/assistant-web. Never log or expose thread keys.

Telemetry and compatibility

onEvent receives completion, error, feedback, and new-thread lifecycle events. Events include resolved surface, entry point, loader version when present, and core compatibility version. They do not include message bodies, context, or thread keys.

The core injects ASSISTANT_CORE_API_VERSION as the stable compatibility major sent in coreVersion; consumers do not configure it, and it is not the npm package version. ASSISTANT_SURFACES contains the stable surface identifiers.

Browser adapters

Browser mounting, Widget ID session exchange, the loader, navigation adapters, and the maintained renderer belong to @mintlify/assistant-web. Import that package explicitly when those behaviors are required. @mintlify/assistant-core never selects or imports a browser adapter automatically.