@proteos/sdk 0.51.1 → 0.53.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteos/sdk",
-  "version": "0.51.1",
+  "version": "0.53.0",
   "license": "Apache-2.0",
   "description": "TypeScript SDK for the Proteos platform",
   "repository": {
@@ -66,8 +66,8 @@
     "tsup": "^8.3.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0",
-    "@proteos/biome-config": "0.0.0",
-    "@proteos/tsconfig": "0.0.0"
+    "@proteos/tsconfig": "0.0.0",
+    "@proteos/biome-config": "0.0.0"
   },
   "scripts": {
     "build": "tsup",

package/src/conversation/index.ts

@@ -33,6 +33,7 @@ import type {
   CreateGlossaryTermRequest,
   CreateSendingRuleRequest,
   CreateToneProfileSetupRequest,
+  CreateTranscriptionFromTextRequest,
   CreateTranscriptionRequest,
   DeleteConnectionQuery,
   DispatchMeetingBotRequest,
@@ -106,6 +107,7 @@ import type {
   UpdatePhoneNumberRequest,
   UpdateSendingRuleRequest,
   UpdateTranscriptionRequest,
+  UpsertToneProfileRequest,
 } from './types.js'
 import { type VoiceService, VoiceServiceImpl } from './voice.js'
 
@@ -1121,6 +1123,20 @@ export interface ToneProfileService {
   getProfile(id: string): Promise<ToneProfile>
   /** The single most-specific profile for a drafting context; 404 when none. */
   resolve(query: ResolveToneProfileQuery): Promise<ToneProfile>
+  /**
+   * Writes a HAND-AUTHORED profile, addressed by its scope tuple rather than an
+   * id — so re-sending the same scope updates the row it created. The row lands
+   * `source: 'manual'`, which locks that scope against synthesis forever after;
+   * it also takes the scope over from a `model` row already there. Needs no
+   * setup: a setup is the opt-in to AI synthesis, and writing a voice by hand is
+   * the opposite of asking for one.
+   */
+  upsertProfile(request: UpsertToneProfileRequest): Promise<ToneProfile>
+  /**
+   * Removes one profile row, manual or model. A deleted model row comes back on
+   * the next run; a deleted manual row hands its scope back to synthesis.
+   */
+  deleteProfile(id: string): Promise<void>
 }
 
 class ToneProfileServiceImpl implements ToneProfileService {
@@ -1170,6 +1186,17 @@ class ToneProfileServiceImpl implements ToneProfileService {
       query,
     )
   }
+
+  upsertProfile(request: UpsertToneProfileRequest): Promise<ToneProfile> {
+    return this.client.request('PUT', `${CONVERSATION_BASE_PATH}/tone-profiles`, request)
+  }
+
+  async deleteProfile(id: string): Promise<void> {
+    await this.client.request(
+      'DELETE',
+      `${CONVERSATION_BASE_PATH}/tone-profiles/${encodeURIComponent(id)}`,
+    )
+  }
 }
 
 /** Batch transcription of stored audio files + materialization. */
@@ -1180,6 +1207,14 @@ export interface TranscriptionService {
    * status is `completed` (or `failed`), then `materialize`.
    */
   createFromFile(request: CreateTranscriptionRequest): Promise<Transcription>
+  /**
+   * Lands an ALREADY WRITTEN transcript. Synchronous — no provider runs, and
+   * the entity comes back `completed`, ready to `materialize` straight away.
+   * The door for authoring a transcript (and so a conversation) from text with
+   * nothing to upload. Same endpoint as `createFromFile`; the shape of the body
+   * chooses the mode, and exactly one of the two is allowed.
+   */
+  createFromText(request: CreateTranscriptionFromTextRequest): Promise<Transcription>
   list(query?: ListTranscriptionsQuery): Promise<ListResponse<Transcription>>
   get(id: string): Promise<Transcription>
   /**
@@ -1204,6 +1239,10 @@ class TranscriptionServiceImpl implements TranscriptionService {
     return this.client.request('POST', `${CONVERSATION_BASE_PATH}/transcriptions`, request)
   }
 
+  createFromText(request: CreateTranscriptionFromTextRequest): Promise<Transcription> {
+    return this.client.request('POST', `${CONVERSATION_BASE_PATH}/transcriptions`, request)
+  }
+
   list(query: ListTranscriptionsQuery = {}): Promise<ListResponse<Transcription>> {
     return this.client.requestWithQuery('GET', `${CONVERSATION_BASE_PATH}/transcriptions`, query)
   }

package/src/conversation/types.ts

@@ -914,6 +914,14 @@ 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'
 
+/**
+ * Who wrote a tone profile, and therefore who may change it. `manual` rows are
+ * hand-authored and authoritative: synthesis never overwrites or prunes them,
+ * and deleting the user's setup (the AI opt-in) leaves them standing. `model`
+ * rows belong to the synthesis sweep, which owns them outright.
+ */
+export type ToneProfileSource = 'manual' | 'model'
+
 /**
  * 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).
@@ -933,7 +941,8 @@ export interface ToneProfileSetup {
 }
 
 /**
- * One generated tone-of-voice instruction row. Rows form a specificity
+ * One tone-of-voice instruction row — synthesized or hand-authored (`source`).
+ * 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
@@ -951,6 +960,8 @@ export interface ToneProfile {
   /** Scopes the row to one individual contact within the group. */
   contact_id?: string
   scope: ToneProfileScope
+  /** Who owns this row — see ToneProfileSource. */
+  source: ToneProfileSource
   /** 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. */
@@ -975,6 +986,30 @@ export interface ListToneProfilesQuery extends PaginationQuery {
   owned_by_id?: string
   channel?: Channel
   scope?: ToneProfileScope
+  /** Narrow to hand-authored (`manual`) or synthesized (`model`) rows. */
+  source?: ToneProfileSource
+}
+
+/**
+ * Writes ONE hand-authored tone profile. The identity is the scope tuple, not
+ * an id — re-sending the same scope updates the row it created. The row lands
+ * `source: 'manual'`, which locks that scope against synthesis; it also takes
+ * the scope over from a `model` row already sitting there.
+ *
+ * Scope grammar (mirrors the resolve precedence): omit `channel` for the
+ * cross-channel base voice; `contact_group_key` needs a `channel`;
+ * `contact_id` needs both, because resolution reaches a contact row only
+ * through its group.
+ */
+export interface UpsertToneProfileRequest {
+  owned_by_id: string
+  channel?: Channel
+  contact_group_key?: string
+  contact_id?: string
+  /** COMPLETE markdown style guide for this tier; never a delta. */
+  instructions: string
+  /** Optional human-facing note on how this tier differs from the one above. */
+  differences?: string
 }
 
 /**
@@ -1229,6 +1264,11 @@ export type ContactAddressKind =
   | 'email'
   | 'phone'
   | 'slack'
+  /** LinkedIn's stable profile id (ACoAA… / ACwAA… / AE…) — what sending needs. */
+  | 'linkedin_id'
+  /** The `/in/<slug>` public identifier — what humans and records hold. */
+  | 'linkedin_public_identifier'
+  /** Legacy alias of `linkedin_id` (rows written before the kind split); read-only. */
   | 'linkedin'
   | 'telegram'
   | 'instagram'
@@ -1466,10 +1506,25 @@ export interface AttachContactAddressRequest {
   name?: string
 }
 
+/** How a contact→record edge came to be: a user's explicit link, or the
+ * binding maintained from the record's contact-address attributes (exactly one
+ * per record; never unlinked by hand). */
+export type ContactRecordLinkSource = 'manual' | 'record'
+
+/** One canonical address key of a contact (the dedup backbone). */
+export interface ContactAddressKey {
+  kind: ContactAddressKind
+  value: string
+  scope?: string
+  raw_value?: string
+}
+
 /**
  * A directed edge from a contact to a business record (entity_slug +
  * record_id). Bare — no role; the relationship's semantics come from the
- * target entity. Immutable once created.
+ * target entity. A `manual` link is immutable once created; a `record`
+ * binding repoints/refreshes as the record's addresses change and carries the
+ * keys the record contributed (`address_keys`).
  */
 export interface ContactRecordLink {
   id: string
@@ -1477,8 +1532,12 @@ export interface ContactRecordLink {
   contact_id: string
   entity_slug: string
   record_id: string
+  source: ContactRecordLinkSource
+  address_keys?: ContactAddressKey[]
   created_at: string
   created_by: UserRef
+  updated_at?: string
+  updated_by?: UserRef
 }
 
 export interface CreateContactRecordLinkRequest {
@@ -1491,6 +1550,7 @@ export interface ListContactRecordLinksQuery extends PaginationQuery {
   contact_id?: string
   entity_slug?: string
   record_id?: string
+  source?: ContactRecordLinkSource
 }
 
 export interface MergeContactsRequest {
@@ -1595,6 +1655,10 @@ export interface Transcription {
   updated_by: UserRef
 }
 
+/**
+ * Transcribes a storage-service audio file. Asynchronous: the row lands
+ * `processing` and the caller polls until `completed`.
+ */
 export interface CreateTranscriptionRequest {
   file_id: string
   language?: string
@@ -1602,6 +1666,38 @@ export interface CreateTranscriptionRequest {
   is_diarized?: boolean
 }
 
+/**
+ * Lands an ALREADY WRITTEN transcript — no provider runs and the row is
+ * `completed` when the call returns. This is how a transcript, and through
+ * `materialize` a conversation, is authored from text with nothing to upload.
+ * `source_file_id` stays empty, which is how a reader tells the two kinds apart.
+ *
+ * Timings are optional: plain text has none, and materialization then sequences
+ * the turns by their position instead of by `start_ms`.
+ */
+/**
+ * One turn of an authored transcript. Distinct from TranscriptTurn (the read
+ * shape, always fully populated) because everything but who-said-what is
+ * derived server-side: an unlabelled speaker becomes "Speaker N", and text with
+ * no timings is sequenced by position at materialization.
+ */
+export interface AuthoredTranscriptTurn {
+  /** Speaker index — the same number means the same person. */
+  speaker: number
+  speaker_label?: string
+  text: string
+  start_ms?: number
+  end_ms?: number
+  confidence?: number
+}
+
+export interface CreateTranscriptionFromTextRequest {
+  turns: AuthoredTranscriptTurn[]
+  language?: string
+  /** Defaults to whether the turns name more than one speaker. */
+  is_diarized?: boolean
+}
+
 /**
  * Edits a COMPLETED transcription in place. `turns`, when present, replace the
  * diarized turns wholesale; `speaker_labels` maps diarized speaker indexes
@@ -1721,9 +1817,17 @@ export type SendingPeriod = 'rolling_24h' | 'rolling_7d' | 'rolling_30d'
  * ONE kind of act performed through a channel connection — shared by a
  * limit's `action` (what it counts), a channel action's `action_type` (what
  * was performed) and the eligibility check. `message` is the plain send
- * (valid on a limit, never on a channel action row).
+ * (valid on a limit, never on a channel action row). `profile_lookup` is the
+ * silent twin of `profile_visit`: one provider read the platform performs to
+ * learn a person's full identity (LinkedIn profile id + public identifier),
+ * ledgered and limited like any other act.
  */
-export type ChannelActionType = 'message' | 'invitation' | 'inmail' | 'profile_visit'
+export type ChannelActionType =
+  | 'message'
+  | 'invitation'
+  | 'inmail'
+  | 'profile_visit'
+  | 'profile_lookup'
 export type Weekday =
   | 'monday'
   | 'tuesday'

package/src/data/index.ts

@@ -1,6 +1,11 @@
 import type { ProteosClient } from '../client.js'
 import { type QueryService, QueryServiceImpl } from './queries.js'
-import { type RecordService, RecordServiceImpl } from './records.js'
+import {
+  type RecordDuplicateService,
+  RecordDuplicateServiceImpl,
+  type RecordService,
+  RecordServiceImpl,
+} from './records.js'
 
 /**
  * Facade for the data-service (records + raw-SQL query API).
@@ -16,10 +21,13 @@ import { type RecordService, RecordServiceImpl } from './records.js'
 export class DataClient {
   readonly records: RecordService
   readonly queries: QueryService
+  /** Duplicate pairs of an entity's records (raised by contact binding). */
+  readonly recordDuplicates: RecordDuplicateService
 
   constructor(client: ProteosClient) {
     this.records = new RecordServiceImpl(client)
     this.queries = new QueryServiceImpl(client)
+    this.recordDuplicates = new RecordDuplicateServiceImpl(client)
   }
 }
 
@@ -33,15 +41,20 @@ export type {
   QueryValidateMeta,
   QueryValidateResponse,
 } from './queries.js'
-export type { RecordService } from './records.js'
+export type { RecordDuplicateService, RecordService } from './records.js'
 export type {
   BatchTransactionError,
   BatchTransactionStatus,
   BatchUpsertRecordsResponse,
   BatchUpsertTransaction,
   BatchUpsertTransactionResult,
+  ListRecordDuplicatesQuery,
   ListRecordsOptions,
+  PublishContactObservationsResponse,
   RecordData,
+  RecordDuplicate,
+  RecordDuplicateSource,
+  RecordDuplicateStatus,
 } from './types.js'
 
 // Re-export Zod schemas

package/src/data/records.ts

@@ -4,8 +4,11 @@ import type { ListResult } from '../types/common.js'
 import type {
   BatchUpsertRecordsResponse,
   BatchUpsertTransaction,
+  ListRecordDuplicatesQuery,
   ListRecordsOptions,
+  PublishContactObservationsResponse,
   RecordData,
+  RecordDuplicate,
 } from './types.js'
 
 const RECORDS_BASE_PATH = '/data/v1/records'
@@ -92,6 +95,26 @@ export interface RecordService {
    * (bare refs) on this path.
    */
   getPublic(orgId: string, entitySlug: string, id: string): Promise<RecordData>
+  /**
+   * Replays ONE page of the entity's records as record_contact_observation
+   * events (the backfill after an attribute became contact-address). Requires
+   * unscoped write on the entity; loop until `page + 1 >= pages_total`.
+   */
+  publishContactObservations(
+    entitySlug: string,
+    options?: { page?: number; page_size?: number },
+  ): Promise<PublishContactObservationsResponse>
+}
+
+/**
+ * Record duplicates — "these two records may be the same thing" pairs of one
+ * entity (see `RecordDuplicate`). Reading = entity read, dismissing = entity write.
+ */
+export interface RecordDuplicateService {
+  list(entitySlug: string, query?: ListRecordDuplicatesQuery): Promise<ListResult<RecordDuplicate>>
+  get(entitySlug: string, id: string): Promise<RecordDuplicate>
+  /** Closes a pair as "not a duplicate" (409 `record_duplicate_not_open` when already closed). */
+  dismiss(entitySlug: string, id: string): Promise<RecordDuplicate>
 }
 
 /**
@@ -149,6 +172,17 @@ export class RecordServiceImpl implements RecordService {
     )
   }
 
+  async publishContactObservations(
+    entitySlug: string,
+    options: { page?: number; page_size?: number } = {},
+  ): Promise<PublishContactObservationsResponse> {
+    return this.client.requestWithQuery<PublishContactObservationsResponse>(
+      'POST',
+      `${RECORDS_BASE_PATH}/${entitySlug}/contact-observations`,
+      options,
+    )
+  }
+
   listPublic(
     orgId: string,
     entitySlug: string,
@@ -180,3 +214,32 @@ export class RecordServiceImpl implements RecordService {
     )
   }
 }
+
+export class RecordDuplicateServiceImpl implements RecordDuplicateService {
+  constructor(private readonly client: ProteosClient) {}
+
+  async list(
+    entitySlug: string,
+    query: ListRecordDuplicatesQuery = {},
+  ): Promise<ListResult<RecordDuplicate>> {
+    return this.client.requestWithQuery<ListResult<RecordDuplicate>>(
+      'GET',
+      `${RECORDS_BASE_PATH}/${entitySlug}/duplicates`,
+      query,
+    )
+  }
+
+  async get(entitySlug: string, id: string): Promise<RecordDuplicate> {
+    return this.client.request<RecordDuplicate>(
+      'GET',
+      `${RECORDS_BASE_PATH}/${entitySlug}/duplicates/${encodeURIComponent(id)}`,
+    )
+  }
+
+  async dismiss(entitySlug: string, id: string): Promise<RecordDuplicate> {
+    return this.client.request<RecordDuplicate>(
+      'POST',
+      `${RECORDS_BASE_PATH}/${entitySlug}/duplicates/${encodeURIComponent(id)}/dismiss`,
+    )
+  }
+}

package/src/data/types.ts

@@ -96,3 +96,55 @@ export const BatchUpsertTransactionResultSchema = z.object({
 export const BatchUpsertRecordsResponseSchema = z.object({
   results: z.array(BatchUpsertTransactionResultSchema),
 })
+
+// ── Record duplicates ─────────────────────────────────────────────────────────
+
+/** How a duplicate pair was detected. `contact_binding` = two records bound to
+ * the same conversation contact through their contact-address attributes. */
+export type RecordDuplicateSource = 'contact_binding' | (string & {})
+
+export type RecordDuplicateStatus = 'open' | 'dismissed' | 'resolved'
+
+/**
+ * "These two records of one entity may be the same thing." Asymmetric:
+ * `primary_record_id` is the record to keep, `secondary_record_id` the
+ * newcomer. A group of colliding records has ONE primary and one row per other
+ * member (four records = three rows). `evidence` is shaped by `source` — for
+ * `contact_binding`: `{ contact_id, address_keys: [{kind, value}] }`.
+ */
+export interface RecordDuplicate {
+  id: string
+  org_id: string
+  entity_slug: string
+  primary_record_id: string
+  secondary_record_id: string
+  source: RecordDuplicateSource
+  evidence: Record<string, unknown>
+  status: RecordDuplicateStatus
+  resolved_by?: { type: string; id: string }
+  resolved_at?: string
+  created_at: string
+  created_by: { type: string; id: string }
+  updated_at: string
+  updated_by: { type: string; id: string }
+}
+
+export interface ListRecordDuplicatesQuery {
+  /** Only pairs this record takes part in (either side). */
+  record_id?: string
+  /** Defaults to `open` on the server. */
+  status?: RecordDuplicateStatus
+  page?: number
+  page_size?: number
+}
+
+/** ONE page of an entity's records replayed as contact observations. */
+export interface PublishContactObservationsResponse {
+  entity_slug: string
+  page: number
+  page_size: number
+  pages_total: number
+  items_total: number
+  published: number
+  skipped: number
+}