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

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@open-mercato/tillio",
+  "version": "0.7.1-develop.7176.1.d229567a50",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "node build.mjs",
+    "test": "jest --config jest.config.cjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./*.ts": {
+      "types": "./src/*.ts",
+      "default": "./dist/*.js"
+    },
+    "./*.tsx": {
+      "types": "./src/*.tsx",
+      "default": "./dist/*.js"
+    },
+    "./*.json": "./src/*.json",
+    "./*": {
+      "types": [
+        "./src/*.ts",
+        "./src/*.tsx"
+      ],
+      "default": "./dist/*.js"
+    },
+    "./*/*.json": "./src/*/*.json",
+    "./*/*": {
+      "types": [
+        "./src/*/*.ts",
+        "./src/*/*.tsx"
+      ],
+      "default": "./dist/*/*.js"
+    },
+    "./*/*/*.json": "./src/*/*/*.json",
+    "./*/*/*": {
+      "types": [
+        "./src/*/*/*.ts",
+        "./src/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*.js"
+    },
+    "./*/*/*/*.json": "./src/*/*/*/*.json",
+    "./*/*/*/*": {
+      "types": [
+        "./src/*/*/*/*.ts",
+        "./src/*/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*/*.js"
+    }
+  },
+  "dependencies": {
+    "@open-mercato/core": "0.7.1-develop.7176.1.d229567a50",
+    "@open-mercato/queue": "0.7.1-develop.7176.1.d229567a50",
+    "@open-mercato/ui": "0.7.1-develop.7176.1.d229567a50"
+  },
+  "peerDependencies": {
+    "@mikro-orm/postgresql": "^7.0.14",
+    "@open-mercato/ai-assistant": "0.7.1-develop.7176.1.d229567a50",
+    "@open-mercato/shared": "0.7.1-develop.7176.1.d229567a50",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-is": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@open-mercato/ai-assistant": "0.7.1-develop.7176.1.d229567a50",
+    "@open-mercato/shared": "0.7.1-develop.7176.1.d229567a50",
+    "@types/jest": "^30.0.0",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.5",
+    "esbuild": "^0.28.1",
+    "glob": "^13.0.6",
+    "jest": "^30.4.2",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "react-is": "^19.2.8",
+    "ts-jest": "^29.4.11",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/open-mercato/open-mercato",
+    "directory": "packages/tillio"
+  },
+  "stableVersion": "0.7.0"
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { metadata } from './modules/tillio/index'

package/src/modules/tillio/__integration__/TC-PHONE-001-pull-readiness.spec.ts

@@ -0,0 +1,38 @@
+import { expect, test } from '@playwright/test'
+import { apiRequest, getAuthToken } from '@open-mercato/core/helpers/integration/api'
+import { readJsonSafe } from '@open-mercato/core/helpers/integration/generalFixtures'
+
+type ReadinessBody = {
+  ok?: boolean
+  environmentReady?: boolean
+  operatorAttached?: boolean
+  envDrift?: boolean
+  blocker?: string | null
+  operatorId?: string | null
+  plugin?: string | null
+}
+
+/**
+ * TC-PHONE-001 — the pull readiness probe reports an unconfigured Tillio environment.
+ *
+ * GET /api/tillio/pull only reads config out of the database; it never calls Tillio.
+ * On a fresh environment no Tillio credentials exist, so readiness must report the
+ * `environment_not_ready` blocker rather than erroring. This asserts the module's own
+ * readiness contract — the blocker precedence rules themselves are unit-tested in
+ * packages/tillio/src/modules/tillio/__tests__/pull-readiness.test.ts.
+ */
+test.describe('TC-PHONE-001: Tillio pull readiness', () => {
+  test('reports environment_not_ready when Tillio is not configured', async ({ request }) => {
+    const token = await getAuthToken(request, 'superadmin')
+    const response = await apiRequest(request, 'GET', '/api/tillio/pull', { token })
+
+    expect(response.status(), 'the readiness probe should be reachable').toBe(200)
+
+    const body = await readJsonSafe<ReadinessBody>(response)
+    expect(body?.ok, 'readiness responds ok even when blocked').toBe(true)
+    expect(body?.environmentReady, 'no Tillio credentials means the environment is not ready').toBe(false)
+    expect(body?.operatorAttached, 'no operator can be attached without an environment').toBe(false)
+    expect(body?.blocker, 'the environment blocker should be reported').toBe('environment_not_ready')
+    expect(body?.operatorId, 'no operator id without an operator').toBeNull()
+  })
+})

package/src/modules/tillio/__integration__/TC-PHONE-002-pull-blocked.spec.ts

@@ -0,0 +1,44 @@
+import { expect, test } from '@playwright/test'
+import { apiRequest, getAuthToken } from '@open-mercato/core/helpers/integration/api'
+import { readJsonSafe } from '@open-mercato/core/helpers/integration/generalFixtures'
+
+type BlockedBody = { ok?: boolean; code?: string; section?: string; message?: string }
+
+/**
+ * TC-PHONE-002 — the pull refuses to run before Tillio is configured.
+ *
+ * The readiness gate returns 409 before `tillioAdapter.fetchCalls` is ever reached, so
+ * this exercises the real POST path without any network traffic to Tillio and without
+ * ingesting anything. That ordering is the point of the test: a regression that moved
+ * the gate below the fetch would turn an unconfigured tenant into a live provider call.
+ *
+ * A pull against a real Tillio environment needs Ringostat credentials and is therefore
+ * a deliberate manual check, not an automated one.
+ */
+test.describe('TC-PHONE-002: Tillio pull blocked before reaching the provider', () => {
+  test('returns a structured 409 when the environment is not configured', async ({ request }) => {
+    const token = await getAuthToken(request, 'superadmin')
+    const response = await apiRequest(request, 'POST', '/api/tillio/pull', {
+      token,
+      data: { from: '2026-03-01', to: '2026-03-02' },
+    })
+
+    expect(response.status(), 'an unconfigured environment must block the pull').toBe(409)
+
+    const body = await readJsonSafe<BlockedBody>(response)
+    expect(body?.ok).toBe(false)
+    expect(body?.code, 'the blocker code drives which settings section the UI opens').toBe('environment_not_ready')
+    expect(body?.section, 'environment blockers route to the environment section').toBe('environment')
+    expect(body?.message, 'the blocker carries an actionable message').toBeTruthy()
+  })
+
+  test('rejects a reversed day range before touching readiness', async ({ request }) => {
+    const token = await getAuthToken(request, 'superadmin')
+    const response = await apiRequest(request, 'POST', '/api/tillio/pull', {
+      token,
+      data: { from: '2026-03-02', to: '2026-03-01' },
+    })
+
+    expect(response.status(), 'from must not be after to').toBe(400)
+  })
+})

package/src/modules/tillio/__integration__/TC-PHONE-003-operators.spec.ts

@@ -0,0 +1,76 @@
+import { expect, test } from '@playwright/test'
+import { apiRequest, getAuthToken } from '@open-mercato/core/helpers/integration/api'
+import { readJsonSafe } from '@open-mercato/core/helpers/integration/generalFixtures'
+
+type OperatorsBody = {
+  ok?: boolean
+  environmentReady?: boolean
+  tenantSystemId?: string | null
+  supportedPlugins?: string[]
+  operators?: Array<{ id?: string; plugin?: string; stale?: boolean }>
+  defaultOperatorId?: string | null
+  envDrift?: boolean
+}
+type BlockedBody = { ok?: boolean; code?: string; section?: string; message?: string }
+
+/**
+ * TC-PHONE-003 — the operator routes answer correctly before Tillio is configured.
+ *
+ * Attaching a real operator calls Tillio (`addConfig`) and needs a Ringostat key, so the
+ * live path stays a manual check. Everything asserted here stops before the network:
+ * the listing reads credentials out of the database, the attach is refused by the
+ * environment gate ahead of `attachOperator`, and detaching an unknown id returns early
+ * without resolving an environment at all.
+ */
+test.describe('TC-PHONE-003: Tillio operators', () => {
+  test('lists an empty operator set on an unconfigured environment', async ({ request }) => {
+    const token = await getAuthToken(request, 'superadmin')
+    const response = await apiRequest(request, 'GET', '/api/tillio/operators', { token })
+
+    expect(response.status(), 'the operator listing should be reachable').toBe(200)
+
+    const body = await readJsonSafe<OperatorsBody>(response)
+    expect(body?.ok).toBe(true)
+    expect(body?.environmentReady, 'no credentials means the environment is not ready').toBe(false)
+    expect(body?.operators, 'no operators can exist without an environment').toEqual([])
+    expect(body?.defaultOperatorId).toBeNull()
+    expect(body?.tenantSystemId).toBeNull()
+    expect(body?.envDrift, 'drift is meaningless with no operators attached').toBe(false)
+    expect(body?.supportedPlugins, 'the UI builds its plugin picker from this list').toEqual(['Ringostat'])
+  })
+
+  test('refuses to attach an operator before the environment is healthy', async ({ request }) => {
+    const token = await getAuthToken(request, 'superadmin')
+    const response = await apiRequest(request, 'POST', '/api/tillio/operators', {
+      token,
+      data: { plugin: 'Ringostat', config: { key: 'qa-tillio-003-never-used' } },
+    })
+
+    expect(response.status(), 'attaching must be gated on a healthy environment').toBe(409)
+
+    const body = await readJsonSafe<BlockedBody>(response)
+    expect(body?.ok).toBe(false)
+    expect(body?.code).toBe('environment_not_ready')
+    expect(body?.section, 'the blocker routes the UI to the environment section').toBe('environment')
+  })
+
+  test('rejects an unsupported plugin', async ({ request }) => {
+    const token = await getAuthToken(request, 'superadmin')
+    const response = await apiRequest(request, 'POST', '/api/tillio/operators', {
+      token,
+      data: { plugin: 'Twilio', config: { key: 'qa-tillio-003-never-used' } },
+    })
+
+    expect(response.status(), 'only Ringostat is a supported plugin today').toBe(400)
+  })
+
+  test('detaching an unknown operator reports that nothing was detached', async ({ request }) => {
+    const token = await getAuthToken(request, 'superadmin')
+    const response = await apiRequest(request, 'DELETE', '/api/tillio/operators/qa-tillio-003-missing', { token })
+
+    expect(response.status()).toBe(200)
+    const body = await readJsonSafe<{ ok?: boolean; detached?: boolean }>(response)
+    expect(body?.ok).toBe(true)
+    expect(body?.detached, 'an unknown id detaches nothing rather than erroring').toBe(false)
+  })
+})

package/src/modules/tillio/__integration__/TC-PHONE-004-pull-widget.spec.ts

@@ -0,0 +1,22 @@
+import { expect, test } from '@playwright/test'
+import { login } from '@open-mercato/core/helpers/integration/auth'
+
+/**
+ * TC-PHONE-004 — the Pull widget reaches the hub's call list toolbar.
+ *
+ * This module injects `tillio.injection.pull-calls` into `data-table:phone_calls.calls:toolbar`,
+ * a spot owned by phone_calls in another package. Nothing in either package fails to compile if
+ * that wiring breaks — the button simply stops rendering — so the injection is asserted here.
+ *
+ * It lives in the provider package on purpose: phone_calls must keep passing with tillio
+ * disabled, so its own page spec cannot assert a Tillio button.
+ */
+test.describe('TC-PHONE-004: Tillio pull widget injection', () => {
+  test('renders the pull action on the phone calls list', async ({ page }) => {
+    await login(page, 'admin')
+    await page.goto('/backend/phone_calls')
+
+    await expect(page.getByRole('heading', { name: 'Phone Calls' })).toBeVisible()
+    await expect(page.getByRole('button', { name: 'Pull calls' })).toBeVisible()
+  })
+})

package/src/modules/tillio/__integration__/TC-PHONE-005-operators-widget.spec.ts

@@ -0,0 +1,27 @@
+import { expect, test } from '@playwright/test'
+import { login } from '@open-mercato/core/helpers/integration/auth'
+
+/**
+ * TC-PHONE-005 — the operator configuration tab reaches the Tillio integration page.
+ *
+ * `tillio.injection.operators` is injected as a tab into this integration's detail spot,
+ * which the integrations module renders from the `IntegrationDefinition`. The registration
+ * chain (definition -> spot id -> injection table) has no compile-time link to the page, so
+ * a break would silently drop the tab.
+ *
+ * The page opens on Credentials, so the tab is activated before asserting its body. With no
+ * credentials stored the widget must guide the user to configure them instead of offering an
+ * operator form — that guidance is the state a fresh tenant actually sees.
+ */
+test.describe('TC-PHONE-005: Tillio operators widget injection', () => {
+  test('renders the operator configuration tab with not-ready guidance', async ({ page }) => {
+    await login(page, 'admin')
+    await page.goto('/backend/integrations/tillio')
+
+    await page.getByRole('tab', { name: 'Operator configuration' }).click()
+
+    await expect(
+      page.getByText('Save the Tillio API URL and key in the Credentials tab, then run the health Check before attaching an operator.'),
+    ).toBeVisible()
+  })
+})

package/src/modules/tillio/__tests__/adapter-fetch-calls.test.ts

@@ -0,0 +1,148 @@
+import { createTillioAdapter } from '../lib/adapter'
+
+const credentials = {
+  apiUrl: 'https://x.example.com',
+  apiKey: 'k',
+  tenantSystemId: 'OM-abc',
+  operator: {
+    id: 'ringostat-1',
+    plugin: 'Ringostat' as const,
+    token: 'tok',
+    tenantDomain: 'app.example.com/OM-abc-ringostat-1',
+  },
+}
+
+const scope = { organizationId: 'org', tenantId: 'ten' }
+
+function call(id: string) {
+  return { id, date: '2026-04-11T12:47:28+0200', type: 'IN', caller: '48111', destination: '48222', status: 'ANSWERED', billSec: '5' }
+}
+
+function page(calls: unknown[], pageNumber: number, pages: number): Response {
+  return new Response(
+    JSON.stringify({ calls, pagination: { total: String(calls.length * pages), page: String(pageNumber), pages: String(pages) } }),
+    { status: 200, headers: { 'content-type': 'application/json' } },
+  )
+}
+
+function queryOf(fetchCall: unknown[]): URLSearchParams {
+  return new URL(fetchCall[0] as string).searchParams
+}
+
+describe('tillioAdapter.fetchCalls', () => {
+  const fetchMock = jest.fn()
+  // The client now validates and DNS-pins every outbound URL, so the test injects both
+  // seams instead of stubbing the global fetch.
+  const tillioAdapter = createTillioAdapter({
+    fetchImpl: fetchMock as unknown as typeof fetch,
+    lookupHost: async () => [{ address: '93.184.216.34', family: 4 }],
+  })
+
+  beforeEach(() => {
+    fetchMock.mockReset()
+  })
+
+  it('walks every page reported by pagination and reports no cursor at the end', async () => {
+    fetchMock
+      .mockResolvedValueOnce(page([call('a')], 1, 3))
+      .mockResolvedValueOnce(page([call('b')], 2, 3))
+      .mockResolvedValueOnce(page([call('c')], 3, 3))
+
+    const batch = await tillioAdapter.fetchCalls({ credentials, scope })
+
+    expect(fetchMock).toHaveBeenCalledTimes(3)
+    expect(batch.calls.map((entry) => entry.externalCallId)).toEqual(['a', 'b', 'c'])
+    expect(batch.nextCursor).toBeNull()
+  })
+
+  it('sends the Warsaw wall-clock window and the operator token', async () => {
+    fetchMock.mockResolvedValue(page([call('a')], 1, 1))
+
+    await tillioAdapter.fetchCalls({
+      credentials,
+      scope,
+      from: new Date('2026-06-10T22:00:00.000Z'),
+      to: new Date('2026-06-11T21:59:00.000Z'),
+    })
+
+    const query = queryOf(fetchMock.mock.calls[0])
+    expect(query.get('from')).toBe('2026-06-11 00:00')
+    expect(query.get('to')).toBe('2026-06-11 23:59')
+    expect(query.get('page')).toBe('1')
+    const headers = (fetchMock.mock.calls[0][1] as RequestInit).headers as Record<string, string>
+    expect(headers['X-Token']).toBe('tok')
+    expect(headers['X-Tenant-Domain']).toBe('app.example.com/OM-abc-ringostat-1')
+  })
+
+  it('sends the window in the configured zone instead of the default one', async () => {
+    fetchMock.mockResolvedValue(page([call('a')], 1, 1))
+
+    await tillioAdapter.fetchCalls({
+      credentials: { ...credentials, timeZone: 'UTC' },
+      scope,
+      from: new Date('2026-06-10T22:00:00.000Z'),
+      to: new Date('2026-06-11T21:59:00.000Z'),
+    })
+
+    const query = queryOf(fetchMock.mock.calls[0])
+    expect(query.get('from')).toBe('2026-06-10 22:00')
+    expect(query.get('to')).toBe('2026-06-11 21:59')
+  })
+
+  it('stops at the batch limit but drains the current page first', async () => {
+    fetchMock
+      .mockResolvedValueOnce(page([call('a'), call('b')], 1, 4))
+      .mockResolvedValueOnce(page([call('c'), call('d')], 2, 4))
+
+    const batch = await tillioAdapter.fetchCalls({ credentials, scope, limit: 3 })
+
+    expect(fetchMock).toHaveBeenCalledTimes(2)
+    expect(batch.calls).toHaveLength(4)
+    expect(batch.nextCursor).toBe('3')
+  })
+
+  it('resumes from the cursor', async () => {
+    fetchMock.mockResolvedValueOnce(page([call('c')], 2, 2))
+
+    const batch = await tillioAdapter.fetchCalls({ credentials, scope, cursor: '2' })
+
+    expect(queryOf(fetchMock.mock.calls[0]).get('page')).toBe('2')
+    expect(batch.calls.map((entry) => entry.externalCallId)).toEqual(['c'])
+    expect(batch.nextCursor).toBeNull()
+  })
+
+  // These three exits used to be indistinguishable from reaching the last page, which let a
+  // provider that ignores `page` pass off one page as the whole range.
+  it('reports the anomaly when the server ignores the requested page', async () => {
+    fetchMock.mockResolvedValue(page([call('a')], 1, 5))
+
+    const batch = await tillioAdapter.fetchCalls({ credentials, scope, cursor: '3' })
+
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    expect(batch.calls).toHaveLength(1)
+    expect(batch.nextCursor).toBeNull()
+    expect(batch.anomaly).toBe('page_not_echoed')
+    expect(batch.anomalyCursor).toBe('3')
+  })
+
+  it('reports the anomaly on an empty page even when more pages are claimed', async () => {
+    fetchMock.mockResolvedValueOnce(page([], 1, 9))
+
+    const batch = await tillioAdapter.fetchCalls({ credentials, scope })
+
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    expect(batch.calls).toHaveLength(0)
+    expect(batch.nextCursor).toBeNull()
+    expect(batch.anomaly).toBe('empty_page')
+  })
+
+  it('reports the anomaly when pagination claims zero pages', async () => {
+    fetchMock.mockResolvedValueOnce(page([call('a')], 1, 0))
+
+    const batch = await tillioAdapter.fetchCalls({ credentials, scope })
+
+    expect(batch.anomaly).toBe('invalid_page_count')
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    expect(batch.nextCursor).toBeNull()
+  })
+})

package/src/modules/tillio/__tests__/client.test.ts

@@ -0,0 +1,203 @@
+import { createTillioClient, redactTillioUrl, type TillioClientDeps } from '../lib/client'
+
+const env = { apiUrl: 'https://x.example.com', apiKey: 'k', tenantSystemId: 'OM-abc' }
+
+const publicLookupHost: TillioClientDeps['lookupHost'] = async () => [{ address: '93.184.216.34', family: 4 }]
+
+function jsonResponse(body: unknown, status = 200, headers: Record<string, string> = {}): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json', ...headers },
+  })
+}
+
+function redirectResponse(status: number, location?: string): Response {
+  return new Response(null, {
+    status,
+    headers: location ? { location } : {},
+  })
+}
+
+function headersOf(call: unknown[]): Record<string, string> {
+  return (call[1] as RequestInit).headers as Record<string, string>
+}
+
+describe('createTillioClient', () => {
+  const fetchMock = jest.fn()
+
+  function client(deps: TillioClientDeps = {}) {
+    return createTillioClient(env, {
+      fetchImpl: fetchMock as unknown as typeof fetch,
+      lookupHost: publicLookupHost,
+      ...deps,
+    })
+  }
+
+  beforeEach(() => {
+    fetchMock.mockReset()
+  })
+
+  it('sends the environment identity headers on getPlugins', async () => {
+    fetchMock.mockResolvedValue(jsonResponse({ plugins: [] }))
+    await client().getPlugins('test_connection')
+    const [url] = fetchMock.mock.calls[0]
+    expect(url).toBe('https://x.example.com/api/plugins')
+    const headers = headersOf(fetchMock.mock.calls[0])
+    expect(headers['X-Api-Key']).toBe('k')
+    expect(headers['X-System']).toBe('OM-abc')
+    expect(headers['X-Tenant']).toBe('OM-abc')
+    expect(headers['X-Tenant-Domain']).toBe('test_connection')
+  })
+
+  it('throws TillioApiError on an error-in-200 body', async () => {
+    fetchMock.mockResolvedValue(jsonResponse({ error: 'unauthorized', message: 'Bad key' }))
+    await expect(client().getPlugins('test_connection')).rejects.toMatchObject({ name: 'TillioApiError', detail: 'unauthorized' })
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('retries on 503 then succeeds', async () => {
+    fetchMock
+      .mockResolvedValueOnce(jsonResponse({}, 503))
+      .mockResolvedValueOnce(jsonResponse({ plugins: [] }))
+    await client().getPlugins('test_connection')
+    expect(fetchMock).toHaveBeenCalledTimes(2)
+  })
+
+  it('fails fast on a network error without retrying', async () => {
+    fetchMock.mockRejectedValue(new Error('ECONNREFUSED'))
+    await expect(client().getPlugins('test_connection')).rejects.toMatchObject({ detail: 'network' })
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('addConfig posts plugin+config with the operator tenant-domain and returns the token', async () => {
+    fetchMock.mockResolvedValue(jsonResponse({ token: 'tok' }))
+    const res = await client().addConfig('Ringostat', { key: 'rk' }, 'x.example.com/OM-abc-ringostat')
+    const [url, init] = fetchMock.mock.calls[0]
+    expect(url).toBe('https://x.example.com/api/config')
+    expect(JSON.parse((init as RequestInit).body as string)).toEqual({ plugin: 'Ringostat', config: { key: 'rk' } })
+    expect(headersOf(fetchMock.mock.calls[0])['X-Tenant-Domain']).toBe('x.example.com/OM-abc-ringostat')
+    expect(res.token).toBe('tok')
+  })
+
+  describe('outbound URL safety', () => {
+    it('refuses to build a client for a private API URL', () => {
+      expect(() => createTillioClient({ ...env, apiUrl: 'http://169.254.169.254' })).toThrow()
+      expect(() => createTillioClient({ ...env, apiUrl: 'http://10.0.0.5' })).toThrow()
+      expect(() => createTillioClient({ ...env, apiUrl: 'http://localhost:9000' })).toThrow()
+    })
+
+    it('blocks a public hostname that resolves to a private address', async () => {
+      const lookupHost = jest.fn(async () => [{ address: '10.0.0.5', family: 4 }])
+      await expect(client({ lookupHost }).getPlugins('test_connection')).rejects.toMatchObject({
+        name: 'TillioApiError',
+        detail: 'private_ip_resolved',
+      })
+      expect(lookupHost).toHaveBeenCalledWith('x.example.com')
+      expect(fetchMock).not.toHaveBeenCalled()
+    })
+
+    it('revalidates DNS on every request, so a rebind between calls is caught', async () => {
+      fetchMock.mockResolvedValue(jsonResponse({ plugins: [] }))
+      const lookupHost = jest.fn()
+        .mockResolvedValueOnce([{ address: '93.184.216.34', family: 4 }])
+        .mockResolvedValueOnce([{ address: '127.0.0.1', family: 4 }])
+      const tillio = client({ lookupHost })
+
+      await tillio.getPlugins('test_connection')
+      await expect(tillio.getPlugins('test_connection')).rejects.toMatchObject({ detail: 'private_ip_resolved' })
+      expect(fetchMock).toHaveBeenCalledTimes(1)
+    })
+
+    it('follows a same-host redirect and revalidates the target', async () => {
+      const lookupHost = jest.fn(publicLookupHost)
+      fetchMock
+        .mockResolvedValueOnce(redirectResponse(302, 'https://x.example.com/api/plugins/v2'))
+        .mockResolvedValueOnce(jsonResponse({ plugins: [] }))
+
+      await client({ lookupHost }).getPlugins('test_connection')
+
+      expect(fetchMock.mock.calls[1][0]).toBe('https://x.example.com/api/plugins/v2')
+      expect(lookupHost).toHaveBeenCalledTimes(2)
+    })
+
+    it('refuses a redirect that leaves the configured host', async () => {
+      fetchMock.mockResolvedValueOnce(redirectResponse(302, 'https://attacker.example.net/api/plugins'))
+      await expect(client().getPlugins('test_connection')).rejects.toMatchObject({ detail: 'redirect' })
+      expect(fetchMock).toHaveBeenCalledTimes(1)
+    })
+
+    it('refuses a redirect pointing at a private address before it is followed', async () => {
+      const lookupHost = jest.fn(publicLookupHost)
+      fetchMock.mockResolvedValueOnce(redirectResponse(302, 'http://169.254.169.254/latest/meta-data'))
+
+      await expect(client({ lookupHost }).getPlugins('test_connection')).rejects.toMatchObject({ detail: 'redirect' })
+
+      // The target is never requested, and never even resolved.
+      expect(fetchMock).toHaveBeenCalledTimes(1)
+      expect(lookupHost).toHaveBeenCalledTimes(1)
+    })
+
+    it('refuses a same-host redirect once that host resolves to a private address', async () => {
+      fetchMock
+        .mockResolvedValueOnce(redirectResponse(302, 'https://x.example.com/api/plugins/v2'))
+        .mockResolvedValueOnce(jsonResponse({ plugins: [] }))
+      const lookupHost = jest.fn()
+        .mockResolvedValueOnce([{ address: '93.184.216.34', family: 4 }])
+        .mockResolvedValueOnce([{ address: '169.254.169.254', family: 4 }])
+
+      await expect(client({ lookupHost }).getPlugins('test_connection')).rejects.toMatchObject({
+        detail: 'private_ip_resolved',
+      })
+      expect(fetchMock).toHaveBeenCalledTimes(1)
+    })
+
+    it('refuses a redirect that downgrades https to http', async () => {
+      fetchMock.mockResolvedValueOnce(redirectResponse(301, 'http://x.example.com/api/plugins'))
+      await expect(client().getPlugins('test_connection')).rejects.toMatchObject({ detail: 'redirect' })
+    })
+
+    it('refuses a redirect without a Location header', async () => {
+      fetchMock.mockResolvedValueOnce(redirectResponse(302))
+      await expect(client().getPlugins('test_connection')).rejects.toMatchObject({ detail: 'redirect' })
+    })
+
+    it('stops after too many redirects', async () => {
+      fetchMock.mockResolvedValue(redirectResponse(302, 'https://x.example.com/api/loop'))
+      await expect(client().getPlugins('test_connection')).rejects.toMatchObject({ detail: 'redirect' })
+      expect(fetchMock).toHaveBeenCalledTimes(4)
+    })
+
+    it('drops the body when a 303 turns the request into a GET', async () => {
+      fetchMock
+        .mockResolvedValueOnce(redirectResponse(303, 'https://x.example.com/api/config/result'))
+        .mockResolvedValueOnce(jsonResponse({ token: 'tok' }))
+
+      await client().addConfig('Ringostat', { key: 'rk' }, 'x.example.com/OM-abc-ringostat')
+
+      const [, followUpInit] = fetchMock.mock.calls[1]
+      expect((followUpInit as RequestInit).method).toBe('GET')
+      expect((followUpInit as RequestInit).body).toBeUndefined()
+    })
+  })
+
+  describe('token redaction', () => {
+    it('keeps the token out of a network failure message', async () => {
+      fetchMock.mockRejectedValue(new Error('ECONNRESET'))
+      const promise = client().deleteConfig('Ringostat', 'super-secret-token', 'x.example.com/OM-abc-ringostat')
+      await expect(promise).rejects.toMatchObject({ detail: 'network' })
+      await expect(promise).rejects.toThrow(/token=\*\*\*/)
+      await expect(promise).rejects.not.toThrow(/super-secret-token/)
+    })
+
+    it('masks only the token parameter', () => {
+      expect(redactTillioUrl('https://x.example.com/api/config?plugin=Ringostat&token=abc')).toBe(
+        'https://x.example.com/api/config?plugin=Ringostat&token=***',
+      )
+      expect(redactTillioUrl('https://x.example.com/api/call?page=2')).toBe('https://x.example.com/api/call?page=2')
+    })
+
+    it('drops the whole query when the URL cannot be parsed', () => {
+      expect(redactTillioUrl('not a url?token=abc')).toBe('not a url')
+    })
+  })
+})