@proteos/sdk 0.49.0 → 0.51.0

package/src/conversation/index.ts

@@ -2,41 +2,59 @@ import type { ProteosClient } from '../client.js'
 import type {
   AcceptMistranscribedTermRequest,
   AgentListener,
+  ApplySendingLimitPresetRequest,
   AttachContactAddressRequest,
+  AttachConversationBriefRequest,
   BlockContactRequest,
+  CallTokenResponse,
+  ChannelAction,
+  ChannelEvent,
   Connection,
+  ConnectorCatalogEntry,
   Contact,
   ContactAddress,
   ContactErasureRequest,
   ContactGroup,
   ContactMergeProposal,
+  ContactRecordLink,
   Conversation,
+  ConversationBrief,
   ConversationFilter,
   ConversationFilterEvent,
   ConversationType,
   CreateAgentListenerRequest,
   CreateConnectionRequest,
   CreateContactGroupRequest,
-  CreateContactRequest,
-  ContactRecordLink,
   CreateContactRecordLinkRequest,
-  ListContactRecordLinksQuery,
+  CreateContactRequest,
+  CreateConversationBriefRequest,
   CreateConversationFilterRequest,
   CreateConversationTypeRequest,
   CreateGlossaryTermRequest,
+  CreateSendingRuleRequest,
   CreateToneProfileSetupRequest,
   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,
@@ -47,22 +65,29 @@ import type {
   ListReactionsResponse,
   ListResponse,
   ListRoomsQuery,
+  ListSendingLimitPresetsQuery,
+  ListSendingRulesQuery,
   ListToneProfileSetupsQuery,
   ListToneProfilesQuery,
   ListTranscriptionsQuery,
-  CallTokenResponse,
   MaterializeTranscriptionRequest,
-  MintCallTokenRequest,
-  PhoneNumber,
-  UpdatePhoneNumberRequest,
   MergeContactsRequest,
   Message,
+  MintCallTokenRequest,
   MistranscribedTerm,
+  PerformChannelActionRequest,
+  PhoneNumber,
   Reaction,
   RecordPermissionEventRequest,
   ResolveToneProfileQuery,
+  RespondChannelActionRequest,
   Room,
+  SendEligibility,
+  SendEligibilityRequest,
+  SendingLimitPreset,
+  SendingRule,
   SendMessageRequest,
+  SetDefaultSenderRequest,
   SyncConnectionRequest,
   ToneProfile,
   ToneProfileSetup,
@@ -72,11 +97,14 @@ import type {
   UpdateConnectionRequest,
   UpdateContactGroupRequest,
   UpdateContactRequest,
+  UpdateConversationBriefRequest,
   UpdateConversationFilterRequest,
   UpdateConversationRequest,
   UpdateConversationTypeRequest,
   UpdateDraftRequest,
   UpdateGlossaryTermRequest,
+  UpdatePhoneNumberRequest,
+  UpdateSendingRuleRequest,
   UpdateTranscriptionRequest,
 } from './types.js'
 import { type VoiceService, VoiceServiceImpl } from './voice.js'
@@ -102,6 +130,14 @@ export class ConversationClient {
   readonly agentListeners: AgentListenerService
   /** Ingest-time filter rules (drop-with-audit) + their event trail. */
   readonly conversationFilters: ConversationFilterService
+  /** Outbound send constraints: windows, connection limits, frequency caps + presets. */
+  readonly sendingRules: SendingRuleService
+  /**
+   * Channel actions: acts performed through a connection that are neither a
+   * 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. */
@@ -118,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)
@@ -126,6 +164,9 @@ export class ConversationClient {
     this.messages = new MessageServiceImpl(client)
     this.agentListeners = new AgentListenerServiceImpl(client)
     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)
@@ -135,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)
   }
 }
 
@@ -223,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 {
@@ -293,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>
@@ -369,7 +522,9 @@ class ContactServiceImpl implements ContactService {
     return this.client.request('POST', `${CONVERSATION_BASE_PATH}/contact-record-links`, request)
   }
 
-  listRecordLinks(query: ListContactRecordLinksQuery = {}): Promise<ListResponse<ContactRecordLink>> {
+  listRecordLinks(
+    query: ListContactRecordLinksQuery = {},
+  ): Promise<ListResponse<ContactRecordLink>> {
     return this.client.requestWithQuery(
       'GET',
       `${CONVERSATION_BASE_PATH}/contact-record-links`,
@@ -549,6 +704,12 @@ export interface MessageService {
   /** One message with its read-time projections (reactions, attachments). */
   get(messageId: string): Promise<Message>
   send(request: SendMessageRequest): Promise<Message>
+  /**
+   * Dry-run of the sending gate: same addressing as send, no content, nothing
+   * minted. Answers whether the send may go out now and, when held, the
+   * earliest instant it may (`earliest_allowed_at`).
+   */
+  checkSendEligibility(request: SendEligibilityRequest): Promise<SendEligibility>
   /**
    * Store an outbound message for human review (status=draft) — same request
    * shape as send, nothing reaches the connector until sendDraft. Originate
@@ -600,6 +761,14 @@ class MessageServiceImpl implements MessageService {
     return this.client.request('POST', `${CONVERSATION_BASE_PATH}/messages/send`, request)
   }
 
+  checkSendEligibility(request: SendEligibilityRequest): Promise<SendEligibility> {
+    return this.client.request(
+      'POST',
+      `${CONVERSATION_BASE_PATH}/messages/send-eligibility`,
+      request,
+    )
+  }
+
   draft(request: SendMessageRequest): Promise<Message> {
     return this.client.request('POST', `${CONVERSATION_BASE_PATH}/messages/draft`, request)
   }
@@ -1136,7 +1305,10 @@ export interface CallService {
     request: UpdatePhoneNumberRequest,
   ): Promise<{ data: PhoneNumber[] }>
   /** Point one number at the platform. Returns the refreshed list. */
-  connectPhoneNumber(connectionId: string, numberExternalId: string): Promise<{ data: PhoneNumber[] }>
+  connectPhoneNumber(
+    connectionId: string,
+    numberExternalId: string,
+  ): Promise<{ data: PhoneNumber[] }>
   /** Release one number (restores its previous handler). Returns the refreshed list. */
   disconnectPhoneNumber(
     connectionId: string,
@@ -1199,3 +1371,238 @@ export type {
   VoiceService,
   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.
+ * A denied send/reply/sendDraft fails with a ProteosError whose `details`
+ * carry `earliest_allowed_at` (429) or the blocked contact (403).
+ */
+export interface SendingRuleService {
+  list(query?: ListSendingRulesQuery): Promise<ListResponse<SendingRule>>
+  get(id: string): Promise<SendingRule>
+  create(request: CreateSendingRuleRequest): Promise<SendingRule>
+  update(id: string, request: UpdateSendingRuleRequest): Promise<SendingRule>
+  delete(id: string): Promise<void>
+  /** The static preset catalog, optionally narrowed to one connector. */
+  listPresets(query?: ListSendingLimitPresetsQuery): Promise<{ data: SendingLimitPreset[] }>
+  /**
+   * Expand a preset into limit rules linked to the given connections,
+   * replacing the limit rules they were linked to before.
+   */
+  applyPreset(request: ApplySendingLimitPresetRequest): Promise<{ data: SendingRule[] }>
+}
+
+class SendingRuleServiceImpl implements SendingRuleService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(query: ListSendingRulesQuery = {}): Promise<ListResponse<SendingRule>> {
+    return this.client.requestWithQuery('GET', `${CONVERSATION_BASE_PATH}/sending-rules`, query)
+  }
+
+  get(id: string): Promise<SendingRule> {
+    return this.client.request(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/sending-rules/${encodeURIComponent(id)}`,
+    )
+  }
+
+  create(request: CreateSendingRuleRequest): Promise<SendingRule> {
+    return this.client.request('POST', `${CONVERSATION_BASE_PATH}/sending-rules`, request)
+  }
+
+  update(id: string, request: UpdateSendingRuleRequest): Promise<SendingRule> {
+    return this.client.request(
+      'PATCH',
+      `${CONVERSATION_BASE_PATH}/sending-rules/${encodeURIComponent(id)}`,
+      request,
+    )
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.client.request(
+      'DELETE',
+      `${CONVERSATION_BASE_PATH}/sending-rules/${encodeURIComponent(id)}`,
+    )
+  }
+
+  listPresets(query: ListSendingLimitPresetsQuery = {}): Promise<{ data: SendingLimitPreset[] }> {
+    return this.client.requestWithQuery(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/sending-rules/presets`,
+      query,
+    )
+  }
+
+  applyPreset(request: ApplySendingLimitPresetRequest): Promise<{ data: SendingRule[] }> {
+    return this.client.request(
+      'POST',
+      `${CONVERSATION_BASE_PATH}/sending-rules/apply-preset`,
+      request,
+    )
+  }
+}
+
+/**
+ * Channel actions — the ledger of acts performed through a connection that
+ * are neither a message nor a reaction (LinkedIn invitations, profile visits,
+ * InMail). A denied perform fails like a denied send (ProteosError with
+ * `details.earliest_allowed_at`); a provider refusal carries its own code
+ * (already_connected, already_invited_recently, invitation_already_received,
+ * connection_limit_reached, insufficient_inmail_credits, inmail_not_allowed,
+ * not_connected_with_recipient). An invitation is pre-flighted with one silent
+ * profile read before anything is sent, so those refusals never mint a
+ * phantom act.
+ */
+export interface ChannelActionService {
+  list(query?: ListChannelActionsQuery): Promise<ListResponse<ChannelAction>>
+  get(id: string): Promise<ChannelAction>
+  /** Performs one act; resolves to the row in its post-perform status. */
+  perform(request: PerformChannelActionRequest): Promise<ChannelAction>
+  /** Withdraws a performed outbound act (an invitation). */
+  cancel(id: string): Promise<ChannelAction>
+  /** Answers an inbound act (a received invitation). */
+  respond(id: string, request: RespondChannelActionRequest): Promise<ChannelAction>
+}
+
+class ChannelActionServiceImpl implements ChannelActionService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(query: ListChannelActionsQuery = {}): Promise<ListResponse<ChannelAction>> {
+    return this.client.requestWithQuery('GET', `${CONVERSATION_BASE_PATH}/channel-actions`, query)
+  }
+
+  get(id: string): Promise<ChannelAction> {
+    return this.client.request(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/channel-actions/${encodeURIComponent(id)}`,
+    )
+  }
+
+  perform(request: PerformChannelActionRequest): Promise<ChannelAction> {
+    return this.client.request('POST', `${CONVERSATION_BASE_PATH}/channel-actions`, request)
+  }
+
+  cancel(id: string): Promise<ChannelAction> {
+    return this.client.request(
+      'POST',
+      `${CONVERSATION_BASE_PATH}/channel-actions/${encodeURIComponent(id)}/cancel`,
+    )
+  }
+
+  respond(id: string, request: RespondChannelActionRequest): Promise<ChannelAction> {
+    return this.client.request(
+      'POST',
+      `${CONVERSATION_BASE_PATH}/channel-actions/${encodeURIComponent(id)}/respond`,
+      request,
+    )
+  }
+}
+
+/**
+ * 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`,
+    )
+  }
+}