@open-mercato/shared 0.4.2-canary-c02407ff85

package/src/lib/commands/scope.ts

@@ -0,0 +1,59 @@
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import type { CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { env } from 'process'
+
+function logScopeViolation(
+  ctx: CommandRuntimeContext,
+  expected: string,
+  actual: string | null
+): void {
+  try {
+    const requestInfo =
+      ctx.request && typeof ctx.request === 'object'
+        ? {
+            method: (ctx.request as Request).method ?? undefined,
+            url: (ctx.request as Request).url ?? undefined,
+          }
+        : null
+    const scope = ctx.organizationScope
+      ? {
+          selectedId: ctx.organizationScope.selectedId ?? null,
+          tenantId: ctx.organizationScope.tenantId ?? null,
+          allowedIdsCount: Array.isArray(ctx.organizationScope.allowedIds)
+            ? ctx.organizationScope.allowedIds.length
+            : null,
+          filterIdsCount: Array.isArray(ctx.organizationScope.filterIds)
+            ? ctx.organizationScope.filterIds.length
+            : null,
+        }
+      : null
+    if (env.NODE_ENV !== 'test') {
+      console.warn('[scope] Forbidden organization scope mismatch detected', {
+        expectedId: expected,
+        actualId: actual,
+        userId: ctx.auth?.sub ?? null,
+        actorTenantId: ctx.auth?.tenantId ?? null,
+        actorOrganizationId: ctx.auth?.orgId ?? null,
+        selectedOrganizationId: ctx.selectedOrganizationId ?? null,
+        organizationIdsCount: Array.isArray(ctx.organizationIds) ? ctx.organizationIds.length : null,
+        scope,
+        request: requestInfo,
+      })
+    }
+  } catch {
+    // best-effort logging
+  }
+}
+
+export function ensureOrganizationScope(ctx: CommandRuntimeContext, organizationId: string): void {
+  // Superadmins with global org access can operate on any organization's records
+  if (ctx.auth?.isSuperAdmin === true || ctx.organizationScope?.allowedIds === null) {
+    return
+  }
+
+  const currentOrg = ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null
+  if (currentOrg && currentOrg !== organizationId) {
+    logScopeViolation(ctx, organizationId, currentOrg)
+    throw new CrudHttpError(403, { error: 'Forbidden' })
+  }
+}

package/src/lib/commands/types.ts

@@ -0,0 +1,63 @@
+import type { AwilixContainer } from 'awilix'
+import { randomUUID } from 'crypto'
+import type { AuthContext } from '../auth/server'
+import type { OrganizationScope } from '@open-mercato/core/modules/directory/utils/organizationScope'
+
+export type CommandRuntimeContext = {
+  container: AwilixContainer
+  auth: AuthContext | null
+  organizationScope: OrganizationScope | null
+  selectedOrganizationId: string | null
+  organizationIds: string[] | null
+  request?: Request
+}
+
+export type CommandLogMetadata = {
+  tenantId?: string | null
+  organizationId?: string | null
+  actorUserId?: string | null
+  actionLabel?: string | null
+  resourceKind?: string | null
+  resourceId?: string | null
+  undoToken?: string | null
+  payload?: unknown
+  snapshotBefore?: unknown
+  snapshotAfter?: unknown
+  changes?: Record<string, unknown> | null
+  context?: Record<string, unknown> | null
+}
+
+export type CommandExecuteResult<TResult> = {
+  result: TResult
+  logEntry: any | null
+}
+
+export type CommandLogBuilderArgs<TInput, TResult> = {
+  input: TInput
+  result: TResult
+  ctx: CommandRuntimeContext
+  snapshots: {
+    before?: unknown
+    after?: unknown
+  }
+}
+
+export interface CommandHandler<TInput = unknown, TResult = unknown> {
+  readonly id: string
+  readonly isUndoable?: boolean
+  prepare?(input: TInput, ctx: CommandRuntimeContext): Promise<{ before?: unknown } | null> | { before?: unknown } | null
+  execute(input: TInput, ctx: CommandRuntimeContext): Promise<TResult> | TResult
+  buildLog?(args: CommandLogBuilderArgs<TInput, TResult>): Promise<CommandLogMetadata | null | undefined> | CommandLogMetadata | null | undefined
+  captureAfter?(input: TInput, result: TResult, ctx: CommandRuntimeContext): Promise<unknown> | unknown
+  undo?(params: { input: TInput; ctx: CommandRuntimeContext; logEntry: any }): Promise<void> | void
+}
+
+export type CommandExecutionOptions<TInput> = {
+  input: TInput
+  ctx: CommandRuntimeContext
+  metadata?: CommandLogMetadata | null
+}
+
+export function defaultUndoToken(): string {
+  return randomUUID()
+}

package/src/lib/crud/__tests__/crud-factory.test.ts

@@ -0,0 +1,333 @@
+import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
+import { z } from 'zod'
+
+// ---- Mocks ----
+const mockEventBus = { emitEvent: jest.fn() }
+
+type Rec = { id: string; organizationId: string; tenantId: string; title?: string; isDone?: boolean; deletedAt?: Date | null }
+let db: Record<string, Rec>
+let idSeq = 1
+let commandBus: { execute: jest.Mock }
+
+const em = {
+  create: (_cls: any, data: any) => ({ ...data, id: `id-${idSeq++}` }),
+  persistAndFlush: async (entity: Rec) => { db[entity.id] = { ...(db[entity.id] || {} as any), ...entity } },
+  findOne: async (_entity: any, where: any) => (em.getRepository(_entity).findOne(where) as any),
+  getRepository: (_cls: any) => ({
+    find: async (where: any) => Object.values(db).filter((r) => {
+      const orgClause = where.organizationId
+      const matchesOrg = !orgClause
+        ? true
+        : (typeof orgClause === 'object' && Array.isArray(orgClause.$in))
+          ? orgClause.$in.includes(r.organizationId)
+          : r.organizationId === orgClause
+      const matchesTenant = !where.tenantId || r.tenantId === where.tenantId
+      const matchesDeleted = where.deletedAt === null ? !r.deletedAt : true
+      return matchesOrg && matchesTenant && matchesDeleted
+    }),
+    findOne: async (where: any) => Object.values(db).find((r) => {
+      if (r.id !== where.id) return false
+      const orgClause = where.organizationId
+      const matchesOrg = !orgClause
+        ? true
+        : (typeof orgClause === 'object' && Array.isArray(orgClause.$in))
+          ? orgClause.$in.includes(r.organizationId)
+          : r.organizationId === orgClause
+      return matchesOrg && r.tenantId === where.tenantId
+    }) || null,
+    removeAndFlush: async (entity: Rec) => { delete db[entity.id] },
+  }),
+}
+
+const queryEngine = {
+  query: jest.fn(async (_entityId: any, _q: any) => ({ items: [{ id: 'id-1', title: 'A', is_done: false, organization_id: 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa', tenant_id: '123e4567-e89b-12d3-a456-426614174000' }], total: 1 })),
+}
+
+const mockDataEngine = {
+  __pendingSideEffects: [] as any[],
+  createOrmEntity: jest.fn(async ({ entity, data }: any) => {
+    const created = em.create(entity, data)
+    await em.persistAndFlush(created as any)
+    return created
+  }),
+  updateOrmEntity: jest.fn(async ({ entity, where, apply }: any) => {
+    const current = await (em.getRepository(entity).findOne(where) as any)
+    if (!current) return null
+    await apply(current)
+    await em.persistAndFlush(current)
+    return current
+  }),
+  deleteOrmEntity: jest.fn(async ({ entity, where, soft, softDeleteField }: any) => {
+    const repo = em.getRepository(entity)
+    const current = await (repo.findOne(where) as any)
+    if (!current) return null
+    if (soft !== false) { (current as any)[softDeleteField || 'deletedAt'] = new Date(); await em.persistAndFlush(current) }
+    else await repo.removeAndFlush(current)
+    return current
+  }),
+  setCustomFields: jest.fn(async (args: any) => {
+    await (setRecordCustomFields as any)(em, args)
+  }),
+  emitOrmEntityEvent: jest.fn(async (_entry: any) => {}),
+  markOrmEntityChange: jest.fn(function (this: any, entry: any) {
+    if (!entry || !entry.entity) return
+    this.__pendingSideEffects.push(entry)
+  }),
+  flushOrmEntityChanges: jest.fn(async function (this: any) {
+    while (this.__pendingSideEffects.length > 0) {
+      const next = this.__pendingSideEffects.shift()
+      await this.emitOrmEntityEvent(next)
+    }
+  }),
+}
+
+const accessLogService = {
+  log: jest.fn(async () => {}),
+}
+
+jest.mock('@open-mercato/shared/lib/di/container', () => ({
+  createRequestContainer: async () => ({
+    resolve: (name: string) => ({
+      em,
+      queryEngine,
+      eventBus: mockEventBus,
+      dataEngine: mockDataEngine,
+      accessLogService,
+      commandBus,
+    } as any)[name],
+  })
+}))
+
+jest.mock('@open-mercato/shared/lib/auth/server', () => {
+  const auth = { sub: 'u1', orgId: 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa', tenantId: '123e4567-e89b-12d3-a456-426614174000', roles: ['admin'] }
+  return {
+    getAuthFromCookies: async () => auth,
+    getAuthFromRequest: async () => auth,
+  }
+})
+
+const setRecordCustomFields = jest.fn(async () => {})
+jest.mock('@open-mercato/core/modules/entities/lib/helpers', () => ({
+  setRecordCustomFields: (...args: any[]) => (setRecordCustomFields as any)(...args)
+}))
+
+// Fake entity class
+class Todo {}
+
+describe('CRUD Factory', () => {
+  beforeEach(() => {
+    db = {}
+    idSeq = 1
+    jest.clearAllMocks()
+    accessLogService.log.mockClear()
+    mockDataEngine.__pendingSideEffects = []
+    commandBus = {
+      execute: jest.fn(async () => ({ result: {}, logEntry: { id: 'log-1' } })),
+    }
+  })
+
+  const querySchema = z.object({
+    page: z.coerce.number().default(1),
+    pageSize: z.coerce.number().default(50),
+    sortField: z.string().default('id'),
+    sortDir: z.enum(['asc','desc']).default('asc'),
+    format: z.enum(['csv', 'json', 'xml', 'markdown']).optional(),
+  })
+  const createSchema = z.object({ title: z.string().min(1), is_done: z.boolean().optional().default(false), cf_priority: z.number().optional() })
+  const updateSchema = z.object({ id: z.string(), title: z.string().optional(), is_done: z.boolean().optional(), cf_priority: z.number().optional() })
+
+  const route = makeCrudRoute({
+    metadata: { GET: { requireAuth: true }, POST: { requireAuth: true }, PUT: { requireAuth: true }, DELETE: { requireAuth: true } },
+    orm: { entity: Todo, idField: 'id', orgField: 'organizationId', tenantField: 'tenantId', softDeleteField: 'deletedAt' },
+    events: { module: 'example', entity: 'todo', persistent: true },
+    indexer: { entityType: 'example.todo' },
+    list: {
+      schema: querySchema,
+      entityId: 'example.todo',
+      fields: ['id','title','is_done'],
+      sortFieldMap: { id: 'id', title: 'title' },
+      buildFilters: () => ({} as any),
+      transformItem: (i: any) => ({ id: i.id, title: i.title, is_done: i.is_done }),
+      allowCsv: true,
+      csv: { headers: ['id','title','is_done'], row: (t) => [t.id, t.title, t.is_done ? '1' : '0'], filename: 'todos.csv' }
+    },
+    create: {
+      schema: createSchema,
+      mapToEntity: (input) => ({ title: (input as any).title, isDone: !!(input as any).is_done }),
+      customFields: { enabled: true, entityId: 'example.todo', pickPrefixed: true },
+    },
+    update: {
+      schema: updateSchema,
+      applyToEntity: (e, input) => { if ((input as any).title !== undefined) (e as any).title = (input as any).title; if ((input as any).is_done !== undefined) (e as any).isDone = !!(input as any).is_done },
+      customFields: { enabled: true, entityId: 'example.todo', pickPrefixed: true },
+    },
+    del: { idFrom: 'query', softDelete: true },
+  })
+
+  it('GET returns JSON list via QueryEngine', async () => {
+    const res = await route.GET(new Request('http://x/api/example/todos?page=1&pageSize=10&sortField=id&sortDir=asc'))
+    expect(res.status).toBe(200)
+    const body = await res.json()
+    expect(body.items.length).toBe(1)
+    expect(body.total).toBe(1)
+    expect(body.items[0]).toEqual({ id: 'id-1', title: 'A', is_done: false })
+    expect(accessLogService.log).toHaveBeenCalledTimes(1)
+    expect(accessLogService.log).toHaveBeenCalledWith(expect.objectContaining({
+      resourceKind: 'example.todo',
+      resourceId: 'id-1',
+      accessType: 'read',
+      tenantId: '123e4567-e89b-12d3-a456-426614174000',
+      organizationId: 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa',
+      actorUserId: 'u1',
+      fields: expect.arrayContaining(['id', 'title', 'is_done']),
+      context: expect.objectContaining({
+        resultCount: 1,
+        accessType: 'read',
+        queryKeys: expect.arrayContaining(['page', 'pageSize', 'sortField', 'sortDir']),
+      }),
+    }))
+  })
+
+  it('GET returns CSV when format=csv', async () => {
+    const res = await route.GET(new Request('http://x/api/example/todos?page=1&pageSize=10&sortField=id&sortDir=asc&format=csv'))
+    expect(res.headers.get('content-type')).toContain('text/csv')
+    expect(res.headers.get('content-disposition')).toContain('todos.csv')
+    const text = await res.text()
+    expect(text.split('\n')[0]).toBe('id,title,is_done')
+    expect(accessLogService.log).toHaveBeenCalledTimes(1)
+  })
+
+  it('GET returns JSON export when format=json', async () => {
+    const res = await route.GET(new Request('http://x/api/example/todos?format=json'))
+    expect(res.headers.get('content-type')).toContain('application/json')
+    expect(res.headers.get('content-disposition')).toContain('todo.json')
+    const text = await res.text()
+    const parsed = JSON.parse(text)
+    expect(Array.isArray(parsed)).toBe(true)
+    expect(parsed[0]).toEqual({ id: 'id-1', title: 'A', is_done: '0' })
+  })
+
+  it('GET returns XML export when format=xml', async () => {
+    const res = await route.GET(new Request('http://x/api/example/todos?format=xml'))
+    expect(res.headers.get('content-type')).toContain('application/xml')
+    expect(res.headers.get('content-disposition')).toContain('todo.xml')
+    const text = await res.text()
+    expect(text).toContain('<records>')
+    expect(text).toContain('<id>id-1</id>')
+    expect(text).toContain('<title>A</title>')
+  })
+
+  it('GET returns Markdown export when format=markdown', async () => {
+    const res = await route.GET(new Request('http://x/api/example/todos?format=markdown'))
+    expect(res.headers.get('content-type')).toContain('text/markdown')
+    expect(res.headers.get('content-disposition')).toContain('todo.md')
+    const text = await res.text()
+    const lines = text.split('\n')
+    expect(lines[0]).toBe('| id | title | is_done |')
+    expect(lines[2]).toContain('id-1')
+  })
+
+  it('GET returns full export when exportScope=full', async () => {
+    const res = await route.GET(new Request('http://x/api/example/todos?format=json&exportScope=full'))
+    expect(res.headers.get('content-type')).toContain('application/json')
+    expect(res.headers.get('content-disposition')).toContain('todo_full.json')
+    const text = await res.text()
+    const parsed = JSON.parse(text)
+    expect(Array.isArray(parsed)).toBe(true)
+    const row = parsed[0]
+    expect(row).toMatchObject({
+      Id: 'id-1',
+      Title: 'A',
+      'Is Done': false,
+      'Organization Id': 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa',
+      'Tenant Id': '123e4567-e89b-12d3-a456-426614174000',
+    })
+  })
+
+  it('POST creates entity, saves custom fields, emits created event', async () => {
+    const res = await route.POST(new Request('http://x/api/example/todos', { method: 'POST', body: JSON.stringify({ title: 'B', is_done: true, cf_priority: 3 }), headers: { 'content-type': 'application/json' } }))
+    expect(res.status).toBe(201)
+    const data = await res.json()
+    expect(data.id).toBeDefined()
+    // CF saved
+    expect(setRecordCustomFields).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ entityId: 'example.todo', values: { priority: 3 } }))
+    // Event + indexer delegated to data engine
+    expect(mockDataEngine.emitOrmEntityEvent).toHaveBeenCalledTimes(1)
+    const createdCall = mockDataEngine.emitOrmEntityEvent.mock.calls.at(0)
+    expect(createdCall).toBeDefined()
+    const [createdArgs] = createdCall!
+    expect(createdArgs.action).toBe('created')
+    expect(createdArgs.identifiers.id).toBe(data.id)
+    expect(createdArgs.events?.module).toBe('example')
+    expect(createdArgs.events?.entity).toBe('todo')
+    expect(createdArgs.indexer?.entityType).toBe('example.todo')
+    // Entity in db
+    const rec = db[data.id]
+    expect(rec).toBeTruthy()
+    expect(rec.title).toBe('B')
+    expect(rec.isDone).toBe(true)
+  })
+
+  it('PUT updates entity, saves custom fields, emits updated event', async () => {
+    // Seed
+    const created = em.create(Todo, { title: 'X', organizationId: 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa', tenantId: '123e4567-e89b-12d3-a456-426614174000' }) as Rec
+    // Force UUID id to satisfy validation
+    created.id = '123e4567-e89b-12d3-a456-426614174001'
+    await em.persistAndFlush(created)
+    const res = await route.PUT(new Request('http://x/api/example/todos', { method: 'PUT', body: JSON.stringify({ id: created.id, title: 'X2', cf_priority: 5 }), headers: { 'content-type': 'application/json' } }))
+    expect(res.status).toBe(200)
+    expect(setRecordCustomFields).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ values: { priority: 5 } }))
+    expect(mockDataEngine.emitOrmEntityEvent).toHaveBeenCalledTimes(1)
+    const updatedCall = mockDataEngine.emitOrmEntityEvent.mock.calls.at(0)
+    expect(updatedCall).toBeDefined()
+    const [updatedArgs] = updatedCall!
+    expect(updatedArgs.action).toBe('updated')
+    expect(updatedArgs.identifiers.id).toBe(created.id)
+    expect(updatedArgs.indexer?.entityType).toBe('example.todo')
+    expect(db[created.id].title).toBe('X2')
+  })
+
+  it('DELETE soft-deletes entity and emits deleted event', async () => {
+    const created = em.create(Todo, { title: 'Y', organizationId: 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa', tenantId: '123e4567-e89b-12d3-a456-426614174000' }) as Rec
+    created.id = '123e4567-e89b-12d3-a456-426614174002'
+    await em.persistAndFlush(created)
+    const res = await route.DELETE(new Request(`http://x/api/example/todos?id=${created.id}`, { method: 'DELETE' }))
+    expect(res.status).toBe(200)
+    expect(mockDataEngine.emitOrmEntityEvent).toHaveBeenCalledTimes(1)
+    const deletedCall = mockDataEngine.emitOrmEntityEvent.mock.calls.at(0)
+    expect(deletedCall).toBeDefined()
+    const [deletedArgs] = deletedCall!
+    expect(deletedArgs.action).toBe('deleted')
+    expect(deletedArgs.identifiers.id).toBe(created.id)
+    expect(deletedArgs.indexer?.entityType).toBe('example.todo')
+    expect(db[created.id].deletedAt).toBeInstanceOf(Date)
+  })
+
+  it('DELETE command route uses domain-specific ids from result when emitting events', async () => {
+    const indexedId = 'line-999'
+    commandBus.execute.mockResolvedValue({
+      result: { lineId: indexedId, orderId: 'order-1' },
+      logEntry: { id: 'log-1' },
+    })
+    const commandRoute = makeCrudRoute({
+      metadata: { DELETE: { requireAuth: true } },
+      orm: { entity: Todo, idField: 'id', orgField: 'organizationId', tenantField: 'tenantId', softDeleteField: 'deletedAt' },
+      indexer: { entityType: 'example.todo' },
+      actions: {
+        delete: {
+          commandId: 'example.todo.delete',
+          schema: z.any(),
+          response: () => ({ ok: true }),
+        },
+      },
+    })
+    const res = await commandRoute.DELETE(new Request('http://x/api/example/todos/command', { method: 'DELETE', body: JSON.stringify({}), headers: { 'content-type': 'application/json' } }))
+    expect(res.status).toBe(200)
+    expect(commandBus.execute).toHaveBeenCalledWith('example.todo.delete', expect.anything())
+    expect(mockDataEngine.emitOrmEntityEvent).toHaveBeenCalledTimes(1)
+    const [deletedArgs] = mockDataEngine.emitOrmEntityEvent.mock.calls[0]!
+    expect(deletedArgs.action).toBe('deleted')
+    expect(deletedArgs.identifiers.id).toBe(indexedId)
+    expect(deletedArgs.indexer?.entityType).toBe('example.todo')
+  })
+})

package/src/lib/crud/__tests__/custom-fields.test.ts

@@ -0,0 +1,150 @@
+import { buildCustomFieldFiltersFromQuery, extractAllCustomFieldEntries, splitCustomFieldPayload, loadCustomFieldValues } from '../custom-fields'
+import { encryptWithAesGcm } from '../../encryption/aes'
+
+const mockEntityManager = (defs: any[]) => ({
+  find: jest.fn().mockResolvedValue(defs),
+})
+
+describe('buildCustomFieldFiltersFromQuery', () => {
+  const definitions = [
+    {
+      id: 'def-fashion-color',
+      key: 'color',
+      kind: 'text',
+      entityId: 'catalog:product',
+      configJson: { fieldset: 'fashion' },
+    },
+    {
+      id: 'def-shared-material',
+      key: 'material',
+      kind: 'text',
+      entityId: 'catalog:product',
+      configJson: {},
+    },
+  ]
+
+  it('generates filters for matching definitions regardless of fieldset when none specified', async () => {
+    const em = mockEntityManager(definitions)
+    const filters = await buildCustomFieldFiltersFromQuery({
+      entityIds: ['catalog:product'],
+      query: { cf_color: 'blue' },
+      em: em as any,
+      tenantId: 'tenant-1',
+    })
+    expect(em.find).toHaveBeenCalled()
+    expect(filters).toEqual({ 'cf:color': 'blue' })
+  })
+
+  it('restricts filters to the requested fieldset code', async () => {
+    const em = mockEntityManager(definitions)
+    const filters = await buildCustomFieldFiltersFromQuery({
+      entityIds: ['catalog:product'],
+      query: { cf_color: 'blue' },
+      em: em as any,
+      tenantId: 'tenant-1',
+      fieldset: 'fashion',
+    })
+    expect(filters).toEqual({ 'cf:color': 'blue' })
+    const emptyFilters = await buildCustomFieldFiltersFromQuery({
+      entityIds: ['catalog:product'],
+      query: { cf_color: 'blue', cf_material: 'cotton' },
+      em: em as any,
+      tenantId: 'tenant-1',
+      fieldset: 'tech',
+    })
+    expect(emptyFilters).toEqual({})
+  })
+})
+
+describe('splitCustomFieldPayload', () => {
+  it('pulls values from customValues map', () => {
+    const raw = {
+      name: 'Channel',
+      customValues: {
+        api_url: 'https://example.dev',
+        priority: 5,
+      },
+    }
+    expect(splitCustomFieldPayload(raw)).toEqual({
+      base: { name: 'Channel' },
+      custom: { api_url: 'https://example.dev', priority: 5 },
+    })
+  })
+
+  it('maps array based customFields entries', () => {
+    const raw = {
+      customFields: [
+        { key: 'api_url', value: 'https://example.dev' },
+        { key: '', value: 'ignored' },
+        { key: 'notes', value: null },
+      ],
+      code: 'demo',
+    }
+    expect(splitCustomFieldPayload(raw)).toEqual({
+      base: { code: 'demo' },
+      custom: {
+        api_url: 'https://example.dev',
+        notes: null,
+      },
+    })
+  })
+})
+
+describe('extractAllCustomFieldEntries', () => {
+  it('merges entries from customValues maps and customFields objects', () => {
+    const item = {
+      customValues: { api_url: 'https://fws1.api', priority: 5 },
+      customFields: { notes: 'memo' },
+      other: 'value',
+    }
+    expect(extractAllCustomFieldEntries(item)).toEqual({
+      cf_api_url: 'https://fws1.api',
+      cf_priority: 5,
+      cf_notes: 'memo',
+    })
+  })
+
+  it('reads entries from customFields arrays and keeps existing cf_* keys', () => {
+    const item = {
+      customFields: [
+        { key: 'api_url', value: 'https://onet.pl' },
+        { key: '', value: 'skip-me' },
+        { key: 'notes' },
+      ],
+      cf_existing: 'foo',
+    }
+    expect(extractAllCustomFieldEntries(item)).toEqual({
+      cf_api_url: 'https://onet.pl',
+      cf_notes: undefined,
+      cf_existing: 'foo',
+    })
+  })
+})
+
+describe('loadCustomFieldValues (encryption)', () => {
+  it('decrypts encrypted custom field payloads when definitions mark them encrypted', async () => {
+    const dek = Buffer.alloc(32, 2).toString('base64')
+    const encrypted = encryptWithAesGcm(JSON.stringify('secret-note'), dek).value
+    const em = {
+      find: jest.fn().mockImplementation((_, where) => {
+        if ((where as any).recordId) {
+          return Promise.resolve([
+            { recordId: 'rec-1', fieldKey: 'note', organizationId: null, tenantId: 'tenant-1', valueText: encrypted, valueMultiline: null, valueInt: null, valueFloat: null, valueBool: null, deletedAt: null },
+          ])
+        }
+        return Promise.resolve([
+          { key: 'note', entityId: 'demo:entity', organizationId: null, tenantId: 'tenant-1', kind: 'text', configJson: { encrypted: true }, isActive: true },
+        ])
+      }),
+    }
+    const mockService = { isEnabled: () => true, getDek: async () => ({ key: dek }) }
+    const values = await loadCustomFieldValues({
+      em: em as any,
+      entityId: 'demo:entity',
+      recordIds: ['rec-1'],
+      tenantIdByRecord: { 'rec-1': 'tenant-1' },
+      encryptionService: mockService as any,
+    })
+    expect(values['rec-1'].cf_note).toBe('secret-note')
+  })
+})