@opencx/widget-core

npm install @opencx/widget-core

interface WidgetConfig {
  token: string;
  language?: Language;
  bot?: { name?: string; avatarUrl?: string };
  isOpen?: boolean;
  openAfterNSeconds?: number;
  theme?: ThemeOptions;
  initialMessages?: string[];
  initialQuestions?: string[];
  collectUserData?: boolean;
  user?: UserConfig;
  headerButtons?: { sessionsScreen?: HeaderButtonU[]; chatScreen?: HeaderButtonU[] };
  modesComponents?: ModeComponent[];
  customComponents?: { onSessionResolved?: CustomComponent; headerTitle?: CustomComponent };
  router?: { goToChatIfNoSessions?: boolean; chatScreenOnly?: boolean };
  oneOpenSessionAllowed?: boolean;
  headers?: Record<string, string>;
  queryParams?: Record<string, string>;
  context?: Record<string, unknown>;
  inline?: boolean;
}

interface ExternalStorage {
  get(key: string): Promise<string | null>;
  set(key: string, value: string): Promise<void>;
  remove(key: string): Promise<void>;
}

type WidgetComponentType = {
  key: WidgetComponentKey;
  component: (props: ComponentContext) => React.ReactNode;
};

type WidgetComponentKey =
  | 'bot_message'
  | 'agent_message'
  | 'loading'
  | 'fallback'
  | string;

type ModeComponent = {
  key: string;
  component: (props: ModeComponentProps) => React.ReactNode;
};

type ModeComponentProps = ComponentContext & {
  mode: ModeDto;
  createStateCheckpoint: (payload: unknown) => Promise<{ success: boolean }>;
  sendMessage: (input: { content: string }) => Promise<void>;
  isSendingMessage: boolean;
};

type ComponentContext = {
  react: typeof React;
  org: { id: string; name: string };
  config: WidgetConfig;
  session: SessionDto | null;
  messages: WidgetMessageU[];
  currentScreen: ScreenU;
};

import { WidgetCtx } from '@opencx/widget-core';

const widgetCtx = await WidgetCtx.initialize({ config });

// Access sub-contexts
widgetCtx.sessionCtx;
widgetCtx.messageCtx;
widgetCtx.contactCtx;
widgetCtx.routerCtx;
widgetCtx.csatCtx;

class WidgetCtx {
  static initialize(opts: { config: WidgetConfig; storage?: ExternalStorage }): Promise<WidgetCtx>;

  sessionCtx: SessionCtx;
  messageCtx: MessageCtx;
  contactCtx: ContactCtx;
  routerCtx: RouterCtx;
  csatCtx: CsatCtx;
  api: ApiCaller;
  modes: ModeDto[];

  resetChat(): void;
}

class SessionCtx {
  sessionState: PrimitiveState<SessionState>;
  sessionsState: PrimitiveState<SessionsState>;

  createSession(): Promise<SessionDto | null>;
  loadMoreSessions(): Promise<void>;
  resolveSession(): Promise<{ success: boolean }>;
  createStateCheckpoint(payload: unknown): Promise<{ success: boolean }>;
}

class MessageCtx {
  state: PrimitiveState<MessageCtxState>;

  sendMessage(input: {
    content: string;
    attachments?: MessageAttachmentType[];
    customData?: Record<string, unknown>;
  }): Promise<void>;

  reset(): void;
}

class ContactCtx {
  state: PrimitiveState<ContactState>;

  shouldCollectData(): boolean;
  createUnverifiedContact(payload: CreateUnverifiedContactDto): Promise<void>;
  setUnverifiedContact(token: string): Promise<void>;
}

class RouterCtx {
  state: PrimitiveState<{ screen: ScreenU }>;

  toSessionsScreen(): void;
  toChatScreen(sessionId?: string): void;
}

type ScreenU = 'welcome' | 'sessions' | 'chat';

class CsatCtx {
  submitCsat(body: { score: number; feedback?: string }): Promise<{ data: unknown; error?: string }>;
}

class PrimitiveState<T> {
  get(): T;
  set(value: T): void;
  setPartial(partial: Partial<T>): void;
  reset(): void;
  subscribe(callback: (value: T) => void): () => void;
}

type WidgetMessageU =
  | WidgetUserMessage
  | WidgetAiMessage
  | WidgetAgentMessage
  | WidgetSystemMessageU;

interface WidgetUserMessage {
  id: string;
  type: 'USER';
  content: string;
  deliveredAt: string | null;
  attachments?: MessageAttachmentType[] | null;
  timestamp: string | null;
  user?: {
    name?: string;
    email?: string;
    phone?: string;
    customData?: Record<string, unknown>;
    avatarUrl?: string;
  };
}

interface WidgetAiMessage<TActionData = unknown> {
  id: string;
  type: 'AI';
  component: string;
  data: {
    message: string;
    variant?: 'default' | 'error';
    action?: { name: string; data: TActionData } | null;
  };
  timestamp: string | null;
  agent?: Agent;
  attachments?: MessageAttachmentType[];
}

interface WidgetAgentMessage {
  id: string;
  type: 'AGENT';
  component: 'agent_message';
  data: {
    message: string;
    variant?: 'default' | 'error';
  };
  timestamp: string | null;
  agent?: Agent;
  attachments?: MessageAttachmentType[];
}

type WidgetSystemMessageU =
  | WidgetSystemMessage__CsatRequested
  | WidgetSystemMessage__CsatSubmitted
  | WidgetSystemMessage__StateCheckpoint;

interface WidgetSystemMessage__CsatRequested {
  id: string;
  type: 'SYSTEM';
  subtype: 'csat_requested';
  timestamp: string | null;
  data: { payload?: undefined };
}

interface WidgetSystemMessage__CsatSubmitted {
  id: string;
  type: 'SYSTEM';
  subtype: 'csat_submitted';
  timestamp: string | null;
  data: {
    payload: {
      score: number | null | undefined;
      feedback: string | null | undefined;
    };
  };
}

interface WidgetSystemMessage__StateCheckpoint {
  id: string;
  type: 'SYSTEM';
  subtype: 'state_checkpoint';
  timestamp: string | null;
  data: { payload: unknown };
}

interface Agent {
  name?: string;
  avatarUrl?: string;
}

interface MessageAttachmentType {
  type: 'image' | 'file';
  url: string;
  name?: string;
  size?: number;
  mimeType?: string;
}