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

package/src/modules/tillio/__tests__/pull-job.test.ts

@@ -0,0 +1,250 @@
+import type { AwilixContainer } from 'awilix'
+import type { PhoneCallProviderAdapter } from '@open-mercato/shared/modules/phone_calls/provider'
+import type { NormalizedPhoneCall } from '@open-mercato/shared/modules/phone_calls/types'
+import { computeEnvFingerprint } from '../lib/operators-store'
+import { runTillioPullJob, type TillioPullJobPayload } from '../lib/pull-job'
+
+jest.mock('../lib/operators', () => ({
+  ...jest.requireActual('../lib/operators'),
+  resolveEnvironment: jest.fn(),
+  readTillioIntegrationState: jest.fn(),
+}))
+
+jest.mock('../lib/operators-store', () => ({
+  ...jest.requireActual('../lib/operators-store'),
+  readOperatorsBlob: jest.fn(),
+}))
+
+const { resolveEnvironment, readTillioIntegrationState } = jest.requireMock('../lib/operators')
+const { readOperatorsBlob } = jest.requireMock('../lib/operators-store')
+
+const environment = { apiUrl: 'https://api.example.com', apiKey: 'key', tenantSystemId: 'OM-1' }
+
+const operator = {
+  id: 'op-1',
+  plugin: 'Ringostat' as const,
+  token: 'tok-1',
+  tenantDomain: 'tenant.example.com',
+  envFingerprint: computeEnvFingerprint(environment),
+}
+
+const payload: TillioPullJobPayload = {
+  progressJobId: 'job-1',
+  scope: { tenantId: 'tn', organizationId: 'org', userId: 'user-1' },
+  from: '2026-08-01',
+  to: '2026-08-02',
+}
+
+function call(externalCallId: string): NormalizedPhoneCall {
+  return {
+    externalCallId,
+    direction: 'inbound',
+    status: 'completed',
+    participants: [],
+    rawPayload: {},
+    providerFacts: {},
+  } as unknown as NormalizedPhoneCall
+}
+
+function createProgressService(overrides: Partial<Record<string, jest.Mock>> = {}) {
+  return {
+    startJob: jest.fn().mockResolvedValue(undefined),
+    updateProgress: jest.fn().mockResolvedValue(undefined),
+    completeJob: jest.fn().mockResolvedValue(undefined),
+    failJob: jest.fn().mockResolvedValue(undefined),
+    markCancelled: jest.fn().mockResolvedValue(undefined),
+    isCancellationRequested: jest.fn().mockResolvedValue(false),
+    ...overrides,
+  }
+}
+
+function createContainer(services: Record<string, unknown>): AwilixContainer {
+  return { resolve: (name: string) => services[name] } as unknown as AwilixContainer
+}
+
+function createAdapter(pages: Array<{ calls: NormalizedPhoneCall[]; nextCursor: string | null }>) {
+  const fetchCalls = jest.fn(async () => pages.shift() ?? { calls: [], nextCursor: null })
+  return { fetchCalls } as unknown as PhoneCallProviderAdapter & { fetchCalls: jest.Mock }
+}
+
+beforeEach(() => {
+  resolveEnvironment.mockResolvedValue(environment)
+  readTillioIntegrationState.mockResolvedValue({ enabled: true, healthy: true })
+  readOperatorsBlob.mockResolvedValue({ operators: [operator], defaultOperatorId: operator.id })
+})
+
+describe('runTillioPullJob', () => {
+  it('follows the provider cursor to the last page and completes the job', async () => {
+    const progressService = createProgressService()
+    const commandBus = { execute: jest.fn().mockResolvedValue({ result: { created: true } }) }
+    const adapter = createAdapter([
+      { calls: [call('a'), call('b')], nextCursor: '2' },
+      { calls: [call('c')], nextCursor: null },
+    ])
+
+    const summary = await runTillioPullJob({
+      container: createContainer({
+        progressService,
+        commandBus,
+        em: {},
+        integrationCredentialsService: {},
+      }),
+      payload,
+      adapter,
+    })
+
+    expect(summary).toMatchObject({ fetched: 3, created: 3, updated: 0, failed: 0, batches: 2 })
+    expect(adapter.fetchCalls.mock.calls[0][0].cursor).toBeNull()
+    expect(adapter.fetchCalls.mock.calls[1][0].cursor).toBe('2')
+    expect(commandBus.execute).toHaveBeenCalledTimes(3)
+    expect(progressService.completeJob).toHaveBeenCalledWith(
+      'job-1',
+      { resultSummary: expect.objectContaining({ fetched: 3 }) },
+      expect.anything(),
+    )
+  })
+
+  it('keeps ingesting the batch after a single call fails', async () => {
+    const progressService = createProgressService()
+    const commandBus = {
+      execute: jest
+        .fn()
+        .mockResolvedValueOnce({ result: { created: true } })
+        .mockRejectedValueOnce(new Error('boom'))
+        .mockResolvedValueOnce({ result: { created: false } }),
+    }
+    const adapter = createAdapter([{ calls: [call('a'), call('b'), call('c')], nextCursor: null }])
+
+    const summary = await runTillioPullJob({
+      container: createContainer({
+        progressService,
+        commandBus,
+        em: {},
+        integrationCredentialsService: {},
+      }),
+      payload,
+      adapter,
+    })
+
+    expect(summary).toMatchObject({ fetched: 3, created: 1, updated: 1, failed: 1 })
+    expect(progressService.completeJob).toHaveBeenCalled()
+  })
+
+  it('stops before touching the provider when the job was cancelled', async () => {
+    const progressService = createProgressService({
+      isCancellationRequested: jest.fn().mockResolvedValue(true),
+    })
+    const adapter = createAdapter([{ calls: [call('a')], nextCursor: null }])
+
+    const summary = await runTillioPullJob({
+      container: createContainer({
+        progressService,
+        commandBus: { execute: jest.fn() },
+        em: {},
+        integrationCredentialsService: {},
+      }),
+      payload,
+      adapter,
+    })
+
+    expect(summary.cancelled).toBe(true)
+    expect(adapter.fetchCalls).not.toHaveBeenCalled()
+    expect(progressService.markCancelled).toHaveBeenCalledWith('job-1', expect.anything())
+    expect(progressService.completeJob).not.toHaveBeenCalled()
+  })
+
+  it('fails the job without pulling when the operator was detached while it waited', async () => {
+    readOperatorsBlob.mockResolvedValue({ operators: [], defaultOperatorId: null })
+    const progressService = createProgressService()
+    const adapter = createAdapter([{ calls: [call('a')], nextCursor: null }])
+
+    await runTillioPullJob({
+      container: createContainer({
+        progressService,
+        commandBus: { execute: jest.fn() },
+        em: {},
+        integrationCredentialsService: {},
+      }),
+      payload,
+      adapter,
+    })
+
+    expect(adapter.fetchCalls).not.toHaveBeenCalled()
+    expect(progressService.failJob).toHaveBeenCalledWith(
+      'job-1',
+      expect.objectContaining({ resultSummary: expect.objectContaining({ code: 'operator_missing' }) }),
+      expect.anything(),
+    )
+    // The bar prints errorMessage verbatim, so a bare code must never land there.
+    expect(progressService.failJob.mock.calls[0][1].errorMessage).not.toBe('operator_missing')
+  })
+
+  it('fails the job with the resume cursor when the batch cap ends the sweep', async () => {
+    const progressService = createProgressService()
+    const commandBus = { execute: jest.fn().mockResolvedValue({ result: { created: true } }) }
+    // Never stops advertising a next page, which is exactly what the cap exists for.
+    const adapter = {
+      fetchCalls: jest.fn(async (input: { cursor: string | null }) => ({
+        calls: [call(`c-${input.cursor ?? '1'}`)],
+        nextCursor: String(Number(input.cursor ?? '1') + 1),
+      })),
+    } as unknown as PhoneCallProviderAdapter & { fetchCalls: jest.Mock }
+
+    const summary = await runTillioPullJob({
+      container: createContainer({
+        progressService,
+        commandBus,
+        em: {},
+        integrationCredentialsService: {},
+      }),
+      payload,
+      adapter,
+    })
+
+    expect(summary.truncated).toBe(true)
+    expect(summary.resumeCursor).not.toBeNull()
+    expect(progressService.completeJob).not.toHaveBeenCalled()
+    expect(progressService.failJob).toHaveBeenCalledWith(
+      'job-1',
+      expect.objectContaining({
+        resultSummary: expect.objectContaining({ code: 'pull_truncated', truncated: true }),
+      }),
+      expect.anything(),
+    )
+  })
+
+  it('fails the job when the provider stops echoing the requested page', async () => {
+    const progressService = createProgressService()
+    const commandBus = { execute: jest.fn().mockResolvedValue({ result: { created: true } }) }
+    const adapter = {
+      fetchCalls: jest.fn(async () => ({
+        calls: [call('a')],
+        nextCursor: null,
+        anomaly: 'page_not_echoed' as const,
+        anomalyCursor: '3',
+      })),
+    } as unknown as PhoneCallProviderAdapter & { fetchCalls: jest.Mock }
+
+    const summary = await runTillioPullJob({
+      container: createContainer({
+        progressService,
+        commandBus,
+        em: {},
+        integrationCredentialsService: {},
+      }),
+      payload,
+      adapter,
+    })
+
+    expect(summary.truncated).toBe(true)
+    expect(summary.resumeCursor).toBe('3')
+    expect(progressService.completeJob).not.toHaveBeenCalled()
+    expect(progressService.failJob).toHaveBeenCalledWith(
+      'job-1',
+      expect.objectContaining({
+        resultSummary: expect.objectContaining({ code: 'pull_pagination_anomaly', anomaly: 'page_not_echoed' }),
+      }),
+      expect.anything(),
+    )
+  })
+})

package/src/modules/tillio/__tests__/pull-readiness.test.ts

@@ -0,0 +1,143 @@
+import { computeEnvFingerprint } from '../lib/operators-store'
+import { PULL_BLOCKER_COPY } from '../lib/error-codes'
+import { blockerSection, evaluateEnvironmentReadiness, evaluatePullReadiness, type PullBlocker } from '../lib/pull-readiness'
+import englishCatalog from '../i18n/en.json'
+
+const environment = { apiUrl: 'https://x.example.com', apiKey: 'k', tenantSystemId: 'OM-abc' }
+
+function operatorWith(envFingerprint: string) {
+  return {
+    id: 'ringostat-1',
+    plugin: 'Ringostat' as const,
+    config: { key: 'secret' },
+    token: 'tok',
+    tenantDomain: 'app.example.com/OM-abc-ringostat-1',
+    envFingerprint,
+  }
+}
+
+const attachedOperator = operatorWith(computeEnvFingerprint(environment))
+
+// The pull and the operator-attach route share this decision. It is asserted directly because a
+// second caller now depends on it, and because the `enabled` term used to be written out at each
+// call site, where one copy lost it.
+describe('evaluateEnvironmentReadiness', () => {
+  it.each([
+    ['nothing configured', null, false, false, 'environment_not_ready'],
+    ['configured but switched off', environment, false, true, 'integration_disabled'],
+    ['configured, on, never checked healthy', environment, true, false, 'environment_not_ready'],
+    ['configured, on and healthy', environment, true, true, null],
+  ] as const)('%s', (_name, env, integrationEnabled, environmentHealthy, expected) => {
+    const readiness = evaluateEnvironmentReadiness({ environment: env, integrationEnabled, environmentHealthy })
+    expect(readiness.blocker).toBe(expected)
+    expect(readiness.ready).toBe(expected === null)
+  })
+})
+
+describe('evaluatePullReadiness', () => {
+  it('clears the pull when the environment is healthy and an operator is attached', () => {
+    expect(
+      evaluatePullReadiness({ environment, integrationEnabled: true, environmentHealthy: true, operator: attachedOperator }),
+    ).toEqual({
+      environmentReady: true,
+      operatorAttached: true,
+      envDrift: false,
+      blocker: null,
+    })
+  })
+
+  it('blocks on a missing environment', () => {
+    const readiness = evaluatePullReadiness({ environment: null, integrationEnabled: true, environmentHealthy: false, operator: null })
+    expect(readiness.blocker).toBe('environment_not_ready')
+    expect(readiness.environmentReady).toBe(false)
+  })
+
+  it('blocks when the environment was never checked as healthy', () => {
+    const readiness = evaluatePullReadiness({ environment, integrationEnabled: true, environmentHealthy: false, operator: attachedOperator })
+    expect(readiness.blocker).toBe('environment_not_ready')
+  })
+
+  // A disabled integration passes every other check, so without its own blocker the UI would
+  // tell the user to re-run a health check that cannot change the outcome.
+  it('blocks a disabled integration even when everything else is ready', () => {
+    const readiness = evaluatePullReadiness({
+      environment,
+      integrationEnabled: false,
+      environmentHealthy: true,
+      operator: attachedOperator,
+    })
+    expect(readiness.blocker).toBe('integration_disabled')
+    expect(readiness.environmentReady).toBe(false)
+  })
+
+  // A fresh install has no integration row, and a missing row reads as disabled. Reporting that
+  // as the blocker would tell the user to enable an integration they have not configured yet,
+  // so the missing environment has to win while there is nothing to switch on.
+  it('reports the missing environment, not the switch, before anything is configured', () => {
+    const readiness = evaluatePullReadiness({
+      environment: null,
+      integrationEnabled: false,
+      environmentHealthy: false,
+      operator: null,
+    })
+    expect(readiness.blocker).toBe('environment_not_ready')
+    expect(readiness.environmentReady).toBe(false)
+  })
+
+  it('blocks when no operator is attached', () => {
+    const readiness = evaluatePullReadiness({ environment, integrationEnabled: true, environmentHealthy: true, operator: null })
+    expect(readiness.blocker).toBe('operator_missing')
+    expect(readiness.operatorAttached).toBe(false)
+  })
+
+  it('blocks when the environment drifted after the operator was attached', () => {
+    const readiness = evaluatePullReadiness({
+      environment,
+      integrationEnabled: true,
+      environmentHealthy: true,
+      operator: operatorWith('stale-fingerprint'),
+    })
+    expect(readiness.blocker).toBe('environment_drift')
+    expect(readiness.envDrift).toBe(true)
+  })
+
+  it('reports an unready environment before a missing operator', () => {
+    const readiness = evaluatePullReadiness({ environment: null, integrationEnabled: true, environmentHealthy: false, operator: null })
+    expect(readiness.blocker).toBe('environment_not_ready')
+  })
+
+  it('maps blockers to the section the UI highlights', () => {
+    expect(blockerSection('integration_disabled')).toBe('environment')
+    expect(blockerSection('environment_not_ready')).toBe('environment')
+    expect(blockerSection('operator_missing')).toBe('operator')
+    expect(blockerSection('environment_drift')).toBe('operator')
+  })
+})
+
+// The pull dialog once worded a switched-off integration as an unconfigured environment, so the
+// server told the user to enable the integration and the screen told them to enter credentials
+// they had already entered. Section mapping above was right; the copy was not.
+describe('PULL_BLOCKER_COPY', () => {
+  const blockers: PullBlocker[] = [
+    'integration_disabled',
+    'environment_not_ready',
+    'operator_missing',
+    'environment_drift',
+  ]
+
+  it('gives every blocker its own wording', () => {
+    const keys = blockers.map((blocker) => PULL_BLOCKER_COPY[blocker].key)
+    expect(new Set(keys).size).toBe(blockers.length)
+  })
+
+  it('words a disabled integration as a disabled integration', () => {
+    expect(PULL_BLOCKER_COPY.integration_disabled.key).toBe('tillio.errors.integrationDisabled')
+  })
+
+  it('ships an English string for every key it names', () => {
+    const catalog = englishCatalog as Record<string, string>
+    for (const blocker of blockers) {
+      expect(catalog[PULL_BLOCKER_COPY[blocker].key]).toBeTruthy()
+    }
+  })
+})

package/src/modules/tillio/__tests__/pull-route.test.ts

@@ -0,0 +1,148 @@
+import { POST } from '../api/pull/route'
+
+jest.mock('@open-mercato/shared/lib/auth/server', () => ({ getAuthFromRequest: jest.fn() }))
+jest.mock('@open-mercato/shared/lib/di/container', () => ({ createRequestContainer: jest.fn() }))
+jest.mock('@open-mercato/shared/lib/crud/route-mutation-guard', () => ({ runRouteMutationGuards: jest.fn() }))
+jest.mock('../lib/pull-job', () => ({
+  ...jest.requireActual('../lib/pull-job'),
+  resolvePullContext: jest.fn(),
+}))
+jest.mock('../lib/queue', () => ({
+  ...jest.requireActual('../lib/queue'),
+  getTillioQueue: jest.fn(),
+}))
+
+const { getAuthFromRequest } = jest.requireMock('@open-mercato/shared/lib/auth/server')
+const { createRequestContainer } = jest.requireMock('@open-mercato/shared/lib/di/container')
+const { runRouteMutationGuards } = jest.requireMock('@open-mercato/shared/lib/crud/route-mutation-guard')
+const { resolvePullContext } = jest.requireMock('../lib/pull-job')
+const { getTillioQueue } = jest.requireMock('../lib/queue')
+
+const auth = { sub: 'user-1', tenantId: 'tn', orgId: 'org' }
+
+function request(body: unknown): Request {
+  return new Request('http://localhost/api/tillio/pull', { method: 'POST', body: JSON.stringify(body) })
+}
+
+// The route takes an advisory lock inside a transaction; the stub keeps the section running
+// without a database, which is the only thing these cases need from it.
+function createEm() {
+  return {
+    transactional: async <T>(run: (tx: unknown) => Promise<T>): Promise<T> =>
+      run({ getConnection: () => ({ execute: async () => undefined }) }),
+  }
+}
+
+function createProgressService(overrides: Record<string, jest.Mock> = {}) {
+  return {
+    getActiveJobs: jest.fn().mockResolvedValue([]),
+    createJob: jest.fn().mockResolvedValue({ id: 'job-1' }),
+    failJob: jest.fn().mockResolvedValue(undefined),
+    ...overrides,
+  }
+}
+
+function wire(progressService: ReturnType<typeof createProgressService>) {
+  createRequestContainer.mockResolvedValue({
+    resolve: (name: string) => {
+      if (name === 'progressService') return progressService
+      if (name === 'em') return createEm()
+      return {}
+    },
+  })
+}
+
+beforeEach(() => {
+  jest.clearAllMocks()
+  getAuthFromRequest.mockResolvedValue(auth)
+  resolvePullContext.mockResolvedValue({ readiness: { blocker: null }, environment: {}, operator: {} })
+  runRouteMutationGuards.mockResolvedValue({ ok: true, runAfterSuccess: jest.fn().mockResolvedValue(undefined) })
+  getTillioQueue.mockReturnValue({ enqueue: jest.fn().mockResolvedValue(undefined) })
+})
+
+describe('POST /api/tillio/pull', () => {
+  it('queues the pull and answers 202 with the progress job id', async () => {
+    const progressService = createProgressService()
+    wire(progressService)
+    const enqueue = jest.fn().mockResolvedValue(undefined)
+    getTillioQueue.mockReturnValue({ enqueue })
+
+    const response = await POST(request({ from: '2026-08-01', to: '2026-08-02' }))
+
+    expect(response.status).toBe(202)
+    await expect(response.json()).resolves.toMatchObject({ ok: true, progressJobId: 'job-1' })
+    expect(enqueue).toHaveBeenCalledWith(expect.objectContaining({ from: '2026-08-01', to: '2026-08-02' }))
+  })
+
+  it('runs the pull on the range a guard rewrote, not the one the caller sent', async () => {
+    const progressService = createProgressService()
+    wire(progressService)
+    const enqueue = jest.fn().mockResolvedValue(undefined)
+    getTillioQueue.mockReturnValue({ enqueue })
+    runRouteMutationGuards.mockResolvedValue({
+      ok: true,
+      modifiedPayload: { to: '2026-08-01' },
+      runAfterSuccess: jest.fn().mockResolvedValue(undefined),
+    })
+
+    const response = await POST(request({ from: '2026-08-01', to: '2026-08-31' }))
+
+    expect(response.status).toBe(202)
+    expect(enqueue).toHaveBeenCalledWith(expect.objectContaining({ to: '2026-08-01' }))
+  })
+
+  it('returns the guard response and creates nothing when a guard blocks the pull', async () => {
+    const progressService = createProgressService()
+    wire(progressService)
+    runRouteMutationGuards.mockResolvedValue({
+      ok: false,
+      response: Response.json({ ok: false, error: 'blocked' }, { status: 422 }),
+    })
+
+    const response = await POST(request({ from: '2026-08-01', to: '2026-08-02' }))
+
+    expect(response.status).toBe(422)
+    expect(progressService.createJob).not.toHaveBeenCalled()
+  })
+
+  it('refuses a second pull while one is already running', async () => {
+    const progressService = createProgressService({
+      getActiveJobs: jest.fn().mockResolvedValue([{ jobType: 'tillio.calls.pull' }]),
+    })
+    wire(progressService)
+
+    const response = await POST(request({ from: '2026-08-01', to: '2026-08-02' }))
+
+    expect(response.status).toBe(429)
+    await expect(response.json()).resolves.toMatchObject({ code: 'pull_already_running' })
+    expect(progressService.createJob).not.toHaveBeenCalled()
+  })
+
+  it('fails the job it just created when the queue rejects the handover', async () => {
+    const progressService = createProgressService()
+    wire(progressService)
+    getTillioQueue.mockReturnValue({ enqueue: jest.fn().mockRejectedValue(new Error('queue down')) })
+
+    const response = await POST(request({ from: '2026-08-01', to: '2026-08-02' }))
+
+    expect(response.status).toBe(500)
+    // Left pending, the orphan would answer 429 to every later pull for this scope.
+    expect(progressService.failJob).toHaveBeenCalledWith('job-1', expect.anything(), expect.anything())
+  })
+
+  it('refuses to queue a pull for a disabled integration', async () => {
+    const progressService = createProgressService()
+    wire(progressService)
+    resolvePullContext.mockResolvedValue({
+      readiness: { blocker: 'integration_disabled' },
+      environment: {},
+      operator: {},
+    })
+
+    const response = await POST(request({ from: '2026-08-01', to: '2026-08-02' }))
+
+    expect(response.status).toBe(409)
+    await expect(response.json()).resolves.toMatchObject({ code: 'integration_disabled', section: 'environment' })
+    expect(progressService.createJob).not.toHaveBeenCalled()
+  })
+})

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

@@ -0,0 +1,53 @@
+import { formatTillioTimestamp, isValidTimeZone, zonedDayEnd, zonedDayStart } from '../lib/tz'
+
+describe('isValidTimeZone', () => {
+  it('accepts IANA zones and rejects anything Intl cannot resolve', () => {
+    expect(isValidTimeZone('Europe/Warsaw')).toBe(true)
+    expect(isValidTimeZone('America/New_York')).toBe(true)
+    expect(isValidTimeZone('UTC')).toBe(true)
+    // Intl resolves fixed-offset zones too, so they pass; only names it cannot resolve fail.
+    expect(isValidTimeZone('+02:00')).toBe(true)
+    expect(isValidTimeZone('Europe/Atlantis')).toBe(false)
+    expect(isValidTimeZone('Warsaw')).toBe(false)
+  })
+})
+
+describe('a configured zone', () => {
+  it('moves the day boundaries with it', () => {
+    expect(zonedDayStart('2026-06-11', 'UTC').toISOString()).toBe('2026-06-11T00:00:00.000Z')
+    expect(zonedDayEnd('2026-06-11', 'UTC').toISOString()).toBe('2026-06-11T23:59:00.000Z')
+    expect(zonedDayStart('2026-06-11', 'America/New_York').toISOString()).toBe('2026-06-11T04:00:00.000Z')
+  })
+})
+
+describe('tillio timezone helpers', () => {
+  it('anchors a day to Europe/Warsaw wall-clock boundaries', () => {
+    expect(zonedDayStart('2026-06-11').toISOString()).toBe('2026-06-10T22:00:00.000Z')
+    expect(zonedDayEnd('2026-06-11').toISOString()).toBe('2026-06-11T21:59:00.000Z')
+  })
+
+  it('handles the spring DST switch, where a day starts at +01:00 and ends at +02:00', () => {
+    expect(zonedDayStart('2026-03-29').toISOString()).toBe('2026-03-28T23:00:00.000Z')
+    expect(zonedDayEnd('2026-03-29').toISOString()).toBe('2026-03-29T21:59:00.000Z')
+  })
+
+  it('handles the autumn DST switch, where a day starts at +02:00 and ends at +01:00', () => {
+    expect(zonedDayStart('2026-10-25').toISOString()).toBe('2026-10-24T22:00:00.000Z')
+    expect(zonedDayEnd('2026-10-25').toISOString()).toBe('2026-10-25T22:59:00.000Z')
+  })
+
+  it('round-trips day boundaries back to the wall-clock format Tillio expects', () => {
+    for (const day of ['2026-01-15', '2026-03-29', '2026-06-11', '2026-10-25', '2026-12-31']) {
+      expect(formatTillioTimestamp(zonedDayStart(day))).toBe(`${day} 00:00`)
+      expect(formatTillioTimestamp(zonedDayEnd(day))).toBe(`${day} 23:59`)
+    }
+  })
+
+  it('formats an instant using the Warsaw wall clock, not the host timezone', () => {
+    expect(formatTillioTimestamp(new Date('2026-04-11T10:47:28.000Z'))).toBe('2026-04-11 12:47')
+  })
+
+  it('rejects a malformed day', () => {
+    expect(() => zonedDayStart('11-04-2026')).toThrow()
+  })
+})

package/src/modules/tillio/__tests__/url-guard.test.ts

@@ -0,0 +1,46 @@
+import { assertPublicTillioApiUrl } from '../lib/url-guard'
+
+describe('assertPublicTillioApiUrl', () => {
+  it('allows public https hosts', () => {
+    expect(() => assertPublicTillioApiUrl('https://x.example.com')).not.toThrow()
+    expect(() => assertPublicTillioApiUrl('https://api.tillio.io/v1')).not.toThrow()
+    expect(() => assertPublicTillioApiUrl('https://example.com:8443')).not.toThrow()
+    expect(() => assertPublicTillioApiUrl('https://8.8.8.8')).not.toThrow()
+  })
+
+  it('rejects plaintext http even on a public host', () => {
+    expect(() => assertPublicTillioApiUrl('http://api.tillio.example.com')).toThrow(/https/)
+    expect(() => assertPublicTillioApiUrl('http://example.com:8443')).toThrow(/https/)
+  })
+
+  it('rejects non-http(s) schemes', () => {
+    expect(() => assertPublicTillioApiUrl('file:///etc/passwd')).toThrow()
+    expect(() => assertPublicTillioApiUrl('gopher://example.com')).toThrow()
+    expect(() => assertPublicTillioApiUrl('not a url')).toThrow()
+  })
+
+  // The private-host cases stay on https so they keep exercising the host checks rather
+  // than tripping the transport check first.
+  it('rejects loopback and localhost', () => {
+    expect(() => assertPublicTillioApiUrl('https://localhost:9000')).toThrow()
+    expect(() => assertPublicTillioApiUrl('https://api.localhost')).toThrow()
+    expect(() => assertPublicTillioApiUrl('https://127.0.0.1')).toThrow()
+    expect(() => assertPublicTillioApiUrl('https://[::1]')).toThrow()
+  })
+
+  it('rejects RFC1918 private ranges', () => {
+    expect(() => assertPublicTillioApiUrl('https://10.0.0.5')).toThrow()
+    expect(() => assertPublicTillioApiUrl('https://172.16.0.1')).toThrow()
+    expect(() => assertPublicTillioApiUrl('https://192.168.1.1')).toThrow()
+  })
+
+  it('rejects link-local / cloud metadata', () => {
+    expect(() => assertPublicTillioApiUrl('https://169.254.169.254')).toThrow()
+    expect(() => assertPublicTillioApiUrl('https://[fe80::1]')).toThrow()
+    expect(() => assertPublicTillioApiUrl('https://0.0.0.0')).toThrow()
+  })
+
+  it('rejects ipv4-mapped ipv6 loopback', () => {
+    expect(() => assertPublicTillioApiUrl('https://[::ffff:127.0.0.1]')).toThrow()
+  })
+})

package/src/modules/tillio/acl.ts

@@ -0,0 +1,5 @@
+export const features = [
+  { id: 'tillio.manage', title: 'Manage Tillio integration', module: 'tillio' },
+]
+
+export default features