@proteos/sdk 0.60.0 → 0.75.0

package/src/data/entity-indexes.ts

@@ -0,0 +1,54 @@
+import type { ProteosClient } from '../client.js'
+import type { CreateEntityIndexRequest, EntityIndex, IndexRecommendation } from './types.js'
+
+const ENTITIES_BASE_PATH = '/data/v1/entities'
+
+/**
+ * Per-entity indexes on the record table and the advisor's recommendations.
+ * Admin surface: gated on the `entities` permission, not on record access.
+ */
+export interface EntityIndexService {
+  /** Every index of the entity (declared, automatic, applied) with live state. */
+  list(entitySlug: string): Promise<EntityIndex[]>
+  /** The advisor's current suggestions for the entity. */
+  recommendations(entitySlug: string): Promise<IndexRecommendation[]>
+  /** Applies one lookup/search index; returns it in `building` state. */
+  create(entitySlug: string, request: CreateEntityIndexRequest): Promise<EntityIndex>
+  /** Removes one APPLIED index (declared/automatic → 409 entity_index_not_deletable). */
+  delete(entitySlug: string, name: string): Promise<void>
+}
+
+export class EntityIndexServiceImpl implements EntityIndexService {
+  constructor(private readonly client: ProteosClient) {}
+
+  async list(entitySlug: string): Promise<EntityIndex[]> {
+    const response = await this.client.request<{ data: EntityIndex[] }>(
+      'GET',
+      `${ENTITIES_BASE_PATH}/${encodeURIComponent(entitySlug)}/indexes`,
+    )
+    return response.data
+  }
+
+  async recommendations(entitySlug: string): Promise<IndexRecommendation[]> {
+    const response = await this.client.request<{ data: IndexRecommendation[] }>(
+      'GET',
+      `${ENTITIES_BASE_PATH}/${encodeURIComponent(entitySlug)}/index-recommendations`,
+    )
+    return response.data
+  }
+
+  async create(entitySlug: string, request: CreateEntityIndexRequest): Promise<EntityIndex> {
+    return this.client.request<EntityIndex>(
+      'POST',
+      `${ENTITIES_BASE_PATH}/${encodeURIComponent(entitySlug)}/indexes`,
+      request,
+    )
+  }
+
+  async delete(entitySlug: string, name: string): Promise<void> {
+    await this.client.request<void>(
+      'DELETE',
+      `${ENTITIES_BASE_PATH}/${encodeURIComponent(entitySlug)}/indexes/${encodeURIComponent(name)}`,
+    )
+  }
+}

package/src/data/index.ts

@@ -1,4 +1,5 @@
 import type { ProteosClient } from '../client.js'
+import { type EntityIndexService, EntityIndexServiceImpl } from './entity-indexes.js'
 import { type QueryService, QueryServiceImpl } from './queries.js'
 import {
   type RecordDuplicateService,
@@ -23,14 +24,18 @@ export class DataClient {
   readonly queries: QueryService
   /** Duplicate pairs of an entity's records (raised by contact binding). */
   readonly recordDuplicates: RecordDuplicateService
+  /** Per-entity indexes on the record table + the advisor's recommendations. */
+  readonly entityIndexes: EntityIndexService
 
   constructor(client: ProteosClient) {
     this.records = new RecordServiceImpl(client)
     this.queries = new QueryServiceImpl(client)
     this.recordDuplicates = new RecordDuplicateServiceImpl(client)
+    this.entityIndexes = new EntityIndexServiceImpl(client)
   }
 }
 
+export type { EntityIndexService } from './entity-indexes.js'
 // Re-export service interfaces
 // Re-export types
 export type {
@@ -48,6 +53,13 @@ export type {
   BatchUpsertRecordsResponse,
   BatchUpsertTransaction,
   BatchUpsertTransactionResult,
+  CreateEntityIndexRequest,
+  EntityIndex,
+  EntityIndexSource,
+  EntityIndexState,
+  EntityIndexType,
+  IndexEvidence,
+  IndexRecommendation,
   ListRecordDuplicatesQuery,
   ListRecordsOptions,
   PublishContactObservationsResponse,

package/src/data/types.ts

@@ -151,3 +151,69 @@ export interface PublishContactObservationsResponse {
   published: number
   skipped: number
 }
+
+// ============================================================================
+// Entity indexes (per-org indexes on an entity's record table)
+// ============================================================================
+
+/** Named by what it does: lookup (=, IN, ranges, sort), unique (lookup that
+ * refuses duplicates), search (substring match on one string attribute). */
+export type EntityIndexType = 'lookup' | 'unique' | 'search'
+
+/** declared = from the entity (is_unique / unique_constraints); automatic =
+ * the platform's relation/user indexes; applied = added per org by an admin. */
+export type EntityIndexSource = 'declared' | 'automatic' | 'applied'
+
+export type EntityIndexState = 'ready' | 'building' | 'invalid' | 'missing'
+
+export interface EntityIndex {
+  name: string
+  type: EntityIndexType
+  attributes: string[]
+  source: EntityIndexSource
+  state?: EntityIndexState
+  size_bytes?: number
+  scans?: number
+  created_at?: string
+}
+
+export const EntityIndexSchema = z.object({
+  name: z.string(),
+  type: z.enum(['lookup', 'unique', 'search']),
+  attributes: z.array(z.string()),
+  source: z.enum(['declared', 'automatic', 'applied']),
+  state: z.enum(['ready', 'building', 'invalid', 'missing']).optional(),
+  size_bytes: z.number().optional(),
+  scans: z.number().optional(),
+  created_at: z.string().optional(),
+})
+
+/** Only slow runs (>= the advisor's slow threshold) are recorded, so
+ * `slow_queries` is the whole sample and `avg_ms` their average. */
+export interface IndexEvidence {
+  slow_queries: number
+  avg_ms: number
+  rows: number
+  scans: number
+  reason: string
+}
+
+export interface IndexRecommendation {
+  action: 'add' | 'remove'
+  index: EntityIndex
+  evidence: IndexEvidence
+  /** On an `add`: applied lookups the new index supersedes. Pass through as
+   * `CreateEntityIndexRequest.replaces` so the create swaps them. */
+  replaces?: string[]
+}
+
+/** Only lookup and search can be applied; uniqueness is declared on the entity. */
+export interface CreateEntityIndexRequest {
+  /** Derived from the attributes when omitted (by_<a>_<b>, search_<a>). */
+  name?: string
+  type: 'lookup' | 'search'
+  attributes: string[]
+  /** Applied lookups this index supersedes (each must be covered by it);
+   * removed in the same step. Required whenever one exists, else 400 index_redundant. */
+  replaces?: string[]
+}

package/src/errors.ts

@@ -10,6 +10,11 @@ export const ErrorCode = {
   INTERNAL_SERVER_ERROR: 'internal_server_error',
   INVALID_PAYLOAD: 'invalid_payload',
   INVALID_PERSONA: 'invalid_persona',
+  /** The server was never reached: DNS, connection refused, network down.
+   *  Carried with httpStatus 0. */
+  NETWORK_ERROR: 'network_error',
+  /** The request timed out client-side. Carried with httpStatus 0. */
+  REQUEST_TIMEOUT: 'request_timeout',
 } as const
 
 export type ErrorCodeType = (typeof ErrorCode)[keyof typeof ErrorCode]

package/src/index.ts

@@ -264,6 +264,8 @@ export type {
   BooleanTagCriteria,
   BounceClassification,
   BounceKind,
+  CallDialStatus,
+  CallMetadata,
   CallStatus,
   CallTokenResponse,
   Channel,
@@ -317,11 +319,31 @@ export type {
   ConversationFilterEvent,
   ConversationFilterService,
   ConversationFilterType,
+  ConversationNote,
+  ConversationNoteService,
+  ConversationObjective,
+  ConversationObjectiveAchievedWhen,
+  ConversationObjectiveCount,
+  ConversationObjectiveDefinition,
+  ConversationObjectiveDefinitionService,
+  ConversationObjectiveMeasure,
+  ConversationObjectiveMeasureKind,
+  ConversationObjectiveProgress,
+  ConversationObjectiveService,
+  ConversationObjectiveSource,
+  ConversationObjectiveStatus,
+  ConversationOutcome,
+  ConversationOutcomeOption,
+  ConversationOutcomeSource,
   ConversationParticipant,
+  ConversationPhase,
+  ConversationPhaseProgress,
+  ConversationPhaseStatus,
   ConversationService,
   ConversationStatus,
   ConversationSummaryStatus,
   ConversationTag,
+  ConversationTagBasis,
   ConversationTagCount,
   ConversationTagCriteria,
   ConversationTagDefinition,
@@ -333,6 +355,7 @@ export type {
   ConversationTaggedEvent,
   ConversationTagQuestion,
   ConversationTagQuestionType,
+  ConversationTagRole,
   ConversationTagScope,
   ConversationTagScreening,
   ConversationTagScreeningResult,
@@ -346,6 +369,8 @@ export type {
   ConversationType,
   ConversationTypeConfig,
   ConversationTypeService,
+  CountConversationObjectivesQuery,
+  CountConversationObjectivesResponse,
   CountConversationTagsQuery,
   CountConversationTagsResponse,
   CreateAgentListenerRequest,
@@ -355,6 +380,8 @@ export type {
   CreateContactRequest,
   CreateConversationBriefRequest,
   CreateConversationFilterRequest,
+  CreateConversationNoteRequest,
+  CreateConversationObjectiveDefinitionRequest,
   CreateConversationTagDefinitionRequest,
   CreateConversationTagRequest,
   CreateConversationTagSetRequest,
@@ -383,6 +410,8 @@ export type {
   FilterMatchOn,
   FrequencyCapRuleConfig,
   GetConnectionHealthQuery,
+  GetManyConversationObjectiveDefinitionsQuery,
+  GetManyConversationObjectivesQuery,
   GlossaryTerm,
   GlossaryTermService,
   InmailParams,
@@ -402,6 +431,7 @@ export type {
   ListConversationBriefsQuery,
   ListConversationFilterEventsQuery,
   ListConversationFiltersQuery,
+  ListConversationNotesQuery,
   ListConversationsQuery,
   ListConversationTagDefinitionsQuery,
   ListConversationTagEvaluationsQuery,
@@ -409,6 +439,7 @@ export type {
   ListConversationTagsQuery,
   ListConversationTypesQuery,
   ListGlossaryTermsQuery,
+  ListMeetingBotsQuery,
   ListMessagesQuery,
   ListMistranscribedTermsQuery,
   // Conversation-local page envelope ({meta, data}) — distinct from the
@@ -419,6 +450,10 @@ export type {
   ListSendingRulesQuery,
   ListToneProfileSetupsQuery,
   ListToneProfilesQuery,
+  ListTranscriptionsQuery,
+  MeetingBot,
+  MeetingBotService,
+  MeetingBotStatus,
   MeetingService,
   MergeContactsRequest,
   MergeProposalStatus,
@@ -464,6 +499,7 @@ export type {
   SendingRuleType,
   SendMessageRequest,
   SendRecipient,
+  SetCallRecordingRequest,
   SetDefaultSenderRequest,
   SyncConnectionRequest,
   ToneProfile,
@@ -478,6 +514,8 @@ export type {
   TranscriptionStatus,
   TranscriptResult,
   TranscriptTurn,
+  TwilioPhoneSettings,
+  TwilioPhoneVoicemailSettings,
   UnreadCounts,
   UpdateAgentListenerRequest,
   UpdateConnectionRequest,
@@ -485,6 +523,9 @@ export type {
   UpdateContactRequest,
   UpdateConversationBriefRequest,
   UpdateConversationFilterRequest,
+  UpdateConversationNoteRequest,
+  UpdateConversationObjectiveDefinitionRequest,
+  UpdateConversationRequest,
   UpdateConversationTagDefinitionRequest,
   UpdateConversationTagRequest,
   UpdateConversationTagSetRequest,
@@ -509,6 +550,14 @@ export type {
   BatchUpsertRecordsResponse,
   BatchUpsertTransaction,
   BatchUpsertTransactionResult,
+  CreateEntityIndexRequest,
+  EntityIndex,
+  EntityIndexService,
+  EntityIndexSource,
+  EntityIndexState,
+  EntityIndexType,
+  IndexEvidence,
+  IndexRecommendation,
   ListRecordDuplicatesQuery,
   ListRecordsOptions,
   PublishContactObservationsResponse,
@@ -752,20 +801,25 @@ export type {
   // Page types
   Page,
   PageAction,
+  PageActionIntent,
   PageActionKind,
   PageExtension,
   PageExtensionPlacement,
   PageExtensionService,
   PageLayout,
+  PageMode,
   PageService,
   PageType,
   PublicAccessOperation,
   PublicPageComponent,
   PublicPageResponse,
+  RecordPageBinding,
   // Relation attribute meta
   RelationAttributeMeta,
   SortConfig,
   SortDirection,
+  TriggerPageBinding,
+  TriggerPhase,
   UpdateAppConfigurationRequest,
   UpdateAppRequest,
   UpdateComponentRequest,
@@ -794,6 +848,7 @@ export {
   AttributeSchema,
   acceptsCurrentUserDefault,
   allCurrencyCodes,
+  bundleVersionOf,
   ColumnSchema,
   ComponentSchema,
   ContactAddressAttributeMetaSchema,
@@ -845,8 +900,10 @@ export {
   parseFileMeta,
   parseRelationMeta,
   platformAttributes,
+  RecordPageBindingSchema,
   RelationAttributeMetaSchema,
   SortConfigSchema,
+  TriggerPageBindingSchema,
   VariableSchema,
 } from './meta/index.js'
 // Scheduling types (scheduling-service: calendar connections, calendars,

package/src/meta/components.ts

@@ -10,6 +10,18 @@ import type {
 
 const COMPONENTS_BASE_PATH = '/meta/v1/components'
 
+/**
+ * The hex digest of a `bundle_checksum` (`sha256:<hex>`), which is what the
+ * bundle endpoint compares its `v` query against. `undefined` for an absent
+ * or malformed checksum.
+ */
+export function bundleVersionOf(bundleChecksum: string | undefined): string | undefined {
+  if (!bundleChecksum) return undefined
+  const separator = bundleChecksum.indexOf(':')
+  const hex = separator === -1 ? bundleChecksum : bundleChecksum.slice(separator + 1)
+  return /^[0-9a-f]{16,}$/i.test(hex) ? hex.toLowerCase() : undefined
+}
+
 /**
  * Service for managing UI component definitions.
  * Components define reusable UI elements in the system.
@@ -81,7 +93,7 @@ export interface ComponentService {
    * @param slug - Component slug
    * @returns The relative bundle URL
    */
-  bundleUrl(slug: string): string
+  bundleUrl(slug: string, bundleChecksum?: string): string
 }
 
 /**
@@ -118,7 +130,15 @@ export class ComponentServiceImpl implements ComponentService {
     await this.client.request<void>('DELETE', `${COMPONENTS_BASE_PATH}/${id}`)
   }
 
-  bundleUrl(slug: string): string {
-    return `${COMPONENTS_BASE_PATH}/${slug}/bundle`
+  /**
+   * Path of the component's compiled bundle. With the component's
+   * `bundle_checksum` the URL is content-addressed (`?v=<hex>`), which the
+   * server answers with an immutable cache policy; without it the bundle
+   * revalidates on every load.
+   */
+  bundleUrl(slug: string, bundleChecksum?: string): string {
+    const version = bundleVersionOf(bundleChecksum)
+    const base = `${COMPONENTS_BASE_PATH}/${slug}/bundle`
+    return version ? `${base}?v=${encodeURIComponent(version)}` : base
   }
 }

package/src/meta/index.ts

@@ -149,6 +149,7 @@ export class MetaClient {
 export type { AppConfigurationService } from './app-configurations.js'
 export type { AppService } from './apps.js'
 export type { ComponentService } from './components.js'
+export { bundleVersionOf } from './components.js'
 export * from './currency/index.js'
 export type { DesignReferenceService } from './design-references.js'
 // Re-export service interfaces
@@ -269,11 +270,16 @@ export type {
   // Page types
   Page,
   PageAction,
+  PageActionIntent,
   PageActionKind,
   // PageExtension types
   PageExtension,
   PageExtensionPlacement,
   PageType,
+  RecordPageBinding,
+  PageMode,
+  TriggerPageBinding,
+  TriggerPhase,
   // User attribute meta
   PrincipalAttributeMeta,
   PrincipalRef,
@@ -310,6 +316,8 @@ export type {
 export {
   AppConfigurationSchema,
   AppHomeSchema,
+  RecordPageBindingSchema,
+  TriggerPageBindingSchema,
   AppSchema,
   AttributeSchema,
   acceptsCurrentUserDefault,

package/src/meta/layout/common-props.ts

@@ -31,6 +31,9 @@ export interface SizingProps {
   /** Floor under `height` (px or %). Under `height: 'fill'` in a column it
    *  replaces the default 320px floor. */
   min_height?: LengthValue
+  /** Ceiling over `height` (px or %). A box that would grow past it scrolls
+   *  its content instead; a field scrolls its value and keeps its label. */
+  max_height?: LengthValue
   grow?: number
   shrink?: number
   align?: LayoutAlign
@@ -40,6 +43,7 @@ const SizingPropsSchema = z.object({
   width: SizeValueSchema.optional(),
   height: SizeValueSchema.optional(),
   min_height: LengthValueSchema.optional(),
+  max_height: LengthValueSchema.optional(),
   grow: z.number().optional(),
   shrink: z.number().optional(),
   align: AlignSchema.optional(),
@@ -87,6 +91,10 @@ export interface CommonProps {
   height?: SizeValue
   /** Floor under `height`, px or %. */
   min_height?: LengthValue
+  /** Ceiling over `height`, px or %. Content past it scrolls inside the
+   *  element (a field scrolls its value, the label stays). A fixed px / %
+   *  `height` bounds the same way. */
+  max_height?: LengthValue
   grow?: number
   shrink?: number
   align?: LayoutAlign
@@ -105,6 +113,7 @@ export const commonPropsShape = {
   width: SizeValueSchema.optional(),
   height: SizeValueSchema.optional(),
   min_height: LengthValueSchema.optional(),
+  max_height: LengthValueSchema.optional(),
   grow: z.number().optional(),
   shrink: z.number().optional(),
   align: AlignSchema.optional(),

package/src/meta/layout/elements.ts

@@ -25,6 +25,7 @@ export const LayoutElementType = {
   WorkflowTrigger: 'workflow_trigger',
   SchedulingPicker: 'scheduling_picker',
   Calendar: 'calendar',
+  Stepper: 'stepper',
 } as const
 export type LayoutElementType = (typeof LayoutElementType)[keyof typeof LayoutElementType]
 
@@ -95,6 +96,41 @@ export type TabsElement = CommonProps & {
   default_tab_id?: string
 }
 
+/**
+ * One stage inside a `stepper` element, bound to one value of the stepper's
+ * enum attribute. Steps are ordered: the step whose `value` the record holds
+ * is current, the ones before it completed, the ones after it upcoming.
+ * `visible_when` hides a step from the rail without changing the order;
+ * `continue_label` overrides the Continue button while this step is current.
+ * Step ids share the page-wide id namespace with element ids.
+ */
+export type LayoutStep = {
+  id: string
+  value: string
+  label: string
+  icon?: string
+  continue_label?: string
+  visible_when?: FilterGroup
+  content: LayoutElement
+}
+
+/**
+ * Tabs for a record that walks through stages: ordered steps bound to one
+ * enum `attribute` of the page record, one content tree per step, and
+ * Continue / Back buttons that write the attribute through the normal record
+ * update — `before_update` hooks stay the authority on readiness and their
+ * refusal is shown inline. Record pages only.
+ */
+export type StepperElement = CommonProps & {
+  type: 'stepper'
+  attribute: string
+  /** Continue button label (default "Continue"); a step's own `continue_label` wins. */
+  continue_label?: string
+  /** Back button label (default "Back"). */
+  back_label?: string
+  steps: LayoutStep[]
+}
+
 export type FieldElement = CommonProps & {
   type: 'field'
   attribute: string
@@ -346,6 +382,7 @@ export type LayoutElement =
   | WorkflowTriggerElement
   | SchedulingPickerElement
   | CalendarElement
+  | StepperElement
 
 // ──────────────────────────────────────────────────────────── Schemas ──
 
@@ -361,6 +398,18 @@ export const LayoutTabSchema: z.ZodType<LayoutTab> = z.lazy(() =>
   }),
 )
 
+export const LayoutStepSchema: z.ZodType<LayoutStep> = z.lazy(() =>
+  z.object({
+    id: z.string().min(1),
+    value: z.string().min(1),
+    label: z.string().min(1),
+    icon: z.string().optional(),
+    continue_label: z.string().optional(),
+    visible_when: FilterGroupSchema.optional(),
+    content: LayoutElementSchema,
+  }),
+)
+
 export const LayoutElementSchema: z.ZodType<LayoutElement> = z.lazy(() =>
   z.discriminatedUnion('type', [
     z.object({
@@ -404,6 +453,14 @@ export const LayoutElementSchema: z.ZodType<LayoutElement> = z.lazy(() =>
       tabs: z.array(LayoutTabSchema),
       default_tab_id: z.string().optional(),
     }),
+    z.object({
+      type: z.literal('stepper'),
+      ...commonPropsShape,
+      attribute: z.string().min(1),
+      continue_label: z.string().optional(),
+      back_label: z.string().optional(),
+      steps: z.array(LayoutStepSchema).min(1),
+    }),
     z.object({
       type: z.literal('field'),
       ...commonPropsShape,

package/src/meta/layout/index.ts

@@ -29,6 +29,8 @@ export {
   type LayoutElement,
   LayoutElementSchema,
   LayoutElementType,
+  type LayoutStep,
+  LayoutStepSchema,
   type LayoutTab,
   LayoutTabSchema,
   type ListElement,
@@ -38,6 +40,7 @@ export {
   type RowElement,
   type SchedulingPickerElement,
   type SectionElement,
+  type StepperElement,
   type TabsElement,
   type TextElement,
   type TextVariant,
@@ -47,7 +50,9 @@ export {
   isPageBackground,
   PAGE_BACKGROUND_COLOR_RE,
   PAGE_BACKGROUND_TOKENS,
+  PAGE_HEADERS,
   type PageBackgroundToken,
+  type PageHeader,
   type PageLayout,
   PageLayoutSchema,
   type PageLayoutSidePanel,

package/src/meta/layout/page-layout.ts

@@ -49,6 +49,14 @@ export const PAGE_BACKGROUND_TOKENS = [
 
 export type PageBackgroundToken = (typeof PAGE_BACKGROUND_TOKENS)[number]
 
+/** Record toolbar shapes. `full` (default) = title strip + actions strip;
+ *  `condensed` = title strip only: a (⋯) overflow with the page actions and
+ *  the record's links (hidden when there are none), then Edit / Delete,
+ *  beside the close button. */
+export const PAGE_HEADERS = ['full', 'condensed'] as const
+
+export type PageHeader = (typeof PAGE_HEADERS)[number]
+
 /**
  * A raw CSS color a page background may use instead of a token: a hex literal
  * or one of a few color functions with a restricted argument charset (no `;{}`,
@@ -76,9 +84,10 @@ export function isPageBackground(text: string): boolean {
  * bg / 1200px / 24px-32px look). `max_width: "fill"` (or `"auto"`) with zero
  * padding lets a component fill the page edge-to-edge.
  *
- * Honored on `platform`, `public` and `kiosk` pages; record pages reject it
- * (enforced server-side). On platform pages it styles the app shell's content
- * area rather than a standalone shell.
+ * Honored on `platform`, `record`, `public` and `kiosk` pages; on platform
+ * and record pages it styles the app shell's content area rather than a
+ * standalone shell. Trigger pages take `max_width` only; `header` is
+ * record-only (enforced server-side).
  */
 export interface PageStyle {
   /** Design-token key (see PAGE_BACKGROUND_TOKENS) or a raw CSS color
@@ -89,6 +98,8 @@ export interface PageStyle {
   /** Horizontal / vertical padding of the content container (Tailwind px/py). */
   padding_x?: StyleSizeValue
   padding_y?: StyleSizeValue
+  /** Record toolbar shape (record pages only); unset = `full`. */
+  header?: PageHeader
 }
 
 export const PageStyleSchema = z.object({
@@ -99,6 +110,7 @@ export const PageStyleSchema = z.object({
   max_width: StyleSizeValueSchema.optional(),
   padding_x: StyleSizeValueSchema.optional(),
   padding_y: StyleSizeValueSchema.optional(),
+  header: z.enum(PAGE_HEADERS).optional(),
 })
 
 /**