@aleph-alpha/chat-kit 1.0.0 → 1.1.0

package/src/composables/useConversations.ts

@@ -0,0 +1,321 @@
+import { generateId, secondsToDate, toError } from '../helpers';
+import type {
+  ConversationSummary,
+  HttpClient,
+  RawConversation,
+  RawConversationList,
+} from '../services/types';
+import { computed, readonly, ref, shallowRef, type Ref } from 'vue';
+
+/**
+ * Internal mapped shape of a list response. Combines the OpenAI envelope's
+ * `has_more` + `last_id` into a single `nextCursor` (null when no more pages),
+ * which is all the composable's pagination loop needs. Not exported because
+ * consumers never see it — they interact via `conversations`, `hasMore`,
+ * and `fetchMore()`.
+ */
+interface ConversationPage {
+  items: ConversationSummary[];
+  nextCursor: string | null;
+}
+
+export interface UseConversationsOptions {
+  httpClient: HttpClient;
+  /** REST path for the conversations resource, e.g. `/conversations`. */
+  path: string;
+  /** Default page size for `fetch` / `fetchMore`. Default: 20. */
+  pageSize?: number;
+}
+
+export interface CreateConversationInput {
+  title?: string;
+  /**
+   * Extra fields merged into the request body's `metadata` object. chat-kit
+   * does not bake in any default metadata; pass anything the server expects
+   * here (e.g. `{ application: 'tiger-chat' }`).
+   */
+  metadata?: Record<string, unknown>;
+}
+
+export interface MutationOptions {
+  /**
+   * If `true`, mutate the local list before the network call and roll back
+   * on failure. Default: `false`.
+   */
+  optimistic?: boolean;
+}
+
+export interface UseConversationsReturn {
+  /**
+   * Reactive list. Readonly so callers cannot mutate the array itself */
+  conversations: Readonly<Ref<readonly ConversationSummary[]>>;
+  /**
+   * True while any fetch or mutation is in flight. Backed by an internal
+   * counter, so it stays `true` for the duration of overlapping operations
+   * and only flips back to `false` once every in-progress request has settled.
+   */
+  isLoading: Readonly<Ref<boolean>>;
+  /** True when the server reported another cursor on the last page. */
+  hasMore: Readonly<Ref<boolean>>;
+  /** Last error from any operation, or `null`. Cleared on the next call. */
+  error: Readonly<Ref<Error | null>>;
+  /** Load the first page. Replaces the list and resets the cursor. */
+  fetch(options?: { limit?: number }): Promise<void>;
+  /** Load the next page using the cursor stored internally. No-op if `!hasMore`. */
+  fetchMore(): Promise<void>;
+  /**
+   * Fetch a single conversation by id from the server. Pure fetch: the list
+   * is not touched (no insert, no replace). Useful for resolving a
+   * conversation that isn't on the first page (e.g. deep-linked URL after a
+   * page reload) where the caller just needs its title or metadata.
+   */
+  fetchById(id: string): Promise<ConversationSummary>;
+  /** Create on the server and prepend to the list. */
+  create(
+    input?: CreateConversationInput,
+    options?: MutationOptions,
+  ): Promise<ConversationSummary>;
+  /** Rename on the server and update the list entry in place. */
+  rename(
+    id: string,
+    title: string,
+    options?: MutationOptions,
+  ): Promise<ConversationSummary>;
+  /** Delete on the server and remove from the list. */
+  remove(id: string, options?: MutationOptions): Promise<void>;
+  /** Local lookup. Does not fetch — only checks the in-memory list. */
+  getById(id: string): ConversationSummary | undefined;
+}
+
+const DEFAULT_PAGE_SIZE = 20;
+
+/**
+ * Reactive list of past conversations backed by an OpenAI-style REST API.
+ *
+ * Owns its own pagination cursor and exposes `hasMore` / `fetchMore` so
+ * callers don't manage paging state themselves. The raw server response
+ * (nested `metadata.title`, unix-second timestamps, `has_more` / `last_id`
+ * envelope) is mapped to the simpler `ConversationSummary` shape inside this
+ * composable; consumers never see the raw response.
+ */
+export function useConversations(
+  options: UseConversationsOptions,
+): UseConversationsReturn {
+  const http = options.httpClient;
+  const path = options.path;
+  const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;
+
+  const conversations = ref<ConversationSummary[]>([]);
+  const inflightCount = shallowRef(0);
+  const isLoading = computed(() => inflightCount.value > 0);
+  const hasMore = shallowRef(false);
+  const error = shallowRef<Error | null>(null);
+  let nextCursor: string | null = null;
+
+  function beginRequest(): void {
+    inflightCount.value++;
+    error.value = null;
+  }
+
+  function endRequest(): void {
+    inflightCount.value--;
+  }
+
+  async function fetchPage(params: {
+    limit: number;
+    cursor: string | null;
+  }): Promise<ConversationPage> {
+    const query: Record<string, unknown> = {
+      limit: params.limit,
+      order: 'desc',
+    };
+    if (params.cursor) query.after = params.cursor;
+
+    const raw = await http.get<RawConversationList>(path, { params: query });
+    return mapConversationList(raw);
+  }
+
+  async function fetch(opts?: { limit?: number }): Promise<void> {
+    beginRequest();
+    try {
+      const page = await fetchPage({
+        limit: opts?.limit ?? pageSize,
+        cursor: null,
+      });
+      conversations.value = page.items;
+      nextCursor = page.nextCursor;
+      hasMore.value = page.nextCursor !== null;
+    } catch (e) {
+      error.value = toError(e);
+      throw error.value;
+    } finally {
+      endRequest();
+    }
+  }
+
+  async function fetchMore(): Promise<void> {
+    if (!hasMore.value || nextCursor === null) return;
+    beginRequest();
+    try {
+      const page = await fetchPage({ limit: pageSize, cursor: nextCursor });
+      conversations.value = [...conversations.value, ...page.items];
+      nextCursor = page.nextCursor;
+      hasMore.value = page.nextCursor !== null;
+    } catch (e) {
+      error.value = toError(e);
+      throw error.value;
+    } finally {
+      endRequest();
+    }
+  }
+
+  async function fetchById(id: string): Promise<ConversationSummary> {
+    beginRequest();
+    try {
+      const raw = await http.get<RawConversation>(`${path}/${id}`);
+      return mapConversation(raw);
+    } catch (e) {
+      error.value = toError(e);
+      throw error.value;
+    } finally {
+      endRequest();
+    }
+  }
+
+  async function create(
+    input?: CreateConversationInput,
+    opts?: MutationOptions,
+  ): Promise<ConversationSummary> {
+    const metadata: Record<string, unknown> = { ...(input?.metadata ?? {}) };
+    if (input?.title !== undefined) metadata.title = input.title;
+    const body = { metadata };
+
+    const previous = conversations.value;
+    let placeholder: ConversationSummary | null = null;
+
+    if (opts?.optimistic) {
+      placeholder = makePlaceholder(input?.title);
+      conversations.value = [placeholder, ...previous];
+    }
+
+    beginRequest();
+    try {
+      const raw = await http.post<RawConversation>(path, body);
+      const created = mapConversation(raw);
+
+      conversations.value = placeholder
+        ? conversations.value.map((c) =>
+            c.id === placeholder!.id ? created : c,
+          )
+        : [created, ...conversations.value];
+
+      return created;
+    } catch (e) {
+      if (placeholder) conversations.value = previous;
+      error.value = toError(e);
+      throw error.value;
+    } finally {
+      endRequest();
+    }
+  }
+
+  async function rename(
+    id: string,
+    title: string,
+    opts?: MutationOptions,
+  ): Promise<ConversationSummary> {
+    const previous = conversations.value;
+
+    if (opts?.optimistic) {
+      conversations.value = previous.map((c) =>
+        c.id === id ? { ...c, title, updatedAt: new Date() } : c,
+      );
+    }
+
+    beginRequest();
+    try {
+      const raw = await http.post<RawConversation>(`${path}/${id}`, {
+        metadata: { title },
+      });
+      const updated = mapConversation(raw);
+      conversations.value = conversations.value.map((c) =>
+        c.id === id ? updated : c,
+      );
+      return updated;
+    } catch (e) {
+      if (opts?.optimistic) conversations.value = previous;
+      error.value = toError(e);
+      throw error.value;
+    } finally {
+      endRequest();
+    }
+  }
+
+  async function remove(id: string, opts?: MutationOptions): Promise<void> {
+    const previous = conversations.value;
+
+    if (opts?.optimistic) {
+      conversations.value = previous.filter((c) => c.id !== id);
+    }
+
+    beginRequest();
+    try {
+      await http.delete(`${path}/${id}`);
+      if (!opts?.optimistic) {
+        conversations.value = previous.filter((c) => c.id !== id);
+      }
+    } catch (e) {
+      if (opts?.optimistic) conversations.value = previous;
+      error.value = toError(e);
+      throw error.value;
+    } finally {
+      endRequest();
+    }
+  }
+
+  function getById(id: string): ConversationSummary | undefined {
+    return conversations.value.find((c) => c.id === id);
+  }
+
+  return {
+    conversations: readonly(conversations) as Readonly<
+      Ref<readonly ConversationSummary[]>
+    >,
+    isLoading,
+    hasMore: readonly(hasMore),
+    error: readonly(error),
+    fetch,
+    fetchMore,
+    fetchById,
+    create,
+    rename,
+    remove,
+    getById,
+  };
+}
+
+function mapConversation(raw: RawConversation): ConversationSummary {
+  return {
+    id: raw.id,
+    title: raw.metadata?.title ?? '',
+    createdAt: secondsToDate(raw.created_at),
+    updatedAt: secondsToDate(raw.updated_at),
+  };
+}
+
+function mapConversationList(raw: RawConversationList): ConversationPage {
+  return {
+    items: raw.data.map(mapConversation),
+    nextCursor: raw.has_more ? (raw.last_id ?? null) : null,
+  };
+}
+
+function makePlaceholder(title: string | undefined): ConversationSummary {
+  const now = new Date();
+  return {
+    id: `pending-${generateId()}`,
+    title: title ?? '',
+    createdAt: now,
+    updatedAt: now,
+  };
+}

package/src/handlers/index.ts

@@ -0,0 +1,9 @@
+export { useMessageHandler } from './useMessageHandler';
+export { useMarkdownParser } from './useMarkdownParser';
+export {
+  provideChatKitLabels,
+  useChatKitLabels,
+  defaultChatKitLabels,
+  CHAT_KIT_LABELS,
+} from './useChatKitLabels';
+export type { ChatKitLabels } from './useChatKitLabels';

package/src/handlers/useChatKitLabels.spec.ts

@@ -0,0 +1,290 @@
+/* eslint-disable vue/one-component-per-file */
+import type { ChatKitLabels } from './useChatKitLabels';
+import {
+  CHAT_KIT_LABELS,
+  defaultChatKitLabels,
+  provideChatKitLabels,
+  useChatKitLabels,
+} from './useChatKitLabels';
+import { render, screen } from '@testing-library/vue';
+import {
+  type ComputedRef,
+  computed,
+  defineComponent,
+  h,
+  nextTick,
+  provide,
+  ref,
+} from 'vue';
+
+describe('useChatKitLabels', () => {
+  it('returns default labels when no provider exists', () => {
+    let result: ComputedRef<ChatKitLabels> | undefined;
+
+    const TestComponent = defineComponent({
+      setup() {
+        result = useChatKitLabels();
+        return () => h('div');
+      },
+    });
+
+    render(TestComponent);
+
+    expect(result!.value).toEqual(defaultChatKitLabels);
+  });
+
+  it('returns provided labels when a ref is used', () => {
+    const customLabels = ref<ChatKitLabels>({
+      agentAvatarAlt: 'Bot-Bild',
+      agentLoadingAvatarAlt: 'Bot lädt',
+      inputPlaceholder: 'Nachricht eingeben...',
+      copyMessageAction: 'Nachricht kopieren',
+      copyMessageActionCopied: 'Kopiert',
+      historyItemUntitled: 'Unbenannte Konversation',
+      historyItemActionAriaLabel: 'Konversationsoptionen',
+      historyItemEditAction: 'Bearbeiten',
+      historyItemDeleteAction: 'Löschen',
+    });
+
+    let result: ComputedRef<ChatKitLabels> | undefined;
+
+    const ChildComponent = defineComponent({
+      setup() {
+        result = useChatKitLabels();
+        return () => h('div');
+      },
+    });
+
+    const ParentComponent = defineComponent({
+      setup() {
+        provideChatKitLabels(customLabels);
+        return () => h(ChildComponent);
+      },
+    });
+
+    render(ParentComponent);
+
+    expect(result!.value).toEqual(customLabels.value);
+  });
+
+  it('merges partial labels with defaults', () => {
+    let result: ComputedRef<ChatKitLabels> | undefined;
+
+    const ChildComponent = defineComponent({
+      setup() {
+        result = useChatKitLabels();
+        return () => h('div');
+      },
+    });
+
+    const ParentComponent = defineComponent({
+      setup() {
+        provideChatKitLabels(() => ({ agentAvatarAlt: 'Agenten-Avatar' }));
+        return () => h(ChildComponent);
+      },
+    });
+
+    render(ParentComponent);
+
+    expect(result!.value).toEqual({
+      ...defaultChatKitLabels,
+      agentAvatarAlt: 'Agenten-Avatar',
+    });
+  });
+
+  it('uses the correct injection key', () => {
+    let result: ComputedRef<ChatKitLabels> | undefined;
+
+    const ChildComponent = defineComponent({
+      setup() {
+        result = useChatKitLabels();
+        return () => h('div');
+      },
+    });
+
+    const customLabels: ChatKitLabels = {
+      agentAvatarAlt: 'Custom alt',
+      agentLoadingAvatarAlt: 'Custom loading',
+      inputPlaceholder: 'Custom placeholder',
+      copyMessageAction: 'Custom copy',
+      copyMessageActionCopied: 'Custom copied',
+      historyItemUntitled: 'Custom untitled',
+      historyItemActionAriaLabel: 'Custom options',
+      historyItemEditAction: 'Custom edit',
+      historyItemDeleteAction: 'Custom delete',
+    };
+
+    const ParentComponent = defineComponent({
+      setup() {
+        provide(
+          CHAT_KIT_LABELS,
+          computed(() => customLabels),
+        );
+        return () => h(ChildComponent);
+      },
+    });
+
+    render(ParentComponent);
+
+    expect(result!.value).toEqual(customLabels);
+  });
+
+  it('reacts to label changes when a getter is provided', async () => {
+    let result: ComputedRef<ChatKitLabels> | undefined;
+
+    const locale = ref<'en' | 'de'>('en');
+
+    const translations = {
+      en: { agentAvatarAlt: 'Agent avatar' },
+      de: { agentAvatarAlt: 'Agenten-Avatar' },
+    };
+
+    const ChildComponent = defineComponent({
+      setup() {
+        result = useChatKitLabels();
+        return () => h('div');
+      },
+    });
+
+    const ParentComponent = defineComponent({
+      setup() {
+        provideChatKitLabels(() => translations[locale.value]);
+        return () => h(ChildComponent);
+      },
+    });
+
+    render(ParentComponent);
+
+    expect(result!.value.agentAvatarAlt).toBe('Agent avatar');
+
+    locale.value = 'de';
+    await nextTick();
+
+    expect(result!.value.agentAvatarAlt).toBe('Agenten-Avatar');
+  });
+
+  it('reacts to label changes when a ref is provided', async () => {
+    let result: ComputedRef<ChatKitLabels> | undefined;
+
+    const overrides = ref<Partial<ChatKitLabels>>({
+      inputPlaceholder: 'Type here...',
+    });
+
+    const ChildComponent = defineComponent({
+      setup() {
+        result = useChatKitLabels();
+        return () => h('div');
+      },
+    });
+
+    const ParentComponent = defineComponent({
+      setup() {
+        provideChatKitLabels(overrides);
+        return () => h(ChildComponent);
+      },
+    });
+
+    render(ParentComponent);
+
+    expect(result!.value.inputPlaceholder).toBe('Type here...');
+
+    overrides.value = { inputPlaceholder: 'Nachricht eingeben...' };
+    await nextTick();
+
+    expect(result!.value.inputPlaceholder).toBe('Nachricht eingeben...');
+  });
+
+  it('accepts a computed ref', () => {
+    let result: ComputedRef<ChatKitLabels> | undefined;
+
+    const locale = ref<'en' | 'de'>('en');
+    const labels = computed(() =>
+      locale.value === 'de'
+        ? { agentAvatarAlt: 'Agenten-Avatar' }
+        : { agentAvatarAlt: 'Agent avatar' },
+    );
+
+    const ChildComponent = defineComponent({
+      setup() {
+        result = useChatKitLabels();
+        return () => h('div');
+      },
+    });
+
+    const ParentComponent = defineComponent({
+      setup() {
+        provideChatKitLabels(labels);
+        return () => h(ChildComponent);
+      },
+    });
+
+    render(ParentComponent);
+
+    expect(result!.value.agentAvatarAlt).toBe('Agent avatar');
+  });
+
+  it('rejects plain objects at the type level', () => {
+    // @ts-expect-error — plain objects must not be accepted
+    provideChatKitLabels({ agentAvatarAlt: 'nope' });
+    expect(true).toBe(true);
+  });
+
+  it('rejects plain strings at the type level', () => {
+    // @ts-expect-error — strings must not be accepted
+    provideChatKitLabels('nope');
+    expect(true).toBe(true);
+  });
+});
+
+describe('CkConversation uses injected labels', () => {
+  it('uses default agentAvatarAlt when no labels are provided', async () => {
+    const { default: CkConversation } =
+      await import('../components/composed/CkConversation/CkConversation.vue');
+
+    render(CkConversation, {
+      props: {
+        messages: [
+          {
+            id: '1',
+            role: 'assistant',
+            content: 'Hi',
+            createdAt: new Date(),
+            status: 'completed',
+          },
+        ],
+        agentAvatarImage: 'bot.png',
+      },
+    });
+
+    expect(screen.getByAltText('Agent avatar')).toBeInTheDocument();
+  });
+
+  it('uses injected agentAvatarAlt from provideChatKitLabels', async () => {
+    const { default: CkConversation } =
+      await import('../components/composed/CkConversation/CkConversation.vue');
+
+    const Wrapper = defineComponent({
+      setup() {
+        provideChatKitLabels(() => ({ agentAvatarAlt: 'Bot-Bild' }));
+        return () =>
+          h(CkConversation, {
+            messages: [
+              {
+                id: '1',
+                role: 'assistant',
+                content: 'Hi',
+                createdAt: new Date(),
+                status: 'completed',
+              },
+            ],
+            agentAvatarImage: 'bot.png',
+          });
+      },
+    });
+
+    render(Wrapper);
+
+    expect(screen.getByAltText('Bot-Bild')).toBeInTheDocument();
+    expect(screen.queryByAltText('Agent avatar')).not.toBeInTheDocument();
+  });
+});

package/src/handlers/useChatKitLabels.ts

@@ -0,0 +1,96 @@
+import type { ComputedRef, InjectionKey, Ref } from 'vue';
+import { computed, inject, provide, toValue } from 'vue';
+
+/**
+ * All user-facing strings in ChatKit that may need translation.
+ *
+ * Consumers override these values by calling `provideChatKitLabels()`
+ * at the top of their component tree and passing translated strings.
+ *
+ * @example
+ * ```ts
+ * import { provideChatKitLabels } from '@aleph-alpha/chat-kit';
+ *
+ * const { t } = useI18n();
+ * provideChatKitLabels(() => ({
+ *   agentAvatarAlt: t('chat.agentAvatarAlt'),
+ *   inputPlaceholder: t('chat.inputPlaceholder'),
+ * }));
+ * ```
+ */
+export type ChatKitLabels = {
+  /** Alt text for the agent avatar image */
+  agentAvatarAlt: string;
+  /** Alt text for the loading avatar image */
+  agentLoadingAvatarAlt: string;
+  /** Placeholder text for the chat input field */
+  inputPlaceholder: string;
+  /** Accessible label / tooltip for the copy-message action button in its idle state */
+  copyMessageAction: string;
+  /** Accessible label / tooltip for the copy-message action button after a successful copy */
+  copyMessageActionCopied: string;
+  /** Fallback title used by `CkHistory` when a conversation has no `title`. */
+  historyItemUntitled: string;
+  /** Accessible name for the trailing kebab trigger on each `CkHistory` row. */
+  historyItemActionAriaLabel: string;
+  /** Label for the "Edit" action in the `CkHistory` row popover menu. */
+  historyItemEditAction: string;
+  /** Label for the "Delete" action in the `CkHistory` row popover menu. */
+  historyItemDeleteAction: string;
+};
+
+/** English defaults used when no labels are provided by the consumer. */
+export const defaultChatKitLabels: ChatKitLabels = {
+  agentAvatarAlt: 'Agent avatar',
+  agentLoadingAvatarAlt: 'Agent loading',
+  inputPlaceholder: 'Type a message...',
+  copyMessageAction: 'Copy response',
+  copyMessageActionCopied: 'Copied!',
+  historyItemUntitled: 'Untitled conversation',
+  historyItemActionAriaLabel: 'Conversation options',
+  historyItemEditAction: 'Edit',
+  historyItemDeleteAction: 'Delete',
+};
+
+/** Vue injection key for ChatKit labels. */
+export const CHAT_KIT_LABELS: InjectionKey<ComputedRef<ChatKitLabels>> =
+  Symbol('chat-kit-labels');
+
+type PartialLabels = Partial<ChatKitLabels>;
+
+/** Only accepts `Ref`, `ComputedRef`, or a getter returning `Partial<ChatKitLabels>`. */
+type ReactiveLabels =
+  | Ref<PartialLabels>
+  | ComputedRef<PartialLabels>
+  | (() => PartialLabels);
+
+/**
+ * Provide ChatKit labels to all descendant components.
+ * Call this in a parent component's `setup()` to override default English strings.
+ *
+ * Only reactive sources are accepted (`Ref`, `ComputedRef`, or a getter function)
+ * so that labels update automatically when the consumer's locale changes.
+ *
+ * Partial overrides are merged with the defaults so consumers only need to
+ * supply the keys they want to translate.
+ */
+export function provideChatKitLabels(labels: ReactiveLabels): void {
+  provide(
+    CHAT_KIT_LABELS,
+    computed(() => ({ ...defaultChatKitLabels, ...toValue(labels) })),
+  );
+}
+
+/**
+ * Retrieve ChatKit labels inside any ChatKit component.
+ * Falls back to `defaultChatKitLabels` when no ancestor has provided labels.
+ *
+ * Returns a `ComputedRef` so that template bindings update automatically
+ * when the provided labels change (e.g. on locale switch).
+ */
+export function useChatKitLabels(): ComputedRef<ChatKitLabels> {
+  return inject(
+    CHAT_KIT_LABELS,
+    computed(() => defaultChatKitLabels),
+  );
+}