@open-mercato/core 0.6.8-develop.6992.1.00c90fecff → 0.6.8-develop.6998.1.d2bc46c56c

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/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,
     },
     {

package/src/modules/data_sync/lib/sync-engine.ts

@@ -7,7 +7,7 @@ import type { ProgressService } from '../../progress/lib/progressService'
 import { STALE_JOB_TIMEOUT_SECONDS } from '../../progress/lib/progressService'
 import { refreshCoverageSnapshot } from '../../query_index/lib/coverage'
 import { emitDataSyncEvent } from '../events'
-import type { DataSyncAdapter, DataMapping, ExportBatch, ImportBatch } from './adapter'
+import type { DataSyncAdapter, DataMapping, ExportBatch, ImportBatch, RunParameterValue } from './adapter'
 import { getDataSyncAdapter, resolveProviderKey } from './adapter-registry'
 import type { SyncRunService } from './sync-run-service'
 import { SyncRunOwnershipConflictError } from './sync-run-service'
@@ -15,6 +15,8 @@ import { createLogger } from '@open-mercato/shared/lib/logger'
 
 const logger = createLogger('data_sync').child({ component: 'sync-engine' })
 
+type RunParameters = Record<string, RunParameterValue>
+
 type SyncScope = {
   organizationId: string
   tenantId: string
@@ -550,6 +552,7 @@ export function createSyncEngine(deps: EngineDeps) {
             mapping,
             scope: { organizationId: scope.organizationId, tenantId: scope.tenantId },
             runId: run.id,
+            parameters: (run.parameters ?? {}) as RunParameters,
           }),
           makeHeartbeatTick(run.progressJobId, scope),
           HEARTBEAT_TICK_MS,
@@ -714,6 +717,7 @@ export function createSyncEngine(deps: EngineDeps) {
             mapping,
             scope: { organizationId: scope.organizationId, tenantId: scope.tenantId },
             runId: run.id,
+            parameters: (run.parameters ?? {}) as RunParameters,
           }),
           makeHeartbeatTick(run.progressJobId, scope),
           HEARTBEAT_TICK_MS,

package/src/modules/data_sync/lib/sync-run-service.ts

@@ -115,6 +115,7 @@ export function createSyncRunService(em: EntityManager) {
       triggeredBy?: string | null
       progressJobId?: string | null
       jobId?: string | null
+      parameters?: Record<string, unknown> | null
     }, scope: SyncScope): Promise<SyncRun> {
       const row = em.create(SyncRun, {
         integrationId: input.integrationId,
@@ -126,6 +127,7 @@ export function createSyncRunService(em: EntityManager) {
         triggeredBy: input.triggeredBy,
         progressJobId: input.progressJobId,
         jobId: input.jobId,
+        parameters: input.parameters ?? null,
         organizationId: scope.organizationId,
         tenantId: scope.tenantId,
       })

package/src/modules/data_sync/migrations/.snapshot-open-mercato.json

@@ -668,6 +668,22 @@
           "comment": null,
           "enumItems": [],
           "mappedType": "integer"
+        },
+        "parameters": {
+          "name": "parameters",
+          "type": "jsonb",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": true,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "enumItems": [],
+          "mappedType": "json"
         }
       },
       "indexes": [
@@ -994,4 +1010,4 @@
   ],
   "views": [],
   "nativeEnums": {}
-}
+}

package/src/modules/data_sync/migrations/Migration20260810120000.ts

@@ -0,0 +1,13 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260810120000 extends Migration {
+
+  override async up(): Promise<void> {
+    this.addSql(`alter table "sync_runs" add column "parameters" jsonb null;`);
+  }
+
+  override async down(): Promise<void> {
+    this.addSql(`alter table "sync_runs" drop column "parameters";`);
+  }
+
+}

package/src/modules/data_sync/workers/sync-scheduled.ts

@@ -7,6 +7,10 @@ import type { SyncRunService } from '../lib/sync-run-service'
 import { SyncSchedule } from '../data/entities'
 import { startDataSyncRun } from '../lib/start-run'
 import { resolveAdapterForIntegration, resolveStartCursor } from '../lib/start-cursor'
+import { normalizeRunParameters } from '../lib/run-parameters'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const logger = createLogger('data_sync').child({ component: 'sync-scheduled' })
 
 type ScheduledSyncPayload = {
   scheduleId: string
@@ -64,17 +68,43 @@ export default async function handle(job: QueuedJob<ScheduledSyncPayload>, ctx:
     return
   }
 
+  const adapter = resolveAdapterForIntegration(schedule.integrationId)
+
   const cursor = schedule.fullSync
     ? null
     : await resolveStartCursor({
         syncRunService,
-        adapter: resolveAdapterForIntegration(schedule.integrationId),
+        adapter,
         integrationId: schedule.integrationId,
         entityType: schedule.entityType,
         direction: schedule.direction,
         scope: job.payload.scope,
       })
 
+  // A schedule carries no parameter form, but the adapter's declared defaults
+  // still apply: normalizing an empty input materializes exactly those, so a
+  // scheduled run reaches the adapter with the same set a manual run would
+  // rather than an empty object. A declaration whose own default is invalid
+  // stops the run instead of handing over a half-applied set.
+  const normalizedParameters = normalizeRunParameters(
+    adapter?.runParameters,
+    schedule.direction,
+    null,
+    schedule.entityType,
+  )
+  if (!normalizedParameters.ok) {
+    logger.error('Scheduled run skipped: adapter declares invalid run parameter defaults', {
+      scheduleId: schedule.id,
+      integrationId: schedule.integrationId,
+      entityType: schedule.entityType,
+      keys: normalizedParameters.errors.map((error) => error.key),
+    })
+    return
+  }
+  const parameters = Object.keys(normalizedParameters.values).length > 0
+    ? normalizedParameters.values
+    : null
+
   schedule.lastRunAt = new Date()
   await em.flush()
 
@@ -88,6 +118,7 @@ export default async function handle(job: QueuedJob<ScheduledSyncPayload>, ctx:
       direction: schedule.direction,
       cursor,
       triggeredBy: 'scheduler',
+      parameters,
     },
   })
 }