@synerise/ai-assistant-core

Core component and API helpers for embedding the Synerise AI Assistant in Preact applications.

Requirements

This package is designed for the Synerise platform. To use it you need:

• An active Synerise tenant and a tracker key
• Network access to https://api.synerise.com (or your custom Synerise API endpoint)
• Preact 10 in your application

If you don't have a Synerise account, visit synerise.com.

Which package do I need?

| Your stack | Package | | --- | --- | | Vanilla JS / no bundler / <script> tag | @synerise/ai-assistant-sdk | | React 18 | @synerise/ai-assistant-react | | Preact | @synerise/ai-assistant-core (this package) | | Build a custom chat UI from primitives | @synerise/ai-assistant-ui |

How packages relate

@synerise/ai-assistant-core  ──>  @synerise/ai-assistant-ui

core provides the high-level AIAssistant component with chat lifecycle, API integration, error handling, streaming, etc. ui provides only visual primitives.

Installation

npm install @synerise/ai-assistant-core preact
# or
pnpm add @synerise/ai-assistant-core preact
# or
yarn add @synerise/ai-assistant-core preact

Peer dependencies

• preact ^10.26.9

What this package provides

• AIAssistant — Preact component with built-in chat lifecycle handling
• assistantApi — direct API helpers (initChat, sendChatMessage, getChatMessages)
• Constants — message types, chat states, error types, operation types
• Errors — typed ApiError and NetworkError classes
• Re-exports from @synerise/ai-assistant-ui — BaseChat, Icon, action/message constants, theme types

Quick start

import { AIAssistant } from "@synerise/ai-assistant-core";

export function SupportChat() {
  return (
    <AIAssistant
      apiUrl="https://api.synerise.com/gen-ai/v3/ai-assistant"
      context={{ profileId: "user-123" }}
      additionalContextValues={{ segment: "premium" }}
      displayMode="bordered"
      onPromptSuccess={(response) => {
        console.log("threadId:", response.meta.threadId);
      }}
      onCustomAction={({ actionName, params }) => {
        console.log("custom action:", actionName, params);
      }}
    />
  );
}

Important props

| Prop | Type | Description | | --- | --- | --- | | apiUrl | string | Base assistant API URL | | context | Context | Per-request context object | | additionalContextValues | AdditionalContextValues | Per-request metadata | | displayMode | "drawer" \| "bordered" | UI layout | | onPromptSuccess | (response) => void | Required. Called after init/message response | | onCustomAction | ({ actionName, params }) => void | Called when the assistant emits a custom action | | threadId | string | If provided, loads an existing conversation | | stream | boolean | Enables SSE mode (text/event-stream) | | fastMode | boolean | Appends fastMode=true query param | | authParams | { code, clientUUID } | Auth payload (alternative to XSRF cookie auth) | | disableXSRFToken | boolean | Skip XSRF token header in fetch calls |

Conversation flow

   ┌──────────┐  initChat()    ┌─────────────┐
   │  init    ├───────────────>│  threadId   │
   └──────────┘                └──────┬──────┘
                                      │
   ┌──────────┐  sendChatMessage()    │
   │  user    ├───────────────────────┤
   │  message │                       │
   └──────────┘                       │
                                      v
                            ┌─────────────────┐
                            │  assistant      │
                            │  response       │
                            │  (POST or SSE)  │
                            └─────────┬───────┘
                                      v
                          onPromptSuccess(response)

AIAssistant orchestrates the entire flow internally. Use assistantApi directly only if you need custom UX (e.g. headless integration).

Direct API usage

import { assistantApi } from "@synerise/ai-assistant-core";

const initResponse = await assistantApi.initChat({
  apiUrl: "https://api.synerise.com/gen-ai/v3/ai-assistant",
  context: { profileId: "user-123" },
  additionalContextValues: { segment: "premium" },
  message: null,
});

const threadId = initResponse?.meta.threadId;

if (threadId) {
  const response = await assistantApi.sendChatMessage({
    apiUrl: "https://api.synerise.com/gen-ai/v3/ai-assistant",
    threadId,
    message: "Show me products for trail running",
    context: { profileId: "user-123" },
    additionalContextValues: { segment: "premium" },
  });

  console.log(response.data.messages);
}

Error handling

import { ApiError, NetworkError, AI_ASSISTANT_ERROR_TYPE } from "@synerise/ai-assistant-core";

try {
  await assistantApi.initChat({ /* ... */ });
} catch (error) {
  if (error instanceof ApiError) {
    console.error("API error:", error.body.errorCode, error.body.message);
    console.error("trace id:", error.body.traceId);
  } else if (error instanceof NetworkError) {
    console.error("Network error — check connectivity");
  }
}

AI_ASSISTANT_ERROR_TYPE enumerates the error types surfaced by the chat component callbacks.

Exports

• AIAssistant
• assistantApi (initChat, sendChatMessage, getChatMessages)
• BaseChat, Icon (re-exported from @synerise/ai-assistant-ui)
• AI_ASSISTANT_MESSAGE_ELEMENT_TYPE, AI_ASSISTANT_MESSAGE_TYPE, AI_ASSISTANT_ERROR_TYPE, AI_ASSISTANT_OPERATION, CHAT_STATE, CHAT_ACTION_TYPE, CHAT_MESSAGE_TYPE
• ApiError, NetworkError
• TypeScript types from AIAssistant.types

Troubleshooting

• document is not defined — this package is browser-only (uses cookies, fetch, DOM). Render only on the client in SSR frameworks.
• 401 / 403 from API — verify your tracker key, that apiUrl matches your tenant, and that disableXSRFToken matches your tenant's auth flow.
• CORS errors — your tenant must allow your origin. Contact Synerise support.
• Using from React — install @synerise/ai-assistant-react instead, which provides a typed React wrapper.

Support

For technical and licensing inquiries: [email protected].

License

Proprietary. See LICENSE.