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

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

@@ -0,0 +1,27 @@
+import type { JobContext, QueuedJob, WorkerMeta } from '@open-mercato/queue'
+import type { SyncEngine } from '../lib/sync-engine'
+
+type SyncJobPayload = {
+  runId: string
+  batchSize: number
+  scope: {
+    organizationId: string
+    tenantId: string
+    userId?: string | null
+  }
+}
+
+export const metadata: WorkerMeta = {
+  queue: 'data-sync-export',
+  id: 'data-sync:export',
+  concurrency: 5,
+}
+
+type HandlerContext = JobContext & {
+  resolve: <T = unknown>(name: string) => T
+}
+
+export default async function handle(job: QueuedJob<SyncJobPayload>, ctx: HandlerContext): Promise<void> {
+  const engine = ctx.resolve<SyncEngine>('dataSyncEngine')
+  await engine.runExport(job.payload.runId, job.payload.batchSize, job.payload.scope)
+}

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

@@ -0,0 +1,27 @@
+import type { JobContext, QueuedJob, WorkerMeta } from '@open-mercato/queue'
+import type { SyncEngine } from '../lib/sync-engine'
+
+type SyncJobPayload = {
+  runId: string
+  batchSize: number
+  scope: {
+    organizationId: string
+    tenantId: string
+    userId?: string | null
+  }
+}
+
+export const metadata: WorkerMeta = {
+  queue: 'data-sync-import',
+  id: 'data-sync:import',
+  concurrency: 5,
+}
+
+type HandlerContext = JobContext & {
+  resolve: <T = unknown>(name: string) => T
+}
+
+export default async function handle(job: QueuedJob<SyncJobPayload>, ctx: HandlerContext): Promise<void> {
+  const engine = ctx.resolve<SyncEngine>('dataSyncEngine')
+  await engine.runImport(job.payload.runId, job.payload.batchSize, job.payload.scope)
+}

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

@@ -0,0 +1,84 @@
+import type { JobContext, QueuedJob, WorkerMeta } from '@open-mercato/queue'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import type { SyncRunService } from '../lib/sync-run-service'
+import { SyncSchedule } from '../data/entities'
+import { getSyncQueue } from '../lib/queue'
+
+type ScheduledSyncPayload = {
+  scheduleId: string
+  scope: {
+    organizationId: string
+    tenantId: string
+  }
+}
+
+export const metadata: WorkerMeta = {
+  queue: 'data-sync-scheduled',
+  id: 'data-sync:scheduled',
+  concurrency: 3,
+}
+
+type HandlerContext = JobContext & {
+  resolve: <T = unknown>(name: string) => T
+}
+
+export default async function handle(job: QueuedJob<ScheduledSyncPayload>, ctx: HandlerContext): Promise<void> {
+  const em = ctx.resolve<EntityManager>('em')
+  const syncRunService = ctx.resolve<SyncRunService>('dataSyncRunService')
+
+  const schedule = await findOneWithDecryption(
+    em,
+    SyncSchedule,
+    {
+      id: job.payload.scheduleId,
+      organizationId: job.payload.scope.organizationId,
+      tenantId: job.payload.scope.tenantId,
+      deletedAt: null,
+    },
+    undefined,
+    job.payload.scope,
+  )
+
+  if (!schedule || !schedule.isEnabled) {
+    return
+  }
+
+  const overlap = await syncRunService.findRunningOverlap(
+    schedule.integrationId,
+    schedule.entityType,
+    schedule.direction,
+    job.payload.scope,
+  )
+  if (overlap) {
+    return
+  }
+
+  const cursor = schedule.fullSync
+    ? null
+    : await syncRunService.resolveCursor(
+        schedule.integrationId,
+        schedule.entityType,
+        schedule.direction,
+        job.payload.scope,
+      )
+
+  const run = await syncRunService.createRun({
+    integrationId: schedule.integrationId,
+    entityType: schedule.entityType,
+    direction: schedule.direction,
+    cursor,
+    triggeredBy: 'scheduler',
+  }, job.payload.scope)
+
+  schedule.lastRunAt = new Date()
+  await em.flush()
+
+  const queueName = schedule.direction === 'import' ? 'data-sync-import' : 'data-sync-export'
+  const queue = getSyncQueue(queueName)
+  await queue.enqueue({
+    runId: run.id,
+    batchSize: 100,
+    scope: job.payload.scope,
+  })
+}

package/src/modules/entities/lib/encryptionDefaults.ts

@@ -144,6 +144,10 @@ export const DEFAULT_ENCRYPTION_MAPS: Array<{ entityId: string; fields: Array<{
       { field: 'context_json' },
     ],
   },
+  {
+    entityId: 'integrations:integration_credentials',
+    fields: [{ field: 'credentials' }],
+  },
   {
     entityId: 'staff:staff_leave_request',
     fields: [

package/src/modules/integrations/AGENTS.md

@@ -0,0 +1,160 @@
+# Integrations Module — Agent Guide
+
+The `integrations` module is the foundation layer for all external connectors (payment gateways, shipping carriers, communication channels, data sync providers, etc.). It provides three shared mechanisms: **Integration Registry**, **Credentials API**, and **Operation Logs**.
+
+**Spec**: `.ai/specs/SPEC-045-2026-02-24-integration-marketplace.md` + `.ai/specs/SPEC-045a-foundation.md`
+
+---
+
+## Module Structure
+
+```
+packages/core/src/modules/integrations/
+├── index.ts                     # Module metadata
+├── di.ts                        # DI registrations (4 services)
+├── acl.ts                       # Features: view, manage, credentials.manage
+├── setup.ts                     # Default role features
+├── events.ts                    # 4 typed events
+├── data/
+│   ├── entities.ts              # IntegrationCredentials, IntegrationState, IntegrationLog, SyncExternalIdMapping
+│   ├── validators.ts            # Zod schemas for all API inputs
+│   └── enrichers.ts             # External ID response enricher
+├── lib/
+│   ├── registry-service.ts      # Read-only access to in-memory integration registry
+│   ├── credentials-service.ts   # Encrypted CRUD + bundle credential fallthrough
+│   ├── state-service.ts         # Enable/disable + API version + reauth + health state
+│   ├── log-service.ts           # Structured logging with scoped loggers + pruning
+│   └── health-service.ts        # Resolves and runs provider health checks via DI
+├── api/
+│   ├── route.ts                 # GET /api/integrations — list all
+│   ├── logs/route.ts            # GET /api/integrations/logs — query logs
+│   └── [id]/
+│       ├── route.ts             # GET /api/integrations/:id — detail
+│       ├── state/route.ts       # PUT — enable/disable
+│       ├── credentials/route.ts # GET/PUT — read/save credentials
+│       ├── version/route.ts     # PUT — change API version
+│       └── health/route.ts      # POST — trigger health check
+├── workers/
+│   └── log-pruner.ts            # Scheduled log retention cleanup
+├── backend/
+│   └── integrations/
+│       ├── page.tsx             # Marketplace listing page
+│       ├── page.meta.ts
+│       ├── [id]/
+│       │   ├── page.tsx         # Integration detail (tabs: credentials/version/health/logs)
+│       │   └── page.meta.ts
+│       └── bundle/[id]/
+│           ├── page.tsx         # Bundle config (shared credentials + per-integration toggles)
+│           └── page.meta.ts
+├── widgets/
+│   ├── injection-table.ts
+│   └── injection/external-ids/
+│       └── widget.client.tsx    # External ID display for any entity detail page
+└── i18n/
+    ├── en.json
+    └── pl.json
+```
+
+## Key Services (DI)
+
+| Service Name | Factory | Purpose |
+|---|---|---|
+| `integrationCredentialsService` | `createCredentialsService(em)` | Encrypted credential CRUD with bundle fallthrough |
+| `integrationStateService` | `createIntegrationStateService(em)` | Upsert integration state (enabled, version, health, reauth) |
+| `integrationLogService` | `createIntegrationLogService(em)` | Structured logging: write, query, prune, scoped logger |
+| `integrationHealthService` | `createHealthService(container, stateService, logService)` | Resolves named health check service from DI, runs check, updates state |
+
+## Adding a New Integration Provider
+
+1. Create a new module (e.g., `packages/core/src/modules/gateway_stripe/`)
+2. Add `integration.ts` at the module root exporting `IntegrationDefinition`
+3. Declare `credentials.fields` for the admin UI to render a dynamic form
+4. Optionally declare `healthCheck.service` (register the service in your `di.ts`)
+5. Optionally declare `apiVersions` for versioned external APIs
+6. Run `yarn generate` to auto-discover the integration
+
+### Bundle Integrations
+
+For platform connectors with multiple integrations (e.g., MedusaJS):
+- Export `bundle: IntegrationBundle` and `integrations: IntegrationDefinition[]`
+- Set `bundleId` on each child integration
+- Bundle credentials are shared via fallthrough: child reads own credentials first, then bundle's
+
+## Credential Resolution Order
+
+1. Direct credentials for the integration ID
+2. If `bundleId` is set, fallback to bundle's credentials
+3. Return `null` if neither exists
+
+## Events
+
+| Event ID | Emitted When |
+|---|---|
+| `integrations.credentials.updated` | Credentials saved |
+| `integrations.state.updated` | Integration enabled/disabled or reauth flag changed |
+| `integrations.version.changed` | API version changed |
+| `integrations.log.created` | Log entry written (excluded from triggers) |
+
+## ACL Features
+
+- `integrations.view` — view marketplace, detail, logs
+- `integrations.manage` — enable/disable, change version, run health checks
+- `integrations.credentials.manage` — read/save credentials
+
+## UMES Extensibility
+
+Integration provider modules can leverage the full **Unified Module Extension System (UMES)** — see `.ai/specs/SPEC-041-2026-02-24-universal-module-extension-system.md` for details.
+
+### Available Extension Points for Providers
+
+| Extension Mechanism | Use Case | Files |
+|---|---|---|
+| **Widget Injection** | Inject UI tabs, cards, or status badges into other modules' pages | `widgets/injection/`, `widgets/injection-table.ts` |
+| **Event Subscribers** | React to integration events (`integrations.state.updated`, etc.) for side-effects | `subscribers/*.ts` |
+| **Entity Extensions** | Link provider data to core entities (e.g., external IDs on orders) | `data/extensions.ts` |
+| **Response Enrichers** | Attach provider-specific data to other modules' API responses | `data/enrichers.ts` |
+| **API Interceptors** | Intercept other modules' API routes (before/after hooks) | `api/interceptors.ts` |
+| **Component Replacement** | Override or wrap UI components from other modules | `widgets/components.ts` |
+| **Menu Injection** | Add sidebar/settings menu items | via `useInjectedMenuItems` |
+| **Notifications** | Emit in-app notifications on integration events | `notifications.ts`, `subscribers/` |
+| **DOM Event Bridge** | Push real-time events to browser (SSE) | Set `clientBroadcast: true` in event definitions |
+
+### Key UMES Imports for Providers
+
+```typescript
+import { InjectionPosition } from '@open-mercato/shared/modules/widgets/injection-position'
+import { useInjectionDataWidgets } from '@open-mercato/ui/backend/injection/useInjectionDataWidgets'
+import { useInjectedMenuItems } from '@open-mercato/ui/backend/injection/useInjectedMenuItems'
+import { useRegisteredComponent } from '@open-mercato/ui/backend/injection/useRegisteredComponent'
+import { useAppEvent } from '@open-mercato/ui/backend/injection/useAppEvent'
+import type { ResponseEnricher } from '@open-mercato/shared/lib/crud/response-enricher'
+import type { ApiInterceptor } from '@open-mercato/shared/lib/crud/api-interceptor'
+```
+
+### Example: External ID Widget
+
+The integrations module itself uses UMES to inject external ID displays on any entity detail page via `widgets/injection/external-ids/widget.client.tsx`, mapped through `widgets/injection-table.ts`. Follow this pattern for provider-specific widgets.
+
+## Progress Delivery Contract
+
+- `ProgressTopBar` polls `/api/progress/active` every 5s (`useProgressPoll`).
+- SSE DOM bridge forwards only events with `clientBroadcast: true`.
+- `progress.job.*` events are not yet marked `clientBroadcast: true` — polling is the active mechanism.
+
+## 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`
+
+## MUST Rules
+
+- **Never import from provider modules** — integrations module is generic; providers import from integrations, not vice versa
+- **Always scope by organizationId + tenantId** — every entity query and service call
+- **Use `findWithDecryption`/`findOneWithDecryption`** for credential reads
+- **Never log credential values** — log service strips secret fields from payload
+- **Health check services** must be registered in DI by the provider module, not by integrations
+- **API routes must export `openApi`** for documentation generation
+- **All user-facing strings** via i18n keys in `i18n/en.json`
+- **Keep ACL default export shape** consistent: `export const features = [...]; export default features`
+- **Registry/type contracts** live in `@open-mercato/shared/modules/integrations/types`

package/src/modules/integrations/acl.ts

@@ -1,4 +1,7 @@
 export const features = [
   { id: 'integrations.view', title: 'View integrations and external ID mappings', module: 'integrations' },
   { id: 'integrations.manage', title: 'Manage integration configurations', module: 'integrations' },
+  { id: 'integrations.credentials.manage', title: 'Manage integration credentials', module: 'integrations' },
 ]
+
+export default features

package/src/modules/integrations/api/[id]/credentials/route.ts

@@ -0,0 +1,142 @@
+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 { getIntegration } from '@open-mercato/shared/modules/integrations/types'
+import { emitIntegrationsEvent } from '../../../events'
+import { saveCredentialsSchema } from '../../../data/validators'
+import type { CredentialsService } from '../../../lib/credentials-service'
+import {
+  resolveUserFeatures,
+  runIntegrationMutationGuardAfterSuccess,
+  runIntegrationMutationGuards,
+} from '../../guards'
+
+const idParamsSchema = z.object({ id: z.string().min(1) })
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['integrations.credentials.manage'] },
+  PUT: { requireAuth: true, requireFeatures: ['integrations.credentials.manage'] },
+}
+
+export const openApi = {
+  tags: ['Integrations'],
+  summary: 'Get or save integration credentials',
+}
+
+function resolveParams(ctx: { params?: Promise<{ id?: string }> | { id?: string } }): Promise<{ id?: string } | undefined> | { id?: string } | undefined {
+  if (!ctx.params) return undefined
+  if (typeof (ctx.params as Promise<unknown>).then === 'function') {
+    return ctx.params as Promise<{ id?: string }>
+  }
+  return ctx.params as { id?: string }
+}
+
+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 rawParams = await resolveParams(ctx)
+  const parsedParams = idParamsSchema.safeParse(rawParams)
+  if (!parsedParams.success) {
+    return NextResponse.json({ error: 'Invalid integration id' }, { status: 400 })
+  }
+
+  const integration = getIntegration(parsedParams.data.id)
+  if (!integration) {
+    return NextResponse.json({ error: 'Integration not found' }, { status: 404 })
+  }
+
+  const container = await createRequestContainer()
+  const credentialsService = container.resolve('integrationCredentialsService') as CredentialsService
+  const scope = { organizationId: auth.orgId as string, tenantId: auth.tenantId }
+
+  const values = await credentialsService.resolve(integration.id, scope)
+
+  return NextResponse.json({
+    integrationId: integration.id,
+    schema: credentialsService.getSchema(integration.id),
+    credentials: values ?? {},
+  })
+}
+
+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 rawParams = await resolveParams(ctx)
+  const parsedParams = idParamsSchema.safeParse(rawParams)
+  if (!parsedParams.success) {
+    return NextResponse.json({ error: 'Invalid integration id' }, { status: 400 })
+  }
+
+  const integration = getIntegration(parsedParams.data.id)
+  if (!integration) {
+    return NextResponse.json({ error: 'Integration not found' }, { status: 404 })
+  }
+
+  const payload = await req.json().catch(() => null)
+  const parsedBody = saveCredentialsSchema.safeParse(payload)
+  if (!parsedBody.success) {
+    return NextResponse.json({ error: 'Invalid credentials payload', details: parsedBody.error.flatten() }, { status: 422 })
+  }
+
+  const container = await createRequestContainer()
+  const guardResult = await runIntegrationMutationGuards(
+    container,
+    {
+    tenantId: auth.tenantId,
+    organizationId: auth.orgId,
+    userId: auth.sub ?? '',
+    resourceKind: 'integrations.integration',
+    resourceId: integration.id,
+    operation: 'update',
+    requestMethod: req.method,
+    requestHeaders: req.headers,
+    mutationPayload: parsedBody.data as Record<string, unknown>,
+    },
+    resolveUserFeatures(auth),
+  )
+  if (!guardResult.ok) {
+    return NextResponse.json(guardResult.errorBody ?? { error: 'Operation blocked by guard' }, { status: guardResult.errorStatus ?? 422 })
+  }
+
+  let payloadData = parsedBody.data
+  if (guardResult.modifiedPayload) {
+    const mergedPayload = { ...parsedBody.data, ...guardResult.modifiedPayload }
+    const reparsed = saveCredentialsSchema.safeParse(mergedPayload)
+    if (!reparsed.success) {
+      return NextResponse.json({ error: 'Invalid credentials payload after guard transform', details: reparsed.error.flatten() }, { status: 422 })
+    }
+    payloadData = reparsed.data
+  }
+
+  const credentialsService = container.resolve('integrationCredentialsService') as CredentialsService
+  const scope = { organizationId: auth.orgId as string, tenantId: auth.tenantId }
+
+  await credentialsService.save(integration.id, payloadData.credentials, scope)
+
+  await emitIntegrationsEvent('integrations.credentials.updated', {
+    integrationId: integration.id,
+    tenantId: auth.tenantId,
+    organizationId: auth.orgId,
+    userId: auth.sub,
+  })
+
+  await runIntegrationMutationGuardAfterSuccess(guardResult.afterSuccessCallbacks, {
+      tenantId: auth.tenantId,
+      organizationId: auth.orgId,
+      userId: auth.sub ?? '',
+      resourceKind: 'integrations.integration',
+      resourceId: integration.id,
+      operation: 'update',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+    })
+
+  return NextResponse.json({ ok: true })
+}

package/src/modules/integrations/api/[id]/health/route.ts

@@ -0,0 +1,53 @@
+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 { getIntegration } from '@open-mercato/shared/modules/integrations/types'
+import type { IntegrationHealthService } from '../../../lib/health-service'
+
+const idParamsSchema = z.object({ id: z.string().min(1) })
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['integrations.manage'] },
+}
+
+export const openApi = {
+  tags: ['Integrations'],
+  summary: 'Run health check for an integration',
+}
+
+export async function POST(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 rawParams = (ctx.params && typeof (ctx.params as Promise<unknown>).then === 'function')
+    ? await (ctx.params as Promise<{ id?: string }>)
+    : (ctx.params as { id?: string } | undefined)
+
+  const parsedParams = idParamsSchema.safeParse(rawParams)
+  if (!parsedParams.success) {
+    return NextResponse.json({ error: 'Invalid integration id' }, { status: 400 })
+  }
+
+  const integration = getIntegration(parsedParams.data.id)
+  if (!integration) {
+    return NextResponse.json({ error: 'Integration not found' }, { status: 404 })
+  }
+
+  const container = await createRequestContainer()
+  const healthService = container.resolve('integrationHealthService') as IntegrationHealthService
+
+  const result = await healthService.runHealthCheck(
+    integration.id,
+    { organizationId: auth.orgId as string, tenantId: auth.tenantId },
+  )
+
+  return NextResponse.json({
+    status: result.status,
+    message: result.message ?? null,
+    details: result.details ?? null,
+    checkedAt: new Date().toISOString(),
+  })
+}

package/src/modules/integrations/api/[id]/route.ts

@@ -0,0 +1,76 @@
+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 { getBundle, getBundleIntegrations, getIntegration } from '@open-mercato/shared/modules/integrations/types'
+import type { CredentialsService } from '../../lib/credentials-service'
+import type { IntegrationStateService } from '../../lib/state-service'
+
+const idParamsSchema = z.object({ id: z.string().min(1) })
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['integrations.view'] },
+}
+
+export const openApi = {
+  tags: ['Integrations'],
+  summary: 'Get integration detail',
+}
+
+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 rawParams = (ctx.params && typeof (ctx.params as Promise<unknown>).then === 'function')
+    ? await (ctx.params as Promise<{ id?: string }>)
+    : (ctx.params as { id?: string } | undefined)
+
+  const parsedParams = idParamsSchema.safeParse(rawParams)
+  if (!parsedParams.success) {
+    return NextResponse.json({ error: 'Invalid integration id' }, { status: 400 })
+  }
+
+  const integration = getIntegration(parsedParams.data.id)
+  if (!integration) {
+    return NextResponse.json({ error: 'Integration not found' }, { status: 404 })
+  }
+
+  const container = await createRequestContainer()
+  const credentialsService = container.resolve('integrationCredentialsService') as CredentialsService
+  const stateService = container.resolve('integrationStateService') as IntegrationStateService
+  const scope = { organizationId: auth.orgId as string, tenantId: auth.tenantId }
+
+  const [credentials, state] = await Promise.all([
+    credentialsService.resolve(integration.id, scope),
+    stateService.get(integration.id, scope),
+  ])
+
+  const bundle = integration.bundleId ? getBundle(integration.bundleId) : undefined
+  const bundleIntegrations = integration.bundleId
+    ? await Promise.all(
+      getBundleIntegrations(integration.bundleId).map(async (item) => {
+        const itemState = await stateService.get(item.id, scope)
+        return {
+          ...item,
+          isEnabled: itemState?.isEnabled ?? true,
+        }
+      }),
+    )
+    : []
+
+  return NextResponse.json({
+    integration,
+    bundle,
+    bundleIntegrations,
+    state: {
+      isEnabled: state?.isEnabled ?? true,
+      apiVersion: state?.apiVersion ?? null,
+      reauthRequired: state?.reauthRequired ?? false,
+      lastHealthStatus: state?.lastHealthStatus ?? null,
+      lastHealthCheckedAt: state?.lastHealthCheckedAt?.toISOString() ?? null,
+    },
+    hasCredentials: Boolean(credentials),
+  })
+}