@open-mercato/core 0.6.8-develop.6993.1.3fc50f3409 → 0.6.8-develop.7000.1.0ae682bad1

package/src/modules/data_sync/i18n/pl.json

@@ -55,6 +55,8 @@
   "data_sync.dashboard.start.fullSync": "Uruchom jako pełną synchronizację",
   "data_sync.dashboard.start.fullSyncHelp": "Zignoruj zapisany kursor i przetwórz w tym przebiegu całe źródło od nowa.",
   "data_sync.dashboard.start.invalidBatchSize": "Rozmiar partii musi mieścić się w zakresie od 1 do 1000.",
+  "data_sync.dashboard.start.parameters": "Parametry uruchomienia",
+  "data_sync.dashboard.start.parametersHelp": "Opcjonalne wartości akceptowane przez tę integrację dla ręcznego uruchomienia.",
   "data_sync.dashboard.start.providerManaged": "Ta integracja uruchamia synchronizacje z własnego przepływu konfiguracji. Otwórz ustawienia integracji, aby kontynuować.",
   "data_sync.dashboard.start.runNowDescription": "Użyj tej opcji dla najbliższej natychmiastowej synchronizacji. Rozmiar partii i tryb pełnej synchronizacji dotyczą wyłącznie tego ręcznego przebiegu.",
   "data_sync.dashboard.start.runNowFootnote": "Ręczne przebiegi od razu pokazują postęp, a po uruchomieniu przenoszą na stronę szczegółów przebiegu.",
@@ -85,6 +87,7 @@
   "data_sync.integrationTab.integrationDisabledNotice": "Integracja jest wyłączona. Możesz teraz zapisać harmonogramy, ale przebiegi pozostaną zablokowane do czasu włączenia integracji.",
   "data_sync.integrationTab.loadError": "Nie udało się załadować harmonogramów synchronizacji.",
   "data_sync.integrationTab.notAvailable": "Ta integracja nie jest zarejestrowana jako dostawca synchronizacji danych.",
+  "data_sync.integrationTab.parametersRequired": "Ten przebieg wymaga parametrów. Uruchom go z panelu Data Sync.",
   "data_sync.integrationTab.providerManaged": "Uruchom tę integrację z jej przepływu konfiguracji dostawcy.",
   "data_sync.integrationTab.providerManagedNotice": "Ten dostawca wymaga własnego przepływu konfiguracji, zanim będzie można uruchomić synchronizację. Użyj karty dostawcy na tej stronie zamiast ogólnych harmonogramów.",
   "data_sync.integrationTab.refresh": "Odśwież",
@@ -96,6 +99,11 @@
   "data_sync.integrationTab.starting": "Uruchamianie...",
   "data_sync.integrationTab.title": "Harmonogramy synchronizacji",
   "data_sync.nav.title": "Synchronizacja danych",
+  "data_sync.runParameters.errors.max": "Pole {label} może wynosić najwyżej {max}.",
+  "data_sync.runParameters.errors.min": "Pole {label} musi wynosić co najmniej {min}.",
+  "data_sync.runParameters.errors.required": "Pole {label} jest wymagane.",
+  "data_sync.runParameters.errors.select": "Pole {label} musi mieć jedną z wartości: {options}.",
+  "data_sync.runParameters.errors.type": "Pole {label} musi mieć typ {type}.",
   "data_sync.runs.detail.back": "Powrót do przebiegów",
   "data_sync.runs.detail.cancel": "Anuluj",
   "data_sync.runs.detail.cancelError": "Nie udało się anulować przebiegu",
@@ -112,6 +120,7 @@
   "data_sync.runs.detail.logs.time": "Czas",
   "data_sync.runs.detail.noLogs": "Brak wpisów w logach",
   "data_sync.runs.detail.notFound": "Nie znaleziono przebiegu synchronizacji.",
+  "data_sync.runs.detail.parameters": "Parametry uruchomienia",
   "data_sync.runs.detail.progress": "Postęp",
   "data_sync.runs.detail.progress.batches": "{count} partii",
   "data_sync.runs.detail.progress.eta": "Pozostało {eta}",
@@ -120,6 +129,7 @@
   "data_sync.runs.detail.progress.percent": "{percent}% ukończono",
   "data_sync.runs.detail.retry": "Ponów",
   "data_sync.runs.detail.retryError": "Nie udało się ponowić przebiegu",
+  "data_sync.runs.detail.retryParametersStale": "Zapisane parametry uruchomienia nie są już poprawne dla tej integracji. Uruchom nowe zadanie z pulpitu Data Sync.",
   "data_sync.runs.detail.retrySuccess": "Przebieg ponowiony",
   "data_sync.runs.detail.title": "Przebieg synchronizacji"
 }

package/src/modules/data_sync/lib/adapter.ts

@@ -38,6 +38,13 @@ export interface StreamImportInput {
   mapping: DataMapping
   scope: TenantScope
   runId?: string
+  /**
+   * Operator-supplied run parameters, normalized against the adapter's
+   * declared `runParameters`. Only declared keys are present; values are
+   * already coerced to the declared types. Empty object when the adapter
+   * declares no parameters.
+   */
+  parameters?: Record<string, RunParameterValue>
 }
 
 export interface ImportItem {
@@ -67,6 +74,8 @@ export interface StreamExportInput {
   scope: TenantScope
   filter?: Record<string, unknown>
   runId?: string
+  /** See {@link StreamImportInput.parameters}. */
+  parameters?: Record<string, RunParameterValue>
 }
 
 export interface ExportItemResult {
@@ -89,6 +98,79 @@ export interface ValidationResult {
   details?: Record<string, unknown>
 }
 
+export type RunParameterType = 'boolean' | 'string' | 'number' | 'select'
+
+export type RunParameterValue = boolean | string | number
+
+export interface RunParameterOption {
+  value: string
+  label?: string
+}
+
+/**
+ * A single operator-facing parameter an adapter accepts when a run is started.
+ *
+ * The `data_sync` UI renders an input per declared parameter, the run API
+ * validates and coerces the submitted values against this declaration, and the
+ * normalized values are handed back to the adapter on `StreamImportInput` /
+ * `StreamExportInput`. Keep declarations generic — this contract is provider
+ * agnostic.
+ */
+export interface RunParameter {
+  /** Stable identifier used as the key in the normalized parameters object. */
+  key: string
+  /**
+   * Human-readable label shown next to the input. Used verbatim when
+   * `labelKey` is absent, and as the fallback when it resolves to nothing.
+   */
+  label: string
+  /**
+   * i18n key the dashboard resolves for the label, preferred over `label`.
+   * Declare it whenever the adapter ships to more than one locale — `label`
+   * alone can only ever be one language.
+   */
+  labelKey?: string
+  type: RunParameterType
+  /** Optional helper text rendered under the input. */
+  description?: string
+  /** i18n key for `description`, preferred over the literal when present. */
+  descriptionKey?: string
+  /**
+   * When true, the run cannot start unless a non-empty value is provided.
+   *
+   * Has no effect on `boolean` parameters: a switch always submits `true` or
+   * `false`, neither of which is blank, so the check can never fire. Use
+   * `defaultValue` to express the intended default instead. This is why the
+   * dashboard renders the required marker only on the input types where the
+   * constraint is real.
+   */
+  required?: boolean
+  /** Pre-filled value; also the value used when the field is left blank. */
+  defaultValue?: RunParameterValue
+  /** Placeholder for `string` / `number` inputs. */
+  placeholder?: string
+  /** i18n key for `placeholder`, preferred over the literal when present. */
+  placeholderKey?: string
+  /** Allowed choices for `select` parameters. */
+  options?: RunParameterOption[]
+  /** Inclusive bounds for `number` parameters. */
+  min?: number
+  max?: number
+  /**
+   * Restrict the parameter to a single run direction. When omitted the
+   * parameter applies to both import and export runs.
+   */
+  direction?: 'import' | 'export'
+  /**
+   * Restrict the parameter to one or more entity types (matched against the
+   * run's `entityType`, i.e. a value from `supportedEntities`). When omitted
+   * the parameter applies to every entity the adapter supports. Use this when
+   * a knob only makes sense for a specific entity's run — e.g. a bulk-reindex
+   * toggle that only applies to the orders backfill.
+   */
+  entityType?: string | string[]
+}
+
 export interface DataSyncAdapter {
   readonly providerKey: string
   readonly direction: 'import' | 'export' | 'bidirectional'
@@ -103,6 +185,12 @@ export interface DataSyncAdapter {
    */
   readonly runMode?: 'generic' | 'provider'
   readonly operationalTelemetry?: boolean
+  /**
+   * Optional operator-facing parameters accepted when a run is started. The
+   * `data_sync` dashboard renders an input per entry, and the normalized values
+   * are passed back on `StreamImportInput` / `StreamExportInput`.
+   */
+  readonly runParameters?: RunParameter[]
 
   /**
    * Batch work MUST be replay-safe.

package/src/modules/data_sync/lib/batch-stream.ts

@@ -0,0 +1,117 @@
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import {
+  withTelemetrySpan,
+  type TelemetrySpan,
+  type TelemetrySpanAttributes,
+  type TelemetryTraceCarrier,
+} from '@open-mercato/shared/lib/telemetry/runtime'
+
+const logger = createLogger('data_sync').child({ component: 'batch-stream' })
+
+/** What the handler wants the stream to do next. */
+export type BatchOutcome = 'continue' | 'stop'
+
+/** Why the stream ended: the adapter ran out of batches, or a handler stopped it. */
+export type BatchStreamResult = 'completed' | 'stopped'
+
+export type BatchStreamOptions = {
+  spanName: string
+  /**
+   * Name for the read that turns out to have drained the stream. That read is
+   * real adapter work — it can be a full remote page fetch that comes back
+   * empty — so it stays traced, but it is not a batch: leaving it under
+   * `spanName` would report one batch more than the run actually processed and
+   * feed an unlabelled, counter-less sample into every batch latency panel.
+   */
+  drainSpanName: string
+  /** Run-level attributes repeated on every batch span (run id, entity type, scope). */
+  attributes?: TelemetrySpanAttributes
+  /** The run's trace, so a rooted batch still points back at what triggered it. */
+  linkTo?: TelemetryTraceCarrier
+}
+
+/**
+ * Close the stream while an error is already in flight. That error is the one
+ * worth propagating, so a secondary cleanup failure is logged rather than
+ * allowed to mask it — which is what `for await` does on a body throw.
+ */
+async function closeQuietly(iterator: AsyncIterator<unknown>): Promise<void> {
+  if (!iterator.return) return
+  try {
+    await iterator.return()
+  } catch (error) {
+    logger.warn('Data sync adapter stream did not close cleanly', { err: error })
+  }
+}
+
+/**
+ * Drive `stream` one batch at a time, running the adapter's read AND `handle`'s
+ * bookkeeping for that batch inside a single ROOT span linked back to the run.
+ *
+ * Rooting per batch is the whole point. A sync run can last days, so leaving its
+ * spans nested under the request that triggered it puts the entire run behind
+ * one sampling decision — below ratio 1.0 a run can emit nothing at all, and at
+ * 1.0 it becomes a single unrenderable trace. A batch is the unit the slowness
+ * analysis actually reasons about, so it gets its own trace and its own
+ * decision.
+ *
+ * The iterator is driven explicitly instead of with `for await` so the span can
+ * wrap `next()`, which is where an adapter generator does its real work — it
+ * reads, transforms and upserts before it ever yields. A stream is only known to
+ * be drained once that read returns `done`, so the last span per run starts
+ * under `spanName` and is renamed to `drainSpanName`: a run over N batches emits
+ * N spans named `spanName` and exactly one named `drainSpanName`.
+ *
+ * Closing follows the language's own `IteratorClose` rules exactly, so adapter
+ * cleanup behaves as it did under `for await`:
+ *
+ * - **exhausted** — the iterator already completed itself; no `return()` call.
+ * - **stopped early** — `return()` is called and a failure to close *is* the
+ *   result, the same as breaking out of `for await`.
+ * - **`handle` threw** — `return()` is called, but its failure is swallowed so
+ *   the handler's error still wins.
+ * - **`next()` threw** — the iterator is already closed; no `return()` call.
+ */
+export async function forEachBatch<TBatch>(
+  stream: AsyncIterable<TBatch>,
+  options: BatchStreamOptions,
+  handle: (batch: TBatch, span: TelemetrySpan) => Promise<BatchOutcome>,
+): Promise<BatchStreamResult> {
+  const iterator = stream[Symbol.asyncIterator]()
+  for (;;) {
+    let readThrew = false
+    let outcome: BatchOutcome | 'exhausted'
+    try {
+      outcome = await withTelemetrySpan(
+        options.spanName,
+        async (span): Promise<BatchOutcome | 'exhausted'> => {
+          let next: IteratorResult<TBatch>
+          try {
+            next = await iterator.next()
+          } catch (error) {
+            readThrew = true
+            throw error
+          }
+          if (next.done) {
+            span.updateName?.(options.drainSpanName)
+            return 'exhausted'
+          }
+          return handle(next.value, span)
+        },
+        {
+          root: true,
+          attributes: options.attributes,
+          links: options.linkTo ? [options.linkTo] : undefined,
+        },
+      )
+    } catch (error) {
+      if (!readThrew) await closeQuietly(iterator)
+      throw error
+    }
+    if (outcome === 'exhausted') return 'completed'
+    if (outcome === 'stop') {
+      await iterator.return?.()
+      return 'stopped'
+    }
+  }
+}

package/src/modules/data_sync/lib/run-parameters.ts

@@ -0,0 +1,196 @@
+import type { RunParameter, RunParameterValue } from './adapter'
+
+export type RunParameterErrorCode = 'required' | 'type' | 'min' | 'max' | 'select'
+
+export type RunParameterError = {
+  key: string
+  /**
+   * Machine-readable reason, so the client can render a translated message.
+   * The dashboard maps these to `data_sync.runParameters.errors.<code>`.
+   */
+  code: RunParameterErrorCode
+  /** Values the translated message interpolates (label, bound, option list). */
+  params: { label: string; type?: string; min?: number; max?: number; options?: string }
+  /**
+   * Pre-rendered English sentence. Kept for non-UI callers (API clients, logs)
+   * and as the client-side fallback; the UI prefers `code` + `params`.
+   */
+  message: string
+}
+
+export type NormalizeRunParametersResult =
+  | { ok: true; values: Record<string, RunParameterValue> }
+  | { ok: false; errors: RunParameterError[] }
+
+/**
+ * Keys that cannot round-trip through a plain object literal. Assigning a
+ * primitive to `__proto__` is silently discarded rather than creating an own
+ * property, so a parameter declared under that key would vanish between the
+ * form and the adapter instead of failing loudly. Rejecting it here — the one
+ * place every surface funnels through — keeps the dashboard, the default-value
+ * builder and the normalizer agreeing on the same parameter set.
+ *
+ * (`constructor` / `prototype` assign normally and are left alone.)
+ */
+const RESERVED_PARAMETER_KEYS = new Set(['__proto__'])
+
+export function isReservedRunParameterKey(key: string): boolean {
+  return RESERVED_PARAMETER_KEYS.has(key)
+}
+
+/**
+ * Returns the declared parameters that apply to a given run. A parameter
+ * without an explicit `direction` applies to both directions; one without an
+ * explicit `entityType` applies to every entity. When `entityType` is omitted
+ * here (the caller does not know the run's entity), entity scoping is skipped.
+ * Parameters declared under a reserved key are dropped.
+ */
+export function getApplicableRunParameters(
+  declared: RunParameter[] | undefined,
+  direction: 'import' | 'export',
+  entityType?: string,
+): RunParameter[] {
+  if (!declared || declared.length === 0) return []
+  return declared.filter((param) => {
+    if (isReservedRunParameterKey(param.key)) return false
+    if (param.direction && param.direction !== direction) return false
+    if (param.entityType !== undefined && entityType !== undefined) {
+      const allowed = Array.isArray(param.entityType) ? param.entityType : [param.entityType]
+      if (!allowed.includes(entityType)) return false
+    }
+    return true
+  })
+}
+
+function isBlank(value: unknown): boolean {
+  return value === undefined || value === null || (typeof value === 'string' && value.trim().length === 0)
+}
+
+function coerceBoolean(value: unknown): boolean | null {
+  if (typeof value === 'boolean') return value
+  if (typeof value === 'number') {
+    if (value === 1) return true
+    if (value === 0) return false
+    return null
+  }
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase()
+    if (['true', '1', 'yes', 'on'].includes(normalized)) return true
+    if (['false', '0', 'no', 'off'].includes(normalized)) return false
+  }
+  return null
+}
+
+function coerceNumber(value: unknown): number | null {
+  if (typeof value === 'number') return Number.isFinite(value) ? value : null
+  if (typeof value === 'string') {
+    const trimmed = value.trim()
+    if (trimmed.length === 0) return null
+    const parsed = Number(trimmed)
+    return Number.isFinite(parsed) ? parsed : null
+  }
+  return null
+}
+
+/**
+ * Validate and coerce an untrusted parameter object against an adapter's
+ * declared `runParameters` for the given run direction and entity type.
+ *
+ * - Parameters that do not apply to the direction or entity type are ignored.
+ * - Undeclared keys in the input are dropped (never passed through).
+ * - Blank values fall back to `defaultValue`; a blank required value is an error.
+ * - Values are coerced to the declared type; the result only contains declared keys.
+ */
+function buildRunParameterError(
+  param: RunParameter,
+  code: RunParameterErrorCode,
+  extra: { type?: string; min?: number; max?: number; options?: string } = {},
+): RunParameterError {
+  const message = code === 'required' ? `${param.label} is required.`
+    : code === 'type' ? `${param.label} must be a ${extra.type}.`
+    : code === 'min' ? `${param.label} must be at least ${extra.min}.`
+    : code === 'max' ? `${param.label} must be at most ${extra.max}.`
+    : `${param.label} must be one of: ${extra.options}.`
+  return { key: param.key, code, params: { label: param.label, ...extra }, message }
+}
+
+type CoerceResult =
+  | { ok: true; value: RunParameterValue }
+  | { ok: false; error: RunParameterError }
+
+/** Coerces and range-checks one non-blank value against its declaration. */
+function coerceDeclaredValue(param: RunParameter, raw: unknown): CoerceResult {
+  switch (param.type) {
+    case 'boolean': {
+      const coerced = coerceBoolean(raw)
+      if (coerced === null) return { ok: false, error: buildRunParameterError(param, 'type', { type: 'boolean' }) }
+      return { ok: true, value: coerced }
+    }
+    case 'number': {
+      const coerced = coerceNumber(raw)
+      if (coerced === null) return { ok: false, error: buildRunParameterError(param, 'type', { type: 'number' }) }
+      if (typeof param.min === 'number' && coerced < param.min) {
+        return { ok: false, error: buildRunParameterError(param, 'min', { min: param.min }) }
+      }
+      if (typeof param.max === 'number' && coerced > param.max) {
+        return { ok: false, error: buildRunParameterError(param, 'max', { max: param.max }) }
+      }
+      return { ok: true, value: coerced }
+    }
+    case 'select': {
+      const candidate = String(raw)
+      const allowed = (param.options ?? []).map((option) => option.value)
+      if (!allowed.includes(candidate)) {
+        return { ok: false, error: buildRunParameterError(param, 'select', { options: allowed.join(', ') }) }
+      }
+      return { ok: true, value: candidate }
+    }
+    case 'string':
+    default:
+      return { ok: true, value: String(raw).trim() }
+  }
+}
+
+export function normalizeRunParameters(
+  declared: RunParameter[] | undefined,
+  direction: 'import' | 'export',
+  raw: Record<string, unknown> | null | undefined,
+  entityType?: string,
+): NormalizeRunParametersResult {
+  const params = getApplicableRunParameters(declared, direction, entityType)
+  const input = raw && typeof raw === 'object' ? raw : {}
+  const values: Record<string, RunParameterValue> = {}
+  const errors: RunParameterError[] = []
+
+  for (const param of params) {
+    // Own-property lookup only: a parameter declared under an inherited name
+    // (`constructor`, `toString`, `valueOf`) would otherwise read back the
+    // inherited function instead of `undefined`, so a required check would
+    // silently pass and a string parameter would coerce the function source.
+    const provided = Object.prototype.hasOwnProperty.call(input, param.key)
+      ? (input as Record<string, unknown>)[param.key]
+      : undefined
+
+    if (isBlank(provided)) {
+      if (param.defaultValue === undefined) {
+        if (param.required) errors.push(buildRunParameterError(param, 'required'))
+        continue
+      }
+      // The declared default goes through the same checks as a submitted
+      // value, so a misdeclared adapter (a `select` default outside its own
+      // options, a number below its own `min`) fails loudly here rather than
+      // shipping an invalid value to itself mid-run.
+      const fallback = coerceDeclaredValue(param, param.defaultValue)
+      if (fallback.ok) values[param.key] = fallback.value
+      else errors.push(fallback.error)
+      continue
+    }
+
+    const coerced = coerceDeclaredValue(param, provided)
+    if (coerced.ok) values[param.key] = coerced.value
+    else errors.push(coerced.error)
+  }
+
+  if (errors.length > 0) return { ok: false, errors }
+  return { ok: true, values }
+}

package/src/modules/data_sync/lib/start-run.ts

@@ -16,6 +16,7 @@ export type StartDataSyncRunInput = {
   cursor?: string | null
   triggeredBy?: string | null
   batchSize?: number
+  parameters?: Record<string, unknown> | null
   createProgressJob?: boolean
   progressJob?: {
     jobType?: string
@@ -64,6 +65,7 @@ export async function startDataSyncRun(params: {
       direction: input.direction,
       cursor: input.cursor ?? null,
       triggeredBy: input.triggeredBy ?? scope.userId ?? null,
+      parameters: input.parameters ?? null,
       progressJobId: progressJob?.id ?? null,
     },
     {