@open-mercato/core 0.4.6-develop-6d72ec5960 → 0.4.6-develop-cd1e2a9a0e

package/dist/modules/integrations/migrations/Migration20260304113737.js

@@ -0,0 +1,19 @@
+import { Migration } from "@mikro-orm/migrations";
+class Migration20260304113737 extends Migration {
+  async up() {
+    this.addSql(`create table "integration_credentials" ("id" uuid not null default gen_random_uuid(), "integration_id" text not null, "credentials" jsonb not null, "organization_id" uuid not null, "tenant_id" uuid not null, "created_at" timestamptz not null, "updated_at" timestamptz not null, "deleted_at" timestamptz null, constraint "integration_credentials_pkey" primary key ("id"));`);
+    this.addSql(`create index "integration_credentials_integration_id_organizatio_291ea_index" on "integration_credentials" ("integration_id", "organization_id", "tenant_id");`);
+    this.addSql(`create table "integration_logs" ("id" uuid not null default gen_random_uuid(), "integration_id" text not null, "run_id" uuid null, "scope_entity_type" text null, "scope_entity_id" uuid null, "level" text not null, "message" text not null, "code" text null, "payload" jsonb null, "organization_id" uuid not null, "tenant_id" uuid not null, "created_at" timestamptz not null, constraint "integration_logs_pkey" primary key ("id"));`);
+    this.addSql(`create index "integration_logs_level_organization_id_tenant_id_c_107e7_index" on "integration_logs" ("level", "organization_id", "tenant_id", "created_at");`);
+    this.addSql(`create index "integration_logs_integration_id_organization_id_te_38189_index" on "integration_logs" ("integration_id", "organization_id", "tenant_id", "created_at");`);
+    this.addSql(`create table "integration_states" ("id" uuid not null default gen_random_uuid(), "integration_id" text not null, "is_enabled" boolean not null default true, "api_version" text null, "reauth_required" boolean not null default false, "last_health_status" text null, "last_health_checked_at" timestamptz null, "organization_id" uuid not null, "tenant_id" uuid not null, "created_at" timestamptz not null, "updated_at" timestamptz not null, "deleted_at" timestamptz null, constraint "integration_states_pkey" primary key ("id"));`);
+    this.addSql(`create index "integration_states_integration_id_organization_id__32acc_index" on "integration_states" ("integration_id", "organization_id", "tenant_id");`);
+    this.addSql(`create table "sync_external_id_mappings" ("id" uuid not null default gen_random_uuid(), "integration_id" text not null, "internal_entity_type" text not null, "internal_entity_id" uuid not null, "external_id" text not null, "sync_status" text not null default 'not_synced', "last_synced_at" timestamptz null, "organization_id" uuid not null, "tenant_id" uuid not null, "created_at" timestamptz not null, "updated_at" timestamptz not null, "deleted_at" timestamptz null, constraint "sync_external_id_mappings_pkey" primary key ("id"));`);
+    this.addSql(`create index "sync_external_id_mappings_integration_id_external__c088c_index" on "sync_external_id_mappings" ("integration_id", "external_id", "organization_id");`);
+    this.addSql(`create index "sync_external_id_mappings_internal_entity_type_int_f9194_index" on "sync_external_id_mappings" ("internal_entity_type", "internal_entity_id", "organization_id");`);
+  }
+}
+export {
+  Migration20260304113737
+};
+//# sourceMappingURL=Migration20260304113737.js.map

package/dist/modules/integrations/migrations/Migration20260304113737.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/integrations/migrations/Migration20260304113737.ts"],
+  "sourcesContent": ["import { Migration } from '@mikro-orm/migrations';\n\nexport class Migration20260304113737 extends Migration {\n\n  override async up(): Promise<void> {\n    this.addSql(`create table \"integration_credentials\" (\"id\" uuid not null default gen_random_uuid(), \"integration_id\" text not null, \"credentials\" jsonb not null, \"organization_id\" uuid not null, \"tenant_id\" uuid not null, \"created_at\" timestamptz not null, \"updated_at\" timestamptz not null, \"deleted_at\" timestamptz null, constraint \"integration_credentials_pkey\" primary key (\"id\"));`);\n    this.addSql(`create index \"integration_credentials_integration_id_organizatio_291ea_index\" on \"integration_credentials\" (\"integration_id\", \"organization_id\", \"tenant_id\");`);\n\n    this.addSql(`create table \"integration_logs\" (\"id\" uuid not null default gen_random_uuid(), \"integration_id\" text not null, \"run_id\" uuid null, \"scope_entity_type\" text null, \"scope_entity_id\" uuid null, \"level\" text not null, \"message\" text not null, \"code\" text null, \"payload\" jsonb null, \"organization_id\" uuid not null, \"tenant_id\" uuid not null, \"created_at\" timestamptz not null, constraint \"integration_logs_pkey\" primary key (\"id\"));`);\n    this.addSql(`create index \"integration_logs_level_organization_id_tenant_id_c_107e7_index\" on \"integration_logs\" (\"level\", \"organization_id\", \"tenant_id\", \"created_at\");`);\n    this.addSql(`create index \"integration_logs_integration_id_organization_id_te_38189_index\" on \"integration_logs\" (\"integration_id\", \"organization_id\", \"tenant_id\", \"created_at\");`);\n\n    this.addSql(`create table \"integration_states\" (\"id\" uuid not null default gen_random_uuid(), \"integration_id\" text not null, \"is_enabled\" boolean not null default true, \"api_version\" text null, \"reauth_required\" boolean not null default false, \"last_health_status\" text null, \"last_health_checked_at\" timestamptz null, \"organization_id\" uuid not null, \"tenant_id\" uuid not null, \"created_at\" timestamptz not null, \"updated_at\" timestamptz not null, \"deleted_at\" timestamptz null, constraint \"integration_states_pkey\" primary key (\"id\"));`);\n    this.addSql(`create index \"integration_states_integration_id_organization_id__32acc_index\" on \"integration_states\" (\"integration_id\", \"organization_id\", \"tenant_id\");`);\n\n    this.addSql(`create table \"sync_external_id_mappings\" (\"id\" uuid not null default gen_random_uuid(), \"integration_id\" text not null, \"internal_entity_type\" text not null, \"internal_entity_id\" uuid not null, \"external_id\" text not null, \"sync_status\" text not null default 'not_synced', \"last_synced_at\" timestamptz null, \"organization_id\" uuid not null, \"tenant_id\" uuid not null, \"created_at\" timestamptz not null, \"updated_at\" timestamptz not null, \"deleted_at\" timestamptz null, constraint \"sync_external_id_mappings_pkey\" primary key (\"id\"));`);\n    this.addSql(`create index \"sync_external_id_mappings_integration_id_external__c088c_index\" on \"sync_external_id_mappings\" (\"integration_id\", \"external_id\", \"organization_id\");`);\n    this.addSql(`create index \"sync_external_id_mappings_internal_entity_type_int_f9194_index\" on \"sync_external_id_mappings\" (\"internal_entity_type\", \"internal_entity_id\", \"organization_id\");`);\n  }\n\n}\n"],
+  "mappings": "AAAA,SAAS,iBAAiB;AAEnB,MAAM,gCAAgC,UAAU;AAAA,EAErD,MAAe,KAAoB;AACjC,SAAK,OAAO,qXAAqX;AACjY,SAAK,OAAO,gKAAgK;AAE5K,SAAK,OAAO,+aAA+a;AAC3b,SAAK,OAAO,8JAA8J;AAC1K,SAAK,OAAO,uKAAuK;AAEnL,SAAK,OAAO,+gBAA+gB;AAC3hB,SAAK,OAAO,2JAA2J;AAEvK,SAAK,OAAO,uhBAAuhB;AACniB,SAAK,OAAO,oKAAoK;AAChL,SAAK,OAAO,iLAAiL;AAAA,EAC/L;AAEF;",
+  "names": []
+}

package/dist/modules/integrations/setup.js

@@ -1,7 +1,7 @@
 const setup = {
   defaultRoleFeatures: {
-    superadmin: ["integrations.view", "integrations.manage"],
-    admin: ["integrations.view", "integrations.manage"],
+    superadmin: ["integrations.view", "integrations.manage", "integrations.credentials.manage"],
+    admin: ["integrations.view", "integrations.manage", "integrations.credentials.manage"],
     employee: ["integrations.view"]
   }
 };

package/dist/modules/integrations/setup.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/modules/integrations/setup.ts"],
-  "sourcesContent": ["import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'\n\nexport const setup: ModuleSetupConfig = {\n  defaultRoleFeatures: {\n    superadmin: ['integrations.view', 'integrations.manage'],\n    admin: ['integrations.view', 'integrations.manage'],\n    employee: ['integrations.view'],\n  },\n}\n\nexport default setup\n"],
-  "mappings": "AAEO,MAAM,QAA2B;AAAA,EACtC,qBAAqB;AAAA,IACnB,YAAY,CAAC,qBAAqB,qBAAqB;AAAA,IACvD,OAAO,CAAC,qBAAqB,qBAAqB;AAAA,IAClD,UAAU,CAAC,mBAAmB;AAAA,EAChC;AACF;AAEA,IAAO,gBAAQ;",
+  "sourcesContent": ["import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'\n\nexport const setup: ModuleSetupConfig = {\n  defaultRoleFeatures: {\n    superadmin: ['integrations.view', 'integrations.manage', 'integrations.credentials.manage'],\n    admin: ['integrations.view', 'integrations.manage', 'integrations.credentials.manage'],\n    employee: ['integrations.view'],\n  },\n}\n\nexport default setup\n"],
+  "mappings": "AAEO,MAAM,QAA2B;AAAA,EACtC,qBAAqB;AAAA,IACnB,YAAY,CAAC,qBAAqB,uBAAuB,iCAAiC;AAAA,IAC1F,OAAO,CAAC,qBAAqB,uBAAuB,iCAAiC;AAAA,IACrF,UAAU,CAAC,mBAAmB;AAAA,EAChC;AACF;AAEA,IAAO,gBAAQ;",
   "names": []
 }

package/dist/modules/integrations/widgets/injection-table.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/modules/integrations/widgets/injection-table.ts"],
-  "sourcesContent": ["import type { ModuleInjectionTable } from '@open-mercato/shared/modules/widgets/injection'\n\n/**\n * Integrations module injection table.\n *\n * The external-ids widget auto-appears on entity detail pages via wildcard spot matching.\n * Status badge widgets are registered by individual integration modules (e.g. sync_medusa).\n */\nexport const injectionTable: ModuleInjectionTable = {\n  // External IDs widget appears in detail page sidebars for all entities\n  'detail:*:sidebar': {\n    widgetId: 'integrations.injection.external-ids',\n    priority: -10,\n  },\n}\n\nexport default injectionTable\n"],
+  "sourcesContent": ["import type { ModuleInjectionTable } from '@open-mercato/shared/modules/widgets/injection'\n\n/**\n * Integrations module injection table.\n *\n * The external-ids widget auto-appears on entity detail pages via wildcard spot matching.\n * Status badge widgets are registered by individual integration provider modules.\n */\nexport const injectionTable: ModuleInjectionTable = {\n  // External IDs widget appears in detail page sidebars for all entities\n  'detail:*:sidebar': {\n    widgetId: 'integrations.injection.external-ids',\n    priority: -10,\n  },\n}\n\nexport default injectionTable\n"],
   "mappings": "AAQO,MAAM,iBAAuC;AAAA;AAAA,EAElD,oBAAoB;AAAA,IAClB,UAAU;AAAA,IACV,UAAU;AAAA,EACZ;AACF;AAEA,IAAO,0BAAQ;",
   "names": []
 }

package/dist/modules/integrations/workers/log-pruner.js

@@ -0,0 +1,18 @@
+const metadata = {
+  queue: "integration-log-pruner",
+  id: "integrations:log-pruner",
+  concurrency: 1
+};
+async function handle(job, ctx) {
+  const logService = ctx.resolve("integrationLogService");
+  const pruned = await logService.pruneOlderThan(job.payload.retentionDays, job.payload.scope);
+  if (pruned > 0) {
+    const logger = logService.scoped("integrations", job.payload.scope);
+    await logger.info(`Pruned ${pruned} log entries older than ${job.payload.retentionDays} days`);
+  }
+}
+export {
+  handle as default,
+  metadata
+};
+//# sourceMappingURL=log-pruner.js.map

package/dist/modules/integrations/workers/log-pruner.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/integrations/workers/log-pruner.ts"],
+  "sourcesContent": ["import type { JobContext, QueuedJob, WorkerMeta } from '@open-mercato/queue'\nimport type { IntegrationLogService } from '../lib/log-service'\n\ntype LogPrunerPayload = {\n  retentionDays: number\n  scope: {\n    organizationId: string\n    tenantId: string\n  }\n}\n\nexport const metadata: WorkerMeta = {\n  queue: 'integration-log-pruner',\n  id: 'integrations:log-pruner',\n  concurrency: 1,\n}\n\ntype HandlerContext = JobContext & {\n  resolve: <T = unknown>(name: string) => T\n}\n\nexport default async function handle(job: QueuedJob<LogPrunerPayload>, ctx: HandlerContext): Promise<void> {\n  const logService = ctx.resolve<IntegrationLogService>('integrationLogService')\n  const pruned = await logService.pruneOlderThan(job.payload.retentionDays, job.payload.scope)\n\n  if (pruned > 0) {\n    const logger = logService.scoped('integrations', job.payload.scope)\n    await logger.info(`Pruned ${pruned} log entries older than ${job.payload.retentionDays} days`)\n  }\n}\n"],
+  "mappings": "AAWO,MAAM,WAAuB;AAAA,EAClC,OAAO;AAAA,EACP,IAAI;AAAA,EACJ,aAAa;AACf;AAMA,eAAO,OAA8B,KAAkC,KAAoC;AACzG,QAAM,aAAa,IAAI,QAA+B,uBAAuB;AAC7E,QAAM,SAAS,MAAM,WAAW,eAAe,IAAI,QAAQ,eAAe,IAAI,QAAQ,KAAK;AAE3F,MAAI,SAAS,GAAG;AACd,UAAM,SAAS,WAAW,OAAO,gBAAgB,IAAI,QAAQ,KAAK;AAClE,UAAM,OAAO,KAAK,UAAU,MAAM,2BAA2B,IAAI,QAAQ,aAAa,OAAO;AAAA,EAC/F;AACF;",
+  "names": []
+}

package/generated/entities/integration_credentials/index.ts

@@ -0,0 +1,8 @@
+export const id = 'id'
+export const integration_id = 'integration_id'
+export const credentials = 'credentials'
+export const organization_id = 'organization_id'
+export const tenant_id = 'tenant_id'
+export const created_at = 'created_at'
+export const updated_at = 'updated_at'
+export const deleted_at = 'deleted_at'

package/generated/entities/integration_log/index.ts

@@ -0,0 +1,12 @@
+export const id = 'id'
+export const integration_id = 'integration_id'
+export const run_id = 'run_id'
+export const scope_entity_type = 'scope_entity_type'
+export const scope_entity_id = 'scope_entity_id'
+export const level = 'level'
+export const message = 'message'
+export const code = 'code'
+export const payload = 'payload'
+export const organization_id = 'organization_id'
+export const tenant_id = 'tenant_id'
+export const created_at = 'created_at'

package/generated/entities/integration_state/index.ts

@@ -0,0 +1,12 @@
+export const id = 'id'
+export const integration_id = 'integration_id'
+export const is_enabled = 'is_enabled'
+export const api_version = 'api_version'
+export const reauth_required = 'reauth_required'
+export const last_health_status = 'last_health_status'
+export const last_health_checked_at = 'last_health_checked_at'
+export const organization_id = 'organization_id'
+export const tenant_id = 'tenant_id'
+export const created_at = 'created_at'
+export const updated_at = 'updated_at'
+export const deleted_at = 'deleted_at'

package/generated/entities/sync_cursor/index.ts

@@ -0,0 +1,8 @@
+export const id = 'id'
+export const integration_id = 'integration_id'
+export const entity_type = 'entity_type'
+export const direction = 'direction'
+export const cursor = 'cursor'
+export const organization_id = 'organization_id'
+export const tenant_id = 'tenant_id'
+export const updated_at = 'updated_at'

package/generated/entities/sync_external_id_mapping/index.ts

@@ -0,0 +1,12 @@
+export const id = 'id'
+export const integration_id = 'integration_id'
+export const internal_entity_type = 'internal_entity_type'
+export const internal_entity_id = 'internal_entity_id'
+export const external_id = 'external_id'
+export const sync_status = 'sync_status'
+export const last_synced_at = 'last_synced_at'
+export const organization_id = 'organization_id'
+export const tenant_id = 'tenant_id'
+export const created_at = 'created_at'
+export const updated_at = 'updated_at'
+export const deleted_at = 'deleted_at'

package/generated/entities/sync_mapping/index.ts

@@ -0,0 +1,8 @@
+export const id = 'id'
+export const integration_id = 'integration_id'
+export const entity_type = 'entity_type'
+export const mapping = 'mapping'
+export const organization_id = 'organization_id'
+export const tenant_id = 'tenant_id'
+export const created_at = 'created_at'
+export const updated_at = 'updated_at'

package/generated/entities/sync_run/index.ts

@@ -0,0 +1,21 @@
+export const id = 'id'
+export const integration_id = 'integration_id'
+export const entity_type = 'entity_type'
+export const direction = 'direction'
+export const status = 'status'
+export const cursor = 'cursor'
+export const initial_cursor = 'initial_cursor'
+export const created_count = 'created_count'
+export const updated_count = 'updated_count'
+export const skipped_count = 'skipped_count'
+export const failed_count = 'failed_count'
+export const batches_completed = 'batches_completed'
+export const last_error = 'last_error'
+export const progress_job_id = 'progress_job_id'
+export const job_id = 'job_id'
+export const triggered_by = 'triggered_by'
+export const organization_id = 'organization_id'
+export const tenant_id = 'tenant_id'
+export const created_at = 'created_at'
+export const updated_at = 'updated_at'
+export const deleted_at = 'deleted_at'

package/generated/entities/sync_schedule/index.ts

@@ -0,0 +1,16 @@
+export const id = 'id'
+export const integration_id = 'integration_id'
+export const entity_type = 'entity_type'
+export const direction = 'direction'
+export const schedule_type = 'schedule_type'
+export const schedule_value = 'schedule_value'
+export const timezone = 'timezone'
+export const full_sync = 'full_sync'
+export const is_enabled = 'is_enabled'
+export const scheduled_job_id = 'scheduled_job_id'
+export const last_run_at = 'last_run_at'
+export const organization_id = 'organization_id'
+export const tenant_id = 'tenant_id'
+export const created_at = 'created_at'
+export const updated_at = 'updated_at'
+export const deleted_at = 'deleted_at'

package/generated/entities.ids.generated.ts

@@ -24,6 +24,8 @@ export const M = {
   "staff": "staff",
   "notifications": "notifications",
   "progress": "progress",
+  "integrations": "integrations",
+  "data_sync": "data_sync",
   "messages": "messages",
   "translations": "translations",
   "inbox_ops": "inbox_ops"
@@ -198,6 +200,18 @@ export const E = {
   "progress": {
     "progress_job": "progress:progress_job"
   },
+  "integrations": {
+    "sync_external_id_mapping": "integrations:sync_external_id_mapping",
+    "integration_credentials": "integrations:integration_credentials",
+    "integration_state": "integrations:integration_state",
+    "integration_log": "integrations:integration_log"
+  },
+  "data_sync": {
+    "sync_run": "data_sync:sync_run",
+    "sync_cursor": "data_sync:sync_cursor",
+    "sync_mapping": "data_sync:sync_mapping",
+    "sync_schedule": "data_sync:sync_schedule"
+  },
   "messages": {
     "message": "messages:message",
     "message_recipient": "messages:message_recipient",

package/generated/entity-fields-registry.ts

@@ -61,6 +61,9 @@ import * as inbox_proposal_action from './entities/inbox_proposal_action/index'
 import * as inbox_settings from './entities/inbox_settings/index'
 import * as indexer_error_log from './entities/indexer_error_log/index'
 import * as indexer_status_log from './entities/indexer_status_log/index'
+import * as integration_credentials from './entities/integration_credentials/index'
+import * as integration_log from './entities/integration_log/index'
+import * as integration_state from './entities/integration_state/index'
 import * as message from './entities/message/index'
 import * as message_access_token from './entities/message_access_token/index'
 import * as message_confirmation from './entities/message_confirmation/index'
@@ -123,6 +126,11 @@ import * as staff_team_member_comment from './entities/staff_team_member_comment
 import * as staff_team_member_job_history from './entities/staff_team_member_job_history/index'
 import * as staff_team_role from './entities/staff_team_role/index'
 import * as step_instance from './entities/step_instance/index'
+import * as sync_cursor from './entities/sync_cursor/index'
+import * as sync_external_id_mapping from './entities/sync_external_id_mapping/index'
+import * as sync_mapping from './entities/sync_mapping/index'
+import * as sync_run from './entities/sync_run/index'
+import * as sync_schedule from './entities/sync_schedule/index'
 import * as tenant from './entities/tenant/index'
 import * as upgrade_action_run from './entities/upgrade_action_run/index'
 import * as user from './entities/user/index'
@@ -197,6 +205,9 @@ export const entityFieldsRegistry: Record<string, Record<string, string>> = {
   inbox_settings,
   indexer_error_log,
   indexer_status_log,
+  integration_credentials,
+  integration_log,
+  integration_state,
   message,
   message_access_token,
   message_confirmation,
@@ -259,6 +270,11 @@ export const entityFieldsRegistry: Record<string, Record<string, string>> = {
   staff_team_member_job_history,
   staff_team_role,
   step_instance,
+  sync_cursor,
+  sync_external_id_mapping,
+  sync_mapping,
+  sync_run,
+  sync_schedule,
   tenant,
   upgrade_action_run,
   user,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/core",
-  "version": "0.4.6-develop-6d72ec5960",
+  "version": "0.4.6-develop-cd1e2a9a0e",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -207,7 +207,7 @@
     }
   },
   "dependencies": {
-    "@open-mercato/shared": "0.4.6-develop-6d72ec5960",
+    "@open-mercato/shared": "0.4.6-develop-cd1e2a9a0e",
     "@types/html-to-text": "^9.0.4",
     "@types/semver": "^7.5.8",
     "@xyflow/react": "^12.6.0",

package/src/modules/data_sync/AGENTS.md

@@ -0,0 +1,157 @@
+# Data Sync Module — Agent Guide
+
+The `data_sync` module provides a streaming data synchronization hub for import/export operations with external systems. It uses an adapter pattern where provider modules register `DataSyncAdapter` implementations.
+
+**Spec**: `.ai/specs/SPEC-045b-data-sync-hub.md`
+
+---
+
+## Module Structure
+
+```
+packages/core/src/modules/data_sync/
+├── index.ts                     # Module metadata
+├── di.ts                        # DI registrations
+├── acl.ts                       # Features: view, run, configure
+├── setup.ts                     # Default role features
+├── events.ts                    # 4 run lifecycle events
+├── data/
+│   ├── entities.ts              # SyncRun, SyncCursor, SyncMapping, SyncSchedule
+│   └── validators.ts            # Zod schemas
+├── lib/
+│   ├── adapter.ts               # DataSyncAdapter interface + batch types
+│   ├── adapter-registry.ts      # Register/get adapters by providerKey
+│   ├── id-mapping.ts            # External ID ↔ local ID lookup and storage
+│   ├── queue.ts                 # Queue helper for enqueuing sync jobs
+│   ├── sync-engine.ts           # Orchestrates streaming import/export with progress
+│   └── sync-run-service.ts      # CRUD for SyncRun + cursor management
+├── api/
+│   ├── run.ts                   # POST /api/data_sync/run — start a sync
+│   ├── runs.ts                  # GET /api/data_sync/runs — list runs
+│   ├── validate.ts              # POST /api/data_sync/validate — validate connection
+│   ├── runs/[id]/
+│   │   ├── route.ts             # GET — run detail
+│   │   ├── cancel.ts            # POST — cancel running sync
+│   │   └── retry.ts             # POST — retry failed sync
+│   └── mappings/
+│       ├── route.ts             # GET/POST — list/create field mappings
+│       └── [id]/route.ts        # GET/PUT/DELETE — manage individual mapping
+├── workers/
+│   ├── sync-import.ts           # Queue handler for import jobs (concurrency: 5)
+│   ├── sync-export.ts           # Queue handler for export jobs (concurrency: 5)
+│   └── sync-scheduled.ts        # Handles scheduler dispatch → creates run + enqueues
+├── backend/
+│   └── data-sync/
+│       ├── page.tsx             # Sync runs dashboard (DataTable)
+│       ├── page.meta.ts
+│       └── runs/[id]/
+│           ├── page.tsx         # Run detail (progress bar, counters, logs)
+│           └── page.meta.ts
+└── i18n/
+    ├── en.json
+    └── pl.json
+```
+
+## Key Services (DI)
+
+| Service Name | Purpose |
+|---|---|
+| `dataSyncRunService` | CRUD for SyncRun, cursor management, overlap detection |
+| `dataSyncEngine` | Orchestrates streaming import/export with batch processing, progress, error logging |
+| `externalIdMappingService` | Maps local entity IDs ↔ external system IDs |
+
+## Adapter Contract
+
+Provider modules implement `DataSyncAdapter`:
+
+```typescript
+interface DataSyncAdapter {
+  providerKey: string
+  direction: 'import' | 'export' | 'bidirectional'
+  supportedEntities: string[]
+  streamImport(entityType: string, cursor: string | null, config: SyncConfig): AsyncIterable<ImportBatch>
+  streamExport?(entityType: string, cursor: string | null, config: SyncConfig): AsyncIterable<ExportBatch>
+  getInitialCursor?(entityType: string): Promise<string | null>
+  getMapping?(entityType: string): Promise<FieldMapping[]>
+  validateConnection?(credentials: Record<string, unknown>): Promise<{ valid: boolean; message?: string }>
+}
+```
+
+Register adapters in your provider module's `di.ts`:
+```typescript
+registerDataSyncAdapter(myAdapter)
+```
+
+## Run Lifecycle
+
+`pending` → `running` → `completed` | `failed` | `cancelled`
+
+- **Cursor persistence**: After each batch, cursor is saved to `SyncCursor`
+- **Resume**: Retry reads the last successful cursor, resumes from there
+- **Progress**: Linked to `ProgressJob` via `progressJobId` for `ProgressTopBar` display
+- **Cancellation**: Via `progressService.isCancellationRequested()`
+
+## Queue Names
+
+| Queue | Worker | Concurrency |
+|---|---|---|
+| `data-sync-import` | `sync-import.ts` | 5 |
+| `data-sync-export` | `sync-export.ts` | 5 |
+| `data-sync-scheduled` | `sync-scheduled.ts` | 3 |
+
+## Events
+
+| Event ID | Emitted When |
+|---|---|
+| `data_sync.run.started` | Sync run begins processing |
+| `data_sync.run.completed` | Sync run finishes successfully |
+| `data_sync.run.failed` | Sync run fails |
+| `data_sync.run.cancelled` | Sync run is cancelled |
+
+## ACL Features
+
+- `data_sync.view` — view sync runs and progress
+- `data_sync.run` — trigger, cancel, retry syncs
+- `data_sync.configure` — manage field mappings and schedules
+
+## UMES Extensibility
+
+Data sync providers can leverage the **Unified Module Extension System (UMES)** to extend platform UI and behavior.
+
+### Available Extension Points for Sync Providers
+
+| Extension Mechanism | Use Case | Files |
+|---|---|---|
+| **Widget Injection** | Inject sync status badges, mapping previews, or progress indicators into entity pages | `widgets/injection/`, `widgets/injection-table.ts` |
+| **Event Subscribers** | React to sync lifecycle events (`data_sync.run.completed`, etc.) for side-effects | `subscribers/*.ts` |
+| **Entity Extensions** | Link sync metadata to core entities | `data/extensions.ts` |
+| **Response Enrichers** | Attach sync status or external ID data to other modules' API responses | `data/enrichers.ts` |
+| **Notifications** | Emit in-app notifications on sync completion/failure | `notifications.ts`, `subscribers/` |
+| **DOM Event Bridge** | Push real-time sync progress to browser (SSE) | Set `clientBroadcast: true` in event definitions |
+| **Menu Injection** | Add sidebar items for provider-specific sync dashboards | via `useInjectedMenuItems` |
+
+### Progress Delivery Contract
+
+- `ProgressTopBar` polls `/api/progress/active` every 5s (`useProgressPoll`).
+- Create `ProgressJob` in `run`/`retry` endpoints; start/update/complete/fail in `sync-engine`.
+- Include `progressJob` details in run detail response.
+- SSE DOM bridge forwards only events with `clientBroadcast: true`.
+- `data_sync.run.*` events are not yet marked `clientBroadcast: true` — polling is the active mechanism.
+- Do not claim SSE-driven progress for sync runs until event definitions and client wiring are explicitly enabled.
+
+### Integration Test Expectations
+
+- Module-local integration tests go under `__integration__/`
+- Use helpers from `@open-mercato/core/modules/core/__integration__/helpers/*`
+- Tests must create prerequisites via API and clean up in `finally`
+- Avoid hard dependency on late-phase modules; keep tests scoped to implemented contracts
+
+## MUST Rules
+
+- **Always scope by organizationId + tenantId** — every entity query
+- **Never import from provider adapter modules** — data_sync is generic
+- **Use the queue system** — never run syncs inline in API handlers
+- **Persist cursor after each batch** — enables resume on failure
+- **Log item-level errors** — don't stop the sync for individual item failures
+- **Check for overlap** before starting a new run (same integration + entityType + direction)
+- **API routes must export `openApi`** for documentation generation

package/src/modules/data_sync/acl.ts

@@ -0,0 +1,7 @@
+export const features = [
+  { id: 'data_sync.view', title: 'View sync runs', module: 'data_sync' },
+  { id: 'data_sync.run', title: 'Run sync operations', module: 'data_sync' },
+  { id: 'data_sync.configure', title: 'Configure sync mappings and schedules', module: 'data_sync' },
+]
+
+export default features

package/src/modules/data_sync/api/mappings/[id]/route.ts

@@ -0,0 +1,158 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { SyncMapping } from '../../../data/entities'
+
+const idParamsSchema = z.object({ id: z.string().uuid() })
+
+const updateMappingSchema = z.object({
+  mapping: z.record(z.string(), z.unknown()),
+})
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['data_sync.view'] },
+  PUT: { requireAuth: true, requireFeatures: ['data_sync.configure'] },
+  DELETE: { requireAuth: true, requireFeatures: ['data_sync.configure'] },
+}
+
+export const openApi = {
+  tags: ['DataSync'],
+  summary: 'Get, update, or delete a field mapping',
+}
+
+async function resolveParams(ctx: { params?: Promise<{ id?: string }> | { id?: string } }) {
+  const rawParams = (ctx.params && typeof (ctx.params as Promise<unknown>).then === 'function')
+    ? await (ctx.params as Promise<{ id?: string }>)
+    : (ctx.params as { id?: string } | undefined)
+  return idParamsSchema.safeParse(rawParams)
+}
+
+export async function GET(req: Request, ctx: { params?: Promise<{ id?: string }> | { id?: string } }) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.tenantId || !auth.orgId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const parsedParams = await resolveParams(ctx)
+  if (!parsedParams.success) {
+    return NextResponse.json({ error: 'Invalid mapping id' }, { status: 400 })
+  }
+
+  const container = await createRequestContainer()
+  const em = container.resolve('em') as EntityManager
+  const scope = { organizationId: auth.orgId as string, tenantId: auth.tenantId }
+
+  const mapping = await findOneWithDecryption(
+    em,
+    SyncMapping,
+    {
+      id: parsedParams.data.id,
+      organizationId: auth.orgId as string,
+      tenantId: auth.tenantId,
+    },
+    undefined,
+    scope,
+  )
+
+  if (!mapping) {
+    return NextResponse.json({ error: 'Mapping not found' }, { status: 404 })
+  }
+
+  return NextResponse.json({
+    id: mapping.id,
+    integrationId: mapping.integrationId,
+    entityType: mapping.entityType,
+    mapping: mapping.mapping,
+    createdAt: mapping.createdAt.toISOString(),
+    updatedAt: mapping.updatedAt.toISOString(),
+  })
+}
+
+export async function PUT(req: Request, ctx: { params?: Promise<{ id?: string }> | { id?: string } }) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.tenantId || !auth.orgId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const parsedParams = await resolveParams(ctx)
+  if (!parsedParams.success) {
+    return NextResponse.json({ error: 'Invalid mapping id' }, { status: 400 })
+  }
+
+  const payload = await req.json().catch(() => null)
+  const parsedBody = updateMappingSchema.safeParse(payload)
+  if (!parsedBody.success) {
+    return NextResponse.json({ error: 'Invalid payload', details: parsedBody.error.flatten() }, { status: 422 })
+  }
+
+  const container = await createRequestContainer()
+  const em = container.resolve('em') as EntityManager
+  const scope = { organizationId: auth.orgId as string, tenantId: auth.tenantId }
+
+  const mapping = await findOneWithDecryption(
+    em,
+    SyncMapping,
+    {
+      id: parsedParams.data.id,
+      organizationId: auth.orgId as string,
+      tenantId: auth.tenantId,
+    },
+    undefined,
+    scope,
+  )
+
+  if (!mapping) {
+    return NextResponse.json({ error: 'Mapping not found' }, { status: 404 })
+  }
+
+  mapping.mapping = parsedBody.data.mapping
+  await em.flush()
+
+  return NextResponse.json({
+    id: mapping.id,
+    integrationId: mapping.integrationId,
+    entityType: mapping.entityType,
+    mapping: mapping.mapping,
+    updatedAt: mapping.updatedAt.toISOString(),
+  })
+}
+
+export async function DELETE(req: Request, ctx: { params?: Promise<{ id?: string }> | { id?: string } }) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.tenantId || !auth.orgId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const parsedParams = await resolveParams(ctx)
+  if (!parsedParams.success) {
+    return NextResponse.json({ error: 'Invalid mapping id' }, { status: 400 })
+  }
+
+  const container = await createRequestContainer()
+  const em = container.resolve('em') as EntityManager
+  const scope = { organizationId: auth.orgId as string, tenantId: auth.tenantId }
+
+  const mapping = await findOneWithDecryption(
+    em,
+    SyncMapping,
+    {
+      id: parsedParams.data.id,
+      organizationId: auth.orgId as string,
+      tenantId: auth.tenantId,
+    },
+    undefined,
+    scope,
+  )
+
+  if (!mapping) {
+    return NextResponse.json({ error: 'Mapping not found' }, { status: 404 })
+  }
+
+  em.remove(mapping)
+  await em.flush()
+
+  return NextResponse.json({ deleted: true })
+}