@proteos/sdk 0.40.0 → 0.41.1

package/package.json

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

package/src/conversation/index.ts

@@ -8,6 +8,7 @@ import type {
   Contact,
   ContactAddress,
   ContactErasureRequest,
+  ContactGroup,
   ContactMergeProposal,
   Conversation,
   ConversationFilter,
@@ -15,9 +16,11 @@ import type {
   ConversationType,
   CreateAgentListenerRequest,
   CreateConnectionRequest,
+  CreateContactGroupRequest,
   CreateConversationFilterRequest,
   CreateConversationTypeRequest,
   CreateGlossaryTermRequest,
+  CreateToneProfileSetupRequest,
   CreateTranscriptionRequest,
   DeleteConnectionQuery,
   DispatchMeetingBotRequest,
@@ -26,6 +29,7 @@ import type {
   ListAgentListenersQuery,
   ListConnectionsQuery,
   ListContactAddressesQuery,
+  ListContactGroupsQuery,
   ListContactMergeProposalsQuery,
   ListContactsQuery,
   ListConversationFilterEventsQuery,
@@ -38,6 +42,8 @@ import type {
   ListReactionsResponse,
   ListResponse,
   ListRoomsQuery,
+  ListToneProfileSetupsQuery,
+  ListToneProfilesQuery,
   ListTranscriptionsQuery,
   MaterializeTranscriptionRequest,
   MergeContactsRequest,
@@ -45,13 +51,17 @@ import type {
   MistranscribedTerm,
   Reaction,
   RecordPermissionEventRequest,
+  ResolveToneProfileQuery,
   Room,
   SendMessageRequest,
   SyncConnectionRequest,
+  ToneProfile,
+  ToneProfileSetup,
   Transcription,
   UnreadCounts,
   UpdateAgentListenerRequest,
   UpdateConnectionRequest,
+  UpdateContactGroupRequest,
   UpdateContactRequest,
   UpdateConversationFilterRequest,
   UpdateConversationRequest,
@@ -87,6 +97,10 @@ export class ConversationClient {
   readonly glossaryTerms: GlossaryTermService
   /** Conversation taxonomy: the types the pre-summary classifier assigns. */
   readonly conversationTypes: ConversationTypeService
+  /** Generic audience taxonomy; membership lives on the contact. */
+  readonly contactGroups: ContactGroupService
+  /** Tone-of-voice synthesis: per-user setups + the generated profiles. */
+  readonly toneProfiles: ToneProfileService
   readonly transcriptions: TranscriptionService
   /** Review-pass findings: likely misheard terms awaiting accept/reject. */
   readonly mistranscribedTerms: MistranscribedTermService
@@ -104,6 +118,8 @@ export class ConversationClient {
     this.conversationFilters = new ConversationFilterServiceImpl(client)
     this.glossaryTerms = new GlossaryTermServiceImpl(client)
     this.conversationTypes = new ConversationTypeServiceImpl(client)
+    this.contactGroups = new ContactGroupServiceImpl(client)
+    this.toneProfiles = new ToneProfileServiceImpl(client)
     this.transcriptions = new TranscriptionServiceImpl(client)
     this.mistranscribedTerms = new MistranscribedTermServiceImpl(client)
     this.meetings = new MeetingServiceImpl(client)
@@ -802,6 +818,136 @@ class ConversationTypeServiceImpl implements ConversationTypeService {
   }
 }
 
+/**
+ * Contact groups: the generic org-shared audience taxonomy. Membership lives
+ * on the contact (`Contact.group_key`, one group per contact — assign via
+ * `contacts.update`); tone-of-voice synthesis reads the groups and
+ * auto-assigns ungrouped correspondents. Keyed by `key` (not id); `upsert` is
+ * the idempotent module-deploy door. Deleting a group clears its members'
+ * membership and purges its tone profile rows.
+ */
+export interface ContactGroupService {
+  list(query?: ListContactGroupsQuery): Promise<ListResponse<ContactGroup>>
+  get(key: string): Promise<ContactGroup>
+  create(request: CreateContactGroupRequest): Promise<ContactGroup>
+  update(key: string, request: UpdateContactGroupRequest): Promise<ContactGroup>
+  /** Idempotent create-or-update by key (PUT) — what `pro module deploy` calls. */
+  upsert(key: string, request: CreateContactGroupRequest): Promise<ContactGroup>
+  delete(key: string): Promise<void>
+}
+
+class ContactGroupServiceImpl implements ContactGroupService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(query: ListContactGroupsQuery = {}): Promise<ListResponse<ContactGroup>> {
+    return this.client.requestWithQuery('GET', `${CONVERSATION_BASE_PATH}/contact-groups`, query)
+  }
+
+  get(key: string): Promise<ContactGroup> {
+    return this.client.request(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/contact-groups/${encodeURIComponent(key)}`,
+    )
+  }
+
+  create(request: CreateContactGroupRequest): Promise<ContactGroup> {
+    return this.client.request('POST', `${CONVERSATION_BASE_PATH}/contact-groups`, request)
+  }
+
+  update(key: string, request: UpdateContactGroupRequest): Promise<ContactGroup> {
+    return this.client.request(
+      'PATCH',
+      `${CONVERSATION_BASE_PATH}/contact-groups/${encodeURIComponent(key)}`,
+      request,
+    )
+  }
+
+  upsert(key: string, request: CreateContactGroupRequest): Promise<ContactGroup> {
+    return this.client.request(
+      'PUT',
+      `${CONVERSATION_BASE_PATH}/contact-groups/${encodeURIComponent(key)}`,
+      { ...request, key },
+    )
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.client.request(
+      'DELETE',
+      `${CONVERSATION_BASE_PATH}/contact-groups/${encodeURIComponent(key)}`,
+    )
+  }
+}
+
+/**
+ * Tone-of-voice synthesis. A setup opts one platform user in (only set-up
+ * users are swept); `synthesize` triggers a whole-user run immediately (202;
+ * 409 `synthesis_in_progress` while one is live). Generated profiles form a
+ * specificity hierarchy — fetch a user's rows with `listProfiles`, or let the
+ * server pick the single most-specific row for a drafting context with
+ * `resolve` (each row is self-contained; never concatenate tiers).
+ */
+export interface ToneProfileService {
+  listSetups(query?: ListToneProfileSetupsQuery): Promise<ListResponse<ToneProfileSetup>>
+  createSetup(request: CreateToneProfileSetupRequest): Promise<ToneProfileSetup>
+  /** Removes the setup AND the user's generated profiles. */
+  deleteSetup(id: string): Promise<void>
+  /** Kicks a whole-user synthesis run off-request (bypasses cadence checks). */
+  synthesize(setupId: string): Promise<void>
+  listProfiles(query?: ListToneProfilesQuery): Promise<ListResponse<ToneProfile>>
+  getProfile(id: string): Promise<ToneProfile>
+  /** The single most-specific profile for a drafting context; 404 when none. */
+  resolve(query: ResolveToneProfileQuery): Promise<ToneProfile>
+}
+
+class ToneProfileServiceImpl implements ToneProfileService {
+  constructor(private readonly client: ProteosClient) {}
+
+  listSetups(query: ListToneProfileSetupsQuery = {}): Promise<ListResponse<ToneProfileSetup>> {
+    return this.client.requestWithQuery(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/tone-profile-setups`,
+      query,
+    )
+  }
+
+  createSetup(request: CreateToneProfileSetupRequest): Promise<ToneProfileSetup> {
+    return this.client.request('POST', `${CONVERSATION_BASE_PATH}/tone-profile-setups`, request)
+  }
+
+  async deleteSetup(id: string): Promise<void> {
+    await this.client.request(
+      'DELETE',
+      `${CONVERSATION_BASE_PATH}/tone-profile-setups/${encodeURIComponent(id)}`,
+    )
+  }
+
+  async synthesize(setupId: string): Promise<void> {
+    await this.client.request(
+      'POST',
+      `${CONVERSATION_BASE_PATH}/tone-profile-setups/${encodeURIComponent(setupId)}/synthesize`,
+    )
+  }
+
+  listProfiles(query: ListToneProfilesQuery = {}): Promise<ListResponse<ToneProfile>> {
+    return this.client.requestWithQuery('GET', `${CONVERSATION_BASE_PATH}/tone-profiles`, query)
+  }
+
+  getProfile(id: string): Promise<ToneProfile> {
+    return this.client.request(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/tone-profiles/${encodeURIComponent(id)}`,
+    )
+  }
+
+  resolve(query: ResolveToneProfileQuery): Promise<ToneProfile> {
+    return this.client.requestWithQuery(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/tone-profiles/resolve`,
+      query,
+    )
+  }
+}
+
 /** Batch transcription of stored audio files + materialization. */
 export interface TranscriptionService {
   /**

package/src/conversation/types.ts

@@ -716,6 +716,131 @@ export interface ListConversationTypesQuery extends PaginationQuery {
   module_slug?: string
 }
 
+/** Who assigned a contact's group membership. */
+export type ContactGroupSource = 'manual' | 'model'
+
+/**
+ * A generic org-shared audience taxonomy entry ("external-client",
+ * "internal-colleague", …) — NOT tone-specific. Membership lives on the
+ * contact (`Contact.group_key`, one group per contact) and is assignable by
+ * any flow; tone-of-voice synthesis both reads and auto-assigns groups.
+ * Module-deployable (contact-groups/<key>.json).
+ */
+export interface ContactGroup {
+  org_id: string
+  /** Immutable identity within the org — what models answer with. */
+  key: string
+  name: string
+  /** Who belongs in the group — injected verbatim into the synthesis prompt. */
+  description?: string
+  /** True when tone synthesis proposed the group. Server-owned. */
+  is_auto_created: boolean
+  /** Module that deployed the group; absent when not module-owned. */
+  module_slug?: string
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+export interface CreateContactGroupRequest {
+  /** Lowercase kebab/snake/camel handle — no spaces. */
+  key: string
+  name: string
+  description?: string
+  module_slug?: string
+}
+
+export interface UpdateContactGroupRequest {
+  name?: string
+  description?: string
+}
+
+export interface ListContactGroupsQuery extends PaginationQuery {
+  /** Case-insensitive substring match on key or name. */
+  search?: string
+  module_slug?: string
+}
+
+/** The whole-user synthesis lifecycle on a tone profile setup. */
+export type ToneProfileSetupStatus = 'empty' | 'processing' | 'ready'
+
+/** A tone profile row's tier — derived, most specific wins at read time. */
+export type ToneProfileScope = 'user' | 'channel' | 'group' | 'contact'
+
+/**
+ * The per-user opt-in for tone-of-voice synthesis: only set-up users are
+ * swept. Also carries the whole-user synthesis claim (status/started_at).
+ */
+export interface ToneProfileSetup {
+  id: string
+  org_id: string
+  /** The profiled platform user. */
+  owned_by: UserRef
+  status: ToneProfileSetupStatus
+  started_at?: string
+  last_synthesized_at?: string
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+/**
+ * One generated tone-of-voice instruction row. Rows form a specificity
+ * hierarchy — user aggregate (the constant voice), per-channel base, per
+ * contact-group, per individual contact — and every row is SELF-CONTAINED: a
+ * drafting consumer injects exactly one row's `instructions` verbatim (use
+ * the resolve endpoint), never a concatenation of tiers.
+ */
+export interface ToneProfile {
+  id: string
+  org_id: string
+  /** The profiled platform user. */
+  owned_by: UserRef
+  /** Absent = the cross-channel user aggregate (the voice proper). */
+  channel?: Channel
+  /** Scopes the row to one contact group; absent = the (user, channel) base. */
+  contact_group_key?: string
+  /** Scopes the row to one individual contact within the group. */
+  contact_id?: string
+  scope: ToneProfileScope
+  /** COMPLETE markdown instruction set, served verbatim to a drafting model. */
+  instructions: string
+  /** Short delta vs the tier above — what a human scans; empty on root tiers. */
+  differences?: string
+  sample_count: number
+  last_message_at?: string
+  last_synthesized_at?: string
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+export interface CreateToneProfileSetupRequest {
+  /** Bare platform user id; the service resolves the full ref. */
+  owned_by_id: string
+}
+
+export type ListToneProfileSetupsQuery = PaginationQuery
+
+export interface ListToneProfilesQuery extends PaginationQuery {
+  owned_by_id?: string
+  channel?: Channel
+  scope?: ToneProfileScope
+}
+
+/**
+ * A drafting context to resolve the single most-specific profile for:
+ * contact → group → channel base → user aggregate.
+ */
+export interface ResolveToneProfileQuery {
+  owned_by_id: string
+  channel?: Channel
+  contact_id?: string
+}
+
 export interface PaginationQuery {
   page?: number
   page_size?: number
@@ -993,6 +1118,13 @@ export interface Contact {
   /** Merge tombstone redirect (set when status is 'merged'). */
   merged_into_contact_id?: string
   source: ContactSource
+  /** ContactGroup membership (one group per contact); absent = unassigned. */
+  group_key?: string
+  /**
+   * Who assigned the group: 'manual' assignments are authoritative (tone
+   * synthesis never overrides them), 'model' ones may be reassigned by a run.
+   */
+  group_source?: ContactGroupSource
   has_manual_edits: boolean
   /** The contact's reachable endpoints, embedded on reads. */
   addresses?: ContactAddress[]
@@ -1105,12 +1237,19 @@ export interface ListContactsQuery extends PaginationQuery {
   /** Free-text needle matched against contact name + address values. */
   q?: string
   status?: ContactStatus
+  /** Members of one contact group (drives group-member lists). */
+  group_key?: string
 }
 
 export interface UpdateContactRequest {
   name?: string
   status?: 'active' | 'archived'
   has_legal_hold?: boolean
+  /**
+   * Assigns the contact to a contact group ('' clears). A PATCH assignment is
+   * stamped group_source='manual' — tone synthesis never overrides it.
+   */
+  group_key?: string
 }
 
 export interface AttachContactAddressRequest {

package/src/index.ts

@@ -221,6 +221,9 @@ export type {
   ContactAddressKind,
   ContactAddressSource,
   ContactErasureRequest,
+  ContactGroup,
+  ContactGroupService,
+  ContactGroupSource,
   ContactMergeProposal,
   ContactRef,
   ContactService,
@@ -244,9 +247,11 @@ export type {
   ConversationTypeService,
   CreateAgentListenerRequest,
   CreateConnectionRequest,
+  CreateContactGroupRequest,
   CreateConversationFilterRequest,
   CreateConversationTypeRequest,
   CreateGlossaryTermRequest,
+  CreateToneProfileSetupRequest,
   DispatchMeetingBotRequest,
   DomainFilterConfig,
   ErasureRequestStatus,
@@ -258,6 +263,7 @@ export type {
   ListAgentListenersQuery,
   ListConnectionsQuery,
   ListContactAddressesQuery,
+  ListContactGroupsQuery,
   ListContactMergeProposalsQuery,
   ListContactsQuery,
   ListConversationFilterEventsQuery,
@@ -271,6 +277,8 @@ export type {
   // PageIterator-based ListResult used by the other modules.
   ListResponse,
   ListRoomsQuery,
+  ListToneProfileSetupsQuery,
+  ListToneProfilesQuery,
   MeetingService,
   MergeContactsRequest,
   MergeProposalStatus,
@@ -293,11 +301,17 @@ export type {
   RecipientKind,
   RecipientRole,
   RecordPermissionEventRequest,
+  ResolveToneProfileQuery,
   RoleBasedFilterConfig,
   Room,
   SendMessageRequest,
   SendRecipient,
   SyncConnectionRequest,
+  ToneProfile,
+  ToneProfileScope,
+  ToneProfileService,
+  ToneProfileSetup,
+  ToneProfileSetupStatus,
   TranscribeStreamOptions,
   Transcription,
   TranscriptionReviewStatus,
@@ -307,6 +321,7 @@ export type {
   UnreadCounts,
   UpdateAgentListenerRequest,
   UpdateConnectionRequest,
+  UpdateContactGroupRequest,
   UpdateContactRequest,
   UpdateConversationFilterRequest,
   UpdateConversationTypeRequest,