@proteos/sdk 0.50.1 → 0.51.0

package/src/conversation/types.ts

@@ -56,6 +56,7 @@ export type ConnectorKey =
   | 'twilio-phone'
   | 'aircall'
   | 'webhook-cti'
+  | 'sendgrid'
 
 /**
  * Telephony lifecycle of one phone call, carried in the call conversation's
@@ -465,6 +466,12 @@ export interface Message {
    */
   child_conversation_id?: string
   child_messages_total?: number
+  /**
+   * Provider-side outcome + engagement projection of an OUTBOUND message on
+   * a sending platform (folded from the channel_event ledger); absent on
+   * channels that report nothing and on inbound rows.
+   */
+  delivery?: MessageDelivery
   metadata: Record<string, unknown>
   error: string
   created_at: string
@@ -473,6 +480,31 @@ export interface Message {
   updated_by: UserRef
 }
 
+/**
+ * Provider-side outcome of an outbound message — a separate axis from
+ * MessageStatus (the message stays `sent` at the platform level once the
+ * provider accepted it): sent → delivered | deferred | bounced | dropped.
+ */
+export type MessageDeliveryStatus = 'sent' | 'delivered' | 'deferred' | 'bounced' | 'dropped'
+
+/** The read-side fold of a message's channel events. */
+export interface MessageDelivery {
+  status: MessageDeliveryStatus
+  delivered_at?: string
+  bounced_at?: string
+  dropped_at?: string
+  /** First HUMAN open / click; totals count every event (machine opens excluded). */
+  opened_at?: string
+  opens_total?: number
+  clicked_at?: string
+  clicks_total?: number
+  spam_reported_at?: string
+  unsubscribed_at?: string
+  /** Latest bounce / drop / deferral text. */
+  reason?: string
+  last_event_at?: string
+}
+
 /**
  * Per-trigger configuration, discriminated by the sibling trigger_type: channel
  * carries external_channel_id, keyword carries phrases, always/mention carry
@@ -631,6 +663,15 @@ export interface SendMessageRequest {
    * `unsupported_content`.
    */
   attachments?: FileRef[]
+  /**
+   * Overrides the sending identity on a sending-platform email connection: a
+   * contact address id on the connection's sender domain
+   * (`connections.listSenders`). Without it: the conversation's pinned sender
+   * → the acting user's own address on the domain → the connection's default.
+   * Off-domain ids fail with `sender_not_found`; connections without a sender
+   * domain refuse it with `sender_domain_not_available`.
+   */
+  sender_address_id?: string
 }
 
 /**
@@ -999,6 +1040,8 @@ export interface ListConversationsQuery extends PaginationQuery {
   /** Threads whose roster contains this external party — the person stream. */
   /** Contact stream: threads whose roster contains the resolved person. */
   contact_id?: string
+  /** "Sent as" stream: threads pinned to one sending identity (a contact address id). */
+  sender_address_id?: string
   /** Opt into the root/latest message projection on each row. */
   include?: 'messages_summary'
 }
@@ -1197,7 +1240,19 @@ export type ContactSource = 'sync' | 'ingest' | 'manual' | 'merge'
 export type ContactStatus = 'active' | 'merged' | 'archived' | 'erased'
 export type ConsentStatus = 'unknown' | 'opted_in' | 'opted_out'
 export type PermissionEventType = 'opt_in' | 'opt_out' | 'block' | 'unblock'
-export type PermissionEventSource = 'manual' | 'import' | 'link_click' | 'reply' | 'api' | 'system'
+/**
+ * Where a permission event came from. `provider` = the sending platform
+ * observed it (its unsubscribe link, a spam complaint relayed by the mailbox
+ * provider, a hard bounce); `link_click` stays for OUR unsubscribe links.
+ */
+export type PermissionEventSource =
+  | 'manual'
+  | 'import'
+  | 'link_click'
+  | 'reply'
+  | 'api'
+  | 'system'
+  | 'provider'
 export type MergeProposalStatus = 'proposed' | 'approved' | 'rejected' | 'superseded'
 export type ErasureRequestStatus = 'requested' | 'completed'
 export type RoomSource = 'sync' | 'ingest'
@@ -1357,6 +1412,12 @@ export interface ListContactsQuery extends PaginationQuery {
   status?: ContactStatus
   /** Members of one contact group (drives group-member lists). */
   group_key?: string
+  /**
+   * The contact bound to one platform user (at most one active contact per
+   * user per org); `'me'` resolves to the caller — a client's way to its own
+   * contact.
+   */
+  platform_user_id?: string
 }
 
 export interface UpdateContactRequest {
@@ -1380,8 +1441,18 @@ export interface UpdateContactRequest {
  * rejects the create with 409 contact_address_taken.
  */
 export interface CreateContactRequest {
-  name: string
-  addresses: AttachContactAddressRequest[]
+  /** Required without platform_user_id; with it, fills an empty name only. */
+  name?: string
+  /** Required (≥1) without platform_user_id; with it, attached to the colleague's contact. */
+  addresses?: AttachContactAddressRequest[]
+  /**
+   * Colleague mode: ensure the contact bound to this platform user (created
+   * from the account directory, or the existing one — every colleague has
+   * exactly one) and attach the addresses to it. 200 when it already
+   * existed, 201 when created; 404 `platform_user_not_found`, 409
+   * `contact_platform_user_conflict`.
+   */
+  platform_user_id?: string
   /** IANA zone name; optional, validated as on update. */
   timezone?: string
   /** BCP-47 language tag; optional, validated as on update. */
@@ -1643,7 +1714,7 @@ export interface DispatchMeetingBotRequest {
  * period), frequency_cap (HOW OFTEN one contact may be contacted per rolling
  * period).
  */
-export type SendingRuleType = 'window' | 'limit' | 'frequency_cap'
+export type SendingRuleType = 'window' | 'limit' | 'frequency_cap' | 'warmup'
 /** Rolling lookback ("last 24 hours from now") — never a calendar day. */
 export type SendingPeriod = 'rolling_24h' | 'rolling_7d' | 'rolling_30d'
 /**
@@ -1684,7 +1755,27 @@ export interface FrequencyCapRuleConfig {
   max_count: number
   period: SendingPeriod
 }
-export type SendingRuleConfig = WindowRuleConfig | LimitRuleConfig | FrequencyCapRuleConfig
+/**
+ * A limit that RAMPS: `start_count` acts of `action` per rolling `period` on
+ * the day the warmup started, growing by `daily_increase` (a count, or a
+ * percent of the previous day's allowance when `is_increase_percent`) every
+ * UTC calendar day until `max_count`, after which it behaves as a plain
+ * limit. `started_at` may be omitted on create — the server stamps now.
+ */
+export interface WarmupRuleConfig {
+  action: ChannelActionType
+  start_count: number
+  daily_increase: number
+  is_increase_percent?: boolean
+  max_count: number
+  period: SendingPeriod
+  started_at: string
+}
+export type SendingRuleConfig =
+  | WindowRuleConfig
+  | LimitRuleConfig
+  | FrequencyCapRuleConfig
+  | WarmupRuleConfig
 
 /**
  * One outbound send constraint, defined once and LINKED to any number of
@@ -1692,6 +1783,85 @@ export type SendingRuleConfig = WindowRuleConfig | LimitRuleConfig | FrequencyCa
  * specific tier wins at send time: names the connection > names the channel >
  * org-wide. Replies skip the rule when `is_reply_exempt`.
  */
+// ── Conversation briefs ──────────────────────────────────────────────────────────────
+
+/**
+ * Lifecycle of a conversation brief: `prepared` (open — editable, waiting for its
+ * call), `used` (attached to a call conversation; terminal), `discarded`
+ * (declined without a call; terminal).
+ */
+export type ConversationBriefStatus = 'prepared' | 'used' | 'discarded'
+
+/**
+ * Guidance prepared AHEAD of a conversation — "talk to these people about
+ * this" — the conversation sibling of a draft message. Binding to a
+ * conversation is always explicit: the softphone carries the brief id into
+ * the call (attached at call start), or `attach` names the conversation.
+ * Nothing matches by contact or number, and any number of briefs may be open
+ * for the same people at once. Records that want a brief (an activity) store
+ * its id; every UI surface renders from the id.
+ */
+export interface ConversationBrief {
+  id: string
+  org_id: string
+  /** Human label ("Renewal call with Dana"); may be empty. */
+  subject: string
+  /** The people the conversation is with (≥ 1, deduplicated, sorted). */
+  contact_ids: string[]
+  /** How the conversation should happen (phone opens the softphone); absent = unspecified. */
+  channel?: Channel
+  /** ConversationType key the conversation is meant to be; stamped on attach. */
+  type_key?: string
+  /** The conversation the brief was used on; absent until used. */
+  conversation_id?: string
+  status: ConversationBriefStatus
+  /** Guidance text (markdown allowed). */
+  content: string
+  used_at?: string
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+export interface CreateConversationBriefRequest {
+  subject?: string
+  /** The people the conversation is with (≥ 1). */
+  contact_ids: string[]
+  /** Must be a known channel when set. */
+  channel?: Channel
+  /** Must name an existing conversation type when set. */
+  type_key?: string
+  content: string
+}
+
+/** PATCH semantics — absent fields keep their value. Only open briefs. */
+export interface UpdateConversationBriefRequest {
+  subject?: string
+  /** Replaces the set wholesale. */
+  contact_ids?: string[]
+  /** Empty string clears the channel. */
+  channel?: Channel | ''
+  content?: string
+  type_key?: string
+}
+
+/** Binds an open brief to a conversation explicitly. */
+export interface AttachConversationBriefRequest {
+  conversation_id: string
+}
+
+export interface ListConversationBriefsQuery extends PaginationQuery {
+  /** Briefs naming this person. */
+  contact_id?: string
+  conversation_id?: string
+  channel?: Channel
+  type_key?: string
+  status?: ConversationBriefStatus
+  sort_by?: string
+  sort?: 'asc' | 'desc'
+}
+
 export interface SendingRule {
   id: string
   org_id: string
@@ -1747,7 +1917,10 @@ export interface SendingLimitPreset {
   description: string
   connector_keys: ConnectorKey[]
   is_recommended: boolean
-  rules: { rule_type: 'limit'; rule_config: LimitRuleConfig }[]
+  rules: (
+    | { rule_type: 'limit'; rule_config: LimitRuleConfig }
+    | { rule_type: 'warmup'; rule_config: WarmupRuleConfig }
+  )[]
 }
 
 export interface ListSendingLimitPresetsQuery {
@@ -1791,6 +1964,271 @@ export interface SendEligibility {
   contact_address_id?: string
 }
 
+// ── Connector catalog ─────────────────────────────────────────────────────────
+
+/**
+ * One connector WIRED in this deployment (registry membership decides
+ * availability). `install_modes` lists the install variants the environment
+ * supports for a direct-install connector (a sending platform's own_account /
+ * managed); empty for OAuth / install-free connectors.
+ */
+/**
+ * ONE sending identity of a domain-authenticated email connection: an email
+ * contact address on the connection's sender domain. A personal sender belongs
+ * to a colleague's contact (`platform_user` set); a shared mailbox (sales@) to
+ * a role contact without one. Computed from the contact directory on read.
+ */
+export interface EmailSender {
+  contact_address_id: string
+  contact_id: string
+  from_email: string
+  from_name: string
+  platform_user?: UserRef
+  /** The connection's fallback sender when neither the thread nor the user pins one. */
+  is_default: boolean
+}
+
+/** Pins a connection's default sender (an address on its sender domain). */
+export interface SetDefaultSenderRequest {
+  contact_address_id: string
+}
+
+export interface ConnectorCatalogEntry {
+  key: ConnectorKey
+  channel: Channel
+  provider: ConnectorProvider
+  install_modes: string[]
+}
+
+// ── Email deliverability (sending-platform connections) ──────────────────────
+
+/** One of a sending platform's suppression lists. */
+export type EmailSuppressionKind =
+  | 'bounces'
+  | 'blocks'
+  | 'spam_reports'
+  | 'invalid_emails'
+  | 'unsubscribes'
+
+/**
+ * Ledger rollup over the last `days` days: DISTINCT messages per event type
+ * (machine opens excluded). Rates are fractions (0–1): delivery / bounce /
+ * hard-bounce over sent, open / click / spam / unsubscribe over delivered.
+ */
+export interface EmailHealthWindow {
+  days: number
+  sent: number
+  delivered: number
+  deferred: number
+  bounced: number
+  hard_bounced: number
+  dropped: number
+  opened: number
+  clicked: number
+  spam_reported: number
+  unsubscribed: number
+  delivery_rate: number
+  bounce_rate: number
+  hard_bounce_rate: number
+  open_rate: number
+  click_rate: number
+  spam_rate: number
+  unsubscribe_rate: number
+}
+
+/** The provider's composite sender-quality score (1–5, computed daily). */
+export interface EmailEngagementQuality {
+  date: string
+  score: number
+  bounce_classification: number
+  bounce_rate: number
+  engagement_recency: number
+  open_rate: number
+  spam_rate: number
+}
+
+/** The provider's own counters for this connection's traffic (its category). */
+export interface EmailProviderStats {
+  days: number
+  requests: number
+  processed: number
+  delivered: number
+  deferred: number
+  bounces: number
+  blocks: number
+  bounce_drops: number
+  invalid_emails: number
+  opens: number
+  unique_opens: number
+  clicks: number
+  unique_clicks: number
+  spam_reports: number
+  spam_report_drops: number
+  unsubscribes: number
+  unsubscribe_drops: number
+}
+
+export interface EmailSuppressionCounts {
+  bounces: number
+  blocks: number
+  spam_reports: number
+  invalid_emails: number
+  unsubscribes: number
+  /** A list hit the page cap — the count is a floor. */
+  is_approximate?: boolean
+}
+
+export interface EmailDnsRecord {
+  host: string
+  type: string
+  data: string
+  is_valid: boolean
+  reason?: string
+}
+
+export interface EmailDomainStatus {
+  domain: string
+  is_valid: boolean
+  dns: EmailDnsRecord[]
+}
+
+export interface EmailSenderStatus {
+  from_email: string
+  /** authenticated_domain | single_sender */
+  mode: string
+  is_verified: boolean
+}
+
+/** One dedicated IP of the account with its warmup state. */
+export interface EmailIp {
+  ip: string
+  is_warming_up: boolean
+  warmup_started_at?: string
+  pools: string[]
+}
+
+/**
+ * The provider's account-level snapshot (refreshed daily by the connector's
+ * sweep, or on demand with `refresh`). Every section is optional — a plan
+ * without the feature or a failed pull leaves it absent and adds a warning.
+ */
+export interface EmailProviderHealth {
+  engagement_quality?: EmailEngagementQuality
+  stats?: EmailProviderStats
+  suppressions?: EmailSuppressionCounts
+  domain?: EmailDomainStatus
+  sender?: EmailSenderStatus
+  ips: EmailIp[]
+  warnings?: string[]
+  refreshed_at: string
+}
+
+/** GET /connections/:id/health — ledger windows + the provider snapshot. */
+export interface EmailHealth {
+  connection_id: string
+  windows: EmailHealthWindow[]
+  provider?: EmailProviderHealth
+}
+
+export interface GetConnectionHealthQuery {
+  /** Force a live provider pull (slow — several provider calls). */
+  refresh?: boolean
+}
+
+/** One address on a provider suppression list. */
+export interface EmailSuppression {
+  kind: EmailSuppressionKind
+  email: string
+  reason?: string
+  status?: string
+  created_at: string
+}
+
+// ── Channel events ────────────────────────────────────────────────────────────
+
+/**
+ * ONE provider-observed occurrence about an outbound message on a sending
+ * platform: the delivery lifecycle (processed → delivered | deferred |
+ * bounced | dropped) and engagement (opened, clicked, spam_reported,
+ * unsubscribed, resubscribed). Provider vocabularies map onto these inside
+ * the connector.
+ */
+export type ChannelEventType =
+  | 'processed'
+  | 'delivered'
+  | 'deferred'
+  | 'bounced'
+  | 'dropped'
+  | 'opened'
+  | 'clicked'
+  | 'spam_reported'
+  | 'unsubscribed'
+  | 'resubscribed'
+
+/** hard = the address is gone (suppressed); soft = this attempt was refused. */
+export type BounceKind = 'hard' | 'soft'
+
+/** The provider's category of a bounce / block. */
+export type BounceClassification =
+  | 'invalid_address'
+  | 'technical_failure'
+  | 'content'
+  | 'reputation'
+  | 'volume'
+  | 'mailbox_unavailable'
+  | 'unclassified'
+
+/**
+ * One row of the channel_event ledger — the sibling of channel actions (acts
+ * WE perform) and reactions (edges): something the provider or the recipient
+ * did that we record. Append-only, deduped on the provider's event id.
+ * Message.delivery and provider-sourced contact permission events derive
+ * from it.
+ */
+export interface ChannelEvent {
+  id: string
+  org_id: string
+  connection_id: string
+  connector_key: ConnectorKey
+  channel: Channel
+  /** The message the event is about; absent when unresolvable. */
+  message_id?: string
+  conversation_id?: string
+  contact_id?: string
+  contact_address_id?: string
+  /** The provider's recipient (lowercased email). */
+  recipient_address: string
+  event_type: ChannelEventType
+  external_event_id: string
+  external_message_id?: string
+  occurred_at: string
+  /** Bounce / deferral / drop text (the SMTP response, the drop reason). */
+  reason?: string
+  response?: string
+  bounce_kind?: BounceKind
+  bounce_classification?: BounceClassification
+  /** The clicked link (clicked events). */
+  url?: string
+  /** An opened event a mail client's privacy proxy generated, not the person. */
+  is_machine_open?: boolean
+  metadata: Record<string, unknown>
+  created_at: string
+  created_by: UserRef
+}
+
+export interface ListChannelEventsQuery extends PaginationQuery {
+  connection_id?: string
+  message_id?: string
+  conversation_id?: string
+  contact_id?: string
+  event_type?: ChannelEventType
+  /** ISO instants bounding occurred_at (from inclusive, until exclusive). */
+  from?: string
+  until?: string
+  sort_by?: string
+  sort?: 'asc' | 'desc'
+}
+
 // ── Channel actions ───────────────────────────────────────────────────────────
 
 /**