feat: add @hypr/helpchat foundation package

packages/helpchat/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@hypr/helpchat",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "~5.8.3"
+  }
+}

packages/helpchat/src/client.ts

@@ -0,0 +1,130 @@
+import type {
+  Contact,
+  Conversation,
+  CreateContactRequest,
+  CreateConversationRequest,
+  FetchFn,
+  HelpChatConfig,
+  Message,
+  SendMessageRequest,
+} from "./types";
+
+function resolveFetch(config: HelpChatConfig): FetchFn {
+  return config.fetchFn ?? globalThis.fetch;
+}
+
+function authHeaders(config: HelpChatConfig): Record<string, string> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+  if (config.accessToken) {
+    headers["Authorization"] = `Bearer ${config.accessToken}`;
+  }
+  return headers;
+}
+
+// ---------------------------------------------------------------------------
+// Contacts
+// ---------------------------------------------------------------------------
+
+export async function createContact(
+  config: HelpChatConfig,
+  req: CreateContactRequest,
+): Promise<Contact> {
+  const fetchFn = resolveFetch(config);
+  const res = await fetchFn(`${config.baseUrl}/support/chatwoot/contact`, {
+    method: "POST",
+    headers: authHeaders(config),
+    body: JSON.stringify(req),
+  });
+  if (!res.ok) {
+    throw new Error(`createContact failed: ${res.status}`);
+  }
+  return res.json() as Promise<Contact>;
+}
+
+// ---------------------------------------------------------------------------
+// Conversations
+// ---------------------------------------------------------------------------
+
+export async function createConversation(
+  config: HelpChatConfig,
+  req: CreateConversationRequest,
+): Promise<{ conversationId: number }> {
+  const fetchFn = resolveFetch(config);
+  const res = await fetchFn(
+    `${config.baseUrl}/support/chatwoot/conversations`,
+    {
+      method: "POST",
+      headers: authHeaders(config),
+      body: JSON.stringify(req),
+    },
+  );
+  if (!res.ok) {
+    throw new Error(`createConversation failed: ${res.status}`);
+  }
+  return res.json() as Promise<{ conversationId: number }>;
+}
+
+export async function listConversations(
+  config: HelpChatConfig,
+  sourceId: string,
+): Promise<Conversation[]> {
+  const fetchFn = resolveFetch(config);
+  const params = new URLSearchParams({ source_id: sourceId });
+  const res = await fetchFn(
+    `${config.baseUrl}/support/chatwoot/conversations?${params}`,
+    {
+      method: "GET",
+      headers: authHeaders(config),
+    },
+  );
+  if (!res.ok) {
+    throw new Error(`listConversations failed: ${res.status}`);
+  }
+  return res.json() as Promise<Conversation[]>;
+}
+
+// ---------------------------------------------------------------------------
+// Messages
+// ---------------------------------------------------------------------------
+
+export async function sendMessage(
+  config: HelpChatConfig,
+  conversationId: number,
+  req: SendMessageRequest,
+): Promise<Message> {
+  const fetchFn = resolveFetch(config);
+  const res = await fetchFn(
+    `${config.baseUrl}/support/chatwoot/conversations/${conversationId}/messages`,
+    {
+      method: "POST",
+      headers: authHeaders(config),
+      body: JSON.stringify(req),
+    },
+  );
+  if (!res.ok) {
+    throw new Error(`sendMessage failed: ${res.status}`);
+  }
+  return res.json() as Promise<Message>;
+}
+
+export async function getMessages(
+  config: HelpChatConfig,
+  conversationId: number,
+  sourceId: string,
+): Promise<Message[]> {
+  const fetchFn = resolveFetch(config);
+  const params = new URLSearchParams({ source_id: sourceId });
+  const res = await fetchFn(
+    `${config.baseUrl}/support/chatwoot/conversations/${conversationId}/messages?${params}`,
+    {
+      method: "GET",
+      headers: authHeaders(config),
+    },
+  );
+  if (!res.ok) {
+    throw new Error(`getMessages failed: ${res.status}`);
+  }
+  return res.json() as Promise<Message[]>;
+}

packages/helpchat/src/events.ts

@@ -0,0 +1,68 @@
+import type { AgentMessage, FetchFn, HelpChatConfig } from "./types";
+
+export interface EventStreamOptions {
+  config: HelpChatConfig;
+  conversationId: number;
+  pubsubToken: string;
+  onMessage: (message: AgentMessage) => void;
+  signal?: AbortSignal;
+}
+
+/**
+ * Connect to the SSE event stream for real-time human agent messages.
+ *
+ * The backend proxies Chatwoot's ActionCable WebSocket into a plain SSE
+ * stream at `/support/chatwoot/conversations/{id}/events`.
+ *
+ * Resolves when the stream ends; rejects on connection error.
+ */
+export async function connectEventStream(
+  options: EventStreamOptions,
+): Promise<void> {
+  const { config, conversationId, pubsubToken, onMessage, signal } = options;
+
+  const fetchFn: FetchFn = config.fetchFn ?? globalThis.fetch;
+
+  const params = new URLSearchParams({ pubsub_token: pubsubToken });
+  const url = `${config.baseUrl}/support/chatwoot/conversations/${conversationId}/events?${params}`;
+
+  const headers: Record<string, string> = { Accept: "text/event-stream" };
+  if (config.accessToken) {
+    headers["Authorization"] = `Bearer ${config.accessToken}`;
+  }
+
+  const res = await fetchFn(url, { method: "GET", headers, signal });
+
+  if (!res.ok || !res.body) {
+    throw new Error(`event stream failed: ${res.status}`);
+  }
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+
+    buffer += decoder.decode(value, { stream: true });
+    const parts = buffer.split("\n\n");
+    buffer = parts.pop() ?? "";
+
+    for (const part of parts) {
+      const dataLine = part
+        .split("\n")
+        .find((line) => line.startsWith("data: "));
+      if (!dataLine) continue;
+
+      try {
+        const payload = JSON.parse(dataLine.slice(6)) as AgentMessage;
+        if (payload.content) {
+          onMessage(payload);
+        }
+      } catch {
+        // skip malformed SSE frames
+      }
+    }
+  }
+}

packages/helpchat/src/index.ts

@@ -0,0 +1,22 @@
+export type {
+  AgentMessage,
+  Contact,
+  Conversation,
+  CreateContactRequest,
+  CreateConversationRequest,
+  FetchFn,
+  HelpChatConfig,
+  Message,
+  SendMessageRequest,
+} from "./types";
+
+export {
+  createContact,
+  createConversation,
+  getMessages,
+  listConversations,
+  sendMessage,
+} from "./client";
+
+export { connectEventStream } from "./events";
+export type { EventStreamOptions } from "./events";

packages/helpchat/src/types.ts

@@ -0,0 +1,56 @@
+/** Custom fetch function signature for platform-agnostic HTTP. */
+export type FetchFn = typeof globalThis.fetch;
+
+/** Configuration for connecting to the helpchat backend. */
+export interface HelpChatConfig {
+  /** Base URL of the support API (e.g. "https://api.example.com"). */
+  baseUrl: string;
+  /** Optional auth token included as Bearer header. */
+  accessToken?: string | null;
+  /** Optional custom fetch implementation (e.g. Tauri HTTP plugin). */
+  fetchFn?: FetchFn;
+}
+
+// ---------------------------------------------------------------------------
+// Request / Response shapes (mirror crates/api-support/src/routes/chatwoot/)
+// ---------------------------------------------------------------------------
+
+export interface CreateContactRequest {
+  identifier: string;
+  name?: string;
+  email?: string;
+  customAttributes?: Record<string, unknown>;
+}
+
+export interface Contact {
+  sourceId: string;
+  pubsubToken: string;
+}
+
+export interface CreateConversationRequest {
+  sourceId: string;
+  customAttributes?: Record<string, unknown>;
+}
+
+export interface Conversation {
+  id: number;
+  inboxId: string | null;
+}
+
+export interface SendMessageRequest {
+  content: string;
+  messageType?: "incoming" | "outgoing";
+  sourceId?: string;
+}
+
+export interface Message {
+  id: string;
+  content: string | null;
+  messageType: string | null;
+  createdAt: string | null;
+}
+
+export interface AgentMessage {
+  content: string;
+  senderName: string;
+}

packages/helpchat/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "include": ["src"],
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2023", "DOM"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "isolatedModules": true,
+    "noEmit": true,
+    "strict": true
+  }
+}