@proteos/sdk 0.31.0 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteos/sdk",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "license": "Apache-2.0",
   "description": "TypeScript SDK for the Proteos platform",
   "repository": {
@@ -66,8 +66,8 @@
     "tsup": "^8.3.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0",
-    "@proteos/tsconfig": "0.0.0",
-    "@proteos/biome-config": "0.0.0"
+    "@proteos/biome-config": "0.0.0",
+    "@proteos/tsconfig": "0.0.0"
   },
   "scripts": {
     "build": "tsup",

package/src/conversation/index.ts

@@ -1,55 +1,56 @@
 import type { ProteosClient } from '../client.js'
-import { type VoiceService, VoiceServiceImpl } from './voice.js'
 import type {
   AgentListener,
-  CreateTranscriptionRequest,
-  ListTranscriptionsQuery,
-  MaterializeTranscriptionRequest,
-  Transcription,
+  AttachContactAddressRequest,
+  BlockContactRequest,
   Connection,
+  Contact,
+  ContactAddress,
+  ContactErasureRequest,
+  ContactMergeProposal,
   Conversation,
+  ConversationFilter,
+  ConversationFilterEvent,
   CreateAgentListenerRequest,
   CreateConnectionRequest,
+  CreateConversationFilterRequest,
   CreateGlossaryTermRequest,
+  CreateTranscriptionRequest,
   DispatchMeetingBotRequest,
   GlossaryTerm,
   InstallConnectionResponse,
   ListAgentListenersQuery,
   ListConnectionsQuery,
-  ListGlossaryTermsQuery,
-  ListConversationsQuery,
-  ListMessagesQuery,
   ListContactAddressesQuery,
   ListContactMergeProposalsQuery,
   ListContactsQuery,
+  ListConversationFilterEventsQuery,
+  ListConversationFiltersQuery,
+  ListConversationsQuery,
+  ListGlossaryTermsQuery,
+  ListMessagesQuery,
   ListReactionsResponse,
   ListResponse,
   ListRoomsQuery,
-  Message,
-  AttachContactAddressRequest,
-  BlockContactRequest,
-  Contact,
-  ContactAddress,
-  ConversationFilter,
-  ConversationFilterEvent,
-  CreateConversationFilterRequest,
-  ListConversationFilterEventsQuery,
-  ListConversationFiltersQuery,
-  UpdateConversationFilterRequest,
-  ContactErasureRequest,
-  ContactMergeProposal,
+  ListTranscriptionsQuery,
+  MaterializeTranscriptionRequest,
   MergeContactsRequest,
-  RecordPermissionEventRequest,
-  UpdateContactRequest,
+  Message,
   Reaction,
+  RecordPermissionEventRequest,
   Room,
   SendMessageRequest,
+  Transcription,
   UnreadCounts,
   UpdateAgentListenerRequest,
   UpdateConnectionRequest,
+  UpdateContactRequest,
+  UpdateConversationFilterRequest,
   UpdateConversationRequest,
+  UpdateDraftRequest,
   UpdateGlossaryTermRequest,
 } from './types.js'
+import { type VoiceService, VoiceServiceImpl } from './voice.js'
 
 const CONVERSATION_BASE_PATH = '/conversations/v1'
 
@@ -121,11 +122,17 @@ class MeetingServiceImpl implements MeetingService {
   }
 
   remove(conversationId: string): Promise<Conversation> {
-    return this.client.request('DELETE', `${CONVERSATION_BASE_PATH}/meetings/${encodeURIComponent(conversationId)}`)
+    return this.client.request(
+      'DELETE',
+      `${CONVERSATION_BASE_PATH}/meetings/${encodeURIComponent(conversationId)}`,
+    )
   }
 
   summarize(conversationId: string): Promise<Conversation> {
-    return this.client.request('POST', `${CONVERSATION_BASE_PATH}/meetings/${encodeURIComponent(conversationId)}/summarize`)
+    return this.client.request(
+      'POST',
+      `${CONVERSATION_BASE_PATH}/meetings/${encodeURIComponent(conversationId)}/summarize`,
+    )
   }
 }
 
@@ -139,7 +146,10 @@ export interface ConnectionService {
   /** Begin the connector's install flow; open the returned URL in a popup. */
   install(id: string): Promise<InstallConnectionResponse>
   /** Search the contact addresses this connection can reach (org-deduped) for the compose picker. */
-  listContactAddresses(connectionId: string, query?: ListContactAddressesQuery): Promise<ListResponse<ContactAddress>>
+  listContactAddresses(
+    connectionId: string,
+    query?: ListContactAddressesQuery,
+  ): Promise<ListResponse<ContactAddress>>
   /** Search a connection's addressable VENUES (Slack channels) for the compose picker. */
   listRooms(connectionId: string, query?: ListRoomsQuery): Promise<ListResponse<Room>>
 }
@@ -152,7 +162,10 @@ class ConnectionServiceImpl implements ConnectionService {
   }
 
   get(id: string): Promise<Connection> {
-    return this.client.request('GET', `${CONVERSATION_BASE_PATH}/connections/${encodeURIComponent(id)}`)
+    return this.client.request(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/connections/${encodeURIComponent(id)}`,
+    )
   }
 
   create(request: CreateConnectionRequest): Promise<Connection> {
@@ -160,18 +173,31 @@ class ConnectionServiceImpl implements ConnectionService {
   }
 
   update(id: string, request: UpdateConnectionRequest): Promise<Connection> {
-    return this.client.request('PATCH', `${CONVERSATION_BASE_PATH}/connections/${encodeURIComponent(id)}`, request)
+    return this.client.request(
+      'PATCH',
+      `${CONVERSATION_BASE_PATH}/connections/${encodeURIComponent(id)}`,
+      request,
+    )
   }
 
   async delete(id: string): Promise<void> {
-    await this.client.request('DELETE', `${CONVERSATION_BASE_PATH}/connections/${encodeURIComponent(id)}`)
+    await this.client.request(
+      'DELETE',
+      `${CONVERSATION_BASE_PATH}/connections/${encodeURIComponent(id)}`,
+    )
   }
 
   install(id: string): Promise<InstallConnectionResponse> {
-    return this.client.request('POST', `${CONVERSATION_BASE_PATH}/connections/${encodeURIComponent(id)}/install`)
+    return this.client.request(
+      'POST',
+      `${CONVERSATION_BASE_PATH}/connections/${encodeURIComponent(id)}/install`,
+    )
   }
 
-  listContactAddresses(connectionId: string, query: ListContactAddressesQuery = {}): Promise<ListResponse<ContactAddress>> {
+  listContactAddresses(
+    connectionId: string,
+    query: ListContactAddressesQuery = {},
+  ): Promise<ListResponse<ContactAddress>> {
     return this.client.requestWithQuery(
       'GET',
       `${CONVERSATION_BASE_PATH}/connections/${encodeURIComponent(connectionId)}/contact-addresses`,
@@ -202,7 +228,9 @@ export interface ContactService {
   unblock(contactId: string, request?: BlockContactRequest): Promise<Contact>
   requestErasure(contactId: string): Promise<ContactErasureRequest>
   listErasureRequests(contactId: string): Promise<ContactErasureRequest[]>
-  listMergeProposals(query?: ListContactMergeProposalsQuery): Promise<ListResponse<ContactMergeProposal>>
+  listMergeProposals(
+    query?: ListContactMergeProposalsQuery,
+  ): Promise<ListResponse<ContactMergeProposal>>
   approveMergeProposal(proposalId: string): Promise<ContactMergeProposal>
   rejectMergeProposal(proposalId: string): Promise<ContactMergeProposal>
 }
@@ -215,11 +243,18 @@ class ContactServiceImpl implements ContactService {
   }
 
   get(id: string): Promise<Contact> {
-    return this.client.request('GET', `${CONVERSATION_BASE_PATH}/contacts/${encodeURIComponent(id)}`)
+    return this.client.request(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/contacts/${encodeURIComponent(id)}`,
+    )
   }
 
   update(id: string, request: UpdateContactRequest): Promise<Contact> {
-    return this.client.request('PATCH', `${CONVERSATION_BASE_PATH}/contacts/${encodeURIComponent(id)}`, request)
+    return this.client.request(
+      'PATCH',
+      `${CONVERSATION_BASE_PATH}/contacts/${encodeURIComponent(id)}`,
+      request,
+    )
   }
 
   attachAddress(contactId: string, request: AttachContactAddressRequest): Promise<Contact> {
@@ -245,7 +280,10 @@ class ContactServiceImpl implements ContactService {
     )
   }
 
-  recordPermissionEvent(contactId: string, request: RecordPermissionEventRequest): Promise<Contact> {
+  recordPermissionEvent(
+    contactId: string,
+    request: RecordPermissionEventRequest,
+  ): Promise<Contact> {
     return this.client.request(
       'POST',
       `${CONVERSATION_BASE_PATH}/contacts/${encodeURIComponent(contactId)}/permission-events`,
@@ -283,8 +321,14 @@ class ContactServiceImpl implements ContactService {
     )
   }
 
-  listMergeProposals(query: ListContactMergeProposalsQuery = {}): Promise<ListResponse<ContactMergeProposal>> {
-    return this.client.requestWithQuery('GET', `${CONVERSATION_BASE_PATH}/contact-merge-proposals`, query)
+  listMergeProposals(
+    query: ListContactMergeProposalsQuery = {},
+  ): Promise<ListResponse<ContactMergeProposal>> {
+    return this.client.requestWithQuery(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/contact-merge-proposals`,
+      query,
+    )
   }
 
   approveMergeProposal(proposalId: string): Promise<ContactMergeProposal> {
@@ -325,23 +369,39 @@ class ConversationServiceImpl implements ConversationService {
   }
 
   get(id: string): Promise<Conversation> {
-    return this.client.request('GET', `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(id)}`)
+    return this.client.request(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(id)}`,
+    )
   }
 
   update(id: string, request: UpdateConversationRequest): Promise<Conversation> {
-    return this.client.request('PATCH', `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(id)}`, request)
+    return this.client.request(
+      'PATCH',
+      `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(id)}`,
+      request,
+    )
   }
 
   end(id: string): Promise<Conversation> {
-    return this.client.request('POST', `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(id)}/end`)
+    return this.client.request(
+      'POST',
+      `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(id)}/end`,
+    )
   }
 
   markRead(id: string): Promise<void> {
-    return this.client.request('POST', `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(id)}/read`)
+    return this.client.request(
+      'POST',
+      `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(id)}/read`,
+    )
   }
 
   markUnread(id: string): Promise<void> {
-    return this.client.request('DELETE', `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(id)}/read`)
+    return this.client.request(
+      'DELETE',
+      `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(id)}/read`,
+    )
   }
 
   unreadCounts(): Promise<UnreadCounts> {
@@ -349,10 +409,30 @@ class ConversationServiceImpl implements ConversationService {
   }
 }
 
-/** Messages within a conversation (ordered by occurred_at) + outbound send + reactions. */
+/** Messages within a conversation (ordered by occurred_at) + outbound send + drafts + reactions. */
 export interface MessageService {
-  listByConversation(conversationId: string, query?: ListMessagesQuery): Promise<ListResponse<Message>>
+  listByConversation(
+    conversationId: string,
+    query?: ListMessagesQuery,
+  ): Promise<ListResponse<Message>>
+  /** One message with its read-time projections (reactions, attachments). */
+  get(messageId: string): Promise<Message>
   send(request: SendMessageRequest): Promise<Message>
+  /**
+   * Store an outbound message for human review (status=draft) — same request
+   * shape as send, nothing reaches the connector until sendDraft. Originate
+   * mode mints a hidden status=draft conversation.
+   */
+  draft(request: SendMessageRequest): Promise<Message>
+  /**
+   * Replace a draft's editable surface (full state, PUT semantics). 409
+   * `draft_not_editable` once the draft was sent or rejected.
+   */
+  updateDraft(messageId: string, request: UpdateDraftRequest): Promise<Message>
+  /** Deliver a draft (draft → pending → sent/failed). 409 on a lost race. */
+  sendDraft(messageId: string): Promise<Message>
+  /** Decline a draft (draft → rejected, terminal). 409 on a lost race. */
+  rejectDraft(messageId: string): Promise<Message>
   /** Aggregated reactions on one message (also rides on Message.reactions). */
   getReactions(messageId: string): Promise<Reaction[]>
   /**
@@ -367,7 +447,10 @@ export interface MessageService {
 class MessageServiceImpl implements MessageService {
   constructor(private readonly client: ProteosClient) {}
 
-  listByConversation(conversationId: string, query: ListMessagesQuery = {}): Promise<ListResponse<Message>> {
+  listByConversation(
+    conversationId: string,
+    query: ListMessagesQuery = {},
+  ): Promise<ListResponse<Message>> {
     return this.client.requestWithQuery(
       'GET',
       `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(conversationId)}/messages`,
@@ -375,10 +458,43 @@ class MessageServiceImpl implements MessageService {
     )
   }
 
+  get(messageId: string): Promise<Message> {
+    return this.client.request(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/messages/${encodeURIComponent(messageId)}`,
+    )
+  }
+
   send(request: SendMessageRequest): Promise<Message> {
     return this.client.request('POST', `${CONVERSATION_BASE_PATH}/messages/send`, request)
   }
 
+  draft(request: SendMessageRequest): Promise<Message> {
+    return this.client.request('POST', `${CONVERSATION_BASE_PATH}/messages/draft`, request)
+  }
+
+  updateDraft(messageId: string, request: UpdateDraftRequest): Promise<Message> {
+    return this.client.request(
+      'PUT',
+      `${CONVERSATION_BASE_PATH}/messages/${encodeURIComponent(messageId)}/draft`,
+      request,
+    )
+  }
+
+  sendDraft(messageId: string): Promise<Message> {
+    return this.client.request(
+      'POST',
+      `${CONVERSATION_BASE_PATH}/messages/${encodeURIComponent(messageId)}/send`,
+    )
+  }
+
+  rejectDraft(messageId: string): Promise<Message> {
+    return this.client.request(
+      'POST',
+      `${CONVERSATION_BASE_PATH}/messages/${encodeURIComponent(messageId)}/reject`,
+    )
+  }
+
   async getReactions(messageId: string): Promise<Reaction[]> {
     const response: ListReactionsResponse = await this.client.request(
       'GET',
@@ -422,7 +538,10 @@ class AgentListenerServiceImpl implements AgentListenerService {
   }
 
   get(id: string): Promise<AgentListener> {
-    return this.client.request('GET', `${CONVERSATION_BASE_PATH}/agent-listeners/${encodeURIComponent(id)}`)
+    return this.client.request(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/agent-listeners/${encodeURIComponent(id)}`,
+    )
   }
 
   create(request: CreateAgentListenerRequest): Promise<AgentListener> {
@@ -430,11 +549,18 @@ class AgentListenerServiceImpl implements AgentListenerService {
   }
 
   update(id: string, request: UpdateAgentListenerRequest): Promise<AgentListener> {
-    return this.client.request('PATCH', `${CONVERSATION_BASE_PATH}/agent-listeners/${encodeURIComponent(id)}`, request)
+    return this.client.request(
+      'PATCH',
+      `${CONVERSATION_BASE_PATH}/agent-listeners/${encodeURIComponent(id)}`,
+      request,
+    )
   }
 
   async delete(id: string): Promise<void> {
-    await this.client.request('DELETE', `${CONVERSATION_BASE_PATH}/agent-listeners/${encodeURIComponent(id)}`)
+    await this.client.request(
+      'DELETE',
+      `${CONVERSATION_BASE_PATH}/agent-listeners/${encodeURIComponent(id)}`,
+    )
   }
 }
 
@@ -449,18 +575,28 @@ export interface ConversationFilterService {
   create(request: CreateConversationFilterRequest): Promise<ConversationFilter>
   update(id: string, request: UpdateConversationFilterRequest): Promise<ConversationFilter>
   delete(id: string): Promise<void>
-  listEvents(id: string, query?: ListConversationFilterEventsQuery): Promise<ListResponse<ConversationFilterEvent>>
+  listEvents(
+    id: string,
+    query?: ListConversationFilterEventsQuery,
+  ): Promise<ListResponse<ConversationFilterEvent>>
 }
 
 class ConversationFilterServiceImpl implements ConversationFilterService {
   constructor(private readonly client: ProteosClient) {}
 
   list(query: ListConversationFiltersQuery = {}): Promise<ListResponse<ConversationFilter>> {
-    return this.client.requestWithQuery('GET', `${CONVERSATION_BASE_PATH}/conversation-filters`, query)
+    return this.client.requestWithQuery(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversation-filters`,
+      query,
+    )
   }
 
   get(id: string): Promise<ConversationFilter> {
-    return this.client.request('GET', `${CONVERSATION_BASE_PATH}/conversation-filters/${encodeURIComponent(id)}`)
+    return this.client.request(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversation-filters/${encodeURIComponent(id)}`,
+    )
   }
 
   create(request: CreateConversationFilterRequest): Promise<ConversationFilter> {
@@ -468,14 +604,24 @@ class ConversationFilterServiceImpl implements ConversationFilterService {
   }
 
   update(id: string, request: UpdateConversationFilterRequest): Promise<ConversationFilter> {
-    return this.client.request('PATCH', `${CONVERSATION_BASE_PATH}/conversation-filters/${encodeURIComponent(id)}`, request)
+    return this.client.request(
+      'PATCH',
+      `${CONVERSATION_BASE_PATH}/conversation-filters/${encodeURIComponent(id)}`,
+      request,
+    )
   }
 
   async delete(id: string): Promise<void> {
-    await this.client.request('DELETE', `${CONVERSATION_BASE_PATH}/conversation-filters/${encodeURIComponent(id)}`)
+    await this.client.request(
+      'DELETE',
+      `${CONVERSATION_BASE_PATH}/conversation-filters/${encodeURIComponent(id)}`,
+    )
   }
 
-  listEvents(id: string, query: ListConversationFilterEventsQuery = {}): Promise<ListResponse<ConversationFilterEvent>> {
+  listEvents(
+    id: string,
+    query: ListConversationFilterEventsQuery = {},
+  ): Promise<ListResponse<ConversationFilterEvent>> {
     return this.client.requestWithQuery(
       'GET',
       `${CONVERSATION_BASE_PATH}/conversation-filters/${encodeURIComponent(id)}/events`,
@@ -506,7 +652,10 @@ class GlossaryTermServiceImpl implements GlossaryTermService {
   }
 
   get(id: string): Promise<GlossaryTerm> {
-    return this.client.request('GET', `${CONVERSATION_BASE_PATH}/glossary-terms/${encodeURIComponent(id)}`)
+    return this.client.request(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/glossary-terms/${encodeURIComponent(id)}`,
+    )
   }
 
   create(request: CreateGlossaryTermRequest): Promise<GlossaryTerm> {
@@ -514,11 +663,18 @@ class GlossaryTermServiceImpl implements GlossaryTermService {
   }
 
   update(id: string, request: UpdateGlossaryTermRequest): Promise<GlossaryTerm> {
-    return this.client.request('PATCH', `${CONVERSATION_BASE_PATH}/glossary-terms/${encodeURIComponent(id)}`, request)
+    return this.client.request(
+      'PATCH',
+      `${CONVERSATION_BASE_PATH}/glossary-terms/${encodeURIComponent(id)}`,
+      request,
+    )
   }
 
   async delete(id: string): Promise<void> {
-    await this.client.request('DELETE', `${CONVERSATION_BASE_PATH}/glossary-terms/${encodeURIComponent(id)}`)
+    await this.client.request(
+      'DELETE',
+      `${CONVERSATION_BASE_PATH}/glossary-terms/${encodeURIComponent(id)}`,
+    )
   }
 }
 
@@ -548,7 +704,10 @@ class TranscriptionServiceImpl implements TranscriptionService {
   }
 
   get(id: string): Promise<Transcription> {
-    return this.client.request('GET', `${CONVERSATION_BASE_PATH}/transcriptions/${encodeURIComponent(id)}`)
+    return this.client.request(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/transcriptions/${encodeURIComponent(id)}`,
+    )
   }
 
   materialize(id: string, request: MaterializeTranscriptionRequest = {}): Promise<Conversation> {

package/src/conversation/types.ts

@@ -61,10 +61,18 @@ export type ConnectorKey =
 export type ConnectorProvider = 'native' | 'unipile' | 'ava'
 
 export type MessageDirection = 'inbound' | 'outbound'
-export type MessageStatus = 'received' | 'pending' | 'sent' | 'failed'
+/**
+ * Delivery state. `draft` = agent-prepared, awaiting human review (a human
+ * sends it → pending → sent/failed, or rejects it → `rejected`, terminal).
+ */
+export type MessageStatus = 'received' | 'pending' | 'sent' | 'failed' | 'draft' | 'rejected'
 export type ConnectionScope = 'org' | 'user'
 export type ConnectionStatus = 'pending' | 'active' | 'error' | 'revoked'
-export type ConversationStatus = 'active' | 'ended' | 'archived'
+/**
+ * `draft` marks a conversation minted BY a draft message (originate-mode
+ * drafting) — hidden from the default list until the first successful send.
+ */
+export type ConversationStatus = 'active' | 'ended' | 'archived' | 'draft'
 export type AgentListenerTriggerType = 'always' | 'mention' | 'channel' | 'keyword'
 
 export interface UserRef {
@@ -309,6 +317,11 @@ export interface Message {
   recipients?: MessageRecipient[]
   content: ContentBlock[]
   status: MessageStatus
+  /**
+   * The message this one was targeted at (thread-mode send/draft anchor);
+   * absent for everything else.
+   */
+  reply_to_message_id?: string
   occurred_at: string
   /** Read-time projection; absent/empty on channels without reactions. */
   reactions?: Reaction[]
@@ -426,6 +439,31 @@ export interface SendMessageRequest {
   attachments?: FileRef[]
 }
 
+/**
+ * Edits a status=draft message — full replacement of the editable surface
+ * (PUT semantics; always send the complete state, including attachments you
+ * want to keep). The addressing MODE is immutable. `subject` applies only
+ * while the draft's conversation is itself status=draft (originate drafts) —
+ * replies derive their subject from the thread.
+ *
+ * Recipient groups are PRESENCE-based: a group that is present (including an
+ * explicit empty `[]` — a clear) replaces the stored recipients from exactly
+ * the provided groups; omitting all three keeps the stored recipients. On any
+ * recipient edit, send all three groups.
+ */
+export interface UpdateDraftRequest {
+  to?: SendRecipient[]
+  /** Email only. */
+  cc?: SendRecipient[]
+  /** Email only. */
+  bcc?: SendRecipient[]
+  subject?: string
+  /** May be empty when attachments are present. */
+  content: ContentBlock[]
+  /** The complete attachment set to keep (omitting one removes its row). */
+  attachments?: FileRef[]
+}
+
 export interface CreateAgentListenerRequest {
   connection_id?: string
   conversation_id?: string