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

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

@@ -0,0 +1,33 @@
+import { createModuleQueue, type Queue } from '@open-mercato/queue'
+import { parseNumberWithDefault } from '@open-mercato/shared/lib/number'
+
+/**
+ * Queue helper for the Tillio provider. Mirrors `getSyncQueue` (data_sync) so the
+ * route and the worker share one queue instance per name.
+ *
+ * Concurrency stays at 1 by default: a pull sweeps Tillio page by page with the
+ * operator's token, and running several sweeps at once only buys provider
+ * throttling. `TILLIO_QUEUE_CONCURRENCY` raises it for deployments that pull for
+ * many organizations at once, capped at the platform ceiling of 20.
+ */
+const queues = new Map<string, Queue<Record<string, unknown>>>()
+
+export const TILLIO_PULL_QUEUE = 'tillio-pull'
+
+// Worker parallelism comes from the worker manifest, not from the producer-side queue
+// instance this module builds, so both read the same value or the variable only pretends
+// to do something.
+export function resolveTillioQueueConcurrency(): number {
+  return Math.min(20, parseNumberWithDefault(process.env.TILLIO_QUEUE_CONCURRENCY, 1, { min: 1, integer: true }))
+}
+
+export function getTillioQueue(queueName: string): Queue<Record<string, unknown>> {
+  const existing = queues.get(queueName)
+  if (existing) return existing
+
+  const created = createModuleQueue<Record<string, unknown>>(queueName, {
+    concurrency: resolveTillioQueueConcurrency(),
+  })
+  queues.set(queueName, created)
+  return created
+}

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

@@ -0,0 +1,121 @@
+// The zone Tillio reports its wall-clock timestamps in. Overridable per environment, because an
+// instance serving another market reports that market's local time.
+export const TILLIO_TIMEZONE = 'Europe/Warsaw'
+
+export function isValidTimeZone(value: string): boolean {
+  try {
+    new Intl.DateTimeFormat('en-US', { timeZone: value })
+    return true
+  } catch {
+    return false
+  }
+}
+
+const DAY_PATTERN = /^\d{4}-\d{2}-\d{2}$/
+
+type WallClock = {
+  year: number
+  month: number
+  day: number
+  hour: number
+  minute: number
+  second: number
+}
+
+function readWallClock(date: Date, timeZone: string): WallClock {
+  const parts = new Intl.DateTimeFormat('en-US', {
+    timeZone,
+    hourCycle: 'h23',
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+  }).formatToParts(date)
+  const read = (type: Intl.DateTimeFormatPartTypes): number =>
+    Number(parts.find((part) => part.type === type)?.value)
+  return {
+    year: read('year'),
+    month: read('month'),
+    day: read('day'),
+    hour: read('hour'),
+    minute: read('minute'),
+    second: read('second'),
+  }
+}
+
+function zoneOffsetMs(date: Date, timeZone: string): number {
+  const wall = readWallClock(date, timeZone)
+  const asUtc = Date.UTC(wall.year, wall.month - 1, wall.day, wall.hour, wall.minute, wall.second)
+  return asUtc - (date.getTime() - date.getMilliseconds())
+}
+
+// Two passes: the first offset is read at the naive instant, which lands in the
+// wrong side of a DST transition for wall-clock times near the switch. Reading
+// the offset again at the corrected instant settles it.
+function zonedWallClockToUtc(
+  day: string,
+  hour: number,
+  minute: number,
+  second: number,
+  timeZone: string,
+): Date {
+  if (!DAY_PATTERN.test(day)) {
+    throw new Error(`[internal] Expected a YYYY-MM-DD day, received "${day}".`)
+  }
+  const [year, month, dayOfMonth] = day.split('-').map(Number)
+  const naive = Date.UTC(year, month - 1, dayOfMonth, hour, minute, second)
+  const firstPass = naive - zoneOffsetMs(new Date(naive), timeZone)
+  return new Date(naive - zoneOffsetMs(new Date(firstPass), timeZone))
+}
+
+export function zonedDayStart(day: string, timeZone: string = TILLIO_TIMEZONE): Date {
+  return zonedWallClockToUtc(day, 0, 0, 0, timeZone)
+}
+
+// 23:59, not 23:59:59: Tillio's date filter is `YYYY-MM-DD HH:mm` with no seconds field (see
+// `formatTillioTimestamp`), so a finer bound cannot survive the trip out. Their own API
+// samples use 23:59 as the end of a day for the same reason.
+export function zonedDayEnd(day: string, timeZone: string = TILLIO_TIMEZONE): Date {
+  return zonedWallClockToUtc(day, 23, 59, 0, timeZone)
+}
+
+export function formatTillioTimestamp(date: Date, timeZone: string = TILLIO_TIMEZONE): string {
+  const wall = readWallClock(date, timeZone)
+  const pad = (value: number): string => String(value).padStart(2, '0')
+  return `${wall.year}-${pad(wall.month)}-${pad(wall.day)} ${pad(wall.hour)}:${pad(wall.minute)}`
+}
+
+const TZ_SUFFIX_PATTERN = /(?:Z|[+-]\d{2}:?\d{2})$/i
+const WALL_CLOCK_PATTERN = /^(\d{4}-\d{2}-\d{2})[ T](\d{2}):(\d{2})(?::(\d{2}))?$/
+
+// Tillio returns `date` in two shapes depending on the operator:
+//  - Ringostat: ISO with an explicit offset ("2026-04-11T12:47:28+0200") -> new Date is unambiguous.
+//  - Play: a Europe/Warsaw wall-clock time with no zone ("2026-05-09 08:49:39"). `new Date` would
+//    read it in the process-local zone, which is wrong on any server that is not Warsaw, so we
+//    resolve it explicitly through the Tillio timezone instead.
+export function parseTillioTimestamp(
+  value: string | null | undefined,
+  timeZone: string = TILLIO_TIMEZONE,
+): Date | null {
+  if (!value) return null
+  const trimmed = value.trim()
+  if (!trimmed) return null
+  if (TZ_SUFFIX_PATTERN.test(trimmed)) {
+    const parsed = new Date(trimmed)
+    return Number.isNaN(parsed.getTime()) ? null : parsed
+  }
+  const match = WALL_CLOCK_PATTERN.exec(trimmed)
+  if (match) {
+    const [, day, hour, minute, second] = match
+    const [year, month, dayOfMonth] = day.split('-').map(Number)
+    // Tillio can emit a zeroed/blank stamp ("0000-00-00 00:00:00") for a missing date; it slips
+    // past the regex but is not a real calendar day, so treat it as "no timestamp" (matching what
+    // `new Date` used to yield here: Invalid Date -> null).
+    if (year < 1971 || month < 1 || month > 12 || dayOfMonth < 1 || dayOfMonth > 31) return null
+    return zonedWallClockToUtc(day, Number(hour), Number(minute), second ? Number(second) : 0, timeZone)
+  }
+  const parsed = new Date(trimmed)
+  return Number.isNaN(parsed.getTime()) ? null : parsed
+}

package/src/modules/tillio/lib/url-guard.ts

@@ -0,0 +1,34 @@
+// SSRF guard for the user-supplied Tillio API URL. `apiUrl` comes from integration
+// credentials, so before createTillioClient ever fetches it we reject non-http(s) schemes
+// and hosts that are loopback / private / link-local (cloud metadata endpoints, internal
+// services). This is the synchronous, construction-time check; the resolution-time half
+// (DNS answers, rebinding, redirect targets) is `safeOutboundFetch` in `client.ts`.
+
+import { assertStaticallySafeOutboundUrl } from '@open-mercato/shared/lib/url-safety'
+
+export const TILLIO_URL_SUBJECT = 'Tillio API URL'
+
+export function assertPublicTillioApiUrl(rawUrl: string): void {
+  // The shared guard decides where a request may go, not whether what it carries stays
+  // confidential, so it admits plaintext http. Every Tillio request sends `X-Api-Key` and,
+  // once an operator is attached, `X-Token`, so http is refused here before any of them
+  // reaches the wire. No development allowance: `apiUrl` always points at Tillio's public
+  // host, and tests stub the transport through `fetchImpl` instead of relaxing this.
+  assertTillioTls(rawUrl)
+  assertStaticallySafeOutboundUrl(rawUrl, {
+    subject: TILLIO_URL_SUBJECT,
+    errorFactory: (_reason, message) => new Error(`${message}.`),
+  })
+}
+
+function assertTillioTls(rawUrl: string): void {
+  let protocol: string
+  try {
+    protocol = new URL(rawUrl).protocol
+  } catch {
+    // Malformed input belongs to the shared guard so one parser owns that message.
+    return
+  }
+  if (protocol !== 'http:') return
+  throw new Error(`${TILLIO_URL_SUBJECT} must use https, so the API key is not sent in cleartext.`)
+}

package/src/modules/tillio/setup.ts

@@ -0,0 +1,49 @@
+import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { applyTillioEnvPreset } from './lib/preset'
+import { createTillioLock, tillioOperatorLockKey } from './lib/locking'
+import type { TillioCredentialsService } from './lib/operators-store'
+
+const logger = createLogger('tillio').child({ component: 'setup' })
+
+export const setup: ModuleSetupConfig = {
+  defaultRoleFeatures: {
+    admin: [
+      'tillio.*',
+    ],
+  },
+
+  async seedDefaults({ tenantId, organizationId, container }) {
+    try {
+      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 },
+        withLock: createTillioLock(
+          container.resolve('em') as EntityManager,
+          tillioOperatorLockKey({ tenantId, organizationId }),
+        ),
+      })
+      if (result.status === 'skipped') {
+        logger.debug('env preset not applied', { reason: result.reason })
+      } else if (result.status === 'blocked') {
+        logger.warn('env preset refused', { reason: result.reason })
+      } else {
+        logger.info('env preset applied', {
+          credentialsAction: result.credentialsAction,
+          health: result.health,
+          operator: result.operator,
+        })
+      }
+    } catch (err) {
+      // A provider preset is never worth failing tenant bootstrap over; the operator can rerun
+      // `mercato tillio configure-from-env` once the deployment is fixed.
+      logger.warn('failed to apply the env preset during tenant setup', { err })
+    }
+  },
+}
+
+export default setup

package/src/modules/tillio/widgets/injection/operators-config/widget.client.tsx

@@ -0,0 +1,304 @@
+'use client'
+
+import * as React from 'react'
+import type { InjectionWidgetComponentProps } from '@open-mercato/shared/modules/widgets/injection'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
+import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { useConfirmDialog } from '@open-mercato/ui/backend/confirm-dialog'
+import { tillioErrorCopy } from '../../../lib/error-codes'
+import type { EnvironmentBlocker } from '../../../lib/pull-readiness'
+import { Alert, AlertDescription, AlertTitle } from '@open-mercato/ui/primitives/alert'
+import { StatusBadge } from '@open-mercato/ui/primitives/status-badge'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { FormField } from '@open-mercato/ui/primitives/form-field'
+import { Input } from '@open-mercato/ui/primitives/input'
+import { Label } from '@open-mercato/ui/primitives/label'
+import { Spinner } from '@open-mercato/ui/primitives/spinner'
+
+type OperatorSummary = {
+  id: string
+  plugin: string
+  tenantDomain: string
+  stale: boolean
+}
+
+type OperatorsResponse = {
+  ok: boolean
+  environmentReady: boolean
+  environmentBlocker: EnvironmentBlocker | null
+  tenantSystemId: string | null
+  supportedPlugins: string[]
+  operators: OperatorSummary[]
+  defaultOperatorId: string | null
+  envDrift: boolean
+}
+
+type AttachResult = {
+  ok: boolean
+  code?: string
+  section?: 'environment' | 'operator'
+  operator?: { id: string; plugin: string; tenantDomain: string }
+}
+
+type DetachResult = {
+  ok: boolean
+  code?: string
+  section?: 'environment' | 'operator'
+  detached?: boolean
+  revoked?: boolean
+  /** Set when the record survived because the token could not be revoked. */
+  canForce?: boolean
+}
+
+export default function OperatorsConfigWidget(
+  _props: InjectionWidgetComponentProps<Record<string, unknown>, Record<string, unknown>>,
+) {
+  const t = useT()
+  const attachErrorText = React.useCallback((code: string | undefined) => {
+    const copy = tillioErrorCopy(code, 'attach_failed')
+    return t(copy.key, copy.fallback)
+  }, [t])
+  const detachErrorText = React.useCallback((code: string | undefined) => {
+    const copy = tillioErrorCopy(code, 'detach_failed')
+    return t(copy.key, copy.fallback)
+  }, [t])
+  const [state, setState] = React.useState<OperatorsResponse | null>(null)
+  const [loading, setLoading] = React.useState(true)
+  const [keyInput, setKeyInput] = React.useState('')
+  const [pending, setPending] = React.useState(false)
+  const { runMutation, retryLastMutation } = useGuardedMutation({
+    contextId: 'tillio-operators',
+    blockedMessage: t('tillio.operators.blocked', 'Operator change blocked by validation.'),
+  })
+  const mutationContext = React.useMemo(
+    () => ({ providerKey: 'tillio', retryLastMutation }),
+    [retryLastMutation],
+  )
+  const { confirm, ConfirmDialogElement } = useConfirmDialog()
+
+  const load = React.useCallback(async () => {
+    setLoading(true)
+    try {
+      const response = await apiCall<OperatorsResponse>('/api/tillio/operators')
+      if (response.ok && response.result) {
+        setState(response.result)
+      } else {
+        setState(null)
+        flash(t('tillio.operators.loadFailed', 'Failed to load Tillio operators.'), 'error')
+      }
+    } finally {
+      setLoading(false)
+    }
+  }, [t])
+
+  React.useEffect(() => {
+    void load()
+  }, [load])
+
+  const attach = React.useCallback(async () => {
+    if (pending) return
+    const key = keyInput.trim()
+    if (!key) {
+      flash(t('tillio.operators.keyRequired', 'Enter the Ringostat key first.'), 'error')
+      return
+    }
+    setPending(true)
+    try {
+      const response = await runMutation({
+        context: mutationContext,
+        mutationPayload: { providerKey: 'tillio', plugin: 'Ringostat' },
+        operation: () =>
+          apiCall<AttachResult>('/api/tillio/operators', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ plugin: 'Ringostat', config: { key } }),
+          }),
+      })
+      const body = response.result as AttachResult | undefined
+      if (!response.ok) {
+        flash(attachErrorText(body?.code), 'error')
+        return
+      }
+      flash(t('tillio.operators.attached', 'Operator attached.'), 'success')
+      setKeyInput('')
+      await load()
+    } finally {
+      setPending(false)
+    }
+  }, [attachErrorText, keyInput, load, mutationContext, pending, runMutation, t])
+
+  const sendDetach = React.useCallback(async (operatorId: string, force: boolean) => {
+    const query = force ? '?force=true' : ''
+    return runMutation({
+      context: mutationContext,
+      mutationPayload: { providerKey: 'tillio', force },
+      operation: () =>
+        apiCall<DetachResult>(`/api/tillio/operators/${encodeURIComponent(operatorId)}${query}`, { method: 'DELETE' }),
+    })
+  }, [mutationContext, runMutation])
+
+  const detach = React.useCallback(async (operatorId: string) => {
+    const confirmed = await confirm({
+      title: t('tillio.operators.detachConfirmTitle', 'Detach this operator?'),
+      text: t('tillio.operators.detachConfirmText', 'The operator will be removed and its Tillio token revoked. You can attach it again afterwards.'),
+      confirmText: t('tillio.operators.detachConfirmAction', 'Detach'),
+      cancelText: t('tillio.operators.cancel', 'Cancel'),
+      variant: 'destructive',
+    })
+    if (!confirmed) return
+    setPending(true)
+    try {
+      const response = await sendDetach(operatorId, false)
+      const body = response.result as DetachResult | undefined
+      if (response.ok) {
+        flash(t('tillio.operators.detached', 'Operator detached.'), 'success')
+        await load()
+        return
+      }
+
+      // The token is still live on Tillio's side, so the record stayed. Removing it anyway
+      // is a separate, explicit decision — it leaves that token behind with no handle to it.
+      if (!body?.canForce) {
+        flash(detachErrorText(body?.code), 'error')
+        return
+      }
+      const forceConfirmed = await confirm({
+        title: t('tillio.operators.forceDetachTitle', 'Detach without revoking?'),
+        text: t('tillio.operators.forceDetachText', 'The Tillio token could not be revoked, so it stays active until you remove it in Tillio. Remove the operator here anyway?'),
+        confirmText: t('tillio.operators.forceDetachAction', 'Detach anyway'),
+        cancelText: t('tillio.operators.cancel', 'Cancel'),
+        variant: 'destructive',
+      })
+      if (!forceConfirmed) return
+
+      const forced = await sendDetach(operatorId, true)
+      if (!forced.ok) {
+        flash(t('tillio.operators.detachFailed', 'Could not detach the operator.'), 'error')
+        return
+      }
+      flash(t('tillio.operators.detachedNotRevoked', 'Operator removed. Revoke its token in Tillio manually.'), 'success')
+      await load()
+    } finally {
+      setPending(false)
+    }
+  }, [confirm, detachErrorText, load, sendDetach, t])
+
+  const copyTenantDomain = React.useCallback(async (tenantDomain: string) => {
+    try {
+      await navigator.clipboard.writeText(tenantDomain)
+      flash(t('tillio.operators.copied', 'Webhook domain copied.'), 'success')
+    } catch {
+      flash(t('tillio.operators.copyFailed', 'Could not copy to clipboard.'), 'error')
+    }
+  }, [t])
+
+  if (loading) {
+    return (
+      <div className="flex items-center gap-2 py-6 text-sm text-muted-foreground">
+        <Spinner />
+        {t('tillio.operators.loading', 'Loading operators...')}
+      </div>
+    )
+  }
+
+  if (!state) {
+    return (
+      <Alert status="error">
+        <AlertTitle>{t('tillio.operators.loadFailed', 'Failed to load Tillio operators.')}</AlertTitle>
+        <AlertDescription>
+          <Button type="button" variant="outline" size="sm" onClick={() => void load()}>
+            {t('tillio.operators.retry', 'Retry')}
+          </Button>
+        </AlertDescription>
+      </Alert>
+    )
+  }
+
+  const operator = state.operators[0] ?? null
+
+  return (
+    <div className="grid gap-4">
+      {ConfirmDialogElement}
+
+      {!state.environmentReady ? (
+        <Alert status="warning">
+          <AlertTitle>
+            {state.environmentBlocker === 'integration_disabled'
+              ? t('tillio.operators.integrationDisabledTitle', 'Integration disabled')
+              : t('tillio.operators.envNotReadyTitle', 'Environment not ready')}
+          </AlertTitle>
+          <AlertDescription>
+            {state.environmentBlocker === 'integration_disabled'
+              ? t('tillio.errors.integrationDisabled', 'The Tillio integration is disabled. Enable it first.')
+              : t('tillio.operators.envNotReadyText', 'Save the Tillio API URL and key in the Credentials tab, then run the health Check before attaching an operator.')}
+          </AlertDescription>
+        </Alert>
+      ) : null}
+
+      {operator && operator.stale ? (
+        <Alert status="warning">
+          <AlertTitle>{t('tillio.operators.driftTitle', 'Environment changed')}</AlertTitle>
+          <AlertDescription>
+            {t('tillio.operators.driftText', 'The environment changed after this operator was attached, so its token may be invalid. Detach and attach it again.')}
+          </AlertDescription>
+        </Alert>
+      ) : null}
+
+      {operator ? (
+        <div className="grid gap-3 rounded-md border border-border p-4">
+          <div className="flex items-center justify-between gap-3">
+            <div className="flex items-center gap-2">
+              <span className="font-medium">{operator.plugin}</span>
+              {operator.stale ? (
+                <StatusBadge variant="warning" dot>{t('tillio.operators.stale', 'Stale')}</StatusBadge>
+              ) : (
+                <StatusBadge variant="success" dot>{t('tillio.operators.active', 'Active')}</StatusBadge>
+              )}
+            </div>
+            <Button type="button" variant="outline" size="sm" onClick={() => void detach(operator.id)} disabled={pending}>
+              {t('tillio.operators.detach', 'Detach')}
+            </Button>
+          </div>
+          <div className="grid gap-1.5">
+            <Label asChild>
+              <span>{t('tillio.operators.webhookDomain', 'Webhook domain (X-Tenant-Domain)')}</span>
+            </Label>
+            <div className="flex items-center gap-2">
+              <code className="min-w-0 flex-1 truncate rounded-md bg-muted px-2 py-1 text-sm">{operator.tenantDomain}</code>
+              <Button type="button" variant="outline" size="sm" onClick={() => void copyTenantDomain(operator.tenantDomain)}>
+                {t('tillio.operators.copy', 'Copy')}
+              </Button>
+            </div>
+            <span className="text-xs text-muted-foreground">
+              {t('tillio.operators.webhookHint', 'Register this URL in your operator panel so Tillio forwards its webhooks here.')}
+            </span>
+          </div>
+        </div>
+      ) : state.environmentReady ? (
+        <div className="grid gap-3 rounded-md border border-border p-4">
+          <FormField
+            label={t('tillio.operators.ringostatKey', 'Ringostat key')}
+            description={t('tillio.operators.ringostatKeyHint', 'One operator at a time. Detach the current one before attaching another.')}
+          >
+            <Input
+              type="password"
+              autoComplete="off"
+              value={keyInput}
+              onChange={(event) => setKeyInput(event.target.value)}
+              placeholder={t('tillio.operators.ringostatKeyPlaceholder', 'Paste the Ringostat integration key')}
+            />
+          </FormField>
+          <div>
+            <Button type="button" onClick={() => void attach()} disabled={pending}>
+              {pending
+                ? t('tillio.operators.attaching', 'Attaching...')
+                : t('tillio.operators.attach', 'Attach operator')}
+            </Button>
+          </div>
+        </div>
+      ) : null}
+    </div>
+  )
+}

package/src/modules/tillio/widgets/injection/operators-config/widget.ts

@@ -0,0 +1,16 @@
+import type { InjectionWidgetModule } from '@open-mercato/shared/modules/widgets/injection'
+import OperatorsConfigWidget from './widget.client'
+
+const widget: InjectionWidgetModule<Record<string, unknown>, Record<string, unknown>> = {
+  metadata: {
+    id: 'tillio.injection.operators',
+    title: 'Operator configuration',
+    description: 'Attach one Tillio operator (Ringostat) on top of the configured environment.',
+    features: ['tillio.manage', 'integrations.manage'],
+    priority: 100,
+    enabled: true,
+  },
+  Widget: OperatorsConfigWidget,
+}
+
+export default widget