@open-mercato/core 0.6.5-develop.5382.1.f542de69af → 0.6.5

package/src/modules/customers/lib/dealsMetrics.ts

@@ -0,0 +1,159 @@
+import type { RateResult } from '@open-mercato/core/modules/currencies/services/exchangeRateService'
+
+/**
+ * Quarter / period helpers for the deals KPI summary. Computed in **UTC** so the
+ * window boundaries are stable regardless of the server timezone — `expected_close_at`
+ * is a bare `Date` (date-only) while `created_at` / `updated_at` are timestamptz, and
+ * mixing local-time boundaries would misbucket deals near a quarter edge.
+ */
+
+export type PeriodWindow = {
+  /** Inclusive lower bound (UTC). */
+  start: Date
+  /** Exclusive upper bound (UTC). */
+  end: Date
+}
+
+export type TrailingMonth = {
+  /** Inclusive lower bound (UTC) of the month bucket. */
+  start: Date
+  /** 'YYYY-MM' label for the bucket. */
+  label: string
+}
+
+export type DeltaDirection = 'up' | 'down' | 'unchanged'
+
+export type Delta = {
+  value: number
+  direction: DeltaDirection
+}
+
+export type CurrencySum = {
+  currency: string
+  total: number
+}
+
+export type ConvertedSums = {
+  total: number
+  convertedAll: boolean
+  missingRateCurrencies: string[]
+}
+
+function startOfQuarterUtc(year: number, quarterStartMonth: number): Date {
+  return new Date(Date.UTC(year, quarterStartMonth, 1, 0, 0, 0, 0))
+}
+
+/**
+ * Returns the [start, end) window of the calendar quarter that contains `now`,
+ * in UTC. Quarters are fixed 3-month blocks: Jan–Mar, Apr–Jun, Jul–Sep, Oct–Dec.
+ * `end` is exclusive (the start of the next quarter).
+ */
+export function getQuarterWindow(now: Date): PeriodWindow {
+  const year = now.getUTCFullYear()
+  const quarterIndex = Math.floor(now.getUTCMonth() / 3)
+  const startMonth = quarterIndex * 3
+  const start = startOfQuarterUtc(year, startMonth)
+  const end = startOfQuarterUtc(year, startMonth + 3)
+  return { start, end }
+}
+
+/**
+ * Returns the [start, end) window of the quarter immediately preceding the one
+ * that contains `now`, in UTC. `end` is exclusive and equals the current quarter's start.
+ */
+export function getPreviousQuarterWindow(now: Date): PeriodWindow {
+  const current = getQuarterWindow(now)
+  const start = startOfQuarterUtc(current.start.getUTCFullYear(), current.start.getUTCMonth() - 3)
+  return { start, end: current.start }
+}
+
+function monthLabel(year: number, monthIndex: number): string {
+  const month = monthIndex + 1
+  return `${year}-${month < 10 ? `0${month}` : month}`
+}
+
+/**
+ * Returns `count` trailing month buckets ending with the month that contains `now`,
+ * ordered oldest → newest. Each bucket exposes its UTC start and a 'YYYY-MM' label.
+ * Used to drive the win-rate sparkline series.
+ */
+export function getTrailingMonths(now: Date, count: number): TrailingMonth[] {
+  const buckets: TrailingMonth[] = []
+  const baseYear = now.getUTCFullYear()
+  const baseMonth = now.getUTCMonth()
+  for (let offset = count - 1; offset >= 0; offset -= 1) {
+    const start = new Date(Date.UTC(baseYear, baseMonth - offset, 1, 0, 0, 0, 0))
+    buckets.push({ start, label: monthLabel(start.getUTCFullYear(), start.getUTCMonth()) })
+  }
+  return buckets
+}
+
+/**
+ * Percentage change of `current` relative to `previous`, rounded to whole percent.
+ * When there is no previous-period baseline, avoid reporting artificial growth.
+ */
+export function computeDelta(current: number, previous: number): Delta {
+  if (previous === 0) {
+    return { value: 0, direction: 'unchanged' }
+  }
+  const change = ((current - previous) / Math.abs(previous)) * 100
+  const value = Math.round(change)
+  if (value > 0) return { value, direction: 'up' }
+  if (value < 0) return { value, direction: 'down' }
+  return { value: 0, direction: 'unchanged' }
+}
+
+function extractRate(result: RateResult | undefined): number | null {
+  if (!result || result.rates.length === 0) return null
+  const rate = Number(result.rates[0].rate)
+  if (!Number.isFinite(rate) || rate <= 0) return null
+  return rate
+}
+
+/**
+ * Converts per-currency sums to the tenant base currency, mirroring the conversion
+ * logic in `api/deals/aggregate/route.ts`:
+ *  - the base currency stays 1:1,
+ *  - other currencies multiply by the rate from `rates` (keyed `"FROM/BASE"`),
+ *  - a currency with no usable rate is excluded from `total` and flagged in
+ *    `missingRateCurrencies` (with `convertedAll: false`).
+ *
+ * When `baseCode` is null there is no base currency configured, so nothing can be
+ * converted: every present currency is reported as missing and `convertedAll` is false.
+ *
+ * `rates` accepts the `Map<string, RateResult>` shape returned by
+ * `exchangeRateService.getRates` so callers can pass its output directly.
+ */
+export function convertSumsToBase(
+  perCurrency: CurrencySum[],
+  baseCode: string | null,
+  rates: Map<string, RateResult>,
+): ConvertedSums {
+  if (!baseCode) {
+    const missing = Array.from(
+      new Set(perCurrency.map((entry) => entry.currency).filter((code): code is string => Boolean(code))),
+    )
+    return { total: 0, convertedAll: missing.length === 0, missingRateCurrencies: missing }
+  }
+
+  let total = 0
+  let convertedAll = true
+  const missingRateCurrencies: string[] = []
+  for (const entry of perCurrency) {
+    if (!entry.currency) continue
+    if (entry.currency === baseCode) {
+      total += entry.total
+      continue
+    }
+    const rate = extractRate(rates.get(`${entry.currency}/${baseCode}`))
+    if (rate !== null) {
+      total += entry.total * rate
+    } else {
+      convertedAll = false
+      if (!missingRateCurrencies.includes(entry.currency)) {
+        missingRateCurrencies.push(entry.currency)
+      }
+    }
+  }
+  return { total: Math.round(total), convertedAll, missingRateCurrencies }
+}

package/src/modules/directory/api/organization-branding/route.ts

@@ -0,0 +1,238 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { runWithCacheTenant } from '@open-mercato/cache'
+import type { CommandBus, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { Organization } from '@open-mercato/core/modules/directory/data/entities'
+import { organizationUpdateSchema } from '@open-mercato/core/modules/directory/data/validators'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import '@open-mercato/core/modules/directory/commands/organizations'
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['directory.organizations.view'] },
+  PUT: { requireAuth: true, requireFeatures: ['directory.organizations.manage'] },
+}
+
+const brandingResponseSchema = z.object({
+  organizationId: z.string().uuid(),
+  organizationName: z.string(),
+  tenantId: z.string().uuid(),
+  logoUrl: z.string().nullable(),
+})
+
+const brandingUpdateSchema = z.object({
+  logoUrl: organizationUpdateSchema.shape.logoUrl,
+})
+
+const errorSchema = z.object({
+  error: z.string(),
+})
+
+type RequestContainer = Awaited<ReturnType<typeof createRequestContainer>>
+
+function buildCommandContext(
+  container: RequestContainer,
+  auth: NonNullable<Awaited<ReturnType<typeof getAuthFromRequest>>>,
+  req: Request,
+  organizationId: string,
+  tenantId: string,
+): CommandRuntimeContext {
+  return {
+    container,
+    auth,
+    organizationScope: {
+      selectedId: organizationId,
+      filterIds: [organizationId],
+      allowedIds: null,
+      tenantId,
+    },
+    selectedOrganizationId: organizationId,
+    organizationIds: [organizationId],
+    request: req,
+  }
+}
+
+async function resolveCurrentOrganization(req: Request) {
+  const { translate } = await resolveTranslations()
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.sub) {
+    return {
+      response: NextResponse.json({ error: translate('api.errors.unauthorized', 'Unauthorized') }, { status: 401 }),
+    }
+  }
+
+  const container = await createRequestContainer()
+  const scope = await resolveOrganizationScopeForRequest({ container, auth, request: req })
+  const organizationId = scope.selectedId ?? auth.orgId ?? null
+  const tenantId = scope.tenantId ?? auth.tenantId ?? null
+  if (!organizationId || !tenantId) {
+    return {
+      response: NextResponse.json(
+        {
+          error: translate(
+            'directory.branding.errors.organizationRequired',
+            'Select a single organization before changing sidebar branding.',
+          ),
+        },
+        { status: 400 },
+      ),
+    }
+  }
+
+  const em = container.resolve('em') as EntityManager
+  const organization = await findOneWithDecryption(
+    em,
+    Organization,
+    { id: organizationId, tenant: tenantId, deletedAt: null },
+    { populate: ['tenant'] },
+    { tenantId, organizationId },
+  )
+  if (!organization) {
+    return {
+      response: NextResponse.json(
+        { error: translate('directory.branding.errors.notFound', 'Organization not found') },
+        { status: 404 },
+      ),
+    }
+  }
+
+  return { auth, container, organization, organizationId, tenantId, translate }
+}
+
+function toResponsePayload(organization: Organization, tenantId: string) {
+  return {
+    organizationId: String(organization.id),
+    organizationName: organization.name,
+    tenantId,
+    logoUrl: organization.logoUrl ?? null,
+  }
+}
+
+async function invalidateSidebarBrandingCache(container: RequestContainer, organizationId: string, tenantId: string) {
+  try {
+    const cache = container.resolve('cache') as {
+      deleteByTags?: (tags: string[]) => Promise<unknown>
+    } | null
+    await runWithCacheTenant(tenantId, () =>
+      cache?.deleteByTags?.([
+        `nav:sidebar:organization:${organizationId}`,
+        `nav:sidebar:tenant:${tenantId}`,
+      ]),
+    )
+  } catch {
+    // Cache invalidation is best-effort; the persisted branding is the source of truth.
+  }
+}
+
+export async function GET(req: Request) {
+  const resolved = await resolveCurrentOrganization(req)
+  if ('response' in resolved) return resolved.response
+
+  return NextResponse.json(toResponsePayload(resolved.organization, resolved.tenantId))
+}
+
+export async function PUT(req: Request) {
+  const resolved = await resolveCurrentOrganization(req)
+  if ('response' in resolved) return resolved.response
+
+  let body: unknown
+  try {
+    body = await req.json()
+  } catch {
+    return NextResponse.json(
+      { error: resolved.translate('directory.branding.errors.invalidLogoUrl', 'Enter a valid image URL.') },
+      { status: 422 },
+    )
+  }
+  if (!body || typeof body !== 'object' || !Object.prototype.hasOwnProperty.call(body, 'logoUrl')) {
+    return NextResponse.json(
+      { error: resolved.translate('directory.branding.errors.invalidLogoUrl', 'Enter a valid image URL.') },
+      { status: 422 },
+    )
+  }
+
+  const parsed = brandingUpdateSchema.safeParse(body)
+  if (!parsed.success) {
+    return NextResponse.json(
+      {
+        error: resolved.translate('directory.branding.errors.invalidLogoUrl', 'Enter a valid image URL.'),
+        issues: parsed.error.issues,
+      },
+      { status: 422 },
+    )
+  }
+
+  try {
+    const commandBus = resolved.container.resolve('commandBus') as CommandBus
+    const ctx = buildCommandContext(
+      resolved.container,
+      resolved.auth,
+      req,
+      resolved.organizationId,
+      resolved.tenantId,
+    )
+    const { result } = await commandBus.execute<Record<string, unknown>, Organization>(
+      'directory.organizations.update',
+      {
+        input: {
+          id: resolved.organizationId,
+          tenantId: resolved.tenantId,
+          logoUrl: parsed.data.logoUrl ?? null,
+        },
+        ctx,
+      },
+    )
+    await invalidateSidebarBrandingCache(resolved.container, resolved.organizationId, resolved.tenantId)
+    return NextResponse.json(toResponsePayload(result, resolved.tenantId))
+  } catch (err) {
+    if (isCrudHttpError(err)) {
+      return NextResponse.json(err.body, { status: err.status })
+    }
+    console.error('directory.organization-branding.update failed', err)
+    return NextResponse.json(
+      { error: resolved.translate('directory.branding.errors.save', 'Failed to update organization branding.') },
+      { status: 400 },
+    )
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Directory',
+  summary: 'Current organization branding',
+  methods: {
+    GET: {
+      summary: 'Read sidebar branding for the selected organization',
+      description: 'Returns the logo URL used by the backend sidebar for the currently selected organization.',
+      responses: [
+        { status: 200, description: 'Organization branding', schema: brandingResponseSchema },
+      ],
+      errors: [
+        { status: 400, description: 'A concrete organization scope is required', schema: errorSchema },
+        { status: 401, description: 'Unauthorized', schema: errorSchema },
+        { status: 404, description: 'Organization not found', schema: errorSchema },
+      ],
+    },
+    PUT: {
+      summary: 'Update sidebar branding for the selected organization',
+      description: 'Stores an external image URL or an internal attachment image URL as the selected organization logo.',
+      requestBody: {
+        contentType: 'application/json',
+        schema: brandingUpdateSchema,
+      },
+      responses: [
+        { status: 200, description: 'Updated organization branding', schema: brandingResponseSchema },
+      ],
+      errors: [
+        { status: 400, description: 'Save failed', schema: errorSchema },
+        { status: 401, description: 'Unauthorized', schema: errorSchema },
+        { status: 422, description: 'Invalid logo URL', schema: errorSchema },
+      ],
+    },
+  },
+}

package/src/modules/directory/api/organizations/route.ts

@@ -250,6 +250,7 @@ export async function GET(req: Request) {
     const items = orgs.map((org) => ({
       id: stringId(org.id),
       name: org.name,
+      logoUrl: org.logoUrl ?? null,
       parentId: org.parentId ?? null,
       tenantId: tenantId,
       isActive: !!org.isActive,
@@ -341,8 +342,10 @@ export async function GET(req: Request) {
     }
 
     const slugByOrgId = new Map<string, string | null>()
+    const logoUrlByOrgId = new Map<string, string | null>()
     for (const org of allOrgs) {
       slugByOrgId.set(String(org.id), org.slug ?? null)
+      logoUrlByOrgId.set(String(org.id), org.logoUrl ?? null)
     }
 
     const tenantIds = Array.from(byTenant.keys())
@@ -426,6 +429,7 @@ export async function GET(req: Request) {
         id: node.id,
         name: node.name,
         slug: slugByOrgId.get(recordId) ?? null,
+        logoUrl: logoUrlByOrgId.get(recordId) ?? null,
         tenantId: tid,
         tenantName: tenantNameMap[tid] ?? tid,
         parentId: node.parentId,
@@ -467,9 +471,11 @@ export async function GET(req: Request) {
   const orgs = await em.find(Organization, orgListFilter, { orderBy: { name: 'ASC' } })
   const hierarchy = computeHierarchyForOrganizations(orgs, tenantId)
   const slugByOrgId = new Map<string, string | null>()
+  const logoUrlByOrgId = new Map<string, string | null>()
   const updatedAtByOrgId = new Map<string, string | null>()
   for (const org of orgs) {
     slugByOrgId.set(String(org.id), org.slug ?? null)
+    logoUrlByOrgId.set(String(org.id), org.logoUrl ?? null)
     updatedAtByOrgId.set(String(org.id), org.updatedAt instanceof Date ? org.updatedAt.toISOString() : null)
   }
 
@@ -533,6 +539,7 @@ export async function GET(req: Request) {
       id: node.id,
       name: node.name,
       slug: slugByOrgId.get(recordId) ?? null,
+      logoUrl: logoUrlByOrgId.get(recordId) ?? null,
       updatedAt: updatedAtByOrgId.get(recordId) ?? null,
       tenantId: node.tenantId,
       tenantName,

package/src/modules/directory/backend/directory/branding/page.meta.ts

@@ -0,0 +1,24 @@
+import React from 'react'
+
+const brandingIcon = React.createElement(
+  'svg',
+  { width: 16, height: 16, viewBox: '0 0 24 24', fill: 'none', stroke: 'currentColor', strokeWidth: 2, strokeLinecap: 'round', strokeLinejoin: 'round' },
+  React.createElement('rect', { x: 3, y: 5, width: 18, height: 14, rx: 2 }),
+  React.createElement('circle', { cx: 8, cy: 10, r: 1.5 }),
+  React.createElement('path', { d: 'm21 15-5-5L5 21' }),
+)
+
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['directory.organizations.manage'],
+  pageTitle: 'Organization branding',
+  pageTitleKey: 'directory.branding.nav',
+  pageGroup: 'Directory',
+  pageGroupKey: 'settings.sections.directory',
+  pageOrder: 0,
+  icon: brandingIcon,
+  pageContext: 'settings' as const,
+  breadcrumb: [{ label: 'Organization branding', labelKey: 'directory.branding.nav' }],
+}
+
+export default metadata