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

package/src/modules/tillio/api/operators/[id]/route.ts

@@ -0,0 +1,90 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { runRouteMutationGuards } from '@open-mercato/shared/lib/crud/route-mutation-guard'
+import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
+import type { IntegrationScope } from '@open-mercato/shared/modules/integrations/types'
+import { tillioErrorCopy } from '../../../lib/error-codes'
+import type { TillioCredentialsService } from '../../../lib/operators-store'
+import {
+  detachOperator,
+  TILLIO_OPERATOR_RESOURCE_KIND,
+  TillioRevocationFailedError,
+} from '../../../lib/operators'
+
+const idParamsSchema = z.object({ id: z.string().trim().min(1) })
+
+export const metadata = {
+  DELETE: { requireAuth: true, requireFeatures: ['tillio.manage', 'integrations.manage'] },
+}
+
+export const openApi = {
+  tags: ['Tillio'],
+  summary: 'Detach a Tillio operator',
+}
+
+export async function DELETE(req: Request, ctx: { params?: Promise<{ id?: string }> | { id?: string } }) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.tenantId || !auth.orgId) {
+    return NextResponse.json({ ok: false, code: 'unauthorized', message: 'Unauthorized' }, { status: 401 })
+  }
+
+  const rawParams = (ctx.params && typeof (ctx.params as Promise<unknown>).then === 'function')
+    ? await (ctx.params as Promise<{ id?: string }>)
+    : (ctx.params as { id?: string } | undefined)
+
+  const parsedParams = idParamsSchema.safeParse(rawParams)
+  if (!parsedParams.success) {
+    return NextResponse.json({ ok: false, code: 'invalid_operator_id', message: 'Invalid operator id' }, { status: 400 })
+  }
+  const operatorId = parsedParams.data.id
+  const force = parseBooleanWithDefault(new URL(req.url).searchParams.get('force'), false)
+
+  const container = await createRequestContainer()
+  const credentialsService = container.resolve('integrationCredentialsService') as TillioCredentialsService
+  const scope: IntegrationScope = { organizationId: auth.orgId, tenantId: auth.tenantId }
+
+  const guarded = await runRouteMutationGuards({
+    container,
+    req,
+    auth: { userId: auth.sub, tenantId: auth.tenantId, organizationId: auth.orgId },
+    input: {
+      resourceKind: TILLIO_OPERATOR_RESOURCE_KIND,
+      resourceId: operatorId,
+      operation: 'delete',
+      mutationPayload: { operatorId, force },
+    },
+  })
+  if (!guarded.ok) return guarded.response
+
+  // A guard that refuses to let `force` through has to be able to say so. Only the flag is
+  // read back: rewriting which operator gets detached would silently retarget the request.
+  const guardedForce = typeof guarded.modifiedPayload?.force === 'boolean'
+    ? guarded.modifiedPayload.force
+    : force
+
+  try {
+    const result = await detachOperator({ credentialsService, scope }, operatorId, { force: guardedForce })
+    await guarded.runAfterSuccess()
+    return NextResponse.json({ ok: true, detached: result.detached, revoked: result.revoked })
+  } catch (err) {
+    if (err instanceof TillioRevocationFailedError) {
+      const code = err.environmentMissing ? 'environment_not_ready' : 'revocation_failed'
+      return NextResponse.json(
+        {
+          ok: false,
+          code,
+          section: err.environmentMissing ? 'environment' : 'operator',
+          message: tillioErrorCopy(code, 'detach_failed').fallback,
+          canForce: true,
+        },
+        { status: 502 },
+      )
+    }
+    return NextResponse.json(
+      { ok: false, code: 'detach_failed', section: 'operator', message: 'Failed to detach the operator.' },
+      { status: 500 },
+    )
+  }
+}

package/src/modules/tillio/api/operators/route.ts

@@ -0,0 +1,191 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { runRouteMutationGuards } from '@open-mercato/shared/lib/crud/route-mutation-guard'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import type { IntegrationScope } from '@open-mercato/shared/modules/integrations/types'
+import {
+  computeEnvFingerprint,
+  readOperatorsBlob,
+  type TillioCredentialsService,
+} from '../../lib/operators-store'
+import { createTillioLock, tillioOperatorLockKey } from '../../lib/locking'
+import { evaluateEnvironmentReadiness, type EnvironmentBlocker } from '../../lib/pull-readiness'
+import {
+  TillioApiError,
+} from '../../lib/errors'
+import { tillioErrorCopy } from '../../lib/error-codes'
+import {
+  attachOperator,
+  classifyTillioError,
+  readTillioIntegrationState,
+  resolveEnvironment,
+  TILLIO_OPERATOR_RESOURCE_KIND,
+  TillioEnvironmentNotReadyError,
+  TillioOperatorLimitError,
+} from '../../lib/operators'
+
+const SUPPORTED_PLUGINS = ['Ringostat'] as const
+const logger = createLogger('tillio').child({ component: 'operators-route' })
+
+// Same blockers as the pull reports, worded for the action the caller was attempting.
+const ATTACH_BLOCKER_MESSAGES: Record<EnvironmentBlocker, string> = {
+  integration_disabled: 'The Tillio integration is disabled. Enable it before attaching an operator.',
+  environment_not_ready: 'Run the Tillio environment health check before attaching an operator.',
+}
+
+const attachBodySchema = z.object({
+  plugin: z.literal('Ringostat'),
+  config: z.object({ key: z.string().trim().min(1) }),
+  label: z.string().trim().optional(),
+})
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['tillio.manage', 'integrations.manage'] },
+  POST: { requireAuth: true, requireFeatures: ['tillio.manage', 'integrations.manage'] },
+}
+
+export const openApi = {
+  tags: ['Tillio'],
+  summary: 'List and attach Tillio operators',
+}
+
+export async function GET(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.tenantId || !auth.orgId) {
+    return NextResponse.json({ ok: false, code: 'unauthorized', message: 'Unauthorized' }, { status: 401 })
+  }
+
+  const container = await createRequestContainer()
+  const credentialsService = container.resolve('integrationCredentialsService') as TillioCredentialsService
+  const em = container.resolve('em') as EntityManager
+  const scope: IntegrationScope = { organizationId: auth.orgId, tenantId: auth.tenantId }
+
+  const environment = await resolveEnvironment(credentialsService, scope)
+  const integrationState = await readTillioIntegrationState(em, scope)
+  const { ready: environmentReady, blocker: environmentBlocker } = evaluateEnvironmentReadiness({
+    environment,
+    integrationEnabled: integrationState.enabled,
+    environmentHealthy: integrationState.healthy,
+  })
+  const blob = await readOperatorsBlob(credentialsService, scope)
+  const currentFingerprint = environment ? computeEnvFingerprint(environment) : null
+
+  const operators = blob.operators.map((operator) => ({
+    id: operator.id,
+    plugin: operator.plugin,
+    tenantDomain: operator.tenantDomain,
+    stale: currentFingerprint ? operator.envFingerprint !== currentFingerprint : true,
+  }))
+
+  return NextResponse.json({
+    ok: true,
+    environmentReady,
+    environmentBlocker,
+    tenantSystemId: environment?.tenantSystemId ?? null,
+    supportedPlugins: SUPPORTED_PLUGINS,
+    operators,
+    defaultOperatorId: blob.defaultOperatorId,
+    envDrift: operators.some((operator) => operator.stale),
+  })
+}
+
+export async function POST(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.tenantId || !auth.orgId) {
+    return NextResponse.json({ ok: false, code: 'unauthorized', message: 'Unauthorized' }, { status: 401 })
+  }
+
+  const parsedBody = attachBodySchema.safeParse(await readJsonSafe(req))
+  if (!parsedBody.success) {
+    return NextResponse.json({ ok: false, code: 'invalid_payload', message: 'Invalid operator payload' }, { status: 400 })
+  }
+
+  const container = await createRequestContainer()
+  const credentialsService = container.resolve('integrationCredentialsService') as TillioCredentialsService
+  const em = container.resolve('em') as EntityManager
+  const scope: IntegrationScope = { organizationId: auth.orgId, tenantId: auth.tenantId }
+
+  const environment = await resolveEnvironment(credentialsService, scope)
+  const integrationState = await readTillioIntegrationState(em, scope)
+  // Provisioning an operator registers a config on Tillio's side, so the environment is checked
+  // here rather than left to the pull to discover. The decision is the shared one; only the
+  // wording is specific to attaching.
+  const { blocker } = evaluateEnvironmentReadiness({
+    environment,
+    integrationEnabled: integrationState.enabled,
+    environmentHealthy: integrationState.healthy,
+  })
+  if (blocker) {
+    return NextResponse.json(
+      { ok: false, code: blocker, section: 'environment', message: ATTACH_BLOCKER_MESSAGES[blocker] },
+      { status: 409 },
+    )
+  }
+
+  const appUrl = process.env.APP_URL ?? ''
+  if (!appUrl.trim()) {
+    return NextResponse.json(
+      { ok: false, code: 'app_url_missing', section: 'environment', message: 'APP_URL is not configured; it is required to derive the operator webhook domain.' },
+      { status: 500 },
+    )
+  }
+
+  const guarded = await runRouteMutationGuards({
+    container,
+    req,
+    auth: { userId: auth.sub, tenantId: auth.tenantId, organizationId: auth.orgId },
+    input: {
+      resourceKind: TILLIO_OPERATOR_RESOURCE_KIND,
+      operation: 'create',
+      // The operator key is a credential, so it is described to guards, never handed to them.
+      mutationPayload: { plugin: parsedBody.data.plugin, label: parsedBody.data.label ?? null },
+    },
+  })
+  if (!guarded.ok) return guarded.response
+
+  const guardedLabel = typeof guarded.modifiedPayload?.label === 'string'
+    ? guarded.modifiedPayload.label
+    : parsedBody.data.label
+
+  try {
+    const operator = await attachOperator(
+      { credentialsService, scope, appUrl, withLock: createTillioLock(em, tillioOperatorLockKey(scope)) },
+      { plugin: parsedBody.data.plugin, config: parsedBody.data.config, label: guardedLabel },
+    )
+    await guarded.runAfterSuccess()
+    return NextResponse.json({
+      ok: true,
+      operator: { id: operator.id, plugin: operator.plugin, tenantDomain: operator.tenantDomain },
+    })
+  } catch (err) {
+    if (err instanceof TillioOperatorLimitError) {
+      return NextResponse.json({ ok: false, code: 'operator_limit', section: 'operator', message: err.message }, { status: 409 })
+    }
+    if (err instanceof TillioEnvironmentNotReadyError) {
+      return NextResponse.json({ ok: false, code: 'environment_not_ready', section: 'environment', message: err.message }, { status: 409 })
+    }
+    if (err instanceof TillioApiError) {
+      const section = classifyTillioError(err)
+      logger.error('Tillio operator attach failed at provider', {
+        section,
+        status: err.status,
+        detail: err.detail,
+        err,
+      })
+      return NextResponse.json(
+        {
+          ok: false,
+          code: 'provider_error',
+          section,
+          message: tillioErrorCopy('provider_error', 'provider_error').fallback,
+        },
+        { status: section === 'environment' ? 502 : 422 },
+      )
+    }
+    return NextResponse.json({ ok: false, code: 'attach_failed', section: 'operator', message: 'Failed to attach the operator.' }, { status: 500 })
+  }
+}

package/src/modules/tillio/api/pull/route.ts

@@ -0,0 +1,213 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { runRouteMutationGuards } from '@open-mercato/shared/lib/crud/route-mutation-guard'
+import type { IntegrationScope } from '@open-mercato/shared/modules/integrations/types'
+import type { ProgressService } from '@open-mercato/core/modules/progress/lib/progressService'
+import { PHONE_CALL_RESOURCE_KIND } from '@open-mercato/shared/modules/phone_calls/types'
+import { TILLIO_PROVIDER_KEY } from '../../integration'
+import {
+  resolvePullContext,
+  TILLIO_PULL_JOB_TYPE,
+  type TillioPullJobPayload,
+} from '../../lib/pull-job'
+import type { TillioCredentialsService } from '../../lib/operators-store'
+import { blockerSection, PULL_BLOCKER_MESSAGES } from '../../lib/pull-readiness'
+import { getTillioQueue, TILLIO_PULL_QUEUE } from '../../lib/queue'
+import { createTillioLock, tillioPullLockKey } from '../../lib/locking'
+
+const logger = createLogger('tillio').child({ component: 'pull-route' })
+
+const daySchema = z.iso.date()
+
+export const pullBodySchema = z
+  .object({
+    from: daySchema,
+    to: daySchema,
+    cursor: z.string().trim().min(1).optional(),
+    limit: z.number().int().positive().max(1000).optional(),
+  })
+  .refine((body) => body.from <= body.to, { message: 'The start day must not be after the end day.' })
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['phone_calls.manage', 'integrations.manage'] },
+  POST: { requireAuth: true, requireFeatures: ['phone_calls.manage', 'integrations.manage'] },
+}
+
+export const openApi = {
+  GET: {
+    tags: ['Tillio'],
+    summary: 'Report whether Tillio is ready to pull phone calls',
+  },
+  POST: {
+    tags: ['Tillio'],
+    summary: 'Queue a Tillio phone-call pull and return its progress job id',
+    responses: [
+      { status: 202, description: 'Pull queued; returns { progressJobId }' },
+      { status: 400, description: 'Invalid day range' },
+      { status: 401, description: 'Unauthorized' },
+      { status: 409, description: 'Tillio is not ready to pull (environment or operator blocker)' },
+      { status: 429, description: 'A pull is already running for this scope' },
+    ],
+  },
+}
+
+export async function GET(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.tenantId || !auth.orgId) {
+    return NextResponse.json({ ok: false, code: 'unauthorized', message: 'Unauthorized' }, { status: 401 })
+  }
+
+  const container = await createRequestContainer()
+  const credentialsService = container.resolve('integrationCredentialsService') as TillioCredentialsService
+  const em = container.resolve('em') as EntityManager
+  const scope: IntegrationScope = { organizationId: auth.orgId, tenantId: auth.tenantId }
+
+  const { readiness, environment, operator } = await resolvePullContext(credentialsService, em, scope)
+
+  return NextResponse.json({
+    ok: true,
+    ...readiness,
+    // The dialog states which zone the picked days are read in, and that zone is per
+    // environment, so it comes from here rather than from a string baked into the widget.
+    timeZone: environment?.timeZone ?? null,
+    operatorId: operator?.id ?? null,
+    plugin: operator?.plugin ?? null,
+  })
+}
+
+export async function POST(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.tenantId || !auth.orgId) {
+    return NextResponse.json({ ok: false, code: 'unauthorized', message: 'Unauthorized' }, { status: 401 })
+  }
+
+  const parsedBody = pullBodySchema.safeParse(await readJsonSafe(req))
+  if (!parsedBody.success) {
+    return NextResponse.json({ ok: false, code: 'invalid_payload', message: 'Invalid pull payload' }, { status: 400 })
+  }
+  const body = parsedBody.data
+
+  const container = await createRequestContainer()
+  const credentialsService = container.resolve('integrationCredentialsService') as TillioCredentialsService
+  const progressService = container.resolve('progressService') as ProgressService
+  const em = container.resolve('em') as EntityManager
+  const scope: IntegrationScope = { organizationId: auth.orgId, tenantId: auth.tenantId }
+  const progressContext = {
+    tenantId: auth.tenantId,
+    organizationId: auth.orgId,
+    userId: auth.sub ?? null,
+  }
+
+  // Checked here as well as in the worker so an unconfigured provider answers immediately
+  // instead of parking a job that can only fail.
+  const { readiness } = await resolvePullContext(credentialsService, em, scope)
+  if (readiness.blocker) {
+    return NextResponse.json(
+      {
+        ok: false,
+        code: readiness.blocker,
+        section: blockerSection(readiness.blocker),
+        message: PULL_BLOCKER_MESSAGES[readiness.blocker],
+      },
+      { status: 409 },
+    )
+  }
+
+  const guarded = await runRouteMutationGuards({
+    container,
+    req,
+    auth: {
+      userId: auth.sub,
+      tenantId: auth.tenantId,
+      organizationId: auth.orgId,
+    },
+    input: {
+      resourceKind: PHONE_CALL_RESOURCE_KIND,
+      operation: 'custom',
+      mutationPayload: { providerKey: TILLIO_PROVIDER_KEY, from: body.from, to: body.to },
+    },
+  })
+  if (!guarded.ok) return guarded.response
+
+  // A guard may narrow the window it was shown, so the job runs on what the guard returned
+  // rather than on what the caller asked for. The rewrite comes from another module, so it
+  // goes back through the same schema before it reaches the queue.
+  const guardedBody = pullBodySchema.safeParse({
+    ...body,
+    ...(typeof guarded.modifiedPayload?.from === 'string' ? { from: guarded.modifiedPayload.from } : {}),
+    ...(typeof guarded.modifiedPayload?.to === 'string' ? { to: guarded.modifiedPayload.to } : {}),
+  })
+  if (!guardedBody.success) {
+    return NextResponse.json(
+      { ok: false, code: 'invalid_payload', message: 'A guard rewrote the pull range into an invalid one' },
+      { status: 400 },
+    )
+  }
+  const range = guardedBody.data
+
+  // The 429 below is a documented contract, so the check and the create happen under a lock
+  // rather than merely close together. Two requests arriving at once would otherwise both see
+  // no active job and both sweep the provider.
+  const withLock = createTillioLock(em, tillioPullLockKey(scope))
+
+  return withLock(async () => {
+    const active = await progressService.getActiveJobs(progressContext)
+    if (active.some((job) => job.jobType === TILLIO_PULL_JOB_TYPE)) {
+      return NextResponse.json(
+        { ok: false, code: 'pull_already_running', section: 'operator', message: 'A Tillio pull is already running.' },
+        { status: 429 },
+      )
+    }
+
+    const progressJob = await progressService.createJob(
+      {
+        jobType: TILLIO_PULL_JOB_TYPE,
+        name: 'Pull calls from Tillio',
+        description: `Pulling Tillio calls from ${range.from} to ${range.to}`,
+        cancellable: true,
+        meta: {
+          resourceKind: PHONE_CALL_RESOURCE_KIND,
+          providerKey: TILLIO_PROVIDER_KEY,
+          from: range.from,
+          to: range.to,
+        },
+      },
+      progressContext,
+    )
+
+    const payload: TillioPullJobPayload = {
+      progressJobId: progressJob.id,
+      scope: { tenantId: scope.tenantId, organizationId: scope.organizationId, userId: auth.sub ?? null },
+      from: range.from,
+      to: range.to,
+      cursor: range.cursor ?? null,
+      limit: range.limit ?? null,
+    }
+    try {
+      await getTillioQueue(TILLIO_PULL_QUEUE).enqueue(payload as unknown as Record<string, unknown>)
+    } catch (err) {
+      // The job row exists but nothing will ever advance it, and the active-job check above
+      // would answer 429 to every later pull until the stale sweep clears it. One unreachable
+      // queue would lock the tenant out of pulling.
+      logger.error('could not enqueue the Tillio pull', { progressJobId: progressJob.id, err })
+      await progressService
+        .failJob(progressJob.id, { errorMessage: 'The pull could not be handed to the queue.' }, progressContext)
+        .catch((failErr: unknown) => {
+          logger.error('could not fail the orphaned pull job', { progressJobId: progressJob.id, err: failErr })
+        })
+      return NextResponse.json(
+        { ok: false, code: 'pull_failed', section: 'operator', message: 'Could not queue the Tillio pull.' },
+        { status: 500 },
+      )
+    }
+
+    await guarded.runAfterSuccess()
+
+    return NextResponse.json({ ok: true, progressJobId: progressJob.id }, { status: 202 })
+  })
+}

package/src/modules/tillio/cli.ts

@@ -0,0 +1,125 @@
+import { createInterface } from 'node:readline'
+import type { ModuleCli } from '@open-mercato/shared/modules/registry'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { applyTillioEnvPreset, TILLIO_ENV_VARS } from './lib/preset'
+import { createTillioLock, tillioOperatorLockKey } from './lib/locking'
+import type { TillioCredentialsService, TillioOperatorRecord } from './lib/operators-store'
+
+const USAGE = [
+  'Usage: yarn mercato tillio configure-from-env --tenant <tenantId> --org <organizationId> [--force]',
+  `Required env: ${TILLIO_ENV_VARS.apiUrl}, ${TILLIO_ENV_VARS.apiKey}`,
+  `Optional env: ${TILLIO_ENV_VARS.ringostatKey} (attaches the operator), ${TILLIO_ENV_VARS.force} (overwrites existing credentials), ${TILLIO_ENV_VARS.replaceOperator} (answers the replacement prompt for unattended runs)`,
+].join('\n')
+
+async function confirmOperatorReplacement(operator: TillioOperatorRecord): Promise<boolean> {
+  if (!process.stdin.isTTY) return false
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    console.log(`[tillio] The environment variables point at a different Tillio instance than the stored ones.`)
+    console.log(`[tillio] Operator ${operator.id} (${operator.plugin}) is attached to the current one and will be revoked before the switch.`)
+    const answer = await new Promise<string>((resolve) => {
+      rl.question('[tillio] Detach it and attach a new one from env? [y/N] ', (value) => resolve(value.trim().toLowerCase()))
+    })
+    return answer === 'y' || answer === 'yes'
+  } finally {
+    rl.close()
+  }
+}
+
+function parseArgs(rest: string[]): Record<string, string | boolean> {
+  const args: Record<string, string | boolean> = {}
+
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index]
+    if (!arg || !arg.startsWith('--')) continue
+
+    const [key, inlineValue] = arg.replace(/^--/, '').split('=')
+    if (inlineValue !== undefined) {
+      args[key] = inlineValue
+      continue
+    }
+
+    const next = rest[index + 1]
+    if (next && !next.startsWith('--')) {
+      args[key] = next
+      index += 1
+      continue
+    }
+
+    args[key] = true
+  }
+
+  return args
+}
+
+function readScopeArg(args: Record<string, string | boolean>, keys: string[]): string | null {
+  for (const key of keys) {
+    const value = args[key]
+    if (typeof value === 'string' && value.trim()) return value.trim()
+  }
+  return null
+}
+
+const configureFromEnv: ModuleCli = {
+  command: 'configure-from-env',
+  async run(rest) {
+    const args = parseArgs(rest)
+    const tenantId = readScopeArg(args, ['tenantId', 'tenant'])
+    const organizationId = readScopeArg(args, ['organizationId', 'orgId', 'org'])
+    const force = args.force === true
+
+    if (!tenantId || !organizationId) {
+      console.log(USAGE)
+      process.exitCode = 1
+      return
+    }
+
+    const container = await createRequestContainer()
+    try {
+      console.log(`[tillio] Configuring tenant ${tenantId}, organization ${organizationId}${force ? ' (force)' : ''}.`)
+
+      const result = await applyTillioEnvPreset({
+        credentialsService: container.resolve('integrationCredentialsService') as TillioCredentialsService,
+        integrationStateService: container.resolve('integrationStateService'),
+        integrationHealthService: container.resolve('integrationHealthService'),
+        integrationLogService: container.resolve('integrationLogService'),
+        scope: { tenantId, organizationId },
+        force,
+        confirmOperatorReplacement,
+        withLock: createTillioLock(
+          container.resolve('em') as EntityManager,
+          tillioOperatorLockKey({ tenantId, organizationId }),
+        ),
+      })
+
+      if (result.status === 'skipped') {
+        console.log(`[tillio] Skipped: ${result.reason}`)
+        return
+      }
+      if (result.status === 'blocked') {
+        console.error(`[tillio] Blocked: ${result.reason}`)
+        process.exitCode = 1
+        return
+      }
+
+      console.log(`[tillio] Credentials ${result.credentialsAction}, health check reported ${result.health}, operator ${result.operator}.`)
+      if (result.health !== 'healthy') {
+        console.log('[tillio] Fix the environment, then rerun this command to finish provisioning.')
+      } else if (result.operator === 'not-requested') {
+        console.log(`[tillio] Set ${TILLIO_ENV_VARS.ringostatKey} and rerun to attach the operator, or attach it in the UI.`)
+      }
+    } catch (error) {
+      console.error(`[tillio] ${error instanceof Error ? error.message : 'Failed to apply the env preset'}`)
+      process.exitCode = 1
+    } finally {
+      const disposable = container as unknown as { dispose?: () => Promise<void> }
+      if (typeof disposable.dispose === 'function') await disposable.dispose()
+    }
+  },
+}
+
+const commands: ModuleCli[] = [configureFromEnv]
+
+export default commands

package/src/modules/tillio/di.ts

@@ -0,0 +1,16 @@
+import { asFunction } from 'awilix'
+import type { AppContainer } from '@open-mercato/shared/lib/di/container'
+import { registerPhoneCallProvider } from '@open-mercato/shared/modules/phone_calls/provider'
+import { tillioAdapter } from './lib/adapter'
+import { createTillioEnvironmentHealthCheck, type CredentialsServiceLike } from './lib/health'
+
+export function register(container: AppContainer) {
+  registerPhoneCallProvider(tillioAdapter)
+
+  container.register({
+    tillioEnvironmentHealthCheck: asFunction(
+      ({ integrationCredentialsService }: { integrationCredentialsService: CredentialsServiceLike }) =>
+        createTillioEnvironmentHealthCheck({ credentialsService: integrationCredentialsService }),
+    ).scoped().proxy(),
+  })
+}