@jokkoo/sdk-web 0.1.0

package/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 Jokkoo
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,51 @@
+# @jokkoo/sdk-web
+
+Framework-agnostic Jokkoo client embed SDK core: API client, realtime transport, token management, and shared utilities (formatting, i18n, message mapping, uploads).
+
+UI bindings for specific frameworks (`@jokkoo/sdk-react`, `@jokkoo/sdk-react-native`, etc.) build on this package.
+
+## Install
+
+```bash
+pnpm add @jokkoo/sdk-web
+```
+
+## Quick start
+
+```typescript
+import { Jokkoo, JokkooApiClient } from "@jokkoo/sdk-web"
+
+Jokkoo.init({
+  clientToken: "ct_...",
+  userTokenProvider: async () => {
+    const res = await fetch("/api/jokkoo-token")
+    const data = await res.json()
+    return data.token as string
+  },
+  locale: "fr",
+  debug: true,
+})
+
+await Jokkoo.getRealtimeClient().connect()
+
+const api = new JokkooApiClient(Jokkoo.getConfig(), Jokkoo.getTokenManager())
+const conversations = await api.getConversations(20, 0)
+```
+
+For React apps, prefer [`@jokkoo/sdk-react`](../sdk-react) which wraps this core with a floating widget UI.
+
+## What's included
+
+- **Core** — `Jokkoo` singleton, `TokenManager`, config validation, debug logging
+- **API** — REST client for conversations, messages, uploads, satisfaction
+- **Realtime** — Socket.IO client on namespace `/sdk` and event constants
+- **Lib** — pure helpers (pagination, formatting, attachments, voice metering, satisfaction)
+- **i18n** — English and French translation catalogs
+
+## Web channels
+
+When using a web channel (`channelType === "web"`), configure **allowed origins** in the Jokkoo dashboard so the API accepts browser requests from your host app.
+
+## License
+
+Apache-2.0

package/dist/index.d.mts

@@ -0,0 +1,419 @@
+import { Socket } from 'socket.io-client';
+
+type ConversationStatus = "open" | "pending" | "pending_closure" | "snoozed" | "closed";
+type ChannelType = "mobile" | "web" | "whatsapp" | "email";
+type MessageSenderType = "end_user" | "agent" | "system";
+type MessageType = "comment" | "note" | "activity";
+interface MessageMetadata {
+    activityType?: string;
+    isVoiceMessage?: boolean;
+    audioDurationMs?: number;
+    [key: string]: unknown;
+}
+interface MessageAttachment {
+    fileId: string;
+    fileName: string;
+    mimeType: string;
+    size?: number | null;
+}
+type ConversationId = number;
+type ClosedConversationReplyBehavior = "create_new" | "reopen";
+interface ClosedConversationPolicy {
+    endUserReplyBehavior: ClosedConversationReplyBehavior;
+    reopenGracePeriodDays: number;
+}
+interface Conversation {
+    id: ConversationId;
+    channelType: ChannelType;
+    status: ConversationStatus;
+    lastMessageText: string | null;
+    lastMessageSenderType?: MessageSenderType | null;
+    assignedAgentName?: string | null;
+    assignedAgentAvatarUrl?: string | null;
+    createdAt: string;
+    updatedAt: string;
+    closedAt?: string | null;
+}
+interface UnreadCountResponse {
+    count: number;
+    conversationIds: number[];
+}
+interface Message {
+    id: number;
+    conversationId: number;
+    endUserId: number;
+    senderId: string | null;
+    senderType: MessageSenderType;
+    messageType?: MessageType;
+    metadata?: MessageMetadata | null;
+    attachments?: MessageAttachment[];
+    content: string;
+    createdAt: string;
+}
+interface PaginatedResponse<T> {
+    data: T[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+interface SendMessagePayload {
+    content: string;
+    conversationId?: number;
+    forceNew?: boolean;
+    fileIds?: string[];
+    metadata?: MessageMetadata | null;
+}
+declare const NEW_CONVERSATION_ID = 0;
+
+type JokkooLocale = "fr" | "en" | (string & {});
+type UserTokenProvider = () => Promise<string>;
+type TokenState = "idle" | "loading" | "ready" | "error";
+type TokenStateListener = (state: TokenState, error?: Error) => void;
+interface JokkooConfig {
+    /** Public channel identifier from Jokkoo dashboard */
+    clientToken: string;
+    /** Callback that returns a fresh user_token JWT from the tenant backend */
+    userTokenProvider: UserTokenProvider;
+    /** Jokkoo API base URL (defaults to production) */
+    baseUrl?: string;
+    /** End-user locale (defaults to "fr") */
+    locale?: JokkooLocale;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Seconds before JWT expiry to proactively refresh (default: 60) */
+    tokenRefreshBufferSeconds?: number;
+}
+interface ResolvedJokkooConfig {
+    clientToken: string;
+    userTokenProvider: UserTokenProvider;
+    baseUrl: string;
+    locale: JokkooLocale;
+    debug: boolean;
+    tokenRefreshBufferSeconds: number;
+}
+interface JokkooState {
+    initialized: boolean;
+    clientToken?: string;
+    baseUrl?: string;
+    locale?: JokkooLocale;
+}
+
+declare class TokenManager {
+    private readonly config;
+    private readonly debug;
+    private cachedToken;
+    private refreshTimer;
+    private inflightRefresh;
+    private state;
+    private listeners;
+    constructor(config: ResolvedJokkooConfig);
+    subscribe(listener: TokenStateListener): () => void;
+    getState(): TokenState;
+    getToken(): Promise<string>;
+    invalidateCachedToken(): void;
+    refreshToken(): Promise<string>;
+    destroy(): void;
+    private scheduleRefresh;
+    private setState;
+}
+
+declare const CLIENT_TOKEN_HEADER = "x-client-token";
+declare const USER_TOKEN_HEADER = "x-user-token";
+declare class JokkooApiError extends Error {
+    readonly status: number;
+    readonly body?: unknown | undefined;
+    constructor(message: string, status: number, body?: unknown | undefined);
+}
+declare class JokkooApiClient {
+    private readonly config;
+    private readonly tokenManager;
+    private readonly debug;
+    constructor(config: ResolvedJokkooConfig, tokenManager: TokenManager);
+    resolveUrl(path: string): string;
+    getConversations(limit: number, offset: number): Promise<PaginatedResponse<Conversation>>;
+    getUnreadCount(): Promise<UnreadCountResponse>;
+    markAsRead(conversationId: number): Promise<void>;
+    getMessages(conversationId: number, limit: number, offset: number): Promise<PaginatedResponse<Message>>;
+    sendMessage(payload: SendMessagePayload): Promise<Message>;
+    requestUploadUrl(fileName: string, mimeType: string, provider?: "s3" | "r2"): Promise<{
+        fileId: string;
+        uploadUrl: string;
+        expiresAt: string;
+    }>;
+    confirmUpload(fileId: string): Promise<{
+        id: string;
+        fileName: string;
+        mimeType: string;
+        size?: number | null;
+    }>;
+    getDownloadUrl(fileId: string): Promise<{
+        downloadUrl: string;
+        expiresAt: string;
+    }>;
+    getConversationPolicies(): Promise<ClosedConversationPolicy>;
+    recordSatisfaction(conversationId: number, score: number): Promise<void>;
+    private request;
+}
+
+interface DebugLogger {
+    log: (message: string, ...details: unknown[]) => void;
+    warn: (message: string, ...details: unknown[]) => void;
+    error: (message: string, ...details: unknown[]) => void;
+    request: (method: string, url: string, details?: Record<string, unknown>) => void;
+    response: (method: string, url: string, status: number, durationMs: number, details?: Record<string, unknown>) => void;
+    requestError: (method: string, url: string, durationMs: number, error: unknown) => void;
+}
+declare function createDebugLogger(enabled: boolean): DebugLogger;
+declare function redactToken(token: string): string;
+
+type RealtimeStatus = "disconnected" | "connecting" | "connected" | "error";
+type RealtimeStatusListener = (status: RealtimeStatus) => void;
+
+declare class JokkooRealtimeClient {
+    private readonly config;
+    private readonly tokenManager;
+    private socket;
+    private status;
+    private readonly listeners;
+    constructor(config: ResolvedJokkooConfig, tokenManager: TokenManager);
+    connect(): Promise<void>;
+    disconnect(): void;
+    getStatus(): RealtimeStatus;
+    onStatusChange(listener: RealtimeStatusListener): () => void;
+    /** @internal For future event subscription by feature modules */
+    getSocket(): Socket | null;
+    private refreshAuth;
+    private setStatus;
+}
+
+declare class JokkooConfigError extends Error {
+    constructor(message: string);
+}
+declare function validateConfig(config: JokkooConfig): ResolvedJokkooConfig;
+
+declare class JokkooSDK {
+    private config;
+    private tokenManager;
+    private realtimeClient;
+    private initialized;
+    init(config: JokkooConfig): void;
+    destroy(): void;
+    isInitialized(): boolean;
+    getState(): JokkooState;
+    /** @internal Used by UI and future messaging modules */
+    getTokenManager(): TokenManager;
+    /** @internal Used by UI and future messaging modules */
+    getRealtimeClient(): JokkooRealtimeClient;
+    /** @internal Used by UI and future messaging modules */
+    getConfig(): ResolvedJokkooConfig;
+    private assertInitialized;
+}
+declare const Jokkoo: JokkooSDK;
+
+type ChatMessageSender = "user" | "agent" | "system";
+interface ChatAttachment {
+    fileId: string;
+    fileName: string;
+    mimeType: string;
+    size?: number | null;
+}
+interface ChatMessage {
+    id: string;
+    sender: ChatMessageSender;
+    text: string;
+    timestamp: string;
+    agentName?: string;
+    agentInitials?: string;
+    agentAvatarUrl?: string | null;
+    attachments?: ChatAttachment[];
+    metadata?: Record<string, unknown> | null;
+}
+declare function mapApiAttachmentToChatAttachment(attachment: MessageAttachment): ChatAttachment;
+
+declare const REALTIME_EVENTS: {
+    readonly ping: "ping";
+    readonly pong: "pong";
+    readonly messageCreated: "message.created";
+    readonly conversationCreated: "conversation.created";
+    readonly conversationUpdated: "conversation.updated";
+};
+declare const REALTIME_NAMESPACE = "/sdk";
+
+interface Translations {
+    supportCenter: string;
+    activeConversation: (count: number) => string;
+    myRequests: string;
+    newSupportRequest: string;
+    noConversationsYet: string;
+    unableToLoadConversations: string;
+    retry: string;
+    newRequest: string;
+    support: string;
+    noMessagesYet: string;
+    newSupportRequestHeader: string;
+    request: string;
+    typeYourMessage: string;
+    sendMessage: string;
+    recordVoiceMessage: string;
+    unableToLoadMessages: string;
+    discussionEnded: string;
+    discussionClosedCanReply: string;
+    rateConversation: string;
+    rateConversationDescription: string;
+    thankYouForRating: string;
+    ratingVeryUnsatisfied: string;
+    ratingUnsatisfied: string;
+    ratingNeutral: string;
+    ratingSatisfied: string;
+    ratingVerySatisfied: string;
+    sendMessageError: string;
+    statusNew: string;
+    statusInProgress: string;
+    statusResolved: string;
+    statusEnded: string;
+    ticketResolved: string;
+    supportAgent: string;
+    welcomeMessage: string;
+    now: string;
+    newMessageIndicator: (count: number) => string;
+    attachFile: string;
+    pickPhotoLibrary: string;
+    pickCamera: string;
+    pickDocument: string;
+    cancel: string;
+    uploadFailed: string;
+    maxAttachmentsReached: string;
+    sharedFiles: string;
+    uploadingAttachment: string;
+    attachmentReady: string;
+    retryUpload: string;
+    openExternally: string;
+    downloadAttachment: string;
+    previewUnavailableInApp: string;
+    previewLoadFailed: string;
+    previewImageFile: string;
+    previewVideoFile: string;
+    previewDocumentFile: string;
+    voiceMessage: string;
+    recording: string;
+    tapToRecord: string;
+    cancelRecording: string;
+    sendRecording: string;
+    microphonePermissionDenied: string;
+    voiceMessageTooShort: string;
+}
+
+declare const en: Translations;
+
+declare const fr: Translations;
+
+declare function getTranslations(locale?: string): Translations;
+
+declare function isTicketActivityMessage(message: Message): boolean;
+/**
+ * Activity messages that should render as passive in-thread events
+ * (no bubble, no sender). Satisfaction surveys stay special-cased elsewhere.
+ */
+declare function isPassiveActivityMessage(message: Message): boolean;
+/** Agent and system messages (including ticket activities) count toward unread. */
+declare function shouldCountMessageAsUnread(message: Message): boolean;
+
+declare function isImageMimeType(mimeType: string): boolean;
+declare function isVideoMimeType(mimeType: string): boolean;
+declare function isAudioMimeType(mimeType: string): boolean;
+declare function isDocumentMimeType(mimeType: string): boolean;
+declare function canPreviewInApp(mimeType: string): boolean;
+declare function formatAttachmentSize(size?: number | null): string;
+declare function formatAudioDuration(durationMs: number): string;
+declare function isVoiceMessageMetadata(metadata?: Record<string, unknown> | null): metadata is {
+    isVoiceMessage: true;
+    audioDurationMs?: number;
+};
+
+declare function isWithinReopenGracePeriod(conversation: Pick<Conversation, "closedAt">, policy: Pick<ClosedConversationPolicy, "reopenGracePeriodDays">): boolean;
+declare function canReplyToClosedConversation(conversation: Pick<Conversation, "status" | "closedAt">, policy: ClosedConversationPolicy | undefined): boolean;
+
+declare const MESSAGE_CONTENT_MIN_LENGTH = 2;
+declare const MESSAGE_CONTENT_MAX_LENGTH = 2000;
+declare const MAX_IMAGE_SIZE_BYTES: number;
+declare const MAX_VIDEO_SIZE_BYTES: number;
+declare const MAX_DOCUMENT_SIZE_BYTES: number;
+declare const MAX_AUDIO_SIZE_BYTES: number;
+declare const MAX_ATTACHMENTS_PER_MESSAGE = 5;
+declare const ALLOWED_ATTACHMENT_MIME_TYPES: readonly ["image/jpeg", "image/png", "image/gif", "image/webp", "video/mp4", "video/quicktime", "video/webm", "application/pdf", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "audio/aac", "audio/mp4", "audio/mpeg", "audio/webm"];
+declare const VOICE_MESSAGE_MIME_TYPE: "audio/mp4";
+declare const VOICE_MESSAGE_STORAGE_PROVIDER: "s3";
+
+type ConversationTitleSource = Pick<Conversation, "assignedAgentName" | "status">;
+declare function getInitialsFromName(name: string): string;
+declare function getConversationDisplayName(conversation: ConversationTitleSource, t: Translations): string;
+declare function getAgentInitials(assignedAgentName: string | null | undefined, fallback: string): string;
+declare function getAgentDisplayName(assignedAgentName: string | null | undefined, t: Translations): string;
+
+type PendingAttachmentStatus = "pending" | "uploading" | "confirming" | "confirmed" | "error";
+interface PendingAttachment {
+    id: string;
+    fileName: string;
+    mimeType: string;
+    uri: string;
+    size: number;
+    status: PendingAttachmentStatus;
+    progress: number;
+    error?: string;
+    confirmedFileId?: string;
+}
+declare function uploadAttachmentFile(apiClient: JokkooApiClient, attachment: PendingAttachment, onProgress: (progress: number, status: PendingAttachmentStatus) => void): Promise<PendingAttachment>;
+declare function createPendingAttachment(input: {
+    fileName: string;
+    mimeType: string;
+    uri: string;
+    size: number;
+}): PendingAttachment;
+declare function canAddMoreAttachments(currentCount: number): boolean;
+
+type SupportedLocale = "fr" | "en";
+declare function formatMessageTimestamp(value: string | Date, locale?: string): string;
+declare function formatRelativeTimestamp(value: string | Date, options?: {
+    locale?: string;
+    nowLabel?: string;
+}): string;
+
+declare function mapMessageToChatMessage(message: Message, translations: Translations, locale?: string, assignedAgentName?: string | null, assignedAgentAvatarUrl?: string | null): ChatMessage;
+declare function createWelcomeMessage(translations: Translations): ChatMessage;
+
+type MessagesPageParam = "latest" | number;
+declare function fetchMessagesPage(apiClient: JokkooApiClient, conversationId: number, pageSize: number, pageParam: MessagesPageParam): Promise<PaginatedResponse<Message>>;
+declare function getOlderMessagesPageParam(lastPage: PaginatedResponse<Message>): number | undefined;
+
+type RealtimeConversationPayload = {
+    id: number;
+    endUserId: number;
+    channelType: ChannelType | string;
+    status: string;
+    lastMessageText: string | null;
+    lastMessageAt?: string | Date | null;
+    assignedAgentName?: string | null;
+    createdAt: string | Date;
+    updatedAt: string | Date;
+};
+declare function mapRealtimeConversationPayload(conversation: RealtimeConversationPayload): Conversation;
+declare function normalizeRealtimeMessage(message: Message): Message;
+
+declare function isSatisfactionRequestMessage(message: Message): boolean;
+declare function getSatisfactionSurveyMessage(messages: Message[]): string | undefined;
+declare function conversationNeedsRating(status: ConversationStatus | undefined, messages: Message[]): boolean;
+
+declare function normalizeMeteringLevel(metering: number): number;
+declare function smoothMeteringSample(previous: number, next: number, alpha?: number): number;
+declare function createIdleMeteringLevels(barCount?: number): number[];
+declare function shiftMeteringLevel(levels: number[], newLevel: number): number[];
+declare function applyLiveBarVariation(level: number, index: number): number;
+declare function createPlaybackBarHeights(count: number, seed: number): number[];
+declare function blendLiveWaveformLevels(levels: number[]): number[];
+
+declare function uploadVoiceRecording(apiClient: JokkooApiClient, uri: string, fileName: string, onProgress?: (progress: number) => void): Promise<string>;
+/** Upload a voice recording Blob directly (preferred for web MediaRecorder). */
+declare function uploadVoiceBlob(apiClient: JokkooApiClient, blob: Blob, fileName: string, mimeType?: string, onProgress?: (progress: number) => void): Promise<string>;
+declare function createVoiceMessageFileName(extension?: string): string;
+
+export { ALLOWED_ATTACHMENT_MIME_TYPES, CLIENT_TOKEN_HEADER, type ChannelType, type ChatAttachment, type ChatMessage, type ChatMessageSender, type ClosedConversationPolicy, type Conversation, type ConversationId, type ConversationStatus, type DebugLogger, Jokkoo, JokkooApiClient, JokkooApiError, type JokkooConfig, JokkooConfigError, type JokkooLocale, JokkooRealtimeClient, type JokkooState, MAX_ATTACHMENTS_PER_MESSAGE, MAX_AUDIO_SIZE_BYTES, MAX_DOCUMENT_SIZE_BYTES, MAX_IMAGE_SIZE_BYTES, MAX_VIDEO_SIZE_BYTES, MESSAGE_CONTENT_MAX_LENGTH, MESSAGE_CONTENT_MIN_LENGTH, type Message, type MessageAttachment, type MessageMetadata, type MessageSenderType, type MessageType, NEW_CONVERSATION_ID, type PaginatedResponse, type PendingAttachment, type PendingAttachmentStatus, REALTIME_EVENTS, REALTIME_NAMESPACE, type RealtimeConversationPayload, type RealtimeStatus, type RealtimeStatusListener, type ResolvedJokkooConfig, type SendMessagePayload, type SupportedLocale, TokenManager, type TokenState, type TokenStateListener, type Translations, USER_TOKEN_HEADER, type UnreadCountResponse, type UserTokenProvider, VOICE_MESSAGE_MIME_TYPE, VOICE_MESSAGE_STORAGE_PROVIDER, applyLiveBarVariation, blendLiveWaveformLevels, canAddMoreAttachments, canPreviewInApp, canReplyToClosedConversation, conversationNeedsRating, createDebugLogger, createIdleMeteringLevels, createPendingAttachment, createPlaybackBarHeights, createVoiceMessageFileName, createWelcomeMessage, en, fetchMessagesPage, formatAttachmentSize, formatAudioDuration, formatMessageTimestamp, formatRelativeTimestamp, fr, getAgentDisplayName, getAgentInitials, getConversationDisplayName, getInitialsFromName, getOlderMessagesPageParam, getSatisfactionSurveyMessage, getTranslations, isAudioMimeType, isDocumentMimeType, isImageMimeType, isPassiveActivityMessage, isSatisfactionRequestMessage, isTicketActivityMessage, isVideoMimeType, isVoiceMessageMetadata, isWithinReopenGracePeriod, mapApiAttachmentToChatAttachment, mapMessageToChatMessage, mapRealtimeConversationPayload, normalizeMeteringLevel, normalizeRealtimeMessage, redactToken, shiftMeteringLevel, shouldCountMessageAsUnread, smoothMeteringSample, uploadAttachmentFile, uploadVoiceBlob, uploadVoiceRecording, validateConfig };