@proteos/sdk 0.50.1 → 0.51.0

package/src/conversation/index.ts

@@ -4,10 +4,13 @@ import type {
   AgentListener,
   ApplySendingLimitPresetRequest,
   AttachContactAddressRequest,
+  AttachConversationBriefRequest,
   BlockContactRequest,
   CallTokenResponse,
   ChannelAction,
+  ChannelEvent,
   Connection,
+  ConnectorCatalogEntry,
   Contact,
   ContactAddress,
   ContactErasureRequest,
@@ -15,6 +18,7 @@ import type {
   ContactMergeProposal,
   ContactRecordLink,
   Conversation,
+  ConversationBrief,
   ConversationFilter,
   ConversationFilterEvent,
   ConversationType,
@@ -23,6 +27,7 @@ import type {
   CreateContactGroupRequest,
   CreateContactRecordLinkRequest,
   CreateContactRequest,
+  CreateConversationBriefRequest,
   CreateConversationFilterRequest,
   CreateConversationTypeRequest,
   CreateGlossaryTermRequest,
@@ -31,17 +36,25 @@ import type {
   CreateTranscriptionRequest,
   DeleteConnectionQuery,
   DispatchMeetingBotRequest,
+  EmailDomainStatus,
+  EmailHealth,
+  EmailSender,
+  EmailSuppression,
+  EmailSuppressionKind,
+  GetConnectionHealthQuery,
   GlossaryTerm,
   InstallConnectionRequest,
   InstallConnectionResponse,
   ListAgentListenersQuery,
   ListChannelActionsQuery,
+  ListChannelEventsQuery,
   ListConnectionsQuery,
   ListContactAddressesQuery,
   ListContactGroupsQuery,
   ListContactMergeProposalsQuery,
   ListContactRecordLinksQuery,
   ListContactsQuery,
+  ListConversationBriefsQuery,
   ListConversationFilterEventsQuery,
   ListConversationFiltersQuery,
   ListConversationsQuery,
@@ -74,6 +87,7 @@ import type {
   SendingLimitPreset,
   SendingRule,
   SendMessageRequest,
+  SetDefaultSenderRequest,
   SyncConnectionRequest,
   ToneProfile,
   ToneProfileSetup,
@@ -83,6 +97,7 @@ import type {
   UpdateConnectionRequest,
   UpdateContactGroupRequest,
   UpdateContactRequest,
+  UpdateConversationBriefRequest,
   UpdateConversationFilterRequest,
   UpdateConversationRequest,
   UpdateConversationTypeRequest,
@@ -122,6 +137,7 @@ export class ConversationClient {
    * message nor a reaction — LinkedIn invitations, profile visits, InMail.
    */
   readonly channelActions: ChannelActionService
+  readonly channelEvents: ChannelEventService
   /** Per-org glossary: custom vocabulary that boosts transcription accuracy. */
   readonly glossaryTerms: GlossaryTermService
   /** Conversation taxonomy: the types the pre-summary classifier assigns. */
@@ -138,6 +154,8 @@ export class ConversationClient {
   /** Realtime speech-to-text (dictation) — moved here from agent-service. */
   readonly voice: VoiceService
   readonly calls: CallService
+  /** Conversation briefs: guidance prepared ahead of a conversation (call, meeting) with a contact. */
+  readonly conversationBriefs: ConversationBriefService
 
   constructor(client: ProteosClient) {
     this.connections = new ConnectionServiceImpl(client)
@@ -148,6 +166,7 @@ export class ConversationClient {
     this.conversationFilters = new ConversationFilterServiceImpl(client)
     this.sendingRules = new SendingRuleServiceImpl(client)
     this.channelActions = new ChannelActionServiceImpl(client)
+    this.channelEvents = new ChannelEventServiceImpl(client)
     this.glossaryTerms = new GlossaryTermServiceImpl(client)
     this.conversationTypes = new ConversationTypeServiceImpl(client)
     this.contactGroups = new ContactGroupServiceImpl(client)
@@ -157,6 +176,7 @@ export class ConversationClient {
     this.meetings = new MeetingServiceImpl(client)
     this.voice = new VoiceServiceImpl(client)
     this.calls = new CallServiceImpl(client)
+    this.conversationBriefs = new ConversationBriefServiceImpl(client)
   }
 }
 
@@ -245,6 +265,33 @@ export interface ConnectionService {
   ): Promise<ListResponse<ContactAddress>>
   /** Search a connection's addressable VENUES (Slack channels) for the compose picker. */
   listRooms(connectionId: string, query?: ListRoomsQuery): Promise<ListResponse<Room>>
+  /**
+   * Deliverability of a sending-platform connection (SendGrid): rates from
+   * the channel_event ledger + the provider's snapshot (engagement quality,
+   * counters, suppression counts, domain/sender state, dedicated IPs).
+   * `email_provider_not_supported` on mailbox connectors.
+   */
+  getHealth(connectionId: string, query?: GetConnectionHealthQuery): Promise<EmailHealth>
+  /** Ask the provider to re-check the sending domain's DNS. */
+  validateDomain(connectionId: string): Promise<EmailDomainStatus>
+  /** Re-send the single-sender verification mail (no-op on an authenticated domain). */
+  resendSenderVerification(connectionId: string): Promise<void>
+  /** Read one provider suppression list live. */
+  listSuppressions(connectionId: string, kind: EmailSuppressionKind): Promise<EmailSuppression[]>
+  /** Take an address off one provider suppression list (a false positive). */
+  removeSuppression(connectionId: string, kind: EmailSuppressionKind, email: string): Promise<void>
+  /** Start / stop the provider's automated warmup on a dedicated IP. */
+  setIpWarmup(connectionId: string, ip: string, isEnabled: boolean): Promise<void>
+  /** The runtime connector catalog: what is wired in this environment + install modes. */
+  listConnectors(): Promise<ConnectorCatalogEntry[]>
+  /**
+   * The sender directory of a domain-authenticated email connection: every
+   * email contact address on its domain (colleagues + shared mailboxes), the
+   * default flagged. Empty on connections without a sender domain.
+   */
+  listSenders(connectionId: string): Promise<EmailSender[]>
+  /** Pin the connection's fallback sender; returns the refreshed directory. */
+  setDefaultSender(connectionId: string, request: SetDefaultSenderRequest): Promise<EmailSender[]>
 }
 
 class ConnectionServiceImpl implements ConnectionService {
@@ -315,13 +362,97 @@ class ConnectionServiceImpl implements ConnectionService {
       query,
     )
   }
+
+  getHealth(connectionId: string, query: GetConnectionHealthQuery = {}): Promise<EmailHealth> {
+    return this.client.requestWithQuery(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/connections/${encodeURIComponent(connectionId)}/health`,
+      query,
+    )
+  }
+
+  validateDomain(connectionId: string): Promise<EmailDomainStatus> {
+    return this.client.request(
+      'POST',
+      `${CONVERSATION_BASE_PATH}/connections/${encodeURIComponent(connectionId)}/domain/validate`,
+    )
+  }
+
+  resendSenderVerification(connectionId: string): Promise<void> {
+    return this.client.request(
+      'POST',
+      `${CONVERSATION_BASE_PATH}/connections/${encodeURIComponent(connectionId)}/sender/verify`,
+    )
+  }
+
+  async listSuppressions(
+    connectionId: string,
+    kind: EmailSuppressionKind,
+  ): Promise<EmailSuppression[]> {
+    const response: { data: EmailSuppression[] } = await this.client.requestWithQuery(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/connections/${encodeURIComponent(connectionId)}/suppressions`,
+      { kind },
+    )
+    return response.data
+  }
+
+  removeSuppression(
+    connectionId: string,
+    kind: EmailSuppressionKind,
+    email: string,
+  ): Promise<void> {
+    return this.client.request(
+      'DELETE',
+      `${CONVERSATION_BASE_PATH}/connections/${encodeURIComponent(connectionId)}/suppressions/${encodeURIComponent(kind)}/${encodeURIComponent(email)}`,
+    )
+  }
+
+  setIpWarmup(connectionId: string, ip: string, isEnabled: boolean): Promise<void> {
+    return this.client.request(
+      isEnabled ? 'POST' : 'DELETE',
+      `${CONVERSATION_BASE_PATH}/connections/${encodeURIComponent(connectionId)}/ip-warmup/${encodeURIComponent(ip)}`,
+    )
+  }
+
+  async listConnectors(): Promise<ConnectorCatalogEntry[]> {
+    const response: { data: ConnectorCatalogEntry[] } = await this.client.request(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/connectors`,
+    )
+    return response.data
+  }
+
+  async listSenders(connectionId: string): Promise<EmailSender[]> {
+    const response: { data: EmailSender[] } = await this.client.request(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/connections/${encodeURIComponent(connectionId)}/senders`,
+    )
+    return response.data
+  }
+
+  async setDefaultSender(
+    connectionId: string,
+    request: SetDefaultSenderRequest,
+  ): Promise<EmailSender[]> {
+    const response: { data: EmailSender[] } = await this.client.request(
+      'PUT',
+      `${CONVERSATION_BASE_PATH}/connections/${encodeURIComponent(connectionId)}/senders/default`,
+      request,
+    )
+    return response.data
+  }
 }
 
 /** The person-level identity layer: contacts, addresses, merges, permissions, erasure. */
 export interface ContactService {
   list(query?: ListContactsQuery): Promise<ListResponse<Contact>>
   get(id: string): Promise<Contact>
-  /** Manually mint a contact (sync dedup — 409 contact_address_taken on any owned address). */
+  /**
+   * Manually mint a contact (sync dedup — 409 contact_address_taken on any
+   * owned address), or with `platform_user_id` ensure a colleague's bound
+   * contact and attach the addresses to it.
+   */
   create(request: CreateContactRequest): Promise<Contact>
   update(id: string, request: UpdateContactRequest): Promise<Contact>
   attachAddress(contactId: string, request: AttachContactAddressRequest): Promise<Contact>
@@ -1241,6 +1372,80 @@ export type {
   VoiceTranscriptionStream,
 } from './voice.js'
 
+/**
+ * Conversation briefs — guidance prepared ahead of a conversation ("talk to
+ * these people about this"; the conversation sibling of message drafts).
+ * Binding is explicit: the softphone carries the brief id into the call, or
+ * `attach` names the conversation. Any number of briefs may be open for the
+ * same people. Edits/attach on a non-open brief fail 409
+ * `conversation_brief_not_editable`; a conversation already carrying a brief
+ * refuses another (409 `conversation_brief_already_attached`).
+ */
+export interface ConversationBriefService {
+  list(query?: ListConversationBriefsQuery): Promise<ListResponse<ConversationBrief>>
+  get(id: string): Promise<ConversationBrief>
+  create(request: CreateConversationBriefRequest): Promise<ConversationBrief>
+  update(id: string, request: UpdateConversationBriefRequest): Promise<ConversationBrief>
+  /** Decline an open brief (prepared → discarded, terminal). */
+  discard(id: string): Promise<ConversationBrief>
+  /** Bind an open brief to a conversation explicitly (prepared → used). */
+  attach(id: string, request: AttachConversationBriefRequest): Promise<ConversationBrief>
+  delete(id: string): Promise<void>
+}
+
+class ConversationBriefServiceImpl implements ConversationBriefService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(query: ListConversationBriefsQuery = {}): Promise<ListResponse<ConversationBrief>> {
+    return this.client.requestWithQuery(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversation-briefs`,
+      query,
+    )
+  }
+
+  get(id: string): Promise<ConversationBrief> {
+    return this.client.request(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversation-briefs/${encodeURIComponent(id)}`,
+    )
+  }
+
+  create(request: CreateConversationBriefRequest): Promise<ConversationBrief> {
+    return this.client.request('POST', `${CONVERSATION_BASE_PATH}/conversation-briefs`, request)
+  }
+
+  update(id: string, request: UpdateConversationBriefRequest): Promise<ConversationBrief> {
+    return this.client.request(
+      'PATCH',
+      `${CONVERSATION_BASE_PATH}/conversation-briefs/${encodeURIComponent(id)}`,
+      request,
+    )
+  }
+
+  discard(id: string): Promise<ConversationBrief> {
+    return this.client.request(
+      'POST',
+      `${CONVERSATION_BASE_PATH}/conversation-briefs/${encodeURIComponent(id)}/discard`,
+    )
+  }
+
+  attach(id: string, request: AttachConversationBriefRequest): Promise<ConversationBrief> {
+    return this.client.request(
+      'POST',
+      `${CONVERSATION_BASE_PATH}/conversation-briefs/${encodeURIComponent(id)}/attach`,
+      request,
+    )
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.client.request(
+      'DELETE',
+      `${CONVERSATION_BASE_PATH}/conversation-briefs/${encodeURIComponent(id)}`,
+    )
+  }
+}
+
 /**
  * Sending rules — outbound send constraints (windows, connection limits,
  * frequency caps), the static limit-preset catalog and its apply expansion.
@@ -1367,3 +1572,37 @@ class ChannelActionServiceImpl implements ChannelActionService {
     )
   }
 }
+
+/**
+ * The channel_event ledger — provider-observed delivery / engagement events
+ * about outbound messages (delivered, bounced, opened, clicked,
+ * spam_reported, unsubscribed, …). Read-only: rows are appended by webhook
+ * ingest. `listByMessage` is the per-message history, oldest first.
+ */
+export interface ChannelEventService {
+  list(query?: ListChannelEventsQuery): Promise<ListResponse<ChannelEvent>>
+  get(id: string): Promise<ChannelEvent>
+  listByMessage(messageId: string): Promise<ListResponse<ChannelEvent>>
+}
+
+class ChannelEventServiceImpl implements ChannelEventService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(query: ListChannelEventsQuery = {}): Promise<ListResponse<ChannelEvent>> {
+    return this.client.requestWithQuery('GET', `${CONVERSATION_BASE_PATH}/channel-events`, query)
+  }
+
+  get(id: string): Promise<ChannelEvent> {
+    return this.client.request(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/channel-events/${encodeURIComponent(id)}`,
+    )
+  }
+
+  listByMessage(messageId: string): Promise<ListResponse<ChannelEvent>> {
+    return this.client.request(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/messages/${encodeURIComponent(messageId)}/events`,
+    )
+  }
+}