@proteos/sdk 0.27.0 → 0.29.0

package/src/conversation/types.ts

@@ -74,12 +74,15 @@ export interface UserRef {
 
 /**
  * Inline snapshot of a person on a message/reaction — the integration-side
- * identity plus, when resolved via email match, the platform user.
+ * identity plus, when resolved, the platform user and the contact id.
+ * (Renamed from ParticipantRef in the contacts model; wire keys unchanged.)
  */
-export interface ParticipantRef {
+export interface ContactRef {
   external_id?: string
   name: string
   email?: string
+  /** The resolved person; absent on pre-contacts snapshots and wire fallbacks. */
+  contact_id?: string
   /** Resolved platform identity (email match); absent when unresolved. */
   platform_user?: UserRef
 }
@@ -90,7 +93,7 @@ export interface ParticipantRef {
  * renders "who it's with" as the non-self subset (1 → single avatar, ≥2 →
  * stacked).
  */
-export interface ConversationParticipant extends ParticipantRef {
+export interface ConversationParticipant extends ContactRef {
   is_self: boolean
 }
 
@@ -101,7 +104,7 @@ export type RecipientRole = 'to' | 'cc' | 'bcc'
  * One addressee of a message with the role it was addressed under. Bcc is only
  * present on messages the platform itself sent (inbound bcc is SMTP-stripped).
  */
-export interface MessageRecipient extends ParticipantRef {
+export interface MessageRecipient extends ContactRef {
   role: RecipientRole
 }
 
@@ -164,7 +167,7 @@ export interface Connection {
   scope: ConnectionScope
   /** Set only when scope=user (the connecting user); absent for org-wide. */
   owner?: UserRef
-  external_workspace_id: string
+  external_account_id: string
   credentials: ConnectionCredentials
   settings: Record<string, unknown>
   status: ConnectionStatus
@@ -232,7 +235,7 @@ export interface Conversation {
   latest_message?: MessagePreview
   messages_total?: number
   /** Up to 3 most recent distinct senders excluding the root sender. */
-  last_repliers?: ParticipantRef[]
+  last_repliers?: ContactRef[]
   /** Requesting user's read marker; absent = never opened. */
   last_read_at?: string
   /**
@@ -252,7 +255,7 @@ export interface Conversation {
  * ~500 chars of text, direction/status for outbound identity.
  */
 export interface MessagePreview {
-  sender: ParticipantRef
+  sender: ContactRef
   text: string
   direction: MessageDirection
   status: MessageStatus
@@ -290,7 +293,7 @@ export interface Attachment {
 export interface Reaction {
   emoji: string
   count: number
-  participants: ParticipantRef[]
+  participants: ContactRef[]
 }
 
 export interface Message {
@@ -301,7 +304,7 @@ export interface Message {
   channel: Channel
   direction: MessageDirection
   external_message_id: string
-  sender: ParticipantRef
+  sender: ContactRef
   /** Who the message was addressed to (To/Cc/Bcc), each tagged with its role. */
   recipients?: MessageRecipient[]
   content: ContentBlock[]
@@ -533,7 +536,8 @@ export interface ListConversationsQuery extends PaginationQuery {
    */
   parent_conversation_id?: string
   /** Threads whose roster contains this external party — the person stream. */
-  participant_external_id?: string
+  /** Contact stream: threads whose roster contains the resolved person. */
+  contact_id?: string
   /** Opt into the root/latest message projection on each row. */
   include?: 'messages_summary'
 }
@@ -562,41 +566,261 @@ export interface ListAgentListenersQuery extends PaginationQuery {
   is_enabled?: boolean
 }
 
-/** Discriminates a send target: a person or a venue. */
-export type RecipientKind = 'participant' | 'room'
-export type ParticipantSource = 'sync' | 'ingest'
+/**
+ * Conversation filters: ingest-time rules that drop matching inbound messages
+ * BEFORE persistence (no message, no contact — only a content-free audit
+ * event). Scope-first evaluation: connection-scoped rules are final when one
+ * matches; global rules apply otherwise. Specificity within a scope:
+ * address > domain > role_based > automated > internal_conversations > all,
+ * allow beats block within a class.
+ */
+export type ConversationFilterType =
+  | 'address'
+  | 'domain'
+  | 'role_based'
+  | 'automated'
+  | 'internal_conversations'
+  | 'all'
+export type ConversationFilterAction = 'block' | 'allow'
+/** Which side of the message address/domain rules test (default: sender). */
+export type FilterMatchOn = 'sender' | 'any_participant'
+/** Deterministic machine-mail header signals the automated filter matches. */
+export type AutomatedSignal =
+  | 'auto_submitted'
+  | 'bulk'
+  | 'mailing_list'
+  | 'bounce'
+  | 'auto_response_suppress'
+
+/** Exact canonical address (lowercased email / E.164 phone / provider id), any channel kind. */
+export interface AddressFilterConfig {
+  kind: ContactAddressKind
+  value: string
+  match_on?: FilterMatchOn
+}
+/** Equals on the parsed email domain (lowercase, no leading '@'). */
+export interface DomainFilterConfig {
+  domain: string
+  match_on?: FilterMatchOn
+}
+/** Sender local-part is a role mailbox; empty prefixes = the built-in set. Email-only. */
+export interface RoleBasedFilterConfig {
+  prefixes?: string[]
+}
+/** Header-signal machine-mail detection; empty signals = all. Email-only. */
+export interface AutomatedFilterConfig {
+  signals?: AutomatedSignal[]
+}
+/** Drops only when sender AND every recipient are on these domains. Always block. */
+export interface InternalConversationsFilterConfig {
+  domains: string[]
+}
+/** Matches every message (empty config) — the scope-control primitive. */
+export type AllFilterConfig = Record<string, never>
+
+export type ConversationFilterConfig =
+  | AddressFilterConfig
+  | DomainFilterConfig
+  | RoleBasedFilterConfig
+  | AutomatedFilterConfig
+  | InternalConversationsFilterConfig
+  | AllFilterConfig
+
+export interface ConversationFilter {
+  id: string
+  org_id: string
+  /** Empty = global (org-wide); set = scoped to that connection. */
+  connection_id: string
+  filter_type: ConversationFilterType
+  action: ConversationFilterAction
+  filter_config?: ConversationFilterConfig
+  is_enabled: boolean
+  /** Read-only rollup: messages this rule dropped in the last 30 days. */
+  recent_event_count?: number
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+/** One drop-audit entry (content-free: routing/identity facts only). */
+export interface ConversationFilterEvent {
+  id: string
+  org_id: string
+  connection_id: string
+  conversation_filter_id: string
+  filter_type: ConversationFilterType
+  reason: string
+  sender_kind?: ContactAddressKind
+  sender_value?: string
+  external_message_id?: string
+  occurred_at: string
+}
+
+export interface CreateConversationFilterRequest {
+  connection_id?: string
+  filter_type: ConversationFilterType
+  action: ConversationFilterAction
+  filter_config?: Record<string, unknown>
+  is_enabled?: boolean
+  /** Opts past the own-domain guard (self_domain_block). */
+  is_self_domain_acknowledged?: boolean
+}
+
+export interface UpdateConversationFilterRequest {
+  /** filter_type and filter_config must be sent together. */
+  filter_type?: ConversationFilterType
+  action?: ConversationFilterAction
+  filter_config?: Record<string, unknown>
+  is_enabled?: boolean
+  is_self_domain_acknowledged?: boolean
+}
+
+export interface ListConversationFiltersQuery extends PaginationQuery {
+  /** Omit = all; '' = global-only; an id = that connection's rules. */
+  connection_id?: string
+  filter_type?: ConversationFilterType
+  action?: ConversationFilterAction
+  is_enabled?: boolean
+}
+
+export type ListConversationFilterEventsQuery = PaginationQuery
+
+/**
+ * Discriminates a send target: a person's contact address or a venue. The
+ * server also accepts the legacy 'participant' value as an alias for
+ * 'contact-address'.
+ */
+export type RecipientKind = 'contact-address' | 'room'
+export type ContactAddressKind =
+  | 'email'
+  | 'phone'
+  | 'slack'
+  | 'linkedin'
+  | 'telegram'
+  | 'instagram'
+  | 'messenger'
+  | 'x'
+  | 'whatsapp'
+export type ContactAddressSource = 'sync' | 'ingest' | 'manual' | 'merge'
+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'
+export type MergeProposalStatus = 'proposed' | 'approved' | 'rejected' | 'superseded'
+export type ErasureRequestStatus = 'requested' | 'completed'
 export type RoomSource = 'sync' | 'ingest'
 
 /**
  * Send-time addressing VO: who/where an originated message goes. Points at a
- * Participant or a Room by kind + external id (never a stored entity itself).
+ * ContactAddress or a Room by kind + external id (never a stored entity itself).
  */
 export interface SendRecipient {
   kind: RecipientKind
-  /** The connector-side id: a room's (Slack channel id) or a participant's (Slack user id, email address). */
+  /** The connector-side id: a room's (Slack channel id) or a contact address's wire identifier (Slack user id, email address). */
   external_id: string
 }
 
-/** A PERSON known on a connection (directory row; resolvable to a platform user). */
-export interface Participant {
+/** The actual PERSON an org communicates with — org-scoped, channel-agnostic. */
+export interface Contact {
   id: string
   org_id: string
-  connection_id: string
-  /** Slack user id / email address — the id to DM or email. */
-  external_id: string
   name: string
-  email?: string
-  /** Resolved platform identity (email match); absent when unresolved. */
+  status: ContactStatus
+  /** Person-level suppression — only block/unblock events move it. */
+  is_blocked: boolean
+  has_legal_hold: boolean
+  consent_status: ConsentStatus
+  consent_updated_at?: string
+  /** Resolved platform identity when the person is a colleague. */
   platform_user?: UserRef
+  /** Merge tombstone redirect (set when status is 'merged'). */
+  merged_into_contact_id?: string
+  source: ContactSource
+  has_manual_edits: boolean
+  /** The contact's reachable endpoints, embedded on reads. */
+  addresses?: ContactAddress[]
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+/** ONE canonical digital endpoint to reach a contact — the dedup backbone. */
+export interface ContactAddress {
+  id: string
+  org_id: string
+  contact_id: string
+  kind: ContactAddressKind
+  /** Provider-tenant qualifier (Slack workspace id); empty for global kinds. */
+  scope?: string
+  /** Canonical scalar (lowercased email, E.164 phone) — the lookup key. */
+  value: string
+  /** The identifier as observed on the wire (WhatsApp JID, original casing). */
+  raw_value?: string
+  /** Per-channel display name. */
+  name: string
+  consent_status: ConsentStatus
+  consent_updated_at?: string
+  is_blocked: boolean
+  source: ContactAddressSource
   metadata: Record<string, unknown>
-  source: ParticipantSource
-  last_seen_at: string
   created_at: string
   created_by: UserRef
   updated_at: string
   updated_by: UserRef
 }
 
+/** One entry in the append-only permission ledger (consent + suppression). */
+export interface ContactPermissionEvent {
+  id: string
+  org_id: string
+  contact_id: string
+  /** Scopes the event to one address; absent/empty = contact-level. */
+  contact_address_id?: string
+  event: PermissionEventType
+  basis?: string
+  source: PermissionEventSource
+  occurred_at: string
+  note?: string
+  evidence?: Record<string, unknown>
+  created_at: string
+  created_by: UserRef
+}
+
+/** One candidate duplicate pair awaiting review. */
+export interface ContactMergeProposal {
+  id: string
+  org_id: string
+  contact_a_id: string
+  contact_b_id: string
+  suggested_winner_id?: string
+  confidence?: number
+  evidence?: Record<string, unknown>
+  verdict?: Record<string, unknown>
+  status: MergeProposalStatus
+  resolved_by?: UserRef
+  resolved_at?: string
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+/** A GDPR Art. 17 erasure request (requested → completed). */
+export interface ContactErasureRequest {
+  id: string
+  org_id: string
+  contact_id: string
+  identifier_hashes: Array<{ kind: ContactAddressKind; hmac: string }>
+  status: ErasureRequestStatus
+  completed_at?: string
+  stats?: Record<string, unknown>
+  created_at: string
+  created_by: UserRef
+}
+
 /** An addressable VENUE on a connection (Slack channel; later meeting rooms). */
 export interface Room {
   id: string
@@ -615,9 +839,53 @@ export interface Room {
   updated_by: UserRef
 }
 
-export interface ListParticipantsQuery extends PaginationQuery {
-  /** Free-text needle matched against display name + external id. */
+export interface ListContactAddressesQuery extends PaginationQuery {
+  /** Free-text needle matched against display name + canonical value. */
+  q?: string
+  kinds?: ContactAddressKind[]
+  scope?: string
+}
+
+export interface ListContactsQuery extends PaginationQuery {
+  /** Free-text needle matched against contact name + address values. */
   q?: string
+  status?: ContactStatus
+}
+
+export interface UpdateContactRequest {
+  name?: string
+  status?: 'active' | 'archived'
+  has_legal_hold?: boolean
+}
+
+export interface AttachContactAddressRequest {
+  kind: ContactAddressKind
+  scope?: string
+  value: string
+  name?: string
+}
+
+export interface MergeContactsRequest {
+  source_contact_id: string
+}
+
+export interface RecordPermissionEventRequest {
+  contact_address_id?: string
+  event: PermissionEventType
+  basis?: string
+  source?: PermissionEventSource
+  occurred_at?: string
+  note?: string
+  evidence?: Record<string, unknown>
+}
+
+export interface BlockContactRequest {
+  contact_address_id?: string
+  note?: string
+}
+
+export interface ListContactMergeProposalsQuery extends PaginationQuery {
+  status?: MergeProposalStatus
 }
 
 export interface ListRoomsQuery extends PaginationQuery {

package/src/index.ts

@@ -196,6 +196,7 @@ export type {
   ContentBlock as MessageContentBlock,
   Conversation,
   ConversationParticipant,
+  ContactService,
   ConversationService,
   ConversationStatus,
   CreateAgentListenerRequest,
@@ -210,7 +211,9 @@ export type {
   ListConversationsQuery,
   ListGlossaryTermsQuery,
   ListMessagesQuery,
-  ListParticipantsQuery,
+  ListContactAddressesQuery,
+  ListContactMergeProposalsQuery,
+  ListContactsQuery,
   // Conversation-local page envelope ({meta, data}) — distinct from the
   // PageIterator-based ListResult used by the other modules.
   ListResponse,
@@ -222,9 +225,43 @@ export type {
   MessageRecipient,
   MessageService,
   MessageStatus,
-  Participant,
-  ParticipantRef,
-  ParticipantSource,
+  AttachContactAddressRequest,
+  BlockContactRequest,
+  ConsentStatus,
+  Contact,
+  ContactAddress,
+  ContactAddressKind,
+  ContactAddressSource,
+  ContactErasureRequest,
+  ContactMergeProposal,
+  ContactRef,
+  ContactSource,
+  ContactStatus,
+  AddressFilterConfig,
+  AllFilterConfig,
+  AutomatedFilterConfig,
+  AutomatedSignal,
+  ConversationFilter,
+  ConversationFilterAction,
+  ConversationFilterConfig,
+  ConversationFilterEvent,
+  ConversationFilterService,
+  ConversationFilterType,
+  CreateConversationFilterRequest,
+  DomainFilterConfig,
+  FilterMatchOn,
+  InternalConversationsFilterConfig,
+  ListConversationFilterEventsQuery,
+  ListConversationFiltersQuery,
+  RoleBasedFilterConfig,
+  UpdateConversationFilterRequest,
+  ErasureRequestStatus,
+  MergeContactsRequest,
+  MergeProposalStatus,
+  PermissionEventSource,
+  PermissionEventType,
+  RecordPermissionEventRequest,
+  UpdateContactRequest,
   Reaction,
   ReactionCapability,
   ReactionOption,

package/src/meta/layout/elements.ts

@@ -88,6 +88,12 @@ export type RelatedListElement = CommonProps & {
   related_entity_slug: string
   via_attribute: string
   list_slug?: string
+  /**
+   * When absent or true, the list enters row-edit mode together with the
+   * host page's edit mode. False keeps the list independent — rows are only
+   * editable through the list's own "Edit records" toggle.
+   */
+  follows_parent_edit_mode?: boolean
 }
 
 export type ComponentElement = CommonProps & {
@@ -182,6 +188,7 @@ export const LayoutElementSchema: z.ZodType<LayoutElement> = z.lazy(() =>
       related_entity_slug: z.string().min(1),
       via_attribute: z.string().min(1),
       list_slug: z.string().min(1).optional(),
+      follows_parent_edit_mode: z.boolean().optional(),
     }),
     z.object({
       type: z.literal('component'),