@proteos/sdk 0.28.0 → 0.29.0

package/package.json

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

package/src/conversation/index.ts

@@ -30,6 +30,12 @@ import type {
   BlockContactRequest,
   Contact,
   ContactAddress,
+  ConversationFilter,
+  ConversationFilterEvent,
+  CreateConversationFilterRequest,
+  ListConversationFilterEventsQuery,
+  ListConversationFiltersQuery,
+  UpdateConversationFilterRequest,
   ContactErasureRequest,
   ContactMergeProposal,
   MergeContactsRequest,
@@ -64,6 +70,8 @@ export class ConversationClient {
   readonly contacts: ContactService
   readonly messages: MessageService
   readonly agentListeners: AgentListenerService
+  /** Ingest-time filter rules (drop-with-audit) + their event trail. */
+  readonly conversationFilters: ConversationFilterService
   /** Per-org glossary: custom vocabulary that boosts transcription accuracy. */
   readonly glossaryTerms: GlossaryTermService
   readonly transcriptions: TranscriptionService
@@ -78,6 +86,7 @@ export class ConversationClient {
     this.contacts = new ContactServiceImpl(client)
     this.messages = new MessageServiceImpl(client)
     this.agentListeners = new AgentListenerServiceImpl(client)
+    this.conversationFilters = new ConversationFilterServiceImpl(client)
     this.glossaryTerms = new GlossaryTermServiceImpl(client)
     this.transcriptions = new TranscriptionServiceImpl(client)
     this.meetings = new MeetingServiceImpl(client)
@@ -429,6 +438,52 @@ class AgentListenerServiceImpl implements AgentListenerService {
   }
 }
 
+/**
+ * Ingest-time conversation filters: block/allow rules that drop matching
+ * inbound messages before persistence, scoped globally or per connection.
+ * listEvents pages a rule's drop-audit trail (who got dropped, when, why).
+ */
+export interface ConversationFilterService {
+  list(query?: ListConversationFiltersQuery): Promise<ListResponse<ConversationFilter>>
+  get(id: string): Promise<ConversationFilter>
+  create(request: CreateConversationFilterRequest): Promise<ConversationFilter>
+  update(id: string, request: UpdateConversationFilterRequest): Promise<ConversationFilter>
+  delete(id: string): Promise<void>
+  listEvents(id: string, query?: ListConversationFilterEventsQuery): Promise<ListResponse<ConversationFilterEvent>>
+}
+
+class ConversationFilterServiceImpl implements ConversationFilterService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(query: ListConversationFiltersQuery = {}): Promise<ListResponse<ConversationFilter>> {
+    return this.client.requestWithQuery('GET', `${CONVERSATION_BASE_PATH}/conversation-filters`, query)
+  }
+
+  get(id: string): Promise<ConversationFilter> {
+    return this.client.request('GET', `${CONVERSATION_BASE_PATH}/conversation-filters/${encodeURIComponent(id)}`)
+  }
+
+  create(request: CreateConversationFilterRequest): Promise<ConversationFilter> {
+    return this.client.request('POST', `${CONVERSATION_BASE_PATH}/conversation-filters`, request)
+  }
+
+  update(id: string, request: UpdateConversationFilterRequest): Promise<ConversationFilter> {
+    return this.client.request('PATCH', `${CONVERSATION_BASE_PATH}/conversation-filters/${encodeURIComponent(id)}`, request)
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.client.request('DELETE', `${CONVERSATION_BASE_PATH}/conversation-filters/${encodeURIComponent(id)}`)
+  }
+
+  listEvents(id: string, query: ListConversationFilterEventsQuery = {}): Promise<ListResponse<ConversationFilterEvent>> {
+    return this.client.requestWithQuery(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversation-filters/${encodeURIComponent(id)}/events`,
+      query,
+    )
+  }
+}
+
 /**
  * Per-org glossary: custom-vocabulary terms that boost transcription accuracy.
  * A term feeds the transcription provider's keyterm prompting; `priority` ranks

package/src/conversation/types.ts

@@ -566,6 +566,126 @@ export interface ListAgentListenersQuery extends PaginationQuery {
   is_enabled?: boolean
 }
 
+/**
+ * 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

package/src/index.ts

@@ -237,6 +237,24 @@ export type {
   ContactRef,
   ContactSource,
   ContactStatus,
+  AddressFilterConfig,
+  AllFilterConfig,
+  AutomatedFilterConfig,
+  AutomatedSignal,
+  ConversationFilter,
+  ConversationFilterAction,
+  ConversationFilterConfig,
+  ConversationFilterEvent,
+  ConversationFilterService,
+  ConversationFilterType,
+  CreateConversationFilterRequest,
+  DomainFilterConfig,
+  FilterMatchOn,
+  InternalConversationsFilterConfig,
+  ListConversationFilterEventsQuery,
+  ListConversationFiltersQuery,
+  RoleBasedFilterConfig,
+  UpdateConversationFilterRequest,
   ErasureRequestStatus,
   MergeContactsRequest,
   MergeProposalStatus,