@proteos/sdk 0.49.0 → 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
@@ -290,6 +291,14 @@ export interface Connection {
   supports_reactions: boolean
   /** The capability descriptor; absent when unsupported. */
   reactions?: ReactionCapability
+  /**
+   * Computed on read like reactions: the channel actions the connector
+   * performs through this connection (invitation, profile_visit, inmail, …).
+   * A separate list from reactions — a reaction toggles an edge on a
+   * message, an action is a performed act with its own lifecycle. Absent
+   * when the connector performs none.
+   */
+  actions?: ChannelActionCapability[]
   /**
    * Computed on read like supports_reactions: who operates the integration
    * (native | unipile). Absent when the connector is not registered in this
@@ -457,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
@@ -465,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
@@ -623,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
 }
 
 /**
@@ -991,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'
 }
@@ -1189,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'
@@ -1220,6 +1283,14 @@ export interface Contact {
   /** Merge tombstone redirect (set when status is 'merged'). */
   merged_into_contact_id?: string
   source: ContactSource
+  /** IANA zone name (Europe/Berlin); absent = unknown. Filled from directory sweeps while empty. */
+  timezone?: string
+  /**
+   * BCP-47 language tag with optional region (de, de-CH, pt-BR); absent =
+   * unknown. Named locale, not language: the region carries formatting
+   * conventions on top of the language.
+   */
+  locale?: string
   /** ContactGroup membership (one group per contact); absent = unassigned. */
   group_key?: string
   /**
@@ -1341,12 +1412,22 @@ 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 {
   name?: string
   status?: 'active' | 'archived'
   has_legal_hold?: boolean
+  /** IANA zone name; normalized server-side, 400 contact_timezone_invalid when unparseable; '' clears. */
+  timezone?: string
+  /** BCP-47 language tag; normalized server-side, 400 contact_locale_invalid when unparseable; '' clears. */
+  locale?: string
   /**
    * Assigns the contact to a contact group ('' clears). A PATCH assignment is
    * stamped group_source='manual' — tone synthesis never overrides it.
@@ -1360,8 +1441,22 @@ 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. */
+  locale?: string
 }
 
 export interface AttachContactAddressRequest {
@@ -1610,3 +1705,636 @@ export interface DispatchMeetingBotRequest {
    */
   language?: string
 }
+
+// ── Sending rules ─────────────────────────────────────────────────────────────
+
+/**
+ * Discriminates a sending rule: window (WHEN sending is allowed, recipient-
+ * local weekday ranges), limit (HOW MUCH one connection may send per rolling
+ * period), frequency_cap (HOW OFTEN one contact may be contacted per rolling
+ * period).
+ */
+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'
+/**
+ * ONE kind of act performed through a channel connection — shared by a
+ * limit's `action` (what it counts), a channel action's `action_type` (what
+ * was performed) and the eligibility check. `message` is the plain send
+ * (valid on a limit, never on a channel action row).
+ */
+export type ChannelActionType = 'message' | 'invitation' | 'inmail' | 'profile_visit'
+export type Weekday =
+  | 'monday'
+  | 'tuesday'
+  | 'wednesday'
+  | 'thursday'
+  | 'friday'
+  | 'saturday'
+  | 'sunday'
+
+/** One open range on one weekday, "HH:MM" wall-clock, from < until, same day. */
+export interface WindowDay {
+  day: Weekday
+  from: string
+  until: string
+}
+export interface WindowRuleConfig {
+  days: WindowDay[]
+  /** IANA zone used for contacts without a timezone. */
+  fallback_timezone: string
+}
+export interface LimitRuleConfig {
+  action: ChannelActionType
+  max_count: number
+  period: SendingPeriod
+  /** Minimum spacing between consecutive sends; 0/absent = none. */
+  min_gap_seconds?: number
+}
+export interface FrequencyCapRuleConfig {
+  max_count: number
+  period: SendingPeriod
+}
+/**
+ * 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
+ * connections and/or channels (both empty = org-wide). Per rule type the most
+ * 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
+  name: string
+  connection_ids: string[]
+  channels: Channel[]
+  rule_type: SendingRuleType
+  rule_config?: SendingRuleConfig
+  is_enabled: boolean
+  is_reply_exempt: boolean
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+export interface CreateSendingRuleRequest {
+  name?: string
+  connection_ids?: string[]
+  channels?: Channel[]
+  rule_type: SendingRuleType
+  rule_config: Record<string, unknown>
+  /** Defaults to true. */
+  is_enabled?: boolean
+  /** Defaults per type: window + frequency_cap true, limit false. */
+  is_reply_exempt?: boolean
+}
+
+export interface UpdateSendingRuleRequest {
+  name?: string
+  /** Replaces the stored links wholesale when present. */
+  connection_ids?: string[]
+  channels?: Channel[]
+  /** rule_type and rule_config must be sent together. */
+  rule_type?: SendingRuleType
+  rule_config?: Record<string, unknown>
+  is_enabled?: boolean
+  is_reply_exempt?: boolean
+}
+
+export interface ListSendingRulesQuery extends PaginationQuery {
+  /** Rules LINKED to this connection. */
+  connection_id?: string
+  channel?: Channel
+  rule_type?: SendingRuleType
+  is_enabled?: boolean
+}
+
+/** A recommended limit bundle for one class of sender account (static catalog). */
+export interface SendingLimitPreset {
+  key: string
+  name: string
+  description: string
+  connector_keys: ConnectorKey[]
+  is_recommended: boolean
+  rules: (
+    | { rule_type: 'limit'; rule_config: LimitRuleConfig }
+    | { rule_type: 'warmup'; rule_config: WarmupRuleConfig }
+  )[]
+}
+
+export interface ListSendingLimitPresetsQuery {
+  connector_key?: ConnectorKey
+}
+
+export interface ApplySendingLimitPresetRequest {
+  connection_ids: string[]
+  preset_key: string
+}
+
+/** Dry-run twin of SendMessageRequest: addressing only, nothing minted. */
+export interface SendEligibilityRequest {
+  conversation_id?: string
+  reply_to_message_id?: string
+  connection_id?: string
+  to?: SendRecipient[]
+  cc?: SendRecipient[]
+  bcc?: SendRecipient[]
+  /**
+   * Widens the check to a channel action (invitation, profile_visit, inmail):
+   * originate mode only, the first `to` recipient is the target. Absent =
+   * message.
+   */
+  action_type?: ChannelActionType
+}
+
+/**
+ * "May this send go out now?" — `reason` is the error code a real send would
+ * fail with (sending_window_closed | sending_limit_reached |
+ * frequency_cap_reached | contact_blocked | contact_opted_out);
+ * `earliest_allowed_at` is set for the temporal three.
+ */
+export interface SendEligibility {
+  is_allowed: boolean
+  reason?: string
+  rule_id?: string
+  rule_type?: SendingRuleType
+  earliest_allowed_at?: string
+  contact_id?: string
+  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 ───────────────────────────────────────────────────────────
+
+/**
+ * Lifecycle of a channel action. Execution: pending → performed | failed.
+ * Outcome (invitations): performed → accepted | declined | withdrawn |
+ * expired; an inbound received invitation starts pending and ends
+ * accepted | declined | expired.
+ */
+export type ChannelActionStatus =
+  | 'pending'
+  | 'performed'
+  | 'failed'
+  | 'accepted'
+  | 'declined'
+  | 'withdrawn'
+  | 'expired'
+/** Our answer to an inbound channel action (a received invitation). */
+export type ChannelActionResponse = 'accept' | 'decline'
+/** What an action type acts on: a person on the channel, or an external object. */
+export type ChannelActionTargetKind = 'contact-address' | 'external'
+
+/**
+ * One action type a connector performs, projected onto `connection.actions`.
+ */
+export interface ChannelActionCapability {
+  action_type: ChannelActionType
+  target_kind: ChannelActionTargetKind
+  /** The act can be withdrawn after performing (an invitation). */
+  is_cancelable: boolean
+  /** An inbound act of this type can be answered (accept / decline). */
+  is_respondable: boolean
+  /** Performing also sends a message that lands as a Message + Conversation (InMail). */
+  is_message_minting: boolean
+  /** Bound of the free-text note the act carries (LinkedIn invitation: 300). */
+  max_note_length?: number
+}
+
+export interface InvitationParams {
+  note?: string
+  email?: string
+}
+export type ProfileVisitParams = Record<string, never>
+export interface InmailParams {
+  subject?: string
+  content: ContentBlock[]
+}
+export type ChannelActionParams = InvitationParams | ProfileVisitParams | InmailParams
+
+/**
+ * One act performed through a channel connection that is neither a message
+ * nor a reaction — a LinkedIn invitation, a profile visit, an InMail (which
+ * ALSO mints a message, see message_id). A LEDGER row: appended, transitioned
+ * along its lifecycle, never toggled. `direction` outbound = we acted;
+ * inbound = someone acted on us (a received invitation you may answer).
+ * `created_by` is the performer on outbound rows (user or agent), the system
+ * on ingested inbound rows; `updated_by` who accepted / declined / withdrew.
+ */
+export interface ChannelAction {
+  id: string
+  org_id: string
+  connection_id: string
+  connector_key: ConnectorKey
+  channel: Channel
+  action_type: ChannelActionType
+  direction: MessageDirection
+  status: ChannelActionStatus
+  contact_id?: string
+  contact_address_id?: string
+  /** The provider-side identity acted on (a LinkedIn member id). */
+  target_external_id: string
+  contact: ContactRef
+  /** An InMail's minted message; an invitation's note-chat once accepted. */
+  message_id?: string
+  conversation_id?: string
+  params?: ChannelActionParams
+  /** The provider handle (Unipile invitation id) — cancel / respond key. */
+  external_action_id?: string
+  error?: string
+  occurred_at: string
+  resolved_at?: string
+  /** Provider enrichment: invitation usage %, network_distance, … */
+  metadata: Record<string, unknown>
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+/** Performs one act. `target` is the person acted on (kind contact-address + the connector-side external id). */
+export interface PerformChannelActionRequest {
+  connection_id: string
+  action_type: ChannelActionType
+  target: SendRecipient
+  /** Per-type input: invitation {note?, email?}; profile_visit {}; inmail {subject?, content}. */
+  params?: Record<string, unknown>
+}
+
+export interface RespondChannelActionRequest {
+  response: ChannelActionResponse
+}
+
+export interface ListChannelActionsQuery extends PaginationQuery {
+  channel?: Channel
+  connection_id?: string
+  action_type?: ChannelActionType
+  direction?: MessageDirection
+  status?: ChannelActionStatus
+  contact_id?: string
+}