@proteos/sdk 0.61.0 → 0.75.0

package/src/conversation/index.ts

@@ -21,11 +21,18 @@ import type {
   ConversationBrief,
   ConversationFilter,
   ConversationFilterEvent,
+  ConversationNote,
+  ConversationObjective,
+  ConversationObjectiveDefinition,
+  ConversationObjectiveProgress,
+  ConversationOutcomeOption,
   ConversationTag,
   ConversationTagDefinition,
   ConversationTagEvaluation,
   ConversationTagSet,
   ConversationType,
+  CountConversationObjectivesQuery,
+  CountConversationObjectivesResponse,
   CountConversationTagsQuery,
   CountConversationTagsResponse,
   CreateAgentListenerRequest,
@@ -35,6 +42,8 @@ import type {
   CreateContactRequest,
   CreateConversationBriefRequest,
   CreateConversationFilterRequest,
+  CreateConversationNoteRequest,
+  CreateConversationObjectiveDefinitionRequest,
   CreateConversationTagDefinitionRequest,
   CreateConversationTagRequest,
   CreateConversationTagSetRequest,
@@ -53,6 +62,8 @@ import type {
   EmailSuppressionKind,
   EvaluateConversationTagsRequest,
   GetConnectionHealthQuery,
+  GetManyConversationObjectiveDefinitionsQuery,
+  GetManyConversationObjectivesQuery,
   GlossaryTerm,
   InstallConnectionRequest,
   InstallConnectionResponse,
@@ -66,8 +77,10 @@ import type {
   ListContactRecordLinksQuery,
   ListContactsQuery,
   ListConversationBriefsQuery,
+  ListMeetingBotsQuery,
   ListConversationFilterEventsQuery,
   ListConversationFiltersQuery,
+  ListConversationNotesQuery,
   ListConversationsQuery,
   ListConversationTagDefinitionsQuery,
   ListConversationTagEvaluationsQuery,
@@ -88,6 +101,7 @@ import type {
   MaterializeTranscriptionRequest,
   MergeContactsRequest,
   Message,
+  MeetingBot,
   MintCallTokenRequest,
   MistranscribedTerm,
   PerformChannelActionRequest,
@@ -102,6 +116,7 @@ import type {
   SendingLimitPreset,
   SendingRule,
   SendMessageRequest,
+  SetCallRecordingRequest,
   SetDefaultSenderRequest,
   SyncConnectionRequest,
   ToneProfile,
@@ -114,6 +129,8 @@ import type {
   UpdateContactRequest,
   UpdateConversationBriefRequest,
   UpdateConversationFilterRequest,
+  UpdateConversationNoteRequest,
+  UpdateConversationObjectiveDefinitionRequest,
   UpdateConversationRequest,
   UpdateConversationTagDefinitionRequest,
   UpdateConversationTagRequest,
@@ -167,6 +184,10 @@ export class ConversationClient {
   readonly conversationTagSets: ConversationTagSetService
   /** Conversation intelligence: the observations produced + their evaluation history. */
   readonly conversationTags: ConversationTagService
+  /** Conversation objectives: WHAT a conversation should achieve (config, keyed, module-deployable). */
+  readonly conversationObjectiveDefinitions: ConversationObjectiveDefinitionService
+  /** Conversation objectives: the org-wide ledger of standings + grouped counts (read-only). */
+  readonly conversationObjectives: ConversationObjectiveService
   /** Generic audience taxonomy; membership lives on the contact. */
   readonly contactGroups: ContactGroupService
   /** Tone-of-voice synthesis: per-user setups + the generated profiles. */
@@ -174,13 +195,17 @@ export class ConversationClient {
   readonly transcriptions: TranscriptionService
   /** Review-pass findings: likely misheard terms awaiting accept/reject. */
   readonly mistranscribedTerms: MistranscribedTermService
-  /** Meeting bots (Ava): dispatch into a meeting URL, remove from a meeting. */
+  /** Meeting bots (Ava): dispatch into a meeting URL, summaries. */
   readonly meetings: MeetingService
+  /** Ava's bots as remembered by the platform: list them, withdraw her from a meeting. */
+  readonly meetingBots: MeetingBotService
   /** Realtime speech-to-text (dictation) — moved here from agent-service. */
   readonly voice: VoiceService
   readonly calls: CallService
   /** Conversation briefs: guidance prepared ahead of a conversation (call, meeting) with a contact. */
   readonly conversationBriefs: ConversationBriefService
+  /** Conversation notes: what a person recorded about a conversation (append log, author-stamped). */
+  readonly conversationNotes: ConversationNoteService
 
   constructor(client: ProteosClient) {
     this.connections = new ConnectionServiceImpl(client)
@@ -197,18 +222,77 @@ export class ConversationClient {
     this.conversationTagDefinitions = new ConversationTagDefinitionServiceImpl(client)
     this.conversationTagSets = new ConversationTagSetServiceImpl(client)
     this.conversationTags = new ConversationTagServiceImpl(client)
+    this.conversationObjectiveDefinitions = new ConversationObjectiveDefinitionServiceImpl(client)
+    this.conversationObjectives = new ConversationObjectiveServiceImpl(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)
+    this.meetingBots = new MeetingBotServiceImpl(client)
     this.voice = new VoiceServiceImpl(client)
     this.calls = new CallServiceImpl(client)
     this.conversationBriefs = new ConversationBriefServiceImpl(client)
+    this.conversationNotes = new ConversationNoteServiceImpl(client)
   }
 }
 
-/** Meeting bots (Ava) — dispatch by meeting URL and removal. */
+/** Conversation notes — what a person recorded about a conversation. */
+export interface ConversationNoteService {
+  /** A conversation's notes, oldest first by default. */
+  list(
+    conversationId: string,
+    query?: ListConversationNotesQuery,
+  ): Promise<ListResponse<ConversationNote>>
+  create(conversationId: string, request: CreateConversationNoteRequest): Promise<ConversationNote>
+  /** Author only (403 `conversation_note_not_author`). */
+  update(id: string, request: UpdateConversationNoteRequest): Promise<ConversationNote>
+  /** Author only (403 `conversation_note_not_author`). */
+  delete(id: string): Promise<void>
+}
+
+class ConversationNoteServiceImpl implements ConversationNoteService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(
+    conversationId: string,
+    query: ListConversationNotesQuery = {},
+  ): Promise<ListResponse<ConversationNote>> {
+    return this.client.requestWithQuery(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(conversationId)}/notes`,
+      query,
+    )
+  }
+
+  create(
+    conversationId: string,
+    request: CreateConversationNoteRequest,
+  ): Promise<ConversationNote> {
+    return this.client.request(
+      'POST',
+      `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(conversationId)}/notes`,
+      request,
+    )
+  }
+
+  update(id: string, request: UpdateConversationNoteRequest): Promise<ConversationNote> {
+    return this.client.request(
+      'PATCH',
+      `${CONVERSATION_BASE_PATH}/conversation-notes/${encodeURIComponent(id)}`,
+      request,
+    )
+  }
+
+  delete(id: string): Promise<void> {
+    return this.client.request(
+      'DELETE',
+      `${CONVERSATION_BASE_PATH}/conversation-notes/${encodeURIComponent(id)}`,
+    )
+  }
+}
+
+/** Meeting bots (Ava) — dispatch by meeting URL, summaries. */
 export interface MeetingService {
   /**
    * Send Ava to a meeting URL. Resolves with the pre-minted meeting
@@ -216,8 +300,6 @@ export interface MeetingService {
    * turns then stream in as inbound messages while the meeting runs.
    */
   dispatch(request: DispatchMeetingBotRequest): Promise<Conversation>
-  /** Make the bot leave the meeting and end the conversation (by conversation id). */
-  remove(conversationId: string): Promise<Conversation>
   /**
    * START regenerating this meeting conversation's markdown summary from its
    * stored transcript, overwriting any existing one when it lands. Generation
@@ -241,17 +323,42 @@ class MeetingServiceImpl implements MeetingService {
     return this.client.request('POST', `${CONVERSATION_BASE_PATH}/meetings`, request)
   }
 
-  remove(conversationId: string): Promise<Conversation> {
+  summarize(conversationId: string): Promise<Conversation> {
     return this.client.request(
-      'DELETE',
-      `${CONVERSATION_BASE_PATH}/meetings/${encodeURIComponent(conversationId)}`,
+      'POST',
+      `${CONVERSATION_BASE_PATH}/meetings/${encodeURIComponent(conversationId)}/summarize`,
     )
   }
+}
 
-  summarize(conversationId: string): Promise<Conversation> {
+/**
+ * Ava's bots as the platform remembers them: what a client shows as "Ava joins"
+ * for a meeting, and the door to withdraw her.
+ */
+export interface MeetingBotService {
+  /** The bots the caller may see, soonest meeting first. */
+  list(query?: ListMeetingBotsQuery): Promise<ListResponse<MeetingBot>>
+  /**
+   * Withdraw Ava from the meeting this bot belongs to: every bot of that
+   * meeting instance the caller may act on (scheduled from their connection,
+   * or on a meeting they are invited to) is cancelled (scheduled) or leaves
+   * the call (live), the rows become `removed`, and the calendar will not
+   * schedule her again. Re-add her explicitly with `meetings.dispatch`.
+   */
+  remove(id: string): Promise<MeetingBot>
+}
+
+class MeetingBotServiceImpl implements MeetingBotService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(query: ListMeetingBotsQuery = {}): Promise<ListResponse<MeetingBot>> {
+    return this.client.requestWithQuery('GET', `${CONVERSATION_BASE_PATH}/meeting-bots`, query)
+  }
+
+  remove(id: string): Promise<MeetingBot> {
     return this.client.request(
-      'POST',
-      `${CONVERSATION_BASE_PATH}/meetings/${encodeURIComponent(conversationId)}/summarize`,
+      'DELETE',
+      `${CONVERSATION_BASE_PATH}/meeting-bots/${encodeURIComponent(id)}`,
     )
   }
 }
@@ -654,6 +761,18 @@ export interface ConversationService {
   get(id: string): Promise<Conversation>
   /** Patch the user-editable surface (subject, summary, status, metadata). */
   update(id: string, request: UpdateConversationRequest): Promise<Conversation>
+  /**
+   * What the conversation may end with: its type's outcomes, then its
+   * channel's system outcomes — the picker's list and the valid
+   * `outcome_key` values for `update`.
+   */
+  listOutcomes(id: string): Promise<{ data: ConversationOutcomeOption[] }>
+  /**
+   * Where the conversation stands against its objectives: the current phase,
+   * every phase's status, every applicable objective's standing and the
+   * definitions they reference — the checklist from one read.
+   */
+  getObjectiveProgress(id: string): Promise<ConversationObjectiveProgress>
   end(id: string): Promise<Conversation>
   /**
    * Hard-delete the conversation, its thread children, and every dependent
@@ -682,6 +801,21 @@ class ConversationServiceImpl implements ConversationService {
     )
   }
 
+  listOutcomes(id: string): Promise<{ data: ConversationOutcomeOption[] }> {
+    return this.client.request(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(id)}/outcomes`,
+    )
+  }
+
+  async getObjectiveProgress(id: string): Promise<ConversationObjectiveProgress> {
+    const response = await this.client.request<{ data: ConversationObjectiveProgress }>(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(id)}/objective-progress`,
+    )
+    return response.data
+  }
+
   update(id: string, request: UpdateConversationRequest): Promise<Conversation> {
     return this.client.request(
       'PATCH',
@@ -1259,6 +1393,14 @@ export interface ConversationTagService {
   list(query?: ListConversationTagsQuery): Promise<ListResponse<ConversationTag>>
   /** Grouped counts for dashboards — `group_by` is a comma-joined string. */
   counts(query?: CountConversationTagsQuery): Promise<CountConversationTagsResponse>
+  /**
+   * The enabled definitions the enabled sets select for the conversation right
+   * now (`evaluate_on` ignored, like a manual evaluation) — what a person may
+   * tag it with, incl. its outcome definition(s) (`role === 'outcome'`).
+   */
+  listApplicableDefinitions(
+    conversationId: string,
+  ): Promise<ListResponse<ConversationTagDefinition>>
 }
 
 class ConversationTagServiceImpl implements ConversationTagService {
@@ -1283,6 +1425,15 @@ class ConversationTagServiceImpl implements ConversationTagService {
     )
   }
 
+  listApplicableDefinitions(
+    conversationId: string,
+  ): Promise<ListResponse<ConversationTagDefinition>> {
+    return this.client.request(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(conversationId)}/tag-definitions`,
+    )
+  }
+
   evaluate(
     conversationId: string,
     request: EvaluateConversationTagsRequest = {},
@@ -1333,6 +1484,143 @@ class ConversationTagServiceImpl implements ConversationTagService {
   }
 }
 
+/**
+ * Conversation objective definitions: WHAT a conversation should achieve —
+ * "confirm the budget", "book the demo" — org-wide or per conversation type,
+ * optionally pinned to one of the type's phases, optionally MEASURED (a tag
+ * value condition or an outcome set) so the platform can tell when it was
+ * achieved. Keyed by `key` (not id); `upsert` is the idempotent module-deploy
+ * door.
+ */
+export interface ConversationObjectiveDefinitionService {
+  list(
+    query?: GetManyConversationObjectiveDefinitionsQuery,
+  ): Promise<ListResponse<ConversationObjectiveDefinition>>
+  /** One page, explicitly (`query.page`) — the door a page walker calls; same wire call as `list`. */
+  listPage(
+    query?: GetManyConversationObjectiveDefinitionsQuery,
+  ): Promise<ListResponse<ConversationObjectiveDefinition>>
+  get(key: string): Promise<ConversationObjectiveDefinition>
+  create(
+    request: CreateConversationObjectiveDefinitionRequest,
+  ): Promise<ConversationObjectiveDefinition>
+  /** Partial update; `measure: null` clears the measure (guidance only). */
+  update(
+    key: string,
+    request: UpdateConversationObjectiveDefinitionRequest,
+  ): Promise<ConversationObjectiveDefinition>
+  /** Idempotent create-or-update by key (PUT) — what `pro module deploy` calls. */
+  upsert(
+    key: string,
+    request: CreateConversationObjectiveDefinitionRequest,
+  ): Promise<ConversationObjectiveDefinition>
+  delete(key: string): Promise<void>
+}
+
+class ConversationObjectiveDefinitionServiceImpl implements ConversationObjectiveDefinitionService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(
+    query: GetManyConversationObjectiveDefinitionsQuery = {},
+  ): Promise<ListResponse<ConversationObjectiveDefinition>> {
+    return this.listPage(query)
+  }
+
+  listPage(
+    query: GetManyConversationObjectiveDefinitionsQuery = {},
+  ): Promise<ListResponse<ConversationObjectiveDefinition>> {
+    return this.client.requestWithQuery(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversation-objective-definitions`,
+      query,
+    )
+  }
+
+  get(key: string): Promise<ConversationObjectiveDefinition> {
+    return this.client.request(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversation-objective-definitions/${encodeURIComponent(key)}`,
+    )
+  }
+
+  create(
+    request: CreateConversationObjectiveDefinitionRequest,
+  ): Promise<ConversationObjectiveDefinition> {
+    return this.client.request(
+      'POST',
+      `${CONVERSATION_BASE_PATH}/conversation-objective-definitions`,
+      request,
+    )
+  }
+
+  update(
+    key: string,
+    request: UpdateConversationObjectiveDefinitionRequest,
+  ): Promise<ConversationObjectiveDefinition> {
+    return this.client.request(
+      'PATCH',
+      `${CONVERSATION_BASE_PATH}/conversation-objective-definitions/${encodeURIComponent(key)}`,
+      request,
+    )
+  }
+
+  upsert(
+    key: string,
+    request: CreateConversationObjectiveDefinitionRequest,
+  ): Promise<ConversationObjectiveDefinition> {
+    return this.client.request(
+      'PUT',
+      `${CONVERSATION_BASE_PATH}/conversation-objective-definitions/${encodeURIComponent(key)}`,
+      { ...request, key },
+    )
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.client.request(
+      'DELETE',
+      `${CONVERSATION_BASE_PATH}/conversation-objective-definitions/${encodeURIComponent(key)}`,
+    )
+  }
+}
+
+/**
+ * Conversation objectives: the org-wide ledger of every applicable
+ * definition's standing on every conversation (open rows included), plus
+ * grouped counts for dashboards. Read-only — a standing is resolved by the
+ * service from the conversation's tags and outcome; the per-conversation
+ * checklist is `conversations.getObjectiveProgress`.
+ */
+export interface ConversationObjectiveService {
+  /** The ledger (filter by conversation, definition, type, phase, channel, status, source, time window on `recorded_at`). */
+  list(query?: GetManyConversationObjectivesQuery): Promise<ListResponse<ConversationObjective>>
+  /** Grouped counts for dashboards — `group_by` is a comma-joined string. */
+  counts(query?: CountConversationObjectivesQuery): Promise<CountConversationObjectivesResponse>
+}
+
+class ConversationObjectiveServiceImpl implements ConversationObjectiveService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(
+    query: GetManyConversationObjectivesQuery = {},
+  ): Promise<ListResponse<ConversationObjective>> {
+    return this.client.requestWithQuery(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversation-objectives`,
+      query,
+    )
+  }
+
+  counts(
+    query: CountConversationObjectivesQuery = {},
+  ): Promise<CountConversationObjectivesResponse> {
+    return this.client.requestWithQuery(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversation-objectives/counts`,
+      query,
+    )
+  }
+}
+
 /**
  * Contact groups: the generic org-shared audience taxonomy. Membership lives
  * on the contact (`Contact.group_key`, one group per contact — assign via
@@ -1624,6 +1912,14 @@ class MistranscribedTermServiceImpl implements MistranscribedTermService {
  */
 export interface CallService {
   mintToken(request: MintCallTokenRequest): Promise<CallTokenResponse>
+  /**
+   * The conversation a provider call became — the softphone's outbound
+   * browser-leg CallSid. 404 `call_not_found` until the call-start callback
+   * minted it (poll briefly).
+   */
+  getCallConversation(connectionId: string, externalCallId: string): Promise<Conversation>
+  /** Start / resume (true) or pause (false) the recording of a live phone conversation. */
+  setRecording(conversationId: string, request: SetCallRecordingRequest): Promise<Conversation>
   /** A phone connection's provider numbers with status + routing. */
   listPhoneNumbers(connectionId: string): Promise<{ data: PhoneNumber[] }>
   /** Replace one number's routing (who it rings). Returns the refreshed list. */
@@ -1651,6 +1947,21 @@ class CallServiceImpl implements CallService {
     return this.client.request('POST', `${CONVERSATION_BASE_PATH}/calls/token`, request)
   }
 
+  getCallConversation(connectionId: string, externalCallId: string): Promise<Conversation> {
+    return this.client.request(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/connections/${encodeURIComponent(connectionId)}/calls/${encodeURIComponent(externalCallId)}`,
+    )
+  }
+
+  setRecording(conversationId: string, request: SetCallRecordingRequest): Promise<Conversation> {
+    return this.client.request(
+      'PUT',
+      `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(conversationId)}/recording`,
+      request,
+    )
+  }
+
   listPhoneNumbers(connectionId: string): Promise<{ data: PhoneNumber[] }> {
     return this.client.request(
       'GET',
@@ -1703,11 +2014,12 @@ export type {
 /**
  * Conversation briefs — guidance prepared ahead of a conversation ("talk to
  * these people about this"; the conversation sibling of message drafts).
- * Binding is explicit: the softphone carries the brief id into the call, or
- * `attach` names the conversation. Any number of briefs may be open for the
- * same people. Edits/attach on a non-open brief fail 409
- * `conversation_brief_not_editable`; a conversation already carrying a brief
- * refuses another (409 `conversation_brief_already_attached`).
+ * Binding is explicit: the softphone carries the brief id into the call, a
+ * brief naming a calendar event attaches to that meeting's conversation when
+ * the meeting bot starts, or `attach` names the conversation. Any number of
+ * briefs may be open for the same people or meeting, and a conversation may
+ * carry several. Edits/attach on a non-open brief fail 409
+ * `conversation_brief_not_editable`.
  */
 export interface ConversationBriefService {
   list(query?: ListConversationBriefsQuery): Promise<ListResponse<ConversationBrief>>