@proteos/sdk 0.49.0 → 0.50.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteos/sdk",
-  "version": "0.49.0",
+  "version": "0.50.1",
   "license": "Apache-2.0",
   "description": "TypeScript SDK for the Proteos platform",
   "repository": {

package/src/auth/platform-entities.ts

@@ -88,6 +88,12 @@ export const PLATFORM_ENTITIES: readonly PlatformEntity[] = [
   { slug: 'contact-groups', name: 'Contact Groups' },
   // Tone-of-voice synthesis: per-user setups + generated instruction profiles.
   { slug: 'tone-profiles', name: 'Tone Profiles' },
+  // Outbound send constraints (windows, connection limits, frequency caps) +
+  // their preset catalog.
+  { slug: 'sending-rules', name: 'Sending Rules' },
+  // The channel_action ledger: acts through a connection that are neither a
+  // message nor a reaction (LinkedIn invitations, profile visits, InMail).
+  { slug: 'channel-actions', name: 'Channel Actions' },
   // Connectors (connector-service). `connections` above is shared; this is the
   // manifest catalog.
   { slug: 'connectors', name: 'Connectors' },

package/src/conversation/index.ts

@@ -2,14 +2,18 @@ import type { ProteosClient } from '../client.js'
 import type {
   AcceptMistranscribedTermRequest,
   AgentListener,
+  ApplySendingLimitPresetRequest,
   AttachContactAddressRequest,
   BlockContactRequest,
+  CallTokenResponse,
+  ChannelAction,
   Connection,
   Contact,
   ContactAddress,
   ContactErasureRequest,
   ContactGroup,
   ContactMergeProposal,
+  ContactRecordLink,
   Conversation,
   ConversationFilter,
   ConversationFilterEvent,
@@ -17,13 +21,12 @@ import type {
   CreateAgentListenerRequest,
   CreateConnectionRequest,
   CreateContactGroupRequest,
-  CreateContactRequest,
-  ContactRecordLink,
   CreateContactRecordLinkRequest,
-  ListContactRecordLinksQuery,
+  CreateContactRequest,
   CreateConversationFilterRequest,
   CreateConversationTypeRequest,
   CreateGlossaryTermRequest,
+  CreateSendingRuleRequest,
   CreateToneProfileSetupRequest,
   CreateTranscriptionRequest,
   DeleteConnectionQuery,
@@ -32,10 +35,12 @@ import type {
   InstallConnectionRequest,
   InstallConnectionResponse,
   ListAgentListenersQuery,
+  ListChannelActionsQuery,
   ListConnectionsQuery,
   ListContactAddressesQuery,
   ListContactGroupsQuery,
   ListContactMergeProposalsQuery,
+  ListContactRecordLinksQuery,
   ListContactsQuery,
   ListConversationFilterEventsQuery,
   ListConversationFiltersQuery,
@@ -47,21 +52,27 @@ 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,
   SyncConnectionRequest,
   ToneProfile,
@@ -77,6 +88,8 @@ import type {
   UpdateConversationTypeRequest,
   UpdateDraftRequest,
   UpdateGlossaryTermRequest,
+  UpdatePhoneNumberRequest,
+  UpdateSendingRuleRequest,
   UpdateTranscriptionRequest,
 } from './types.js'
 import { type VoiceService, VoiceServiceImpl } from './voice.js'
@@ -102,6 +115,13 @@ 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
   /** Per-org glossary: custom vocabulary that boosts transcription accuracy. */
   readonly glossaryTerms: GlossaryTermService
   /** Conversation taxonomy: the types the pre-summary classifier assigns. */
@@ -126,6 +146,8 @@ 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.glossaryTerms = new GlossaryTermServiceImpl(client)
     this.conversationTypes = new ConversationTypeServiceImpl(client)
     this.contactGroups = new ContactGroupServiceImpl(client)
@@ -369,7 +391,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 +573,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 +630,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 +1174,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 +1240,130 @@ export type {
   VoiceService,
   VoiceTranscriptionStream,
 } from './voice.js'
+
+/**
+ * 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,
+    )
+  }
+}

package/src/conversation/types.ts

@@ -290,6 +290,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
@@ -1220,6 +1228,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
   /**
@@ -1347,6 +1363,10 @@ 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.
@@ -1362,6 +1382,10 @@ export interface UpdateContactRequest {
 export interface CreateContactRequest {
   name: string
   addresses: AttachContactAddressRequest[]
+  /** 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 +1634,269 @@ 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'
+/** 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
+}
+export type SendingRuleConfig = WindowRuleConfig | LimitRuleConfig | FrequencyCapRuleConfig
+
+/**
+ * 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`.
+ */
+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 }[]
+}
+
+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
+}
+
+// ── 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
+}

package/src/errors.ts

@@ -23,12 +23,24 @@ export class ProteosError extends Error {
   readonly httpStatus: number
   /** API error code (e.g., 'not_found', 'unauthorized') */
   readonly code: ErrorCodeType | string
-
-  constructor(message: string, httpStatus: number, code: ErrorCodeType | string) {
+  /**
+   * Optional machine-readable payload beside the message — e.g. a denied send's
+   * `earliest_allowed_at` / `rule_id`, the offending `contact_id`. Absent on
+   * most errors.
+   */
+  readonly details: Record<string, unknown> | undefined
+
+  constructor(
+    message: string,
+    httpStatus: number,
+    code: ErrorCodeType | string,
+    details?: Record<string, unknown>,
+  ) {
     super(message)
     this.name = 'ProteosError'
     this.httpStatus = httpStatus
     this.code = code
+    this.details = details
 
     // V8-specific API for cleaner stack traces; not present in all runtimes
     const v8Capture = (Error as unknown as { captureStackTrace?: (t: object, c: unknown) => void })
@@ -112,6 +124,7 @@ export function getDefaultErrorCode(httpStatus: number): ErrorCodeType | string
 export interface ApiErrorResponse {
   code?: string
   message?: string
+  details?: Record<string, unknown>
 }
 
 /**
@@ -121,6 +134,7 @@ export async function parseErrorResponse(response: Response): Promise<ProteosErr
   const httpStatus = response.status
   let code: string = getDefaultErrorCode(httpStatus)
   let message = 'Unknown error'
+  let details: Record<string, unknown> | undefined
 
   try {
     const body = await response.text()
@@ -136,6 +150,9 @@ export async function parseErrorResponse(response: Response): Promise<ProteosErr
       } else {
         message = body || `HTTP ${httpStatus}`
       }
+      if (json.details && typeof json.details === 'object') {
+        details = json.details
+      }
     } catch {
       // Not JSON, use body as message
       message = body.trim() || `HTTP ${httpStatus}`
@@ -144,5 +161,5 @@ export async function parseErrorResponse(response: Response): Promise<ProteosErr
     message = `HTTP ${httpStatus}`
   }
 
-  return new ProteosError(message, httpStatus, code)
+  return new ProteosError(message, httpStatus, code, details)
 }