@open-mercato/tillio 0.7.1-develop.7176.1.d229567a50

package/src/modules/tillio/lib/normalizer.ts

@@ -0,0 +1,184 @@
+import { z } from 'zod'
+import type {
+  NormalizedPhoneCall,
+  NormalizedPhoneCallParticipant,
+  NormalizedPhoneCallRecording,
+  PhoneCallDirection,
+  PhoneCallStatus,
+} from '@open-mercato/shared/modules/phone_calls/types'
+import type { TillioOperatorPlugin } from './operators-store'
+import { parseTillioTimestamp } from './tz'
+
+const stringish = z.union([z.string(), z.number()]).transform((value) => String(value))
+
+const tillioCallSchema = z.object({
+  id: stringish,
+  date: stringish.optional(),
+  type: stringish.optional(),
+  caller: stringish.optional(),
+  destination: stringish.optional(),
+  status: stringish.optional(),
+  waitTime: stringish.optional(),
+  billSec: stringish.optional(),
+  extraFields: z.record(z.string(), z.unknown()).optional(),
+})
+
+export type TillioRawCall = z.infer<typeof tillioCallSchema>
+
+const ANSWERED_STATUSES = new Set(['ANSWERED', 'PROPER', 'REPEATED', 'CONNECTED'])
+// The call reached the callee side but no conversation happened: nobody picked up,
+// voicemail took it, there was nowhere to forward it, or the callee was on another
+// call.
+const MISSED_STATUSES = new Set(['NO ANSWER', 'NO FORWARD', 'VOICEMAIL', 'NO EXTENSION', 'BUSY'])
+// The call could not be set up at all (SIP 603).
+const FAILED_STATUSES = new Set(['FAILED'])
+
+const HTML_ENTITIES: Record<string, string> = {
+  '&quot;': '"',
+  '&apos;': "'",
+  '&#39;': "'",
+  '&lt;': '<',
+  '&gt;': '>',
+  '&amp;': '&',
+}
+
+export type TillioCallExtraction = {
+  callerDisplayName?: string | null
+  recording?: NormalizedPhoneCallRecording | null
+  providerFacts?: Record<string, unknown>
+}
+
+export type TillioCallExtractor = (extraFields: Record<string, unknown>) => TillioCallExtraction
+
+export type NormalizeContext = {
+  operatorId: string
+  plugin: TillioOperatorPlugin
+  timeZone?: string
+}
+
+function decodeHtmlEntities(value: string): string {
+  return value.replace(/&(?:quot|apos|#39|lt|gt|amp);/g, (entity) => HTML_ENTITIES[entity] ?? entity)
+}
+
+// Ringostat sends a SIP-style `"display name" <uri>` string, HTML-escaped.
+function extractDisplayName(value: string): string | null {
+  const decoded = decodeHtmlEntities(value).trim()
+  if (!decoded) return null
+  const uriStart = decoded.indexOf('<')
+  const beforeUri = (uriStart >= 0 ? decoded.slice(0, uriStart) : decoded).trim()
+  const name = beforeUri.startsWith('"') && beforeUri.endsWith('"')
+    ? beforeUri.slice(1, -1).trim()
+    : beforeUri
+  return name || null
+}
+
+function readString(source: Record<string, unknown>, key: string): string | null {
+  const value = source[key]
+  if (typeof value === 'string' && value.trim()) return value.trim()
+  if (typeof value === 'number') return String(value)
+  return null
+}
+
+function parseSeconds(value: string | undefined): number | null {
+  if (value === undefined) return null
+  const parsed = Number(value)
+  if (!Number.isFinite(parsed) || parsed < 0) return null
+  return Math.trunc(parsed)
+}
+
+function mapDirection(type: string | undefined): PhoneCallDirection {
+  switch ((type ?? '').trim().toUpperCase()) {
+    case 'IN':
+      return 'inbound'
+    case 'OUT':
+      return 'outbound'
+    default:
+      return 'unknown'
+  }
+}
+
+// A billed call connected, whatever the textual status claims. A status Tillio has
+// not documented yet stays 'unknown' rather than being reported as a failure.
+export function mapStatus(status: string | undefined, durationSeconds: number | null): PhoneCallStatus {
+  if (durationSeconds !== null && durationSeconds > 0) return 'answered'
+  const normalized = (status ?? '').trim().toUpperCase()
+  if (ANSWERED_STATUSES.has(normalized)) return 'answered'
+  if (MISSED_STATUSES.has(normalized)) return 'missed'
+  if (FAILED_STATUSES.has(normalized)) return 'failed'
+  return 'unknown'
+}
+
+export const ringostatExtractor: TillioCallExtractor = (extraFields) => {
+  const providerFacts: Record<string, unknown> = {}
+  const callCard = readString(extraFields, 'call_card')
+  if (callCard) providerFacts.tillioCallCardUrl = callCard
+
+  const recordingUrl = readString(extraFields, 'recording')
+  const hasRecording = readString(extraFields, 'has_recording') === '1' && Boolean(recordingUrl)
+
+  const rawCaller = readString(extraFields, 'caller')
+
+  return {
+    callerDisplayName: rawCaller ? extractDisplayName(rawCaller) : null,
+    recording: hasRecording ? { url: recordingUrl } : null,
+    providerFacts,
+  }
+}
+
+const EXTRACTORS: Record<TillioOperatorPlugin, TillioCallExtractor> = {
+  Ringostat: ringostatExtractor,
+}
+
+export function getExtractorForPlugin(plugin: TillioOperatorPlugin): TillioCallExtractor {
+  return EXTRACTORS[plugin]
+}
+
+export function normalizeTillioCall(
+  rawCall: Record<string, unknown>,
+  context: NormalizeContext,
+): NormalizedPhoneCall {
+  const parsed = tillioCallSchema.safeParse(rawCall)
+  if (!parsed.success) {
+    throw new Error('[internal] Tillio returned a call payload without a usable id.')
+  }
+  const call = parsed.data
+  const extraction = getExtractorForPlugin(context.plugin)(call.extraFields ?? {})
+
+  const durationSeconds = parseSeconds(call.billSec)
+  const waitTimeSeconds = parseSeconds(call.waitTime)
+
+  const participants: NormalizedPhoneCallParticipant[] = []
+  if (call.caller) {
+    participants.push({
+      role: 'caller',
+      phoneNumber: call.caller,
+      displayName: extraction.callerDisplayName ?? null,
+    })
+  }
+  if (call.destination) {
+    participants.push({ role: 'callee', phoneNumber: call.destination })
+  }
+
+  const providerFacts: Record<string, unknown> = {
+    ...extraction.providerFacts,
+    tillioStatus: call.status ?? null,
+    tillioType: call.type ?? null,
+    operatorId: context.operatorId,
+    plugin: context.plugin,
+  }
+  if (waitTimeSeconds !== null) providerFacts.tillioWaitTimeSeconds = waitTimeSeconds
+
+  return {
+    externalCallId: call.id,
+    direction: mapDirection(call.type),
+    status: mapStatus(call.status, durationSeconds),
+    participants,
+    recording: extraction.recording ?? null,
+    startedAt: parseTillioTimestamp(call.date, context.timeZone),
+    answeredAt: null,
+    endedAt: null,
+    durationSeconds,
+    providerFacts,
+    rawPayload: rawCall,
+  }
+}

package/src/modules/tillio/lib/operators-store.ts

@@ -0,0 +1,77 @@
+import { scryptSync } from 'node:crypto'
+import { z } from 'zod'
+import type { IntegrationScope } from '@open-mercato/shared/modules/integrations/types'
+
+// Own key in the credentials store rather than a table: `integration_credentials.integration_id` is
+// plain text with no registry lookup, so a provider key is accepted and the token inherits the
+// store's encryption. Distinct from TILLIO_INTEGRATION_ID so detaching never touches the environment.
+export const TILLIO_OPERATORS_INTEGRATION_ID = 'tillio_operators'
+
+export const operatorPluginSchema = z.enum(['Ringostat'])
+export type TillioOperatorPlugin = z.infer<typeof operatorPluginSchema>
+
+export const ringostatConfigSchema = z.object({
+  key: z.string().trim().min(1),
+})
+
+export const operatorRecordSchema = z.object({
+  id: z.string().trim().min(1),
+  plugin: operatorPluginSchema,
+  label: z.string().trim().optional(),
+  config: z.record(z.string(), z.unknown()),
+  token: z.string().trim().min(1),
+  tenantDomain: z.string().trim().min(1),
+  envFingerprint: z.string().trim().min(1),
+})
+export type TillioOperatorRecord = z.infer<typeof operatorRecordSchema>
+
+export const operatorsBlobSchema = z.object({
+  operators: z.array(operatorRecordSchema).default([]),
+  defaultOperatorId: z.string().trim().nullable().default(null),
+})
+export type TillioOperatorsBlob = z.infer<typeof operatorsBlobSchema>
+
+const EMPTY_BLOB: TillioOperatorsBlob = { operators: [], defaultOperatorId: null }
+
+export type TillioCredentialsService = {
+  getRaw: (integrationId: string, scope: IntegrationScope) => Promise<Record<string, unknown> | null>
+  save: (integrationId: string, credentials: Record<string, unknown>, scope: IntegrationScope) => Promise<void>
+}
+
+export function computeEnvFingerprint(env: { tenantSystemId: string; apiUrl: string; apiKey: string }): string {
+  const material = `${env.tenantSystemId}\n${env.apiUrl}\n${env.apiKey}`
+  return scryptSync(material, 'open-mercato:tillio:environment-fingerprint:v1', 32).toString('hex')
+}
+
+export function resolveAppHost(appUrl: string): string {
+  const trimmed = appUrl.trim()
+  if (!trimmed) return ''
+  try {
+    return new URL(trimmed).host
+  } catch {
+    return trimmed.replace(/^\/+/, '').split('/')[0] ?? ''
+  }
+}
+
+export function buildTenantDomain(appUrl: string, tenantSystemId: string, operatorId: string): string {
+  const host = resolveAppHost(appUrl)
+  if (!host) throw new Error('[internal] APP_URL is not configured; cannot build the Tillio X-Tenant-Domain.')
+  return `${host}/${tenantSystemId}-${operatorId}`
+}
+
+export async function readOperatorsBlob(
+  credentialsService: TillioCredentialsService,
+  scope: IntegrationScope,
+): Promise<TillioOperatorsBlob> {
+  const raw = await credentialsService.getRaw(TILLIO_OPERATORS_INTEGRATION_ID, scope)
+  const parsed = operatorsBlobSchema.safeParse(raw ?? {})
+  return parsed.success ? parsed.data : EMPTY_BLOB
+}
+
+export async function saveOperatorsBlob(
+  credentialsService: TillioCredentialsService,
+  scope: IntegrationScope,
+  blob: TillioOperatorsBlob,
+): Promise<void> {
+  await credentialsService.save(TILLIO_OPERATORS_INTEGRATION_ID, blob, scope)
+}

package/src/modules/tillio/lib/operators.ts

@@ -0,0 +1,269 @@
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import type { IntegrationScope } from '@open-mercato/shared/modules/integrations/types'
+import { TillioApiError } from './errors'
+import { createTillioClient } from './client'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { IntegrationState } from '@open-mercato/core/modules/integrations/data/entities'
+import { environmentSchema, readTenantSystemId } from './environment'
+import type { TillioLockRunner } from './locking'
+import { TILLIO_TIMEZONE } from './tz'
+import { TILLIO_INTEGRATION_ID } from '../integration'
+import {
+  buildTenantDomain,
+  computeEnvFingerprint,
+  operatorPluginSchema,
+  readOperatorsBlob,
+  ringostatConfigSchema,
+  saveOperatorsBlob,
+  type TillioCredentialsService,
+  type TillioOperatorPlugin,
+  type TillioOperatorRecord,
+} from './operators-store'
+
+const logger = createLogger('tillio').child({ component: 'operators' })
+
+export type TillioResolvedEnvironment = {
+  apiUrl: string
+  apiKey: string
+  tenantSystemId: string
+  timeZone: string
+}
+
+export const TILLIO_OPERATOR_RESOURCE_KIND = 'tillio.operator'
+
+export type OperatorErrorSection = 'environment' | 'operator'
+
+export class TillioEnvironmentNotReadyError extends Error {
+  constructor(message = 'The Tillio environment is not ready. Save credentials and run the health check first.') {
+    super(message)
+    this.name = 'TillioEnvironmentNotReadyError'
+  }
+}
+
+export class TillioOperatorLimitError extends Error {
+  constructor(message = 'An operator is already attached. Detach it before attaching another one.') {
+    super(message)
+    this.name = 'TillioOperatorLimitError'
+  }
+}
+
+/**
+ * Raised when the operator's token could not be revoked at Tillio. The local record stays in
+ * place, because dropping it would leave a live token nobody holds a handle to any more.
+ * `environmentMissing` separates the two outcomes for the caller: a provider failure is worth
+ * retrying, a missing environment is not — it needs the credentials fixed, or a forced detach.
+ */
+export class TillioRevocationFailedError extends Error {
+  readonly environmentMissing: boolean
+
+  constructor(environmentMissing: boolean, message?: string) {
+    super(
+      message
+        ?? (environmentMissing
+          ? 'The Tillio environment is no longer configured, so the operator token cannot be revoked.'
+          : 'Tillio did not confirm the operator token was revoked.'),
+    )
+    this.name = 'TillioRevocationFailedError'
+    this.environmentMissing = environmentMissing
+  }
+}
+
+export function classifyTillioError(err: unknown): OperatorErrorSection {
+  if (err instanceof TillioApiError) {
+    if (err.status === 0 || err.status === 401 || err.status === 403) return 'environment'
+  }
+  return 'operator'
+}
+
+export async function resolveEnvironment(
+  credentialsService: TillioCredentialsService,
+  scope: IntegrationScope,
+): Promise<TillioResolvedEnvironment | null> {
+  const raw = await credentialsService.getRaw(TILLIO_INTEGRATION_ID, scope)
+  const parsed = environmentSchema.safeParse(raw ?? {})
+  if (!parsed.success) return null
+  // Falls back to the legacy location until the next health check moves the identity across.
+  const tenantSystemId = (await readTenantSystemId(credentialsService, scope)) ?? parsed.data.tenantSystemId
+  if (!tenantSystemId) return null
+  return {
+    apiUrl: parsed.data.apiUrl,
+    apiKey: parsed.data.apiKey,
+    tenantSystemId,
+    timeZone: parsed.data.timeZone ?? TILLIO_TIMEZONE,
+  }
+}
+
+export type TillioIntegrationState = {
+  /** The administrator's switch. Provisioning and sweeps stay off while it is false. */
+  enabled: boolean
+  /** The last probe result. Says Tillio answers, not that anybody wants us talking to it. */
+  healthy: boolean
+}
+
+// Both signals come off one row, and they fail for different reasons a user fixes in different
+// places, so callers get them apart rather than folded into a single boolean. A missing row
+// reads as disabled, matching `integrationStateService.resolveState`, which falls back to the
+// descriptor's `defaultState` and to `false` without one. The Tillio descriptor declares no
+// `defaultState`, so adding one there means switching this over to that service.
+export async function readTillioIntegrationState(
+  em: EntityManager,
+  scope: IntegrationScope,
+): Promise<TillioIntegrationState> {
+  const state = await findOneWithDecryption(
+    em,
+    IntegrationState,
+    {
+      integrationId: TILLIO_INTEGRATION_ID,
+      organizationId: scope.organizationId,
+      tenantId: scope.tenantId,
+      deletedAt: null,
+    },
+    undefined,
+    { tenantId: scope.tenantId, organizationId: scope.organizationId },
+  )
+  return {
+    enabled: state?.isEnabled ?? false,
+    healthy: state?.lastHealthStatus === 'healthy',
+  }
+}
+
+function operatorIdForPlugin(plugin: TillioOperatorPlugin): string {
+  return `${plugin.toLowerCase()}-1`
+}
+
+function normalizeOperatorConfig(plugin: TillioOperatorPlugin, config: Record<string, unknown>): Record<string, unknown> {
+  if (plugin === 'Ringostat') return ringostatConfigSchema.parse(config)
+  return config
+}
+
+export type AttachOperatorDeps = {
+  credentialsService: TillioCredentialsService
+  scope: IntegrationScope
+  appUrl: string
+  /**
+   * Serializes the slot check and the write. Required rather than optional so a new call site
+   * has to decide: passing `(run) => run()` says the caller knows it cannot contend.
+   */
+  withLock: TillioLockRunner
+}
+
+export type AttachOperatorInput = {
+  plugin: TillioOperatorPlugin
+  config: Record<string, unknown>
+  label?: string
+}
+
+export async function attachOperator(
+  deps: AttachOperatorDeps,
+  input: AttachOperatorInput,
+): Promise<TillioOperatorRecord> {
+  const plugin = operatorPluginSchema.parse(input.plugin)
+  const config = normalizeOperatorConfig(plugin, input.config)
+
+  const environment = await resolveEnvironment(deps.credentialsService, deps.scope)
+  if (!environment) throw new TillioEnvironmentNotReadyError()
+
+  const blob = await readOperatorsBlob(deps.credentialsService, deps.scope)
+  if (blob.operators.length > 0) throw new TillioOperatorLimitError()
+
+  const operatorId = operatorIdForPlugin(plugin)
+  const tenantDomain = buildTenantDomain(deps.appUrl, environment.tenantSystemId, operatorId)
+  const client = createTillioClient(environment)
+
+  await client.validateConfig(plugin, config, tenantDomain)
+  const { token } = await client.addConfig(plugin, config, tenantDomain)
+
+  const record: TillioOperatorRecord = {
+    id: operatorId,
+    plugin,
+    ...(input.label ? { label: input.label } : {}),
+    config,
+    token,
+    tenantDomain,
+    // Pins the operator to the environment that issued its token. If the environment is later
+    // edited the pairing is stale, and comparing this fingerprint is what raises `environment_drift`
+    // instead of pulling against an instance the operator never belonged to.
+    envFingerprint: computeEnvFingerprint(environment),
+  }
+
+  try {
+    // The remote calls above stay outside the lock: holding a database transaction while
+    // waiting on Tillio would tie a connection to their latency. Inside it, the slot is
+    // re-checked and written as one step, so a concurrent attach either loses here and is
+    // undone below, or wins and is the only stored operator.
+    await deps.withLock(async () => {
+      const current = await readOperatorsBlob(deps.credentialsService, deps.scope)
+      if (current.operators.length > 0) throw new TillioOperatorLimitError()
+
+      await saveOperatorsBlob(deps.credentialsService, deps.scope, {
+        operators: [record],
+        defaultOperatorId: operatorId,
+      })
+    })
+  } catch (err) {
+    // `addConfig` already registered this operator on Tillio's side. If we cannot persist it
+    // locally we would lose the only reference to that remote config, so undo it before failing.
+    await client.deleteConfig(plugin, token, tenantDomain).catch((revokeErr: unknown) => {
+      logger.error('could not roll back the remote operator config', { operatorId, err: revokeErr })
+    })
+    throw err
+  }
+
+  return record
+}
+
+export type DetachOperatorDeps = {
+  credentialsService: TillioCredentialsService
+  scope: IntegrationScope
+}
+
+export type DetachOperatorOptions = {
+  /**
+   * Drop the local record even though the token could not be revoked. The caller has to
+   * decide this explicitly, because the token stays live on Tillio's side afterwards.
+   */
+  force?: boolean
+}
+
+export async function detachOperator(
+  deps: DetachOperatorDeps,
+  operatorId: string,
+  options: DetachOperatorOptions = {},
+): Promise<{ ok: boolean; detached: boolean; revoked: boolean }> {
+  const blob = await readOperatorsBlob(deps.credentialsService, deps.scope)
+  const operator = blob.operators.find((entry) => entry.id === operatorId)
+  if (!operator) return { ok: true, detached: false, revoked: false }
+
+  const environment = await resolveEnvironment(deps.credentialsService, deps.scope)
+  let revoked = false
+  if (!environment) {
+    if (!options.force) throw new TillioRevocationFailedError(true)
+  } else {
+    try {
+      const client = createTillioClient(environment)
+      await client.deleteConfig(operator.plugin, operator.token, operator.tenantDomain)
+      revoked = true
+    } catch (err) {
+      logger.error('could not revoke the Tillio operator token', {
+        operatorId,
+        status: err instanceof TillioApiError ? err.status : undefined,
+        detail: err instanceof TillioApiError ? err.detail : undefined,
+        err,
+      })
+      if (!options.force) {
+        throw new TillioRevocationFailedError(false)
+      }
+    }
+  }
+
+  const remaining = blob.operators.filter((entry) => entry.id !== operatorId)
+  await saveOperatorsBlob(deps.credentialsService, deps.scope, {
+    operators: remaining,
+    defaultOperatorId: blob.defaultOperatorId === operatorId
+      ? (remaining[0]?.id ?? null)
+      : blob.defaultOperatorId,
+  })
+
+  return { ok: true, detached: true, revoked }
+}