@proteos/sdk 0.26.3 → 0.28.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,141 @@ 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'
+/**
+ * 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 +719,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,25 @@ export type {
   MessageRecipient,
   MessageService,
   MessageStatus,
-  Participant,
-  ParticipantRef,
-  ParticipantSource,
+  AttachContactAddressRequest,
+  BlockContactRequest,
+  ConsentStatus,
+  Contact,
+  ContactAddress,
+  ContactAddressKind,
+  ContactAddressSource,
+  ContactErasureRequest,
+  ContactMergeProposal,
+  ContactRef,
+  ContactSource,
+  ContactStatus,
+  ErasureRequestStatus,
+  MergeContactsRequest,
+  MergeProposalStatus,
+  PermissionEventSource,
+  PermissionEventType,
+  RecordPermissionEventRequest,
+  UpdateContactRequest,
   Reaction,
   ReactionCapability,
   ReactionOption,

package/src/meta/layout/control-registry.json

@@ -23,7 +23,8 @@
     "user-picker",
     "currency",
     "knowledge-text",
-    "file"
+    "file",
+    "file-viewer"
   ],
   "controls": {
     "string": {
@@ -65,6 +66,6 @@
     "user": { "primary": "user-picker", "compatible": ["user-picker"] },
     "currency": { "primary": "currency", "compatible": ["currency"] },
     "knowledge-text": { "primary": "knowledge-text", "compatible": ["knowledge-text"] },
-    "file": { "primary": "file", "compatible": ["file"] }
+    "file": { "primary": "file", "compatible": ["file", "file-viewer"] }
   }
 }

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'),

package/src/storage/files.ts

@@ -40,11 +40,15 @@ export interface FileService {
   create(metadata: CreateFileMetadata): Promise<StorageFile>
 
   /**
-   * Updates a file's metadata (name, `public_access`). Only the fields present
-   * in `metadata` are changed. Setting `public_access: ["read"]` exposes the
-   * file on the UNAUTHENTICATED public download route; `[]` revokes it.
+   * Updates a file's metadata (name, `public_access`) and, when `file` is
+   * given, replaces the bytes IN PLACE — a new version under the SAME id, so
+   * every `FileRef { id }` pointing at it now resolves to the new content.
+   * Only the metadata fields present are changed. Setting
+   * `public_access: ["read"]` exposes the file on the UNAUTHENTICATED public
+   * download route; `[]` revokes it. Replacing a locked file is rejected by
+   * the storage-service.
    */
-  update(id: string, metadata: UpdateFileMetadata): Promise<StorageFile>
+  update(id: string, metadata: UpdateFileMetadata, file?: File): Promise<StorageFile>
 
   /**
    * Mints a short-lived upload URL for a file. The bytes are PUT directly to this URL
@@ -157,12 +161,16 @@ export class FileServiceImpl implements FileService {
     return response.data
   }
 
-  async update(id: string, metadata: UpdateFileMetadata): Promise<StorageFile> {
+  async update(id: string, metadata: UpdateFileMetadata, file?: File): Promise<StorageFile> {
+    // Part order is load-bearing: the storage-service reads `metadata` first
+    // and stops consuming parts at `file` — metadata appended after the file
+    // part would be silently dropped.
     const formData = new FormData()
     formData.append(
       'metadata',
       new Blob([JSON.stringify(metadata)], { type: 'application/json' }),
     )
+    if (file) formData.append('file', file, metadata.name ?? file.name)
     const response = await this.client.requestMultipart<{ data: StorageFile }>(
       'PATCH',
       `${FILES_BASE_PATH}/${id}`,

package/src/types/common.ts

@@ -103,13 +103,16 @@ export const PLATFORM_USER_ID = 'platform'
 /**
  * A reference to a stored file — the value stored by every `file` attribute.
  * `id` is the storage-service file id; `name` is the denormalised filename the
- * record carries so it has a human label without a storage round-trip. Size and
+ * record carries so it has a human label without a storage round-trip.
+ * `content_type` is an optional denormalised MIME hint so renderers can pick a
+ * viewer without a storage round-trip; when absent (legacy values), size and
  * content type are resolved from the storage-service by `id` on read. Mirrors
  * the backend's `common.FileRef`.
  */
 export interface FileRef {
   id: string
   name: string
+  content_type?: string
 }
 
 /**
@@ -118,6 +121,8 @@ export interface FileRef {
 export const FileRefSchema = z.object({
   id: z.string(),
   name: z.string(),
+  // Mirrors the server-side validator: when present, must be non-empty.
+  content_type: z.string().min(1).optional(),
 })
 
 /**