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

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

@@ -0,0 +1,329 @@
+import { z } from 'zod'
+import { FetchTimeoutError } from '@open-mercato/shared/lib/http/fetchWithTimeout'
+import { safeOutboundFetch, UnsafeOutboundUrlError, type HostLookup } from '@open-mercato/shared/lib/url-safety'
+import { TillioApiError } from './errors'
+import { assertPublicTillioApiUrl, TILLIO_URL_SUBJECT } from './url-guard'
+
+const TILLIO_REQUEST_TIMEOUT_MS = 15_000
+const TILLIO_MIN_REQUEST_SPACING_MS = 200
+const TILLIO_MAX_RETRIES = 3
+const TILLIO_RETRY_BASE_MS = 500
+const TILLIO_RETRY_MAX_MS = 8_000
+const TILLIO_MAX_REDIRECTS = 3
+const RETRYABLE_STATUSES = new Set([429, 503])
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308])
+
+// Tillio's rate limit is per environment, not per request, so the spacing has to be shared
+// by every client this process builds. As a closure variable it reset with each client —
+// and clients are built per request — so it never actually throttled. Still per process:
+// horizontally the server-side limit stays the real backstop.
+let lastRequestAt = 0
+
+export type TillioClientDeps = {
+  /** Test seam handed to `safeOutboundFetch`; production uses the DNS-pinned default. */
+  fetchImpl?: typeof fetch
+  /** Test seam for the DNS resolution that outbound URL validation performs. */
+  lookupHost?: HostLookup
+}
+
+// The token travels in the query string (`DELETE /api/config` accepts it nowhere else),
+// so no URL may be pasted into an error message as-is.
+export function redactTillioUrl(rawUrl: string): string {
+  try {
+    const url = new URL(rawUrl)
+    if (url.searchParams.has('token')) url.searchParams.set('token', '***')
+    return url.toString()
+  } catch {
+    return rawUrl.split('?')[0] ?? ''
+  }
+}
+
+export type TillioPlugin = 'Ringostat' | 'P4' | 'Focus' | 'Plus'
+
+export type TillioClientEnvironment = {
+  apiUrl: string
+  apiKey: string
+  tenantSystemId: string
+}
+
+const addConfigResponseSchema = z.object({ token: z.string().min(1) })
+const errorResponseSchema = z.object({
+  error: z.string(),
+  message: z.string().optional(),
+})
+
+// Tillio serializes pagination counters as strings ("52", "1"); tolerate numbers too.
+const counterSchema = z.union([z.string(), z.number()]).transform((value, ctx) => {
+  const parsed = Number(value)
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    ctx.addIssue({ code: 'custom', message: 'Tillio returned an unusable pagination counter' })
+    return z.NEVER
+  }
+  return Math.trunc(parsed)
+})
+
+// Calls stay raw records here: mapping is the normalizer's job, and `raw_snapshot`
+// must keep every field Tillio sent, including operator-specific `extraFields`.
+const getCallsResponseSchema = z.object({
+  calls: z.array(z.record(z.string(), z.unknown())).default([]),
+  pagination: z.object({
+    total: counterSchema,
+    page: counterSchema,
+    pages: counterSchema,
+  }),
+})
+
+export type TillioCallsPage = z.infer<typeof getCallsResponseSchema>
+
+export type GetCallsParams = {
+  tenantDomain: string
+  token: string
+  from?: string
+  to?: string
+  page?: number
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+function clampRetryAfterMs(header: string | null, fallback: number): number {
+  if (!header) return fallback
+  const seconds = Number(header)
+  if (Number.isFinite(seconds) && seconds >= 0) return Math.min(seconds * 1000, TILLIO_RETRY_MAX_MS)
+  return fallback
+}
+
+function backoffMs(attempt: number): number {
+  const exponential = Math.min(TILLIO_RETRY_BASE_MS * 2 ** attempt, TILLIO_RETRY_MAX_MS)
+  const jitter = Math.floor(Math.random() * TILLIO_RETRY_BASE_MS)
+  return exponential + jitter
+}
+
+export function createTillioClient(environment: TillioClientEnvironment, deps: TillioClientDeps = {}) {
+  const apiUrl = environment.apiUrl.trim().replace(/\/+$/, '')
+  const apiKey = environment.apiKey.trim()
+  const tenantSystemId = environment.tenantSystemId.trim()
+  if (!apiUrl) throw new Error('Tillio environment is missing the API URL.')
+  if (!apiKey) throw new Error('Tillio environment is missing the API key.')
+  if (!tenantSystemId) throw new Error('Tillio environment is missing the tenant system id.')
+  // SSRF guard: apiUrl is user-supplied, so reject loopback/private/link-local targets
+  // before any request goes out (covers health check, validate, attach/detach, pull).
+  assertPublicTillioApiUrl(apiUrl)
+  const apiHostname = new URL(apiUrl).hostname.toLowerCase()
+
+  function buildHeaders(tenantDomain: string, token?: string): Record<string, string> {
+    const headers: Record<string, string> = {
+      'X-Api-Key': apiKey,
+      'X-System': tenantSystemId,
+      'X-Tenant': tenantSystemId,
+      'X-Tenant-Domain': tenantDomain,
+    }
+    if (token) headers['X-Token'] = token
+    return headers
+  }
+
+  async function throttle(): Promise<void> {
+    const wait = Math.max(0, TILLIO_MIN_REQUEST_SPACING_MS - (Date.now() - lastRequestAt))
+    if (wait > 0) await sleep(wait)
+    lastRequestAt = Date.now()
+  }
+
+  function resolveUrl(path: string, query?: Record<string, string>): string {
+    const url = new URL(path.replace(/^\/+/, ''), `${apiUrl}/`)
+    if (query) for (const [key, value] of Object.entries(query)) url.searchParams.set(key, value)
+    return url.toString()
+  }
+
+  // `safeOutboundFetch` validates the URL, pins the connection to the address it validated
+  // (so DNS cannot rebind between check and connect) and never follows redirects on its own.
+  async function fetchOnce(
+    method: string,
+    url: string,
+    init: { headers: Record<string, string>; body?: unknown },
+  ): Promise<Response> {
+    const hasBody = init.body !== undefined
+    const controller = new AbortController()
+    const timer = setTimeout(
+      () => controller.abort(new FetchTimeoutError(redactTillioUrl(url), TILLIO_REQUEST_TIMEOUT_MS)),
+      TILLIO_REQUEST_TIMEOUT_MS,
+    )
+    try {
+      return await safeOutboundFetch(
+        url,
+        {
+          method,
+          headers: {
+            accept: 'application/json',
+            ...(hasBody ? { 'content-type': 'application/json' } : {}),
+            ...init.headers,
+          },
+          ...(hasBody ? { body: JSON.stringify(init.body) } : {}),
+          signal: controller.signal,
+        },
+        { subject: TILLIO_URL_SUBJECT, lookupHost: deps.lookupHost, fetchImpl: deps.fetchImpl },
+      )
+    } catch (err) {
+      if ((err as { name?: string } | null)?.name === 'AbortError') {
+        const reason = (controller.signal as AbortSignal & { reason?: unknown }).reason
+        if (reason instanceof Error) throw reason
+      }
+      throw err
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+
+  // Every hop goes back through `fetchOnce`, so a redirect target is validated exactly like
+  // the original URL. The request carries `X-Api-Key` and `X-Token`, so a hop that leaves the
+  // configured host — or downgrades https to http — would hand those credentials to someone
+  // else and is refused instead of followed.
+  function resolveRedirectTarget(currentUrl: string, response: Response): string {
+    const location = response.headers.get('location')
+    if (!location) {
+      throw new TillioApiError(
+        `Tillio answered ${response.status} without a Location header`,
+        response.status,
+        'redirect',
+      )
+    }
+    let target: URL
+    try {
+      target = new URL(location, currentUrl)
+    } catch {
+      throw new TillioApiError(`Tillio redirected to an unusable location`, response.status, 'redirect')
+    }
+    const current = new URL(currentUrl)
+    if (target.hostname.toLowerCase() !== apiHostname) {
+      throw new TillioApiError(
+        `Tillio redirected off the configured host, to "${target.hostname}"`,
+        response.status,
+        'redirect',
+      )
+    }
+    if (current.protocol === 'https:' && target.protocol !== 'https:') {
+      throw new TillioApiError('Tillio redirected from https to a plaintext URL', response.status, 'redirect')
+    }
+    return target.toString()
+  }
+
+  async function rawRequest(
+    method: string,
+    url: string,
+    init: { headers: Record<string, string>; body?: unknown },
+    attempt = 0,
+  ): Promise<Response> {
+    await throttle()
+    let currentMethod = method
+    let currentUrl = url
+    let currentInit = init
+    let response: Response
+    for (let hop = 0; ; hop += 1) {
+      try {
+        response = await fetchOnce(currentMethod, currentUrl, currentInit)
+      } catch (err) {
+        if (err instanceof FetchTimeoutError) {
+          throw new TillioApiError(
+            `Tillio request timed out: ${currentMethod} ${redactTillioUrl(currentUrl)}`,
+            0,
+            'timeout',
+          )
+        }
+        if (err instanceof UnsafeOutboundUrlError) {
+          throw new TillioApiError(`Tillio request blocked: ${err.message}`, 0, err.reason)
+        }
+        const message = err instanceof Error ? err.message : 'network error'
+        throw new TillioApiError(
+          `Tillio request failed: ${currentMethod} ${redactTillioUrl(currentUrl)}: ${message}`,
+          0,
+          'network',
+        )
+      }
+
+      if (!REDIRECT_STATUSES.has(response.status)) break
+      if (hop >= TILLIO_MAX_REDIRECTS) {
+        throw new TillioApiError(
+          `Tillio redirected more than ${TILLIO_MAX_REDIRECTS} times`,
+          response.status,
+          'redirect',
+        )
+      }
+      currentUrl = resolveRedirectTarget(currentUrl, response)
+      // 303 means "fetch the result with GET", so the body must not be replayed.
+      if (response.status === 303 && currentMethod !== 'GET' && currentMethod !== 'HEAD') {
+        currentMethod = 'GET'
+        currentInit = { headers: currentInit.headers }
+      }
+    }
+
+    if (RETRYABLE_STATUSES.has(response.status) && attempt < TILLIO_MAX_RETRIES) {
+      const delay = clampRetryAfterMs(response.headers.get('retry-after'), backoffMs(attempt))
+      await sleep(delay)
+      return rawRequest(method, url, init, attempt + 1)
+    }
+
+    return response
+  }
+
+  async function requestJson<T>(
+    method: string,
+    path: string,
+    options: { headers: Record<string, string>; body?: unknown; query?: Record<string, string>; schema: z.ZodType<T> },
+  ): Promise<T> {
+    const url = resolveUrl(path, options.query)
+    const response = await rawRequest(method, url, { headers: options.headers, body: options.body })
+    const text = await response.text()
+
+    let parsed: unknown
+    try {
+      parsed = text ? JSON.parse(text) : {}
+    } catch {
+      throw new TillioApiError(
+        response.ok ? 'Tillio returned a non-JSON response' : `Tillio request failed (${response.status})`,
+        response.status,
+        text.slice(0, 200),
+      )
+    }
+
+    const asError = errorResponseSchema.safeParse(parsed)
+    if (asError.success && asError.data.error) {
+      throw new TillioApiError(asError.data.message ?? asError.data.error, response.status, asError.data.error)
+    }
+
+    if (!response.ok) {
+      throw new TillioApiError(`Tillio request failed (${response.status})`, response.status, JSON.stringify(parsed).slice(0, 200))
+    }
+
+    return options.schema.parse(parsed)
+  }
+
+  return {
+    async getPlugins(tenantDomain: string): Promise<unknown> {
+      return requestJson('GET', '/api/plugins', { headers: buildHeaders(tenantDomain), schema: z.unknown() })
+    },
+
+    async getCalls(params: GetCallsParams): Promise<TillioCallsPage> {
+      const query: Record<string, string> = {}
+      if (params.from) query.from = params.from
+      if (params.to) query.to = params.to
+      if (params.page !== undefined) query.page = String(params.page)
+      return requestJson('GET', '/api/call', {
+        headers: buildHeaders(params.tenantDomain, params.token),
+        query,
+        schema: getCallsResponseSchema,
+      })
+    },
+
+    async validateConfig(plugin: TillioPlugin, config: Record<string, unknown>, tenantDomain: string): Promise<void> {
+      await requestJson('POST', '/api/config/validate', { headers: buildHeaders(tenantDomain), body: { plugin, config }, schema: z.unknown() })
+    },
+
+    async addConfig(plugin: TillioPlugin, config: Record<string, unknown>, tenantDomain: string): Promise<{ token: string }> {
+      return requestJson('POST', '/api/config', { headers: buildHeaders(tenantDomain), body: { plugin, config }, schema: addConfigResponseSchema })
+    },
+
+    async deleteConfig(plugin: TillioPlugin, token: string, tenantDomain: string): Promise<void> {
+      await requestJson('DELETE', '/api/config', { headers: buildHeaders(tenantDomain), query: { plugin, token }, schema: z.unknown() })
+    },
+  }
+}

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

@@ -0,0 +1,53 @@
+import { randomBytes } from 'node:crypto'
+import { z } from 'zod'
+import type { IntegrationScope } from '@open-mercato/shared/modules/integrations/types'
+import { isValidTimeZone } from './tz'
+
+// Own key, like the operators blob: saving integration credentials keeps the submitted fields
+// plus the schema's secret fields, and the identity is in neither, so it was dropped on every save.
+export const TILLIO_ENVIRONMENT_IDENTITY_INTEGRATION_ID = 'tillio_environment'
+
+export const ENV_PROBE_TENANT_DOMAIN = 'test_connection'
+
+export const environmentSchema = z.object({
+  apiUrl: z.string().trim().min(1),
+  apiKey: z.string().trim().min(1),
+  tenantSystemId: z.string().trim().optional(),
+  // Optional so an environment saved before this field existed still parses; readers fall back to
+  // TILLIO_TIMEZONE.
+  timeZone: z
+    .string()
+    .trim()
+    .refine(isValidTimeZone, { message: 'Expected an IANA time zone name' })
+    .optional(),
+})
+
+export type TillioEnvironment = z.infer<typeof environmentSchema>
+
+const identitySchema = z.object({ tenantSystemId: z.string().trim().min(1) })
+
+export type TillioIdentityStore = {
+  getRaw: (integrationId: string, scope: IntegrationScope) => Promise<Record<string, unknown> | null>
+  save: (integrationId: string, credentials: Record<string, unknown>, scope: IntegrationScope) => Promise<void>
+}
+
+export function generateTenantSystemId(): string {
+  return `OM-${randomBytes(6).toString('hex')}`
+}
+
+export async function readTenantSystemId(
+  credentialsService: TillioIdentityStore,
+  scope: IntegrationScope,
+): Promise<string | null> {
+  const raw = await credentialsService.getRaw(TILLIO_ENVIRONMENT_IDENTITY_INTEGRATION_ID, scope)
+  const parsed = identitySchema.safeParse(raw ?? {})
+  return parsed.success ? parsed.data.tenantSystemId : null
+}
+
+export async function saveTenantSystemId(
+  credentialsService: TillioIdentityStore,
+  scope: IntegrationScope,
+  tenantSystemId: string,
+): Promise<void> {
+  await credentialsService.save(TILLIO_ENVIRONMENT_IDENTITY_INTEGRATION_ID, { tenantSystemId }, scope)
+}

package/src/modules/tillio/lib/error-codes.ts

@@ -0,0 +1,67 @@
+import type { PullBlocker } from './pull-readiness'
+
+// Routes answer with a stable code and the widgets own the wording, so a non-English user never
+// sees a server string. `message` stays in the payload for API consumers and logs only.
+export const TILLIO_ERROR_CODES = [
+  'unauthorized',
+  'invalid_payload',
+  'invalid_operator_id',
+  'integration_disabled',
+  'environment_not_ready',
+  'operator_missing',
+  'environment_drift',
+  'pull_already_running',
+  'pull_failed',
+  'app_url_missing',
+  'operator_limit',
+  'provider_error',
+  'revocation_failed',
+  'attach_failed',
+  'detach_failed',
+] as const
+
+export type TillioErrorCode = typeof TILLIO_ERROR_CODES[number]
+
+type TillioErrorCopy = { key: string; fallback: string }
+
+const COPY: Record<TillioErrorCode, TillioErrorCopy> = {
+  unauthorized: { key: 'tillio.errors.unauthorized', fallback: 'Your session expired. Sign in again.' },
+  invalid_payload: { key: 'tillio.errors.invalidPayload', fallback: 'The request was rejected as invalid.' },
+  invalid_operator_id: { key: 'tillio.errors.invalidOperatorId', fallback: 'That operator id is not valid.' },
+  integration_disabled: { key: 'tillio.errors.integrationDisabled', fallback: 'The Tillio integration is disabled. Enable it first.' },
+  environment_not_ready: { key: 'tillio.errors.environmentNotReady', fallback: 'Configure the Tillio credentials and run the health check first.' },
+  operator_missing: { key: 'tillio.errors.operatorMissing', fallback: 'Attach a Tillio operator first.' },
+  environment_drift: { key: 'tillio.errors.environmentDrift', fallback: 'The environment changed after the operator was attached. Detach and attach it again.' },
+  pull_already_running: { key: 'tillio.errors.pullAlreadyRunning', fallback: 'A pull is already running. Wait for it to finish.' },
+  pull_failed: { key: 'tillio.errors.pullFailed', fallback: 'Could not pull calls from Tillio.' },
+  app_url_missing: { key: 'tillio.errors.appUrlMissing', fallback: 'APP_URL is not configured, so the operator webhook domain cannot be derived.' },
+  operator_limit: { key: 'tillio.errors.operatorLimit', fallback: 'An operator is already attached. Detach it first.' },
+  provider_error: { key: 'tillio.errors.providerError', fallback: 'Tillio rejected the request.' },
+  revocation_failed: { key: 'tillio.errors.revocationFailed', fallback: 'The Tillio token could not be revoked.' },
+  attach_failed: { key: 'tillio.errors.attachFailed', fallback: 'Could not attach the operator.' },
+  detach_failed: { key: 'tillio.errors.detachFailed', fallback: 'Could not detach the operator.' },
+}
+
+export function tillioErrorCopy(code: string | null | undefined, fallbackCode: TillioErrorCode): TillioErrorCopy {
+  const known = TILLIO_ERROR_CODES.find((entry) => entry === code)
+  return COPY[known ?? fallbackCode]
+}
+
+// Keyed by the shared union so a blocker the server learns to report cannot reach the dialog
+// unworded: adding one to `PullBlocker` fails this record until it gets copy of its own. The pull
+// entries are worded for the action in progress, which the generic `COPY` above cannot be.
+export const PULL_BLOCKER_COPY: Record<PullBlocker, TillioErrorCopy> = {
+  integration_disabled: COPY.integration_disabled,
+  environment_not_ready: {
+    key: 'tillio.pull.envNotReady',
+    fallback: 'Configure the Tillio credentials and run the health check on the integration page first.',
+  },
+  operator_missing: {
+    key: 'tillio.pull.operatorMissing',
+    fallback: 'Attach a Tillio operator on the integration page before pulling calls.',
+  },
+  environment_drift: {
+    key: 'tillio.pull.envDrift',
+    fallback: 'The Tillio environment changed after the operator was attached. Detach and attach it again before pulling calls.',
+  },
+}

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

@@ -0,0 +1,11 @@
+export class TillioApiError extends Error {
+  readonly status: number
+  readonly detail: string
+
+  constructor(message: string, status: number, detail: string) {
+    super(message)
+    this.name = 'TillioApiError'
+    this.status = status
+    this.detail = detail
+  }
+}

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

@@ -0,0 +1,57 @@
+import type { IntegrationScope } from '@open-mercato/shared/modules/integrations/types'
+import { TillioApiError } from './errors'
+import { createTillioClient } from './client'
+import {
+  ENV_PROBE_TENANT_DOMAIN,
+  environmentSchema,
+  generateTenantSystemId,
+  readTenantSystemId,
+  saveTenantSystemId,
+  type TillioIdentityStore,
+} from './environment'
+
+export type CredentialsServiceLike = TillioIdentityStore
+
+type HealthResult = {
+  status: 'healthy' | 'degraded' | 'unhealthy'
+  message?: string
+  details?: Record<string, unknown>
+}
+
+export function createTillioEnvironmentHealthCheck(deps: { credentialsService: CredentialsServiceLike }) {
+  return {
+    async check(credentials: Record<string, unknown> | null, scope: IntegrationScope): Promise<HealthResult> {
+      const parsed = environmentSchema.safeParse(credentials ?? {})
+      if (!parsed.success) {
+        return { status: 'unhealthy', message: 'Environment is not configured (set the Tillio API URL and API key).' }
+      }
+
+      // Writes on first run: the client sends this id as X-System/X-Tenant and refuses to build
+      // without one, so the probe below cannot run before it exists. A subscriber on
+      // `integrations.credentials.updated` would leave a window where Check reports "not configured".
+      let tenantSystemId = await readTenantSystemId(deps.credentialsService, scope)
+      if (!tenantSystemId) {
+        // Adopts an identity still sitting in the legacy record before minting a new one:
+        // a fresh id would change X-System/X-Tenant and invalidate every operator token.
+        tenantSystemId = parsed.data.tenantSystemId ?? generateTenantSystemId()
+        try {
+          await saveTenantSystemId(deps.credentialsService, scope, tenantSystemId)
+        } catch (err) {
+          const message = err instanceof Error ? err.message : 'Failed to persist the environment identity'
+          return { status: 'unhealthy', message }
+        }
+      }
+
+      try {
+        const client = createTillioClient({ apiUrl: parsed.data.apiUrl, apiKey: parsed.data.apiKey, tenantSystemId })
+        // No dedicated ping endpoint, so listing plugins stands in for one: read-only and over the
+        // same auth path a real call takes. The probe domain is a throwaway — no operator exists yet.
+        await client.getPlugins(ENV_PROBE_TENANT_DOMAIN)
+        return { status: 'healthy', message: 'Tillio environment connected.' }
+      } catch (err) {
+        const message = err instanceof TillioApiError || err instanceof Error ? err.message : 'Environment check failed'
+        return { status: 'unhealthy', message }
+      }
+    },
+  }
+}

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

@@ -0,0 +1,30 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { IntegrationScope } from '@open-mercato/shared/modules/integrations/types'
+
+/**
+ * Runs `run` with a scope-wide lock held. Both call sites read state, talk to Tillio and then
+ * write, and neither store underneath them offers a compare-and-set, so re-checking before the
+ * write can only narrow the race, never close it.
+ *
+ * `pg_advisory_xact_lock` is the same primitive `attachments`, `notifications` and `sso` use, and
+ * it releases with the transaction, so a request that dies mid-section cannot leave it held. The
+ * transaction exists to own the lock: the work inside writes through its own services and is not
+ * made atomic by it.
+ */
+export type TillioLockRunner = <T>(run: () => Promise<T>) => Promise<T>
+
+export function createTillioLock(em: EntityManager, key: string): TillioLockRunner {
+  return async <T>(run: () => Promise<T>): Promise<T> =>
+    em.transactional(async (tx) => {
+      await tx.getConnection().execute('select pg_advisory_xact_lock(hashtext(?::text))', [key])
+      return run()
+    })
+}
+
+export function tillioOperatorLockKey(scope: IntegrationScope): string {
+  return `tillio:operators:${scope.tenantId}:${scope.organizationId}`
+}
+
+export function tillioPullLockKey(scope: IntegrationScope): string {
+  return `tillio:pull:${scope.tenantId}:${scope.organizationId}`
+}