@open-mercato/core 0.5.1-develop.2663.2c29774b5b → 0.5.1-develop.2681.c559bb2bc3

package/src/modules/customers/api/interactions/conflicts/route.ts

@@ -0,0 +1,196 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { CustomerInteraction } from '../../../data/entities'
+
+const querySchema = z.object({
+  date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+  startTime: z.string().regex(/^\d{2}:\d{2}$/),
+  duration: z.coerce.number().int().min(1).max(1440),
+  excludeId: z.string().uuid().optional(),
+  userId: z.string().uuid().optional(),
+  timezoneOffsetMinutes: z.coerce.number().int().min(-900).max(900).optional(),
+})
+
+const conflictItemSchema = z.object({
+  id: z.string(),
+  title: z.string().nullable(),
+  startTime: z.string(),
+  endTime: z.string(),
+  type: z.string(),
+})
+
+const responseSchema = z.object({
+  ok: z.literal(true),
+  result: z.object({
+    hasConflicts: z.boolean(),
+    conflicts: z.array(conflictItemSchema),
+  }),
+})
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['customers.interactions.view'] },
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Customers',
+  methods: {
+    GET: {
+      summary: 'Detect scheduling conflicts',
+      description: 'Checks for overlapping planned interactions within the requested time window.',
+      query: querySchema,
+      responses: [
+        {
+          status: 200,
+          description: 'Conflict detection result',
+          schema: responseSchema,
+        },
+      ],
+    },
+  },
+}
+
+export async function GET(req: Request) {
+  const { translate } = await resolveTranslations()
+  try {
+    const queryUrl = new URL(req.url)
+    const query = querySchema.parse(Object.fromEntries(queryUrl.searchParams))
+    const container = await createRequestContainer()
+    const auth = await getAuthFromRequest(req)
+
+    if (!auth || !auth.tenantId) {
+      throw new CrudHttpError(401, {
+        error: translate('customers.errors.unauthorized', 'Unauthorized'),
+      })
+    }
+
+    const scope = await resolveOrganizationScopeForRequest({ container, auth, request: req })
+    const organizationIds = Array.isArray(scope?.filterIds) && scope.filterIds.length > 0
+      ? scope.filterIds
+      : auth.orgId
+        ? [auth.orgId]
+        : []
+
+    const offsetMinutes = query.timezoneOffsetMinutes ?? 0
+    const offsetSign = offsetMinutes >= 0 ? '+' : '-'
+    const absMinutes = Math.abs(offsetMinutes)
+    const offsetHours = String(Math.floor(absMinutes / 60)).padStart(2, '0')
+    const offsetMins = String(absMinutes % 60).padStart(2, '0')
+    const offsetSuffix = `${offsetSign}${offsetHours}:${offsetMins}`
+    const windowStart = new Date(`${query.date}T${query.startTime}:00${offsetSuffix}`)
+    const windowEnd = new Date(windowStart.getTime() + query.duration * 60_000)
+
+    if (Number.isNaN(windowStart.getTime()) || Number.isNaN(windowEnd.getTime())) {
+      throw new CrudHttpError(400, { error: translate('customers.errors.invalid_date_time', 'Invalid date/time') })
+    }
+
+    const checkUserId = query.userId ?? auth.userId
+    const em = (container.resolve('em') as EntityManager).fork()
+    const knex = em.getKnex()
+
+    const baseQuery = knex('customer_interactions')
+      .where('tenant_id', auth.tenantId)
+      .where('status', 'planned')
+      .whereNotNull('scheduled_at')
+      .whereNull('deleted_at')
+
+    if (organizationIds.length === 1) {
+      baseQuery.where('organization_id', organizationIds[0])
+    } else if (organizationIds.length > 1) {
+      baseQuery.whereIn('organization_id', organizationIds)
+    }
+
+    if (checkUserId) {
+      baseQuery.where(function () {
+        this.where('author_user_id', checkUserId).orWhere('owner_user_id', checkUserId)
+      })
+    }
+
+    if (query.excludeId) {
+      baseQuery.whereNot('id', query.excludeId)
+    }
+
+    // Overlap condition: existing.start < windowEnd AND existing.end > windowStart
+    // end = scheduled_at + duration_minutes (default 30 if null)
+    baseQuery.where(function () {
+      this.where('scheduled_at', '<', windowEnd.toISOString())
+        .andWhere(
+          knex.raw(
+            '(scheduled_at + make_interval(mins => COALESCE(duration_minutes, 30))) > ?',
+            [windowStart.toISOString()],
+          ),
+        )
+    })
+
+    // Raw SELECT: reads only unencrypted columns (id, scheduled_at, duration_minutes, interaction_type); title is excluded to avoid ciphertext leakage and is resolved below via findWithDecryption.
+    const rows = await baseQuery
+      .select('id', 'scheduled_at', 'duration_minutes', 'interaction_type')
+      .orderBy('scheduled_at', 'asc')
+      .limit(10) as Array<{
+        id: string
+        scheduled_at: string | Date
+        duration_minutes: number | null
+        interaction_type: string
+      }>
+
+    const decryptionScope = {
+      tenantId: auth.tenantId ?? null,
+      organizationId: auth.orgId ?? null,
+    }
+    const conflictIds = rows.map((row) => row.id)
+    const interactionFilter: Record<string, unknown> = {
+      id: { $in: conflictIds },
+      tenantId: auth.tenantId,
+      deletedAt: null,
+    }
+    if (organizationIds.length === 1) {
+      interactionFilter.organizationId = organizationIds[0]
+    } else if (organizationIds.length > 1) {
+      interactionFilter.organizationId = { $in: organizationIds }
+    }
+    const decryptedInteractions = conflictIds.length > 0
+      ? await findWithDecryption(
+          em,
+          CustomerInteraction,
+          interactionFilter as any,
+          undefined,
+          decryptionScope,
+        )
+      : []
+    const titleById = new Map<string, string | null>()
+    for (const record of decryptedInteractions) {
+      titleById.set((record as any).id, ((record as any).title ?? null) as string | null)
+    }
+
+    const conflicts = rows.map((row) => {
+      const start = new Date(row.scheduled_at)
+      const durationMin = row.duration_minutes ?? 30
+      const end = new Date(start.getTime() + durationMin * 60_000)
+      return {
+        id: row.id,
+        title: titleById.has(row.id) ? titleById.get(row.id) ?? null : null,
+        startTime: start.toLocaleTimeString('en-US', { hour: '2-digit', minute: '2-digit', hour12: false }),
+        endTime: end.toLocaleTimeString('en-US', { hour: '2-digit', minute: '2-digit', hour12: false }),
+        type: row.interaction_type,
+      }
+    })
+
+    return NextResponse.json({
+      ok: true,
+      result: { hasConflicts: conflicts.length > 0, conflicts },
+    })
+  } catch (err) {
+    if (err instanceof CrudHttpError) {
+      return NextResponse.json(err.body, { status: err.status })
+    }
+    console.error('[customers/interactions/conflicts] GET failed', err)
+    return NextResponse.json({ error: translate('customers.errors.internal', 'Internal server error') }, { status: 500 })
+  }
+}

package/src/modules/customers/api/interactions/counts/route.ts

@@ -0,0 +1,112 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+
+const querySchema = z.object({
+  entityId: z.string().uuid(),
+  status: z.enum(['done', 'planned']).optional(),
+})
+
+const responseSchema = z.object({
+  ok: z.literal(true),
+  result: z.object({
+    call: z.number(),
+    email: z.number(),
+    meeting: z.number(),
+    note: z.number(),
+    total: z.number(),
+  }),
+})
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['customers.interactions.view'] },
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Customers',
+  methods: {
+    GET: {
+      summary: 'Get interaction counts by type',
+      description: 'Returns per-type interaction counts scoped to an entity.',
+      query: querySchema,
+      responses: [
+        {
+          status: 200,
+          description: 'Counts by interaction type',
+          schema: responseSchema,
+        },
+      ],
+    },
+  },
+}
+
+export async function GET(req: Request) {
+  try {
+    const queryUrl = new URL(req.url)
+    const query = querySchema.parse(Object.fromEntries(queryUrl.searchParams))
+    const container = await createRequestContainer()
+    const auth = await getAuthFromRequest(req)
+    const { translate } = await resolveTranslations()
+
+    if (!auth || !auth.tenantId) {
+      throw new CrudHttpError(401, {
+        error: translate('customers.errors.unauthorized', 'Unauthorized'),
+      })
+    }
+
+    const scope = await resolveOrganizationScopeForRequest({ container, auth, request: req })
+    const organizationIds = Array.isArray(scope?.filterIds) && scope.filterIds.length > 0
+      ? scope.filterIds
+      : auth.orgId
+        ? [auth.orgId]
+        : []
+    const em = (container.resolve('em') as EntityManager).fork()
+    const knex = em.getKnex()
+
+    const baseQuery = knex('customer_interactions')
+      .where('entity_id', query.entityId)
+      .where('tenant_id', auth.tenantId)
+      .whereNull('deleted_at')
+
+    if (organizationIds.length === 1) {
+      baseQuery.where('organization_id', organizationIds[0])
+    } else if (organizationIds.length > 1) {
+      baseQuery.whereIn('organization_id', organizationIds)
+    }
+
+    if (query.status) {
+      baseQuery.where('status', query.status)
+    }
+
+    // Raw SELECT: reads only unencrypted columns (id, interaction_type); title/notes are excluded to avoid ciphertext leakage.
+    const rows = await baseQuery
+      .select('interaction_type')
+      .count('* as count')
+      .groupBy('interaction_type') as Array<{ interaction_type: string; count: string | number }>
+
+    const counts: Record<string, number> = { call: 0, email: 0, meeting: 0, note: 0 }
+    let total = 0
+    for (const row of rows) {
+      const count = typeof row.count === 'string' ? parseInt(row.count, 10) : row.count
+      const type = row.interaction_type
+      if (type in counts) {
+        counts[type] = count
+      }
+      total += count
+    }
+
+    return NextResponse.json({ ok: true, result: { ...counts, total } })
+  } catch (err) {
+    if (err instanceof CrudHttpError) {
+      return NextResponse.json(err.body, { status: err.status })
+    }
+    console.error('[customers/interactions/counts] GET failed', err)
+    return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
+  }
+}

package/src/modules/customers/api/interactions/route.ts

@@ -31,6 +31,7 @@ const interactionSortFieldSchema = z.enum([
   'status',
   'priority',
   'interactionType',
+  'title',
 ])
 
 const listSchema = z
@@ -41,9 +42,12 @@ const listSchema = z
     dealId: z.string().uuid().optional(),
     status: z.string().optional(),
     interactionType: z.string().optional(),
+    type: z.string().optional(),
     excludeInteractionType: z.string().optional(),
+    search: z.string().trim().min(1).optional(),
     from: z.string().optional(),
     to: z.string().optional(),
+    pinned: z.enum(['true', 'false']).optional(),
     sortField: interactionSortFieldSchema.optional(),
     sortDir: z.enum(['asc', 'desc']).optional(),
   })
@@ -133,6 +137,17 @@ type InteractionListRow = {
   appearance_icon: string | null
   appearance_color: string | null
   source: string | null
+  duration_minutes: number | null
+  location: string | null
+  all_day: boolean | null
+  recurrence_rule: string | null
+  recurrence_end: Date | null
+  participants: Array<{ userId: string; name?: string; email?: string; status?: string }> | null
+  reminder_minutes: number | null
+  visibility: string | null
+  linked_entities: Array<{ id: string; type: string; label: string }> | null
+  guest_permissions: { canInviteOthers?: boolean; canModify?: boolean; canSeeList?: boolean } | null
+  pinned: boolean
   organization_id: string
   tenant_id: string
   created_at: Date
@@ -162,6 +177,7 @@ const interactionSortConfig = {
   status: { column: 'status', type: 'text' as const, defaultDir: 'asc' as const },
   priority: { column: 'priority', type: 'number' as const, defaultDir: 'desc' as const },
   interactionType: { column: 'interaction_type', type: 'text' as const, defaultDir: 'asc' as const },
+  title: { column: 'title', type: 'text' as const, defaultDir: 'asc' as const },
 } as const
 
 function toIsoString(value: unknown): string | null {
@@ -328,6 +344,17 @@ export async function GET(req: Request) {
         'appearance_icon',
         'appearance_color',
         'source',
+        'duration_minutes',
+        'location',
+        'all_day',
+        'recurrence_rule',
+        'recurrence_end',
+        'participants',
+        'reminder_minutes',
+        'visibility',
+        'linked_entities',
+        'guest_permissions',
+        'pinned',
         'organization_id',
         'tenant_id',
         'created_at',
@@ -353,14 +380,37 @@ export async function GET(req: Request) {
     if (query.interactionType) {
       rowsQuery.andWhere('interaction_type', query.interactionType)
     }
+    if (query.type) {
+      const types = query.type.split(',').map((t) => t.trim()).filter(Boolean)
+      if (types.length > 0) {
+        rowsQuery.whereIn('interaction_type', types)
+      }
+    }
+    if (query.pinned === 'true') {
+      rowsQuery.andWhere('pinned', true)
+    } else if (query.pinned === 'false') {
+      rowsQuery.andWhere('pinned', false)
+    }
     if (query.excludeInteractionType) {
       rowsQuery.andWhereNot('interaction_type', query.excludeInteractionType)
     }
+    if (query.search) {
+      const searchTerm = `%${query.search}%`
+      rowsQuery.andWhere(function applySearch() {
+        this.whereRaw("coalesce(title, '') ilike ?", [searchTerm]).orWhereRaw("coalesce(body, '') ilike ?", [searchTerm])
+      })
+    }
     if (query.from) {
-      rowsQuery.andWhere('scheduled_at', '>=', new Date(query.from))
+      rowsQuery.andWhereRaw(
+        "coalesce(occurred_at, scheduled_at, created_at) >= ?",
+        [new Date(query.from)],
+      )
     }
     if (query.to) {
-      rowsQuery.andWhere('scheduled_at', '<=', new Date(query.to))
+      rowsQuery.andWhereRaw(
+        "coalesce(occurred_at, scheduled_at, created_at) <= ?",
+        [new Date(query.to)],
+      )
     }
     if (cursor) {
       const op = sortDir === 'asc' ? '>' : '<'
@@ -438,6 +488,18 @@ export async function GET(req: Request) {
       appearanceIcon: row.appearance_icon ?? null,
       appearanceColor: row.appearance_color ?? null,
       source: row.source ?? null,
+      duration: row.duration_minutes ?? null,
+      durationMinutes: row.duration_minutes ?? null,
+      location: row.location ?? null,
+      allDay: row.all_day ?? null,
+      recurrenceRule: row.recurrence_rule ?? null,
+      recurrenceEnd: toIsoString(row.recurrence_end),
+      participants: row.participants ?? null,
+      reminderMinutes: row.reminder_minutes ?? null,
+      visibility: row.visibility ?? null,
+      linkedEntities: row.linked_entities ?? null,
+      guestPermissions: row.guest_permissions ?? null,
+      pinned: row.pinned ?? false,
       organizationId: row.organization_id,
       tenantId: row.tenant_id,
       createdAt: toIsoString(row.created_at) ?? new Date().toISOString(),
@@ -500,6 +562,37 @@ const interactionListItemSchema = z
     appearanceIcon: z.string().nullable().optional(),
     appearanceColor: z.string().nullable().optional(),
     source: z.string().nullable().optional(),
+    duration: z.number().nullable().optional(),
+    durationMinutes: z.number().nullable().optional(),
+    location: z.string().nullable().optional(),
+    allDay: z.boolean().nullable().optional(),
+    recurrenceRule: z.string().nullable().optional(),
+    recurrenceEnd: z.string().nullable().optional(),
+    participants: z.array(
+      z.object({
+        userId: z.string().uuid(),
+        name: z.string().optional(),
+        email: z.string().optional(),
+        status: z.string().optional(),
+      }),
+    ).nullable().optional(),
+    reminderMinutes: z.number().nullable().optional(),
+    visibility: z.string().nullable().optional(),
+    linkedEntities: z.array(
+      z.object({
+        id: z.string().uuid(),
+        type: z.string(),
+        label: z.string(),
+      }),
+    ).nullable().optional(),
+    guestPermissions: z
+      .object({
+        canInviteOthers: z.boolean().optional(),
+        canModify: z.boolean().optional(),
+        canSeeList: z.boolean().optional(),
+      })
+      .nullable()
+      .optional(),
     organizationId: z.string().uuid().nullable().optional(),
     tenantId: z.string().uuid().nullable().optional(),
     createdAt: z.string().nullable(),

package/src/modules/customers/api/labels/assign/route.ts

@@ -0,0 +1,202 @@
+import { NextResponse } from 'next/server'
+import { CustomerEntity } from '../../../data/entities'
+import { labelAssignCommandSchema, labelAssignmentSchema, type LabelAssignCommandInput } from '../../../data/validators'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { CommandBus } from '@open-mercato/shared/lib/commands'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import type { RbacService } from '@open-mercato/core/modules/auth/services/rbacService'
+import { serializeOperationMetadata } from '@open-mercato/shared/lib/commands/operationMetadata'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { z } from 'zod'
+import { resolveLabelActorUserId } from '../auth'
+import {
+  runCrudMutationGuardAfterSuccess,
+  validateCrudMutationGuard,
+} from '@open-mercato/shared/lib/crud/mutation-guard'
+import {
+  createMissingCustomerLabelTablesError,
+  isMissingCustomerLabelTable,
+} from '../table-errors'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+
+export const metadata = {
+  POST: { requireAuth: true },
+}
+
+const labelAssignmentRequestSchema = labelAssignmentSchema.extend({
+  organizationId: z.string().uuid().optional(),
+})
+
+function resolveResourceKind(kind: 'person' | 'company' | null | undefined): string {
+  if (kind === 'company') return 'customers.company'
+  return 'customers.person'
+}
+
+function resolveRequiredFeature(kind: 'person' | 'company' | null | undefined): string {
+  return kind === 'company' ? 'customers.companies.manage' : 'customers.people.manage'
+}
+
+export async function POST(req: Request) {
+  try {
+    const { translate } = await resolveTranslations()
+    const container = await createRequestContainer()
+    const auth = await getAuthFromRequest(req)
+    const actorUserId = resolveLabelActorUserId(auth)
+    if (!auth || !auth.tenantId || !actorUserId) {
+      return NextResponse.json({ error: translate('customers.errors.unauthorized', 'Unauthorized') }, { status: 401 })
+    }
+
+    const body = labelAssignmentRequestSchema.parse(await readJsonSafe(req, {}))
+    const scope = await resolveOrganizationScopeForRequest({
+      container,
+      auth,
+      request: req,
+      selectedId: body.organizationId ?? undefined,
+    })
+    const organizationId = scope?.selectedId ?? auth.orgId ?? null
+    if (!organizationId) {
+      throw new CrudHttpError(400, { error: translate('customers.errors.organization_required', 'Organization context is required') })
+    }
+
+    const em = (container.resolve('em') as EntityManager).fork()
+    const targetEntity = await findOneWithDecryption(
+      em,
+      CustomerEntity,
+      {
+        id: body.entityId,
+        tenantId: auth.tenantId,
+        organizationId,
+        deletedAt: null,
+      },
+      undefined,
+      { tenantId: auth.tenantId, organizationId },
+    )
+    if (!targetEntity) {
+      throw new CrudHttpError(404, { error: translate('customers.errors.entity_not_found', 'Entity not found') })
+    }
+    const entityKind = targetEntity.kind === 'person' || targetEntity.kind === 'company' ? targetEntity.kind : null
+    const resourceKind = resolveResourceKind(entityKind)
+
+    const rbac = container.resolve('rbacService') as RbacService | undefined
+    if (!rbac) {
+      throw new CrudHttpError(500, { error: translate('customers.errors.internal', 'Internal error') })
+    }
+    const requiredFeature = resolveRequiredFeature(entityKind)
+    const hasFeature = await rbac.userHasAllFeatures(actorUserId, [requiredFeature], {
+      tenantId: auth.tenantId,
+      organizationId,
+    })
+    if (!hasFeature) {
+      throw new CrudHttpError(403, { error: translate('customers.errors.access_denied', 'Access denied') })
+    }
+
+    const guardResult = await validateCrudMutationGuard(container, {
+      tenantId: auth.tenantId,
+      organizationId,
+      userId: actorUserId,
+      resourceKind,
+      resourceId: body.entityId,
+      operation: 'custom',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+      mutationPayload: body,
+    })
+    if (guardResult && !guardResult.ok) {
+      return NextResponse.json(guardResult.body, { status: guardResult.status })
+    }
+
+    const commandInput = labelAssignCommandSchema.parse({
+      labelId: body.labelId,
+      entityId: body.entityId,
+      tenantId: auth.tenantId,
+      organizationId,
+    } satisfies LabelAssignCommandInput)
+
+    const commandBus = container.resolve('commandBus') as CommandBus
+    const { result, logEntry } = await commandBus.execute<LabelAssignCommandInput, { assignmentId: string; created: boolean; entityKind: 'person' | 'company' | null }>(
+      'customers.labels.assign',
+      {
+        input: commandInput,
+        ctx: {
+          container,
+          auth,
+          organizationScope: scope,
+          selectedOrganizationId: organizationId,
+          organizationIds: scope?.filterIds ?? (auth.orgId ? [auth.orgId] : null),
+          request: req,
+        },
+      },
+    )
+
+    if (guardResult?.ok && guardResult.shouldRunAfterSuccess) {
+      await runCrudMutationGuardAfterSuccess(container, {
+        tenantId: auth.tenantId,
+        organizationId,
+        userId: actorUserId,
+        resourceKind,
+        resourceId: body.entityId,
+        operation: 'custom',
+        requestMethod: req.method,
+        requestHeaders: req.headers,
+        metadata: guardResult.metadata ?? null,
+      })
+    }
+
+    const response = NextResponse.json({ id: result.assignmentId }, { status: result.created ? 201 : 200 })
+    if (result.created && logEntry?.undoToken && logEntry.id && logEntry.commandId) {
+      response.headers.set(
+        'x-om-operation',
+        serializeOperationMetadata({
+          id: logEntry.id,
+          undoToken: logEntry.undoToken,
+          commandId: logEntry.commandId,
+          actionLabel: logEntry.actionLabel ?? null,
+          resourceKind: logEntry.resourceKind ?? 'customers.labelAssignment',
+          resourceId: logEntry.resourceId ?? result.assignmentId,
+          executedAt: logEntry.createdAt instanceof Date ? logEntry.createdAt.toISOString() : new Date().toISOString(),
+        }),
+      )
+    }
+    return response
+  } catch (err) {
+    if (isMissingCustomerLabelTable(err)) {
+      const migrationError = await createMissingCustomerLabelTablesError()
+      return NextResponse.json(migrationError.body, { status: migrationError.status })
+    }
+    if (err instanceof CrudHttpError) {
+      return NextResponse.json(err.body, { status: err.status })
+    }
+    console.error('[customers/labels/assign.POST]', err)
+    const { translate: fallbackTranslate } = await resolveTranslations()
+    return NextResponse.json(
+      { error: fallbackTranslate('customers.errors.failed_to_assign_label', 'Failed to assign label') },
+      { status: 500 },
+    )
+  }
+}
+
+const responseSchema = z.object({ id: z.string().uuid() })
+const errorSchema = z.object({ error: z.string() })
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Customers',
+  summary: 'Assign label to entity',
+  methods: {
+    POST: {
+      summary: 'Assign label',
+      requestBody: { contentType: 'application/json', schema: labelAssignmentRequestSchema },
+      responses: [
+        { status: 201, description: 'Assigned', schema: responseSchema },
+        { status: 200, description: 'Already assigned', schema: responseSchema },
+      ],
+      errors: [
+        { status: 404, description: 'Label or entity not found', schema: errorSchema },
+      ],
+    },
+  },
+}

package/src/modules/customers/api/labels/auth.ts

@@ -0,0 +1,19 @@
+import type { AuthContext } from '@open-mercato/shared/lib/auth/server'
+
+const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+
+export function resolveLabelActorUserId(auth: AuthContext): string | null {
+  if (!auth) return null
+
+  const apiUserId = typeof auth.userId === 'string' ? auth.userId.trim() : ''
+  if (apiUserId && uuidRegex.test(apiUserId)) {
+    return apiUserId
+  }
+
+  if (auth.isApiKey) {
+    return null
+  }
+
+  const subjectId = typeof auth.sub === 'string' ? auth.sub.trim() : ''
+  return subjectId && uuidRegex.test(subjectId) ? subjectId : null
+}