@proteos/sdk 0.18.1

package/src/conversation/types.ts

@@ -0,0 +1,590 @@
+/**
+ * Wire types for conversation-service (/conversations/v1) — hand-maintained
+ * mirror of packages/go/model/conversation (snake_case, Is-prefixed booleans).
+ */
+
+import type { FileRef } from '../types/common.js'
+
+/** Platform medium a conversation lives on (closed enum; platform identity). */
+export type Channel =
+  | 'slack'
+  | 'email'
+  | 'linkedin'
+  | 'sms'
+  | 'teams'
+  | 'telegram'
+  | 'whatsapp'
+  | 'meeting'
+  | 'adhoc'
+  | 'instagram'
+  | 'messenger'
+  | 'x'
+
+/**
+ * Concrete integration serving a channel (typed union — one value per shipped
+ * connector; runtime availability is decided by the service's registry).
+ * The unipile-* family serves the six messaging systems aggregated through
+ * Unipile — one key per messaging system.
+ */
+export type ConnectorKey =
+  | 'slack'
+  | 'gmail'
+  | 'echo'
+  | 'unipile-whatsapp'
+  | 'unipile-linkedin'
+  | 'unipile-telegram'
+  | 'unipile-instagram'
+  | 'unipile-messenger'
+  | 'unipile-x'
+
+/**
+ * Who operates the integration mechanics behind a connector: Proteos' own
+ * integration (native) or an account aggregated through Unipile (unipile).
+ * Computed on connection reads; the UI groups the connector catalog by it.
+ */
+export type ConnectorProvider = 'native' | 'unipile'
+
+export type MessageDirection = 'inbound' | 'outbound'
+export type MessageStatus = 'received' | 'pending' | 'sent' | 'failed'
+export type ConnectionScope = 'org' | 'user'
+export type ConnectionStatus = 'pending' | 'active' | 'error' | 'revoked'
+export type ConversationStatus = 'active' | 'ended' | 'archived'
+export type AgentListenerTriggerType = 'always' | 'mention' | 'channel' | 'keyword'
+
+export interface UserRef {
+  type: string
+  id: string
+}
+
+/**
+ * Inline snapshot of a person on a message/reaction — the integration-side
+ * identity plus, when resolved via email match, the platform user.
+ */
+export interface ParticipantRef {
+  external_id?: string
+  name: string
+  email?: string
+  /** Resolved platform identity (email match); absent when unresolved. */
+  platform_user?: UserRef
+}
+
+/**
+ * One member of a conversation's roster — everyone in the thread, INCLUDING the
+ * connected account itself. The account's own entries carry is_self=true; a UI
+ * renders "who it's with" as the non-self subset (1 → single avatar, ≥2 →
+ * stacked).
+ */
+export interface ConversationParticipant extends ParticipantRef {
+  is_self: boolean
+}
+
+/** How a MessageRecipient was addressed: primary, carbon copy, blind copy. */
+export type RecipientRole = 'to' | 'cc' | 'bcc'
+
+/**
+ * One addressee of a message with the role it was addressed under. Bcc is only
+ * present on messages the platform itself sent (inbound bcc is SMTP-stripped).
+ */
+export interface MessageRecipient extends ParticipantRef {
+  role: RecipientRole
+}
+
+/**
+ * One unit of message content — what was SAID. Files a message CARRIED are
+ * NOT content: they are Attachment rows (Message.attachments).
+ */
+export interface ContentBlock {
+  type: 'text' | 'html'
+  text?: string
+  /**
+   * Sanitized rich email body (ingest-time allowlist: layout tables, inline
+   * styles, https images; no scripts/forms/handlers). Rides ALONGSIDE the
+   * canonical text block. Render only in an isolated, script-less surface.
+   */
+  html?: string
+}
+
+/** Secret material is redacted on every read ("********" when set). */
+export interface ConnectionCredentials {
+  bot_token?: string
+  bot_user_id?: string
+  refresh_token?: string
+  access_token?: string
+  token_expires_at?: string
+  granted_scopes?: string
+  /** Aggregator-hosted account identity (unipile-*) — nothing secret. */
+  account_id?: string
+  owner_provider_id?: string
+}
+
+/** How a channel's reaction vocabulary is shaped. */
+export type ReactionSetKind = 'open' | 'fixed'
+
+/** One entry of a fixed reaction vocabulary (token = the value to send). */
+export interface ReactionOption {
+  token: string
+  unicode?: string
+  label?: string
+}
+
+/**
+ * A connector's declarative reaction capability, projected onto the
+ * connection read: open → show an emoji picker; fixed → exactly the allowed
+ * buttons; absent (connection.reactions undefined) → no affordance.
+ */
+export interface ReactionCapability {
+  kind: ReactionSetKind
+  allowed?: ReactionOption[]
+  /** 0 = unbounded (Slack); 1 = single-slot (a new reaction replaces the old). */
+  max_per_actor: number
+}
+
+export interface Connection {
+  id: string
+  org_id: string
+  connector_key: ConnectorKey
+  channel: Channel
+  name: string
+  scope: ConnectionScope
+  /** Set only when scope=user (the connecting user); absent for org-wide. */
+  owner?: UserRef
+  external_workspace_id: string
+  credentials: ConnectionCredentials
+  settings: Record<string, unknown>
+  status: ConnectionStatus
+  /** Computed on read: the connector implements the reaction capability. */
+  supports_reactions: boolean
+  /** The capability descriptor; absent when unsupported. */
+  reactions?: ReactionCapability
+  /**
+   * Computed on read like supports_reactions: who operates the integration
+   * (native | unipile). Absent when the connector is not registered in this
+   * environment.
+   */
+  provider?: ConnectorProvider
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+export interface Conversation {
+  id: string
+  org_id: string
+  connection_id: string
+  channel: Channel
+  external_conversation_id: string
+  subject: string
+  status: ConversationStatus
+  /**
+   * Room directory row a room-borne thread (Slack channel conversation) lives
+   * in; absent for DMs, email, meeting, adhoc.
+   */
+  room_id?: string
+  /**
+   * Main conversation a child conversation forked from (Slack: the channel's
+   * main conversation; provider-side the child is a native Slack thread);
+   * absent for main/DM/email/meeting/adhoc.
+   */
+  parent_conversation_id?: string
+  /**
+   * Message id of the child conversation's root message, which lives in the
+   * parent conversation; absent when the root is unknown (predates ingest).
+   */
+  started_by_message_id?: string
+  started_at?: string
+  ended_at?: string
+  /**
+   * The thread's complete roster — everyone in it, including the connected
+   * account (its own entries marked is_self). Deduped by external_id; the
+   * queryable person dimension. Replaces the old single `counterpart`.
+   */
+  participants?: ConversationParticipant[]
+  last_message_at: string
+  metadata: Record<string, unknown>
+  /**
+   * Messages summary — present only when the list opted in via
+   * include: 'messages_summary'. Renders a hub stream row (root on Slack,
+   * latest on email, reply affordance) without a per-conversation fetch.
+   */
+  root_message?: MessagePreview
+  latest_message?: MessagePreview
+  messages_total?: number
+  /** Up to 3 most recent distinct senders excluding the root sender. */
+  last_repliers?: ParticipantRef[]
+  /** Requesting user's read marker; absent = never opened. */
+  last_read_at?: string
+  /**
+   * Server-computed unread predicate for the requesting user: activity after
+   * the marker AND the latest message is inbound.
+   */
+  is_unread: boolean
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+/**
+ * Compact snapshot of one message riding on conversation reads
+ * (include: 'messages_summary'): enough for a stream row — who, the first
+ * ~500 chars of text, direction/status for outbound identity.
+ */
+export interface MessagePreview {
+  sender: ParticipantRef
+  text: string
+  direction: MessageDirection
+  status: MessageStatus
+  occurred_at: string
+}
+
+/**
+ * Aggregated unread-conversation counts for the requesting user (unit:
+ * conversations, not messages) — the envelope total and per-channel badges.
+ */
+export interface UnreadCounts {
+  total: number
+  channels: Partial<Record<Channel, number>>
+}
+
+/**
+ * One file that arrived with a message. `file` is the platform FileRef —
+ * bytes live in storage-service; size and content type resolve from storage
+ * by id. content_id/is_inline carry the MIME inline-image semantics
+ * (cid: references in the html body vs user-facing downloads).
+ */
+export interface Attachment {
+  id: string
+  org_id: string
+  message_id: string
+  connection_id: string
+  file: FileRef
+  content_id?: string
+  is_inline: boolean
+  created_at: string
+  created_by: UserRef
+}
+
+/** Aggregated reactions on a message: one entry per emoji (native token). */
+export interface Reaction {
+  emoji: string
+  count: number
+  participants: ParticipantRef[]
+}
+
+export interface Message {
+  id: string
+  org_id: string
+  conversation_id: string
+  connection_id: string
+  channel: Channel
+  direction: MessageDirection
+  external_message_id: string
+  sender: ParticipantRef
+  /** Who the message was addressed to (To/Cc/Bcc), each tagged with its role. */
+  recipients?: MessageRecipient[]
+  content: ContentBlock[]
+  status: MessageStatus
+  occurred_at: string
+  /** Read-time projection; absent/empty on channels without reactions. */
+  reactions?: Reaction[]
+  /** Read-time projection of the message's attachment rows; absent without files. */
+  attachments?: Attachment[]
+  /**
+   * Child-conversation projection (read-time, per-conversation lists): the
+   * conversation rooted at this message and its message count — the "N
+   * replies" affordance. Absent for messages no child conversation forked
+   * from.
+   */
+  child_conversation_id?: string
+  child_messages_total?: number
+  metadata: Record<string, unknown>
+  error: string
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+/**
+ * Per-trigger configuration, discriminated by the sibling trigger_type: channel
+ * carries external_channel_id, keyword carries phrases, always/mention carry
+ * neither. (Serialized as the bare variant; both fields optional here.)
+ */
+export interface AgentListenerTriggerConfig {
+  external_channel_id?: string
+  phrases?: string[]
+}
+
+export interface AgentListener {
+  id: string
+  org_id: string
+  connection_id: string
+  conversation_id: string
+  name: string
+  agent_key: string
+  trigger_type: AgentListenerTriggerType
+  trigger_config: AgentListenerTriggerConfig
+  /** The user the dispatcher acts as when driving the agent. */
+  acting_user: UserRef
+  is_enabled: boolean
+  priority: number
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+export interface CreateConnectionRequest {
+  connector_key: ConnectorKey
+  name: string
+  scope: ConnectionScope
+  settings?: Record<string, unknown>
+}
+
+export interface UpdateConnectionRequest {
+  name?: string
+  settings?: Record<string, unknown>
+}
+
+export interface InstallConnectionResponse {
+  authorization_url: string
+}
+
+export interface SendMessageRequest {
+  /** Reply mode: send into this existing conversation. */
+  conversation_id?: string
+  /**
+   * Targeted reply: reply aimed at ONE message (mutually exclusive with the
+   * other modes). Slack starts/continues the child conversation rooted at
+   * that message (carrying parent_conversation_id/started_by_message_id —
+   * provider-side a native Slack thread); email replies in the same
+   * conversation with In-Reply-To anchored at the target; channels without
+   * message-targeted replies reject with `child_conversation_not_supported`.
+   */
+  reply_to_message_id?: string
+  /** Originate mode (omit conversation_id): connection_id + at least one To are required. */
+  connection_id?: string
+  /**
+   * Primary destinations for originate: one room (Slack channel) OR one-or-more
+   * participants (email To, a Slack DM, or several users → a Slack MPIM).
+   */
+  to?: SendRecipient[]
+  /** Carbon-copy participants (email only). */
+  cc?: SendRecipient[]
+  /** Blind-carbon-copy participants (email only). */
+  bcc?: SendRecipient[]
+  /** Optional subject, used by email when originating. */
+  subject?: string
+  /** May be empty when attachments are present. */
+  content: ContentBlock[]
+  /**
+   * Files to send with the message. Pre-upload each file to storage-service
+   * and reference it here ({id, name}); the server downloads the bytes and
+   * hands them to the channel connector (Slack: one native message with the
+   * text as its comment; Gmail: multipart/mixed mail; ≤25MB per file, Slack
+   * ≤10 files per message). Channels without file support reject with
+   * `unsupported_content`.
+   */
+  attachments?: FileRef[]
+}
+
+export interface CreateAgentListenerRequest {
+  connection_id?: string
+  conversation_id?: string
+  name: string
+  agent_key: string
+  trigger_type: AgentListenerTriggerType
+  trigger_config?: AgentListenerTriggerConfig
+  /** A bare user id; the service wraps it into a person UserRef. */
+  acting_user_id: string
+  /** Omit to default to enabled. */
+  is_enabled?: boolean
+  priority?: number
+}
+
+export interface UpdateAgentListenerRequest {
+  name?: string
+  agent_key?: string
+  trigger_type?: AgentListenerTriggerType
+  trigger_config?: AgentListenerTriggerConfig
+  acting_user_id?: string
+  is_enabled?: boolean
+  priority?: number
+}
+
+export interface PaginationQuery {
+  page?: number
+  page_size?: number
+  sort_by?: string
+  sort_direction?: 'asc' | 'desc'
+}
+
+export interface ListConnectionsQuery extends PaginationQuery {
+  connector_key?: string
+  channel?: string
+  scope?: string
+  status?: string
+}
+
+export interface ListConversationsQuery extends PaginationQuery {
+  channel?: string
+  status?: string
+  connection_id?: string
+  /** Conversations of one room (Slack channel) — the room stream. */
+  room_id?: string
+  /** Child conversations forked from one main conversation. */
+  parent_conversation_id?: string
+  /** Threads whose roster contains this external party — the person stream. */
+  participant_external_id?: string
+  /** Opt into the root/latest message projection on each row. */
+  include?: 'messages_summary'
+}
+
+export interface ListMessagesQuery extends PaginationQuery {
+  direction?: string
+  status?: string
+}
+
+export interface ListAgentListenersQuery extends PaginationQuery {
+  connection_id?: string
+  conversation_id?: string
+  agent_key?: string
+  is_enabled?: boolean
+}
+
+/** Discriminates a send target: a person or a venue. */
+export type RecipientKind = 'participant' | 'room'
+export type ParticipantSource = 'sync' | 'ingest'
+export type RoomSource = 'sync' | 'ingest'
+
+/**
+ * Send-time addressing VO: who/where an originated message goes. Points at a
+ * Participant or a Room by kind + external id (never a stored entity itself).
+ */
+export interface SendRecipient {
+  kind: RecipientKind
+  /** The connector-side id: a room's (Slack channel id) or a participant's (Slack user id, email address). */
+  external_id: string
+}
+
+/** A PERSON known on a connection (directory row; resolvable to a platform user). */
+export interface Participant {
+  id: string
+  org_id: string
+  connection_id: string
+  /** Slack user id / email address — the id to DM or email. */
+  external_id: string
+  name: string
+  email?: string
+  /** Resolved platform identity (email match); absent when unresolved. */
+  platform_user?: UserRef
+  metadata: Record<string, unknown>
+  source: ParticipantSource
+  last_seen_at: string
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+/** An addressable VENUE on a connection (Slack channel; later meeting rooms). */
+export interface Room {
+  id: string
+  org_id: string
+  connection_id: string
+  /** Slack channel id — the id to post into. */
+  external_id: string
+  name: string
+  metadata: Record<string, unknown>
+  /** How the row was populated: a directory sweep or minted at ingest. */
+  source: RoomSource
+  last_seen_at: string
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+export interface ListParticipantsQuery extends PaginationQuery {
+  /** Free-text needle matched against display name + external id. */
+  q?: string
+}
+
+export interface ListRoomsQuery extends PaginationQuery {
+  /** Free-text needle matched against name + external id. */
+  q?: string
+}
+
+export interface AddReactionRequest {
+  /** Connector-native token (Slack shortcode like "thumbsup"). */
+  emoji: string
+}
+
+export interface ListReactionsResponse {
+  data: Reaction[]
+}
+
+export interface ResponseMeta {
+  page: number
+  page_size: number
+  items_total: number
+  pages_total: number
+}
+
+export interface ListResponse<T> {
+  meta: ResponseMeta
+  data: T[]
+}
+
+export type TranscriptionStatus = 'pending' | 'processing' | 'completed' | 'failed'
+
+export interface TranscriptTurn {
+  speaker: number
+  speaker_label: string
+  text: string
+  start_ms: number
+  end_ms: number
+  confidence: number
+}
+
+export interface Transcription {
+  id: string
+  org_id: string
+  source_file_id: string
+  audio_file_id: string
+  transcript_file_id: string
+  status: TranscriptionStatus
+  language: string
+  duration_seconds: number
+  model: string
+  is_diarized: boolean
+  turns: TranscriptTurn[]
+  speaker_count: number
+  provider_request_id: string
+  conversation_id: string
+  error: string
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+export interface CreateTranscriptionRequest {
+  file_id: string
+  language?: string
+  model?: string
+  is_diarized?: boolean
+}
+
+/** Channel defaults to adhoc; meeting is the only other allowed target. */
+export interface MaterializeTranscriptionRequest {
+  channel?: Channel
+  subject?: string
+  /** Maps diarized speaker indexes ("0", "1", …) to display names. */
+  speaker_names?: Record<string, string>
+}
+
+export interface ListTranscriptionsQuery extends PaginationQuery {
+  status?: string
+}

package/src/conversation/voice.ts

@@ -0,0 +1,123 @@
+import type { ProteosClient } from '../client.js'
+
+const VOICE_BASE_PATH = '/conversations/v1/voice'
+
+/** One normalized transcription update streamed back from the server. */
+export interface TranscriptResult {
+  /** The recognized text for this segment. */
+  transcript: string
+  /** True once this segment is final and will not change. */
+  is_final: boolean
+  /** True when the server detected end-of-speech (a natural pause). */
+  speech_final: boolean
+  /** Recognition confidence, 0–1. */
+  confidence: number
+}
+
+/** Options for opening a live transcription stream. */
+export interface TranscribeStreamOptions {
+  /** BCP-47 language code (e.g. `en`, `de`). Defaults to the server's default. */
+  language?: string
+  /** Stream interim (non-final) results as audio arrives. Defaults to `true`. */
+  interimResults?: boolean
+  /** Add punctuation to results. Defaults to `true`. */
+  punctuate?: boolean
+  /** Format entities (numbers, dates…) in results. Defaults to `true`. */
+  smartFormat?: boolean
+  /**
+   * Raw audio encoding (e.g. `linear16`). Omit for containerized audio
+   * (WebM/Opus from MediaRecorder), which the server auto-detects.
+   */
+  encoding?: string
+  /** Sample rate in Hz. Required only when `encoding` is set. */
+  sampleRate?: number
+  /** Called for each transcription result. */
+  onResult: (result: TranscriptResult) => void
+  /** Called if the stream errors. */
+  onError?: (error: Event) => void
+  /** Called when the stream closes (either side). */
+  onClose?: () => void
+}
+
+/** A live transcription session: push audio in, results arrive via `onResult`. */
+export interface VoiceTranscriptionStream {
+  /** Forward one audio chunk (binary) to the server. */
+  sendAudio(chunk: Blob | ArrayBufferView | ArrayBuffer): void
+  /** Ask the server to flush pending results without closing the stream. */
+  finalize(): void
+  /** Close the stream. */
+  close(): void
+}
+
+/**
+ * Service for realtime speech-to-text on conversation-service.
+ *
+ * Transcription is a WebSocket: open a stream, push audio chunks, and receive
+ * {@link TranscriptResult}s. The transcription provider is a server-side concern
+ * and is not exposed here.
+ *
+ * @example
+ * ```ts
+ * const stream = await agent.voice.transcribeStream({
+ *   onResult: (r) => console.log(r.transcript, r.is_final),
+ * });
+ * recorder.ondataavailable = (e) => stream.sendAudio(e.data);
+ * // …later: stream.finalize(); stream.close();
+ * ```
+ */
+export interface VoiceService {
+  /**
+   * Opens a live transcription stream and resolves once it is connected.
+   *
+   * @param options - Stream configuration and result/lifecycle callbacks
+   * @returns A handle to push audio and control the stream
+   */
+  transcribeStream(options: TranscribeStreamOptions): Promise<VoiceTranscriptionStream>
+}
+
+export class VoiceServiceImpl implements VoiceService {
+  constructor(private readonly client: ProteosClient) {}
+
+  async transcribeStream(options: TranscribeStreamOptions): Promise<VoiceTranscriptionStream> {
+    const query = buildQuery(options)
+    const socket = await this.client.openWebSocket(`${VOICE_BASE_PATH}/transcribe/stream${query}`)
+    socket.binaryType = 'arraybuffer'
+
+    socket.onmessage = (event: MessageEvent) => {
+      if (typeof event.data !== 'string') return
+      try {
+        options.onResult(JSON.parse(event.data) as TranscriptResult)
+      } catch {
+        // Ignore malformed frames.
+      }
+    }
+    if (options.onError) socket.onerror = options.onError
+    socket.onclose = () => options.onClose?.()
+
+    const isOpen = () => socket.readyState === WebSocket.OPEN
+
+    return {
+      sendAudio: (chunk) => {
+        if (isOpen()) socket.send(chunk)
+      },
+      finalize: () => {
+        if (isOpen()) socket.send(JSON.stringify({ type: 'finalize' }))
+      },
+      close: () => socket.close(),
+    }
+  }
+}
+
+/** Serializes options into the endpoint's query string (snake_case wire format). */
+function buildQuery(options: TranscribeStreamOptions): string {
+  const params = new URLSearchParams()
+  if (options.language) params.set('language', options.language)
+  if (options.interimResults !== undefined)
+    params.set('interim_results', String(options.interimResults))
+  if (options.punctuate !== undefined) params.set('punctuate', String(options.punctuate))
+  if (options.smartFormat !== undefined) params.set('smart_format', String(options.smartFormat))
+  if (options.encoding) params.set('encoding', options.encoding)
+  if (options.sampleRate !== undefined) params.set('sample_rate', String(options.sampleRate))
+  const queryString = params.toString()
+  return queryString ? `?${queryString}` : ''
+}