@proteos/sdk 0.61.0 → 0.75.0

package/src/conversation/types.ts

@@ -3,7 +3,7 @@
  * mirror of packages/go/model/conversation (snake_case, Is-prefixed booleans).
  */
 
-import type { PrincipalRef } from '../meta/types.js'
+import type { PageAction, PrincipalRef } from '../meta/types.js'
 import type { FileRef } from '../types/common.js'
 
 /**
@@ -74,6 +74,16 @@ export interface MintCallTokenRequest {
   connection_id: string
 }
 
+/**
+ * PUT /conversations/:id/recording — the in-call recording control on a live
+ * phone conversation: true starts (or resumes) the recording, false pauses
+ * it. A recording that did not run from answer to hangup is marked
+ * `has_partial_recording` on the conversation's metadata.
+ */
+export interface SetCallRecordingRequest {
+  is_recording_enabled: boolean
+}
+
 /**
  * Which system answers a provider phone number: connected to this platform,
  * in use by another integration (connecting takes it over, disconnecting
@@ -114,6 +124,69 @@ export interface UpdatePhoneNumberRequest {
   routing?: PhoneNumberRouting
 }
 
+/**
+ * twilio-phone `connection.settings.voicemail` — what a caller hears when no
+ * agent takes the ring. The greeting is spoken by the provider's text-to-speech
+ * in `language`; absent or blank fields fall back to platform defaults.
+ */
+export interface TwilioPhoneVoicemailSettings {
+  is_enabled: boolean
+  /** Empty = the platform's default English text. At most 1000 characters. */
+  greeting?: string
+  /** BCP-47, one of the supported TTS languages; default en-US. */
+  language?: string
+  /** 10..300, default 120. */
+  max_duration_seconds?: number
+}
+
+/**
+ * The typed slice of a twilio-phone `connection.settings` the softphone reads
+ * (`Connection.settings` stays an open map on the wire).
+ */
+export interface TwilioPhoneSettings {
+  is_softphone_enabled?: boolean
+  is_recording_enabled?: boolean
+  is_realtime_transcription_enabled?: boolean
+  /** How long the parallel ring waits before the call counts as missed; 5..60, default 25. */
+  ring_timeout_seconds?: number
+  voicemail?: TwilioPhoneVoicemailSettings
+}
+
+/** Why an inbound ring ended without one of our people on the line. */
+export type CallDialStatus =
+  | 'no_answer'
+  | 'busy'
+  | 'failed'
+  | 'canceled'
+  /** Nobody was routed to the number. */
+  | 'unrouted'
+  /** The caller left while it rang. */
+  | 'caller_hung_up'
+
+/**
+ * The call facts a phone conversation carries in `metadata` (mirrors the
+ * backend's logic/call-status.go + call-voicemail.go). Every key is optional
+ * on the wire; read defensively.
+ */
+export interface CallMetadata {
+  call_direction?: 'inbound' | 'outbound'
+  call_status?: CallStatus
+  from_number?: string
+  to_number?: string
+  /** Provider talk time; on a missed call it includes greeting + voicemail. */
+  duration_seconds?: number
+  recording_external_id?: string
+  recording_file_id?: string
+  is_recording_enabled?: boolean
+  has_partial_recording?: boolean
+  /** No agent took the inbound call. */
+  is_missed?: boolean
+  dial_status?: CallDialStatus
+  /** `offered` once the greeting played, `recorded` once the message landed. */
+  voicemail_status?: 'offered' | 'recorded'
+  voicemail_duration_seconds?: number
+}
+
 /** The minted grant the Voice JS SDK consumes (`new Device(token, { edge })`). */
 export interface CallTokenResponse {
   token: string
@@ -339,6 +412,14 @@ export interface Conversation {
    * classified or no type matched.
    */
   type_key?: string
+  /** How the conversation ended — one of its type's outcome keys; absent = none yet. */
+  outcome_key?: string
+  /** Who set the outcome: `user` (never overridden by the model) or `model`. */
+  outcome_source?: ConversationOutcomeSource
+  outcome_set_by?: UserRef
+  outcome_set_at?: string
+  /** The conversation currently holds objective rows (maintained by the objective sync). */
+  has_objectives: boolean
   status: ConversationStatus
   /**
    * Room directory row a room-borne thread (Slack channel conversation) lives
@@ -351,6 +432,13 @@ export interface Conversation {
    * absent for main/DM/email/meeting/adhoc.
    */
   parent_conversation_id?: string
+  /**
+   * iCalendar UID of the calendar meeting this conversation was born from
+   * (stamped when the meeting bot starts); absent for everything else. With
+   * `started_at` it names the meeting INSTANCE on every invitee's calendar —
+   * Google's UID names a series, Microsoft's one occurrence.
+   */
+  calendar_event_ical_uid?: string
   /**
    * Message id of the child conversation's root message, which lives in the
    * parent conversation; absent when the root is unknown (predates ingest).
@@ -825,6 +913,33 @@ export interface ConversationTypeConfig {
  * `Conversation.type_key` and `config.summary_prompt_key` may swap the summary
  * system prompt. Module-deployable (conversation-types/<key>.json).
  */
+/**
+ * One way a conversation of a type can end — "booked", "not_interested",
+ * "callback". The type's list is the vocabulary a person picks from (the
+ * softphone after a call, the conversation header) and the choice a
+ * `role: 'outcome'` tag definition detects among. `description` is what the
+ * model reads to tell outcomes apart (the name when empty).
+ */
+export interface ConversationOutcome {
+  /** Platform key — the value stored on `Conversation.outcome_key`. */
+  key: string
+  name: string
+  description?: string
+}
+
+/**
+ * One stage a conversation of a type moves through — "intro", "discovery",
+ * "close". The type's list is ordered; progress through it is DERIVED from
+ * the objectives pinned to each phase (every measured objective of a phase
+ * achieved ⇒ the phase is done), never detected on its own. `description`
+ * is for humans (the checklist, the summary prompt).
+ */
+export interface ConversationPhase {
+  key: string
+  name: string
+  description?: string
+}
+
 export interface ConversationType {
   org_id: string
   /** Immutable identity within the org — what the classifier answers with. */
@@ -833,6 +948,19 @@ export interface ConversationType {
   /** When a conversation IS this type — injected verbatim into the classifier prompt. */
   definition: string
   config: ConversationTypeConfig
+  /** Ordered; empty = the type tracks no outcome. */
+  outcomes: ConversationOutcome[]
+  /** Ordered; empty = the type tracks no phases. */
+  phases: ConversationPhase[]
+  /**
+   * The type's next steps — the live call's quick actions and the wrap-up's
+   * "Next steps". Same contract as `Page.actions`; each button's
+   * `visible_when` reads the conversation scope (`conversation.status` for
+   * the stage, `conversation.outcome_key`, `records_by_entity.<slug>`,
+   * `tags_by_definition.<key>`, …); no rule = offered throughout. Ordered;
+   * empty = none.
+   */
+  actions: PageAction[]
   /** Module that deployed the type; absent when not module-owned. */
   module_slug?: string
   created_at: string
@@ -847,6 +975,12 @@ export interface CreateConversationTypeRequest {
   name?: string
   definition: string
   config?: ConversationTypeConfig
+  /** Replaces the list wholesale; omit = none. */
+  outcomes?: ConversationOutcome[]
+  /** Replaces the list wholesale; omit = none. */
+  phases?: ConversationPhase[]
+  /** Replaces the list wholesale; omit = none. */
+  actions?: PageAction[]
   module_slug?: string
 }
 
@@ -855,6 +989,12 @@ export interface UpdateConversationTypeRequest {
   definition?: string
   /** Replaces the stored config wholesale; send `{}` to clear the prompt link. */
   config?: ConversationTypeConfig
+  /** Replaces the list wholesale; `[]` clears it. */
+  outcomes?: ConversationOutcome[]
+  /** Replaces the list wholesale; `[]` clears it. */
+  phases?: ConversationPhase[]
+  /** Replaces the list wholesale; `[]` clears it. */
+  actions?: PageAction[]
 }
 
 export interface ListConversationTypesQuery extends PaginationQuery {
@@ -891,6 +1031,45 @@ export type ConversationTagScope = 'conversation' | 'message' | 'span'
  */
 export type ConversationTagEvaluatorKind = 'decide' | 'reason'
 
+/**
+ * What a definition is judged over: `conversation` (its messages, windowed per
+ * trigger — the default) or `summary` (the conversation's final summary plus
+ * the humans' notes; conversation scope only; planned only once the
+ * conversation has a summary, so never by a realtime evaluation).
+ */
+export type ConversationTagBasis = 'conversation' | 'summary'
+
+/**
+ * Who set a conversation's outcome: a person (never overridden), the model
+ * (a `role: 'outcome'` tag) or the service itself from a channel fact (a call
+ * nobody answered, a meeting nobody joined).
+ */
+export type ConversationOutcomeSource = 'user' | 'model' | 'system'
+
+/**
+ * One outcome a conversation may take, as `conversations.listOutcomes`
+ * lists them: the type's outcomes (`source: 'type'`) followed by the
+ * channel's system outcomes (`source: 'system'` — phone: not_reached /
+ * voicemail / wrong_number; meetings: no_show / cancelled; email: no_reply /
+ * bounced / declined; chat: no_reply / declined). The service sets the ones
+ * it can tell by itself; a person may pick any.
+ */
+export interface ConversationOutcomeOption {
+  key: string
+  name: string
+  description?: string
+  source: 'type' | 'system'
+}
+
+/**
+ * The special part a definition plays beyond being an observation. `outcome`
+ * = THE result of the conversation: a choice question at conversation scope,
+ * one value per conversation, the human's choice beats the model's (an
+ * evaluation never asks the model an outcome a user already set), surfaced in
+ * the softphone and the conversation header. `phase` is reserved.
+ */
+export type ConversationTagRole = 'outcome'
+
 /**
  * WHY an evaluation ran: `realtime` (the debounced window after new messages),
  * `completion` (the conversation completed — final transcript + summary for
@@ -1002,6 +1181,10 @@ export interface ConversationTagDefinition {
   /** `span` requires `evaluator.kind = 'reason'`. */
   scope: ConversationTagScope
   evaluator: ConversationTagEvaluator
+  /** `summary` requires conversation scope. */
+  basis: ConversationTagBasis
+  /** Absent = a plain observation. `outcome` requires a choice question at conversation scope. */
+  role?: ConversationTagRole
   /**
    * Narrows message/span-scope judging to messages of these directions (e.g.
    * inbound only for customer sentiment); empty = all. Ignored for
@@ -1258,6 +1441,10 @@ export interface CreateConversationTagDefinitionRequest {
   question: ConversationTagQuestion
   scope: ConversationTagScope
   evaluator: ConversationTagEvaluator
+  /** Omitted ⇒ `conversation`. */
+  basis?: ConversationTagBasis
+  /** Omitted ⇒ none. */
+  role?: ConversationTagRole | ''
   directions?: MessageDirection[]
   /** 0..1 */
   min_confidence?: number
@@ -1278,6 +1465,9 @@ export interface UpdateConversationTagDefinitionRequest {
   question?: ConversationTagQuestion
   scope?: ConversationTagScope
   evaluator?: ConversationTagEvaluator
+  basis?: ConversationTagBasis
+  /** Empty string clears the role. */
+  role?: ConversationTagRole | ''
   directions?: MessageDirection[]
   /** 0..1 */
   min_confidence?: number
@@ -1292,6 +1482,8 @@ export interface ListConversationTagDefinitionsQuery extends PaginationQuery {
   group?: string
   /** Exact filter. */
   scope?: string
+  /** Exact filter — `outcome` lists the outcome definitions. */
+  role?: string
   is_enabled?: boolean
   /** Case-insensitive substring match on key or name. */
   search?: string
@@ -1348,6 +1540,265 @@ export interface ListConversationTagSetsQuery extends PaginationQuery {
   search?: string
 }
 
+// ── Conversation objectives ──────────────────────────────────────────────
+
+/**
+ * How an objective definition's achievement is told: `tag` (a tag on a tag
+ * definition meets a value condition) or `outcome` (the conversation's
+ * outcome is one of a set).
+ */
+export type ConversationObjectiveMeasureKind = 'tag' | 'outcome'
+
+/**
+ * The value condition — exactly one field set, matched to the question type
+ * of the measured tag definition (boolean / choice / score) or, for kind
+ * `outcome`, `choice_in` over outcome keys. `score_min` is the 0-based level
+ * index a score tag must reach (tag values store the level index).
+ */
+export interface ConversationObjectiveAchievedWhen {
+  boolean?: boolean
+  choice_in?: string[]
+  score_min?: number
+}
+
+/**
+ * How an objective's achievement is told:
+ *
+ * - kind `tag`: a non-dismissed tag on `tag_definition_key` whose value meets
+ *   `achieved_when` (a pending tag ⇒ achieved, provisional). The tag
+ *   definition must be conversation-scoped and role-less — a person ticks the
+ *   objective by creating a user tag on it, unticks by deleting that tag.
+ * - kind `outcome`: the conversation's `outcome_key` is one of
+ *   `achieved_when.choice_in` (the type's outcomes and the channel's system
+ *   outcomes) — ticked through the outcome picker.
+ */
+export interface ConversationObjectiveMeasure {
+  kind: ConversationObjectiveMeasureKind
+  /** Required for kind `tag`; absent for kind `outcome`. */
+  tag_definition_key?: string
+  achieved_when: ConversationObjectiveAchievedWhen
+}
+
+/**
+ * One thing a conversation should achieve — "confirm the budget", "agree a
+ * next step", "book the demo". Applies to every conversation (`type_key`
+ * absent) or to conversations of one type, may be pinned to one of that
+ * type's phases (the checklist groups by phase, and a phase counts as done
+ * once every measured objective in it is achieved), and may be MEASURED so
+ * the platform tells whether it was achieved (no `measure` = guidance only,
+ * a line on the checklist). Its instance on a conversation is a
+ * ConversationObjective — the same definition → instance split as
+ * ConversationTagDefinition → ConversationTag. Keyed by `key`;
+ * module-deployable (conversation-objective-definitions/<key>.json).
+ */
+export interface ConversationObjectiveDefinition {
+  org_id: string
+  key: string
+  name: string
+  description?: string
+  /** Restricts the objective to one conversation type; absent = every conversation. */
+  type_key?: string
+  /** Pins the objective to one of the type's phases (requires `type_key`); absent = ungrouped. */
+  phase_key?: string
+  /** How achievement is told; absent = guidance only. */
+  measure?: ConversationObjectiveMeasure
+  is_enabled: boolean
+  /** Module that deployed the definition; absent when not module-owned. */
+  module_slug?: string
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+/**
+ * Creates one objective definition. `phase_key` requires `type_key` and must
+ * be one of that type's phases. A `tag` measure names a CONVERSATION-scoped,
+ * role-less tag definition and its `achieved_when` must match the question
+ * type (boolean ⇒ `{boolean: true}`; choice ⇒ `{choice_in ⊆ options}`; score
+ * ⇒ `{score_min: level index}`); an `outcome` measure takes `{choice_in}` over
+ * outcome keys (the type's outcomes ∪ the channel system outcomes when
+ * typed). `is_enabled` omitted ⇒ true. `module_slug` is stamped by
+ * `pro module deploy`.
+ */
+export interface CreateConversationObjectiveDefinitionRequest {
+  key: string
+  name: string
+  description?: string
+  type_key?: string
+  phase_key?: string
+  measure?: ConversationObjectiveMeasure
+  is_enabled?: boolean
+  module_slug?: string
+}
+
+/**
+ * Partial update — an omitted field leaves the stored value untouched.
+ * `measure` is tri-state: omitted keeps it, `null` clears it (guidance only),
+ * a value replaces it wholesale. `key` is immutable.
+ */
+export interface UpdateConversationObjectiveDefinitionRequest {
+  name?: string
+  description?: string
+  type_key?: string
+  phase_key?: string
+  measure?: ConversationObjectiveMeasure | null
+  is_enabled?: boolean
+}
+
+export interface GetManyConversationObjectiveDefinitionsQuery extends PaginationQuery {
+  /** Definitions deployed by one module. */
+  module_slug?: string
+  type_key?: string
+  phase_key?: string
+  is_enabled?: boolean
+  /** Case-insensitive substring match on key or name. */
+  search?: string
+}
+
+/**
+ * An objective's standing on a conversation: open (not yet, or no longer,
+ * achieved) or achieved. Whether an achieved standing is still provisional is
+ * the separate `is_provisional` flag, never a third status.
+ */
+export type ConversationObjectiveStatus = 'open' | 'achieved'
+
+/**
+ * Who achieved an objective: a person (a user tag or a hand-picked outcome),
+ * the model (a detected tag or outcome) or the system (a channel-level
+ * outcome the service set by itself).
+ */
+export type ConversationObjectiveSource = 'user' | 'model' | 'system'
+
+/** Where a conversation stands in one of its type's phases. */
+export type ConversationPhaseStatus = 'done' | 'current' | 'upcoming' | 'untracked'
+
+/**
+ * One objective definition's standing on one conversation: open or achieved,
+ * by whom, when, and on which tag. Resolved live for the per-conversation
+ * read (ConversationObjectiveProgress) AND persisted as the ledger row of
+ * the same shape — one row per APPLICABLE definition, open rows included,
+ * rewritten at every change point. Never user-written.
+ */
+export interface ConversationObjective {
+  org_id: string
+  conversation_id: string
+  definition_key: string
+  /** The conversation's channel, denormalized at resolution time. */
+  channel: Channel
+  /** The conversation's type, denormalized at resolution time. */
+  type_key?: string
+  /** The definition's phase, denormalized at resolution time. */
+  phase_key?: string
+  status: ConversationObjectiveStatus
+  /** Who achieved it; absent while open. */
+  source?: ConversationObjectiveSource
+  /**
+   * The backing tag is still `pending` — a realtime detection on a live
+   * spoken conversation the completion pass has not confirmed. Never true for
+   * a user or system source.
+   */
+  is_provisional: boolean
+  achieved_at?: string
+  /**
+   * The tag that achieved a tag-measured objective (the one to delete to
+   * untick when `source` is user); absent for outcome measures.
+   */
+  tag_id?: string
+  /** The conversation's status at resolution time — an open objective on an ended conversation was missed. */
+  is_conversation_ended: boolean
+  /** When this standing was resolved (the ledger write). */
+  recorded_at: string
+}
+
+/**
+ * One row of `conversationObjectives.counts`: the grouped columns that were
+ * requested plus the count.
+ */
+export interface ConversationObjectiveCount {
+  definition_key?: string
+  status?: ConversationObjectiveStatus
+  source?: ConversationObjectiveSource
+  is_provisional?: boolean
+  type_key?: string
+  phase_key?: string
+  channel?: Channel
+  count: number
+}
+
+/**
+ * One of the type's phases as the conversation stands in it, derived from
+ * the objectives pinned to the phase: `done` = every measured objective
+ * achieved (≥ 1 measured; provisional counts); `current` = the first phase
+ * in type order that is not done and has a measured objective; `upcoming` =
+ * after the current one; `untracked` = no measured objective, so progress
+ * cannot be told (dim, never current). `completed_at` is the latest
+ * `achieved_at` among the phase's measured objectives once done.
+ */
+export interface ConversationPhaseProgress extends ConversationPhase {
+  status: ConversationPhaseStatus
+  completed_at?: string
+}
+
+/**
+ * `conversations.getObjectiveProgress`: where the conversation stands — the
+ * current phase key (`''` when the type has no phases or every tracked phase
+ * is done), every phase with its status, every applicable objective with its
+ * standing, and the applicable definitions the objectives reference by
+ * `definition_key` (join `objectives[].definition_key` → `definitions[].key`
+ * for name / description / measure). Objectives are ordered: ungrouped first,
+ * then by the type's phase order, then name.
+ */
+export interface ConversationObjectiveProgress {
+  phase_key: string
+  phases: ConversationPhaseProgress[]
+  objectives: ConversationObjective[]
+  definitions: ConversationObjectiveDefinition[]
+}
+
+/** The org-wide ledger read (`conversationObjectives.list`); `since`/`until` bound `recorded_at`. */
+export interface GetManyConversationObjectivesQuery extends PaginationQuery {
+  conversation_id?: string
+  definition_key?: string
+  type_key?: string
+  phase_key?: string
+  channel?: string
+  status?: string
+  source?: string
+  is_provisional?: boolean
+  is_conversation_ended?: boolean
+  /** Lower bound on `recorded_at` (inclusive), RFC 3339. */
+  since?: string
+  /** Upper bound on `recorded_at` (exclusive), RFC 3339. */
+  until?: string
+}
+
+/**
+ * Groups the ledger for dashboards. `group_by` is a COMMA-JOINED string (not
+ * an array — the query serializer repeats array keys) whitelisted to
+ * definition_key, status, source, is_provisional, type_key, phase_key,
+ * channel (order kept; default `definition_key,status`).
+ */
+export interface CountConversationObjectivesQuery {
+  group_by?: string
+  definition_key?: string
+  type_key?: string
+  phase_key?: string
+  channel?: string
+  status?: string
+  source?: string
+  is_provisional?: boolean
+  is_conversation_ended?: boolean
+  /** Lower bound on `recorded_at` (inclusive), RFC 3339. */
+  since?: string
+  /** Upper bound on `recorded_at` (exclusive), RFC 3339. */
+  until?: string
+}
+
+export interface CountConversationObjectivesResponse {
+  data: ConversationObjectiveCount[]
+}
+
 /**
  * The manual door (`conversationTags.create`): a person tags a conversation,
  * a message or a span. Anchors follow the definition's scope (conversation:
@@ -1649,6 +2100,11 @@ export interface ListConversationsQuery extends PaginationQuery {
   channel?: string
   status?: string
   connection_id?: string
+  type_key?: string
+  /** The meeting conversations born from one calendar event UID. */
+  calendar_event_ical_uid?: string
+  /** How conversations ended (one of a type's outcome keys). */
+  outcome_key?: string
   /**
    * Conversations of one room (Slack channel) — the room stream. A
    * present-but-EMPTY string is meaningful: it filters to the room-LESS
@@ -1691,6 +2147,15 @@ export interface UpdateConversationRequest {
   summary?: string
   status?: ConversationStatus
   metadata?: Record<string, unknown>
+  /** Set the type by hand (must exist; `''` clears). Leaves the outcome alone. */
+  type_key?: string
+  /**
+   * How the conversation ended — one of `conversations.listOutcomes(id)`
+   * (its type's outcomes or its channel's system outcomes; `''` clears). The
+   * person's choice: never overridden by the model or the service. 400
+   * `conversation_outcome_unknown` when the key is in neither list.
+   */
+  outcome_key?: string
 }
 
 export interface ListMessagesQuery extends PaginationQuery {
@@ -2417,6 +2882,68 @@ export interface DispatchMeetingBotRequest {
    * transcription provider is deepgram_streaming.
    */
   language?: string
+  /**
+   * The calendar meeting instance the bot is sent for — `calendar_event_ical_uid`
+   * with `start_at` (the instance start, ISO) link the meeting conversation and
+   * its bot to the calendar so the event's surface can follow them.
+   */
+  calendar_event_ical_uid?: string
+  start_at?: string
+}
+
+/**
+ * Lifecycle of an Ava bot: `scheduled` (sent, not yet in the call) → `joining`
+ * → `recording` → `ended` | `failed`, or `removed` (a person withdrew Ava —
+ * terminal; a removed meeting is not scheduled again).
+ */
+export type MeetingBotStatus =
+  | 'scheduled'
+  | 'joining'
+  | 'recording'
+  | 'ended'
+  | 'failed'
+  | 'removed'
+
+/**
+ * The platform's memory of one Ava bot — "Ava joins this meeting", whoever's
+ * calendar scheduled her. One bot per meeting instance per org when bot
+ * deduplication is on; several rows can share an instance when it is off.
+ */
+export interface MeetingBot {
+  id: string
+  org_id: string
+  /** The connection (calendar / adhoc) that scheduled the bot. */
+  connection_id: string
+  /** The provider's bot id; the meeting conversation's external id once begun. */
+  external_bot_id: string
+  /** The provider calendar-event id the bot was scheduled on; absent for adhoc. */
+  provider_event_id?: string
+  calendar_event_ical_uid?: string
+  start_at?: string
+  meeting_url?: string
+  title?: string
+  status: MeetingBotStatus
+  /**
+   * Platform users among the invitees: they see the bot — and may withdraw
+   * Ava from their meeting — without owning the connection that scheduled her.
+   */
+  invitee_user_ids: string[]
+  /** The meeting conversation; absent until the bot starts the meeting. */
+  conversation_id?: string
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+export interface ListMeetingBotsQuery extends PaginationQuery {
+  /** Meetings starting at/after this ISO instant. */
+  start_after?: string
+  /** Meetings starting before this ISO instant. */
+  start_before?: string
+  /** One calendar meeting (pair with the window to name an instance). */
+  calendar_event_ical_uid?: string
+  status?: MeetingBotStatus
 }
 
 // ── Sending rules ─────────────────────────────────────────────────────────────
@@ -2527,13 +3054,28 @@ export interface ConversationBrief {
   org_id: string
   /** Human label ("Renewal call with Dana"); may be empty. */
   subject: string
-  /** The people the conversation is with (≥ 1, deduplicated, sorted). */
+  /** The people the conversation is with (deduplicated, sorted; may be empty — a phone brief has ≥ 1). */
   contact_ids: string[]
   /** How the conversation should happen (phone opens the softphone); absent = unspecified. */
   channel?: Channel
   /** ConversationType key the conversation is meant to be; stamped on attach. */
   type_key?: string
-  /** The conversation the brief was used on; absent until used. */
+  /**
+   * The calendar event (one person's copy) the brief prepares; attached to
+   * the meeting's conversation when the meeting bot starts. Absent = no meeting.
+   */
+  calendar_event_id?: string
+  /** The brief is every invitee's, not only the event owner's. */
+  is_shared_with_participants: boolean
+  /** The meeting instance the event belongs to (resolved from the event; read-only). */
+  calendar_event_ical_uid?: string
+  calendar_event_start_at?: string
+  /**
+   * The platform users the brief is for (the event owner; every resolved
+   * invitee when shared) — they read it next to its creator. Read-only.
+   */
+  invitee_user_ids: string[]
+  /** The conversation the brief was used on; absent until used. A conversation may carry several briefs. */
   conversation_id?: string
   status: ConversationBriefStatus
   /** Guidance text (markdown allowed). */
@@ -2547,13 +3089,17 @@ export interface ConversationBrief {
 
 export interface CreateConversationBriefRequest {
   subject?: string
-  /** The people the conversation is with (≥ 1). */
-  contact_ids: string[]
+  /** The people the conversation is with (may be empty). */
+  contact_ids?: string[]
   /** Must be a known channel when set. */
   channel?: Channel
   /** Must name an existing conversation type when set. */
   type_key?: string
   content: string
+  /** The caller's view of a calendar event the brief prepares (the caller must be able to read it). */
+  calendar_event_id?: string
+  /** Every invitee's brief instead of only the event owner's (requires calendar_event_id). */
+  is_shared_with_participants?: boolean
 }
 
 /** PATCH semantics — absent fields keep their value. Only open briefs. */
@@ -2565,6 +3111,9 @@ export interface UpdateConversationBriefRequest {
   channel?: Channel | ''
   content?: string
   type_key?: string
+  /** Re-ties the brief; empty string unties it (and drops the sharing). */
+  calendar_event_id?: string
+  is_shared_with_participants?: boolean
 }
 
 /** Binds an open brief to a conversation explicitly. */
@@ -2576,6 +3125,14 @@ export interface ListConversationBriefsQuery extends PaginationQuery {
   /** Briefs naming this person. */
   contact_id?: string
   conversation_id?: string
+  /** The briefs for one person's copy of a calendar event. */
+  calendar_event_id?: string
+  /** Every visible brief of a meeting, across invitees' copies (+ start to pin one instance). */
+  calendar_event_ical_uid?: string
+  calendar_event_start_at?: string
+  /** The briefs of the meetings starting in [after, before) — a calendar's visible range. */
+  calendar_event_start_after?: string
+  calendar_event_start_before?: string
   channel?: Channel
   type_key?: string
   status?: ConversationBriefStatus
@@ -3059,3 +3616,35 @@ export interface ListChannelActionsQuery extends PaginationQuery {
   status?: ChannelActionStatus
   contact_id?: string
 }
+
+/**
+ * What a PERSON recorded about a conversation — during a call, after a
+ * meeting, while reading a thread. An append log, author-stamped, never
+ * merged. Notes feed the summary (what the human found important) and the
+ * summary-basis tag evaluations. As visible as the conversation; only the
+ * author edits or deletes.
+ */
+export interface ConversationNote {
+  id: string
+  org_id: string
+  conversation_id: string
+  /** Markdown allowed. */
+  content: string
+  created_at: string
+  created_by: UserRef
+  updated_at: string
+  updated_by: UserRef
+}
+
+export interface CreateConversationNoteRequest {
+  content: string
+}
+
+export interface UpdateConversationNoteRequest {
+  content: string
+}
+
+export interface ListConversationNotesQuery extends PaginationQuery {
+  sort_by?: string
+  sort?: 'asc' | 'desc'
+}