@proteos/sdk 0.57.1 → 0.58.0

package/src/conversation/index.ts

@@ -21,7 +21,13 @@ import type {
   ConversationBrief,
   ConversationFilter,
   ConversationFilterEvent,
+  ConversationTag,
+  ConversationTagDefinition,
+  ConversationTagEvaluation,
+  ConversationTagSet,
   ConversationType,
+  CountConversationTagsQuery,
+  CountConversationTagsResponse,
   CreateAgentListenerRequest,
   CreateConnectionRequest,
   CreateContactGroupRequest,
@@ -29,6 +35,9 @@ import type {
   CreateContactRequest,
   CreateConversationBriefRequest,
   CreateConversationFilterRequest,
+  CreateConversationTagDefinitionRequest,
+  CreateConversationTagRequest,
+  CreateConversationTagSetRequest,
   CreateConversationTypeRequest,
   CreateGlossaryTermRequest,
   CreateSendingRuleRequest,
@@ -42,6 +51,7 @@ import type {
   EmailSender,
   EmailSuppression,
   EmailSuppressionKind,
+  EvaluateConversationTagsRequest,
   GetConnectionHealthQuery,
   GlossaryTerm,
   InstallConnectionRequest,
@@ -59,6 +69,10 @@ import type {
   ListConversationFilterEventsQuery,
   ListConversationFiltersQuery,
   ListConversationsQuery,
+  ListConversationTagDefinitionsQuery,
+  ListConversationTagEvaluationsQuery,
+  ListConversationTagSetsQuery,
+  ListConversationTagsQuery,
   ListConversationTypesQuery,
   ListGlossaryTermsQuery,
   ListMessagesQuery,
@@ -101,6 +115,9 @@ import type {
   UpdateConversationBriefRequest,
   UpdateConversationFilterRequest,
   UpdateConversationRequest,
+  UpdateConversationTagDefinitionRequest,
+  UpdateConversationTagRequest,
+  UpdateConversationTagSetRequest,
   UpdateConversationTypeRequest,
   UpdateDraftRequest,
   UpdateGlossaryTermRequest,
@@ -144,6 +161,12 @@ export class ConversationClient {
   readonly glossaryTerms: GlossaryTermService
   /** Conversation taxonomy: the types the pre-summary classifier assigns. */
   readonly conversationTypes: ConversationTypeService
+  /** Conversation intelligence: WHAT to look for — typed questions asked of conversations. */
+  readonly conversationTagDefinitions: ConversationTagDefinitionService
+  /** Conversation intelligence: WHERE and WHEN definitions are evaluated. */
+  readonly conversationTagSets: ConversationTagSetService
+  /** Conversation intelligence: the observations produced + their evaluation history. */
+  readonly conversationTags: ConversationTagService
   /** Generic audience taxonomy; membership lives on the contact. */
   readonly contactGroups: ContactGroupService
   /** Tone-of-voice synthesis: per-user setups + the generated profiles. */
@@ -171,6 +194,9 @@ export class ConversationClient {
     this.channelEvents = new ChannelEventServiceImpl(client)
     this.glossaryTerms = new GlossaryTermServiceImpl(client)
     this.conversationTypes = new ConversationTypeServiceImpl(client)
+    this.conversationTagDefinitions = new ConversationTagDefinitionServiceImpl(client)
+    this.conversationTagSets = new ConversationTagSetServiceImpl(client)
+    this.conversationTags = new ConversationTagServiceImpl(client)
     this.contactGroups = new ContactGroupServiceImpl(client)
     this.toneProfiles = new ToneProfileServiceImpl(client)
     this.transcriptions = new TranscriptionServiceImpl(client)
@@ -1044,6 +1070,266 @@ class ConversationTypeServiceImpl implements ConversationTypeService {
   }
 }
 
+/**
+ * Conversation tag definitions: WHAT to look for in a conversation — one
+ * typed question (boolean / choice / score) plus where its answers anchor
+ * (`scope`) and which model path answers (`evaluator`). A definition is only
+ * evaluated through the tag sets that reference it. Keyed by `key` (not id);
+ * `upsert` is the idempotent module-deploy door.
+ */
+export interface ConversationTagDefinitionService {
+  list(
+    query?: ListConversationTagDefinitionsQuery,
+  ): Promise<ListResponse<ConversationTagDefinition>>
+  get(key: string): Promise<ConversationTagDefinition>
+  create(request: CreateConversationTagDefinitionRequest): Promise<ConversationTagDefinition>
+  update(
+    key: string,
+    request: UpdateConversationTagDefinitionRequest,
+  ): Promise<ConversationTagDefinition>
+  /** Idempotent create-or-update by key (PUT) — what `pro module deploy` calls. */
+  upsert(
+    key: string,
+    request: CreateConversationTagDefinitionRequest,
+  ): Promise<ConversationTagDefinition>
+  delete(key: string): Promise<void>
+}
+
+class ConversationTagDefinitionServiceImpl implements ConversationTagDefinitionService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(
+    query: ListConversationTagDefinitionsQuery = {},
+  ): Promise<ListResponse<ConversationTagDefinition>> {
+    return this.client.requestWithQuery(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversation-tag-definitions`,
+      query,
+    )
+  }
+
+  get(key: string): Promise<ConversationTagDefinition> {
+    return this.client.request(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversation-tag-definitions/${encodeURIComponent(key)}`,
+    )
+  }
+
+  create(request: CreateConversationTagDefinitionRequest): Promise<ConversationTagDefinition> {
+    return this.client.request(
+      'POST',
+      `${CONVERSATION_BASE_PATH}/conversation-tag-definitions`,
+      request,
+    )
+  }
+
+  update(
+    key: string,
+    request: UpdateConversationTagDefinitionRequest,
+  ): Promise<ConversationTagDefinition> {
+    return this.client.request(
+      'PATCH',
+      `${CONVERSATION_BASE_PATH}/conversation-tag-definitions/${encodeURIComponent(key)}`,
+      request,
+    )
+  }
+
+  upsert(
+    key: string,
+    request: CreateConversationTagDefinitionRequest,
+  ): Promise<ConversationTagDefinition> {
+    return this.client.request(
+      'PUT',
+      `${CONVERSATION_BASE_PATH}/conversation-tag-definitions/${encodeURIComponent(key)}`,
+      { ...request, key },
+    )
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.client.request(
+      'DELETE',
+      `${CONVERSATION_BASE_PATH}/conversation-tag-definitions/${encodeURIComponent(key)}`,
+    )
+  }
+}
+
+/**
+ * Conversation tag sets: WHERE and WHEN a group of definitions is evaluated.
+ * A set needs at least one conversation selector (`channels`,
+ * `connection_ids`, `type_keys`) — tagging is opt-in, never org-wide by
+ * accident — and `evaluate_on` is a non-empty subset of realtime|completion.
+ * Keyed by `key` (not id); `upsert` is the idempotent module-deploy door.
+ */
+export interface ConversationTagSetService {
+  list(query?: ListConversationTagSetsQuery): Promise<ListResponse<ConversationTagSet>>
+  get(key: string): Promise<ConversationTagSet>
+  create(request: CreateConversationTagSetRequest): Promise<ConversationTagSet>
+  update(key: string, request: UpdateConversationTagSetRequest): Promise<ConversationTagSet>
+  /** Idempotent create-or-update by key (PUT) — what `pro module deploy` calls. */
+  upsert(key: string, request: CreateConversationTagSetRequest): Promise<ConversationTagSet>
+  delete(key: string): Promise<void>
+}
+
+class ConversationTagSetServiceImpl implements ConversationTagSetService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(query: ListConversationTagSetsQuery = {}): Promise<ListResponse<ConversationTagSet>> {
+    return this.client.requestWithQuery(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversation-tag-sets`,
+      query,
+    )
+  }
+
+  get(key: string): Promise<ConversationTagSet> {
+    return this.client.request(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversation-tag-sets/${encodeURIComponent(key)}`,
+    )
+  }
+
+  create(request: CreateConversationTagSetRequest): Promise<ConversationTagSet> {
+    return this.client.request('POST', `${CONVERSATION_BASE_PATH}/conversation-tag-sets`, request)
+  }
+
+  update(key: string, request: UpdateConversationTagSetRequest): Promise<ConversationTagSet> {
+    return this.client.request(
+      'PATCH',
+      `${CONVERSATION_BASE_PATH}/conversation-tag-sets/${encodeURIComponent(key)}`,
+      request,
+    )
+  }
+
+  upsert(key: string, request: CreateConversationTagSetRequest): Promise<ConversationTagSet> {
+    return this.client.request(
+      'PUT',
+      `${CONVERSATION_BASE_PATH}/conversation-tag-sets/${encodeURIComponent(key)}`,
+      { ...request, key },
+    )
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.client.request(
+      'DELETE',
+      `${CONVERSATION_BASE_PATH}/conversation-tag-sets/${encodeURIComponent(key)}`,
+    )
+  }
+}
+
+/**
+ * Conversation tags: the observations definitions make on conversations,
+ * plus the evaluations that produced them. Per-conversation reads/writes
+ * hang off the conversation; `update`/`delete` address a tag by id; `list`
+ * and `counts` are the org-wide streams. Span offsets are UNICODE CODE POINT
+ * indexes (end exclusive) — convert to/from UTF-16 before slicing JS strings.
+ */
+export interface ConversationTagService {
+  /** Tags on one conversation (pending, active and dismissed unless `status` filters). */
+  listByConversation(
+    conversationId: string,
+    query?: ListConversationTagsQuery,
+  ): Promise<ListResponse<ConversationTag>>
+  /** A person tags a conversation, a message or a span (source = user, confidence 1). */
+  create(conversationId: string, request: CreateConversationTagRequest): Promise<ConversationTag>
+  /**
+   * Start a manual evaluation (202). Resolves with the PENDING evaluation as
+   * soon as it is accepted — the tagger runs server-side beyond this request.
+   * Poll `listEvaluations(conversationId)` until that evaluation's status is
+   * `done` | `failed`, then re-read the tags. 409
+   * `conversation_tag_set_not_matched` when no enabled set matches the
+   * conversation; 409 `conversation_tag_evaluation_in_progress` while another
+   * evaluation is still running.
+   */
+  evaluate(
+    conversationId: string,
+    request?: EvaluateConversationTagsRequest,
+  ): Promise<ConversationTagEvaluation>
+  /** The evaluation history of one conversation (newest first by default). */
+  listEvaluations(
+    conversationId: string,
+    query?: ListConversationTagEvaluationsQuery,
+  ): Promise<ListResponse<ConversationTagEvaluation>>
+  /** Flip a tag between active and dismissed (the feedback loop) and/or annotate why. */
+  update(id: string, request: UpdateConversationTagRequest): Promise<ConversationTag>
+  delete(id: string): Promise<void>
+  /** Org-wide tag stream (filter by definition, value, channel, contact, time window). */
+  list(query?: ListConversationTagsQuery): Promise<ListResponse<ConversationTag>>
+  /** Grouped counts for dashboards — `group_by` is a comma-joined string. */
+  counts(query?: CountConversationTagsQuery): Promise<CountConversationTagsResponse>
+}
+
+class ConversationTagServiceImpl implements ConversationTagService {
+  constructor(private readonly client: ProteosClient) {}
+
+  listByConversation(
+    conversationId: string,
+    query: ListConversationTagsQuery = {},
+  ): Promise<ListResponse<ConversationTag>> {
+    return this.client.requestWithQuery(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(conversationId)}/tags`,
+      query,
+    )
+  }
+
+  create(conversationId: string, request: CreateConversationTagRequest): Promise<ConversationTag> {
+    return this.client.request(
+      'POST',
+      `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(conversationId)}/tags`,
+      request,
+    )
+  }
+
+  evaluate(
+    conversationId: string,
+    request: EvaluateConversationTagsRequest = {},
+  ): Promise<ConversationTagEvaluation> {
+    return this.client.request(
+      'POST',
+      `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(conversationId)}/tags/evaluate`,
+      request,
+    )
+  }
+
+  listEvaluations(
+    conversationId: string,
+    query: ListConversationTagEvaluationsQuery = {},
+  ): Promise<ListResponse<ConversationTagEvaluation>> {
+    return this.client.requestWithQuery(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(conversationId)}/tag-evaluations`,
+      query,
+    )
+  }
+
+  update(id: string, request: UpdateConversationTagRequest): Promise<ConversationTag> {
+    return this.client.request(
+      'PATCH',
+      `${CONVERSATION_BASE_PATH}/conversation-tags/${encodeURIComponent(id)}`,
+      request,
+    )
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.client.request(
+      'DELETE',
+      `${CONVERSATION_BASE_PATH}/conversation-tags/${encodeURIComponent(id)}`,
+    )
+  }
+
+  list(query: ListConversationTagsQuery = {}): Promise<ListResponse<ConversationTag>> {
+    return this.client.requestWithQuery('GET', `${CONVERSATION_BASE_PATH}/conversation-tags`, query)
+  }
+
+  counts(query: CountConversationTagsQuery = {}): Promise<CountConversationTagsResponse> {
+    return this.client.requestWithQuery(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversation-tags/counts`,
+      query,
+    )
+  }
+}
+
 /**
  * Contact groups: the generic org-shared audience taxonomy. Membership lives
  * on the contact (`Contact.group_key`, one group per contact — assign via