@open-mercato/ui 0.7.1-develop.7122.1.421cefe668 → 0.7.1-develop.7130.1.fef2396fd8

package/src/ai/__tests__/AiAssistantLauncher.test.tsx

@@ -7,6 +7,7 @@ import { act, screen, waitFor } from '@testing-library/react'
 import { renderWithProviders } from '@open-mercato/shared/lib/testing/renderWithProviders'
 import { apiCall } from '../../backend/utils/apiCall'
 import { AiAssistantLauncher, AI_ASSISTANT_LAUNCHER_OPEN_EVENT } from '../AiAssistantLauncher'
+import { useAiAssistantAvailable } from '../useAiAssistantAvailable'
 
 jest.mock('next/navigation', () => ({
   useRouter: () => ({ replace: jest.fn() }),
@@ -18,11 +19,18 @@ jest.mock('../../backend/utils/apiCall', () => ({
   apiCall: jest.fn(),
 }))
 
+jest.mock('../useAiAssistantAvailable', () => ({
+  useAiAssistantAvailable: jest.fn(() => true),
+}))
+
 const apiCallMock = apiCall as unknown as jest.Mock
+const aiAvailableMock = useAiAssistantAvailable as jest.MockedFunction<typeof useAiAssistantAvailable>
 
 describe('<AiAssistantLauncher>', () => {
   beforeEach(() => {
     apiCallMock.mockReset()
+    aiAvailableMock.mockReset()
+    aiAvailableMock.mockReturnValue(true)
     apiCallMock.mockImplementation(async (url: string) => {
       if (url === '/api/ai_assistant/health') {
         return { ok: true, result: { healthy: true } }
@@ -61,4 +69,63 @@ describe('<AiAssistantLauncher>', () => {
     expect(await screen.findByRole('dialog', { name: 'AI assistants' })).toBeInTheDocument()
     expect(screen.getByText('Catalog Assistant')).toBeInTheDocument()
   }, 60_000)
+
+  it('renders nothing and probes no endpoint when the AI assistant is unavailable', async () => {
+    aiAvailableMock.mockReturnValue(false)
+
+    const { container } = renderWithProviders(<AiAssistantLauncher />)
+
+    expect(container.firstChild).toBeNull()
+
+    // Give the effects a chance to run before asserting they never did.
+    await act(async () => {
+      await Promise.resolve()
+    })
+
+    expect(apiCallMock).not.toHaveBeenCalled()
+    expect(screen.queryByRole('button', { name: 'Open AI assistant' })).toBeNull()
+  })
+
+  it('ignores the global launcher shortcut event when the AI assistant is unavailable', async () => {
+    aiAvailableMock.mockReturnValue(false)
+
+    renderWithProviders(<AiAssistantLauncher />)
+
+    act(() => {
+      window.dispatchEvent(new CustomEvent(AI_ASSISTANT_LAUNCHER_OPEN_EVENT))
+    })
+
+    await act(async () => {
+      await Promise.resolve()
+    })
+
+    expect(screen.queryByRole('dialog', { name: 'AI assistants' })).toBeNull()
+    expect(apiCallMock).not.toHaveBeenCalled()
+  })
+
+  // The gate is fail-closed until the backend chrome payload arrives, so on an
+  // enabled install the launcher always mounts unavailable first and only then
+  // flips. The probes must fire on that transition, and only once.
+  it('probes exactly once when the gate opens after mount', async () => {
+    aiAvailableMock.mockReturnValue(false)
+
+    const { rerender } = renderWithProviders(<AiAssistantLauncher />)
+
+    await act(async () => {
+      await Promise.resolve()
+    })
+    expect(apiCallMock).not.toHaveBeenCalled()
+
+    aiAvailableMock.mockReturnValue(true)
+    rerender(<AiAssistantLauncher />)
+
+    await waitFor(() => {
+      expect(screen.getAllByRole('button', { name: 'Open AI assistant' }).length).toBeGreaterThan(0)
+    })
+
+    const agentsCalls = apiCallMock.mock.calls.filter(
+      ([url]) => url === '/api/ai_assistant/ai/agents',
+    )
+    expect(agentsCalls).toHaveLength(1)
+  }, 60_000)
 })

package/src/ai/__tests__/AiChatSessions.test.tsx

@@ -24,6 +24,10 @@ jest.mock('../conversation-store', () => {
   }
 })
 
+jest.mock('../useAiAssistantAvailable', () => ({
+  useAiAssistantAvailable: jest.fn(() => true),
+}))
+
 jest.mock('@open-mercato/shared/lib/logger', () => {
   const mocked = {
     debug: jest.fn(),
@@ -41,9 +45,11 @@ import {
   listAiServerConversations,
   createAiServerConversation,
 } from '../conversation-store'
+import { useAiAssistantAvailable } from '../useAiAssistantAvailable'
 
 const listMock = listAiServerConversations as jest.MockedFunction<typeof listAiServerConversations>
 const createMock = createAiServerConversation as jest.MockedFunction<typeof createAiServerConversation>
+const aiAvailableMock = useAiAssistantAvailable as jest.MockedFunction<typeof useAiAssistantAvailable>
 const loggerError = createLogger('ui').error as jest.Mock
 const loggerWarn = createLogger('ui').warn as jest.Mock
 
@@ -84,6 +90,8 @@ describe('<AiChatSessionsProvider> — tenant/org scope isolation', () => {
     listMock.mockResolvedValue(null)
     createMock.mockReset()
     createMock.mockResolvedValue(null)
+    aiAvailableMock.mockReset()
+    aiAvailableMock.mockReturnValue(true)
     loggerError.mockClear()
     loggerWarn.mockClear()
     // Reset scope to a known starting point. The module-level state in
@@ -292,3 +300,72 @@ describe('<AiChatSessionsProvider> — tenant/org scope isolation', () => {
     expect(window.localStorage.getItem(scopedKey(null, null))).not.toBeNull()
   })
 })
+
+describe('<AiChatSessionsProvider> — ai_assistant availability gate', () => {
+  beforeEach(() => {
+    window.localStorage.clear()
+    listMock.mockReset()
+    listMock.mockResolvedValue([])
+    createMock.mockReset()
+    createMock.mockResolvedValue(null)
+    aiAvailableMock.mockReset()
+    loggerError.mockClear()
+    loggerWarn.mockClear()
+    act(() => {
+      emitOrganizationScopeChanged({ tenantId: 'T1', organizationId: 'O1' })
+    })
+  })
+
+  afterEach(() => {
+    window.localStorage.clear()
+  })
+
+  it('skips the server conversation sync when the AI assistant is unavailable', async () => {
+    aiAvailableMock.mockReturnValue(false)
+
+    renderWithProviders(<Harness agentId="assistant" />)
+
+    // Children still render — the provider owns context every backend page needs.
+    await waitFor(() => {
+      expect(screen.getByTestId('session-count').textContent).toBe('0')
+    })
+
+    expect(listMock).not.toHaveBeenCalled()
+    expect(loggerWarn).not.toHaveBeenCalled()
+    expect(loggerError).not.toHaveBeenCalled()
+  })
+
+  it('syncs once when the AI assistant is available', async () => {
+    aiAvailableMock.mockReturnValue(true)
+
+    renderWithProviders(<Harness agentId="assistant" />)
+
+    await waitFor(() => {
+      expect(listMock).toHaveBeenCalledTimes(1)
+    })
+    expect(listMock).toHaveBeenCalledWith({ limit: 100 })
+  })
+
+  // The gate is fail-closed while the backend chrome payload is still null,
+  // which is the state at mount on every install. So on an enabled install the
+  // sync only ever happens on the re-run triggered by `aiAvailable` flipping
+  // true — this pins that dependency.
+  it('syncs once the availability gate opens after mount', async () => {
+    aiAvailableMock.mockReturnValue(false)
+
+    const { rerender } = renderWithProviders(<Harness agentId="assistant" />)
+
+    await waitFor(() => {
+      expect(screen.getByTestId('session-count').textContent).toBe('0')
+    })
+    expect(listMock).not.toHaveBeenCalled()
+
+    aiAvailableMock.mockReturnValue(true)
+    rerender(<Harness agentId="assistant" />)
+
+    await waitFor(() => {
+      expect(listMock).toHaveBeenCalledTimes(1)
+    })
+    expect(listMock).toHaveBeenCalledWith({ limit: 100 })
+  })
+})

package/src/ai/__tests__/useAiAssistantAvailable.test.tsx

@@ -0,0 +1,96 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import * as React from 'react'
+import { render, screen } from '@testing-library/react'
+import type { BackendChromePayload } from '@open-mercato/shared/modules/navigation/backendChrome'
+import { useBackendChrome } from '../../backend/BackendChromeProvider'
+import { getEnabledModuleIds } from '@open-mercato/shared/modules/widgets/injection-loader'
+import { useAiAssistantAvailable } from '../useAiAssistantAvailable'
+
+jest.mock('../../backend/BackendChromeProvider', () => ({
+  useBackendChrome: jest.fn(),
+}))
+
+jest.mock('@open-mercato/shared/modules/widgets/injection-loader', () => ({
+  getEnabledModuleIds: jest.fn(),
+  subscribeToInjectionRegistryChanges: () => () => {},
+}))
+
+const useBackendChromeMock = useBackendChrome as jest.MockedFunction<typeof useBackendChrome>
+const getEnabledModuleIdsMock = getEnabledModuleIds as jest.MockedFunction<typeof getEnabledModuleIds>
+
+function Probe() {
+  const available = useAiAssistantAvailable()
+  return <span data-testid="available">{String(available)}</span>
+}
+
+function setChrome(grantedFeatures: string[] | null) {
+  useBackendChromeMock.mockReturnValue({
+    payload: grantedFeatures === null
+      ? null
+      : ({ grantedFeatures } as unknown as BackendChromePayload),
+    isLoading: false,
+    isReady: true,
+    refresh: async () => {},
+  })
+}
+
+function renderProbe(): string | null {
+  render(<Probe />)
+  return screen.getByTestId('available').textContent
+}
+
+describe('useAiAssistantAvailable', () => {
+  beforeEach(() => {
+    useBackendChromeMock.mockReset()
+    getEnabledModuleIdsMock.mockReset()
+  })
+
+  it('is true when the module is enabled and the feature is granted', () => {
+    getEnabledModuleIdsMock.mockReturnValue(new Set(['auth', 'ai_assistant']))
+    setChrome(['auth.users.view', 'ai_assistant.view'])
+
+    expect(renderProbe()).toBe('true')
+  })
+
+  it('is false when the module is absent from the enabled registry', () => {
+    getEnabledModuleIdsMock.mockReturnValue(new Set(['auth', 'customers']))
+    setChrome(['auth.users.view', 'ai_assistant.view'])
+
+    expect(renderProbe()).toBe('false')
+  })
+
+  it('is false when the feature is not granted', () => {
+    getEnabledModuleIdsMock.mockReturnValue(new Set(['auth', 'ai_assistant']))
+    setChrome(['auth.users.view'])
+
+    expect(renderProbe()).toBe('false')
+  })
+
+  it('is false while the backend chrome payload has not arrived', () => {
+    getEnabledModuleIdsMock.mockReturnValue(new Set(['auth', 'ai_assistant']))
+    setChrome(null)
+
+    expect(renderProbe()).toBe('false')
+  })
+
+  it('treats an unregistered module set as "not known yet" rather than disabled', () => {
+    // `registerEnabledModuleIds` runs from an async client-bootstrap import, so
+    // `null` here means the registry has not landed — not that the module is off.
+    getEnabledModuleIdsMock.mockReturnValue(null)
+    setChrome(['ai_assistant.view'])
+
+    expect(renderProbe()).toBe('true')
+  })
+
+  it('matches a module wildcard grant', () => {
+    // Superadmins carry `<module>.*`, expanded server-side for enabled modules
+    // only. A plain `includes()` would miss it.
+    getEnabledModuleIdsMock.mockReturnValue(new Set(['ai_assistant']))
+    setChrome(['ai_assistant.*'])
+
+    expect(renderProbe()).toBe('true')
+  })
+})

package/src/ai/index.ts

@@ -27,6 +27,11 @@ export {
   type UseAiChatInput,
   type UseAiChatResult,
 } from './useAiChat'
+export {
+  useAiAssistantAvailable,
+  AI_ASSISTANT_MODULE_ID,
+  AI_ASSISTANT_VIEW_FEATURE,
+} from './useAiAssistantAvailable'
 export {
   useAiShortcuts,
   type UseAiShortcutsOptions,

package/src/ai/useAiAssistantAvailable.ts

@@ -0,0 +1,50 @@
+"use client"
+
+import * as React from 'react'
+import {
+  getEnabledModuleIds,
+  subscribeToInjectionRegistryChanges,
+} from '@open-mercato/shared/modules/widgets/injection-loader'
+import { hasFeature } from '@open-mercato/shared/security/features'
+import { useBackendChrome } from '../backend/BackendChromeProvider'
+
+export const AI_ASSISTANT_MODULE_ID = 'ai_assistant'
+export const AI_ASSISTANT_VIEW_FEATURE = 'ai_assistant.view'
+
+function readEnabledModuleIds(): ReadonlySet<string> | null {
+  return getEnabledModuleIds()
+}
+
+function readEnabledModuleIdsOnServer(): ReadonlySet<string> | null {
+  return null
+}
+
+/**
+ * Whether the AI assistant surfaces should mount at all.
+ *
+ * Every `/api/ai_assistant/*` route is gated on `ai_assistant.view`, and an
+ * installation that does not enable the module has no such routes to answer.
+ * Mounting the launcher or the conversation sync in either case only produces
+ * 404s / 403s, so both call sites consult this first instead of probing.
+ *
+ * Two independent signals have to agree:
+ *   - the client enabled-module registry, populated from the generated
+ *     `enabled-module-ids.generated.ts` during client bootstrap. It registers
+ *     asynchronously, so `null` means "not known yet", not "module absent".
+ *   - `ai_assistant.view` in the backend chrome payload. The server already
+ *     drops grants owned by disabled modules (and expands a superadmin `*`
+ *     into enabled modules only), and the payload is fetched once and cached
+ *     by `BackendChromeProvider`, so this costs no extra request. It stays
+ *     fail-closed until the payload arrives, which is what keeps the cold-load
+ *     window quiet.
+ */
+export function useAiAssistantAvailable(): boolean {
+  const { payload } = useBackendChrome()
+  const enabledModuleIds = React.useSyncExternalStore(
+    subscribeToInjectionRegistryChanges,
+    readEnabledModuleIds,
+    readEnabledModuleIdsOnServer,
+  )
+  const moduleEnabled = enabledModuleIds === null || enabledModuleIds.has(AI_ASSISTANT_MODULE_ID)
+  return moduleEnabled && hasFeature(payload?.grantedFeatures, AI_ASSISTANT_VIEW_FEATURE)
+}

package/src/backend/detail/__tests__/addressFormat.taxId.test.ts

@@ -0,0 +1,33 @@
+import { resolveTaxIdLabel } from '../addressFormat'
+
+// This module is a documented near-identical twin of `@open-mercato/core`'s `customers/utils/
+// addressFormat`, and the spec forbids letting the two drift. The core copy has these cases; without
+// them here, a change made on one side and forgotten on the other passes CI.
+
+describe('resolveTaxIdLabel — the ui twin', () => {
+  const BY_TYPE = { plNip: 'NIP', euVat: 'EU VAT', other: 'Tax number' }
+
+  // The distinction the scheme exists for: `1234567890` and `PL1234567890` are the same business, so
+  // one flat label necessarily misnames one of them.
+  it('names a domestic identifier and an EU VAT number differently', () => {
+    expect(resolveTaxIdLabel(BY_TYPE, 'pl_nip')).toBe('NIP')
+    expect(resolveTaxIdLabel(BY_TYPE, 'eu_vat')).toBe('EU VAT')
+  })
+
+  // Naming a foreign number after a domestic scheme renames it, so an unknown scheme takes the
+  // neutral label rather than the nearest guess. This is also what lets the vocabulary widen.
+  it('falls back to the neutral label for unknown and missing schemes', () => {
+    expect(resolveTaxIdLabel(BY_TYPE, 'other')).toBe('Tax number')
+    expect(resolveTaxIdLabel(BY_TYPE, 'us_ein')).toBe('Tax number')
+    expect(resolveTaxIdLabel(BY_TYPE, null)).toBe('Tax number')
+    expect(resolveTaxIdLabel(BY_TYPE, undefined)).toBe('Tax number')
+  })
+
+  it('accepts a plain string, which names every scheme the same', () => {
+    expect(resolveTaxIdLabel('Tax ID', 'eu_vat')).toBe('Tax ID')
+  })
+
+  it('has no label to give when the caller supplies none', () => {
+    expect(resolveTaxIdLabel(undefined, 'pl_nip')).toBeUndefined()
+  })
+})

package/src/backend/detail/addressFormat.tsx

@@ -12,6 +12,34 @@ export type AddressValue = {
   postalCode?: string | null
   country?: string | null
   companyName?: string | null
+  /**
+   * Contact details that belong to the ADDRESS rather than to the customer: who to call about this
+   * delivery, and the tax identifier this invoice address was billed under. They remain available to
+   * address editors and snapshot payloads, but are deliberately excluded from `formatAddressLines`
+   * and `AddressView`, whose existing contract remains postal-only.
+   *
+   * `taxIdType` interprets the value in Stripe's `{country}_{kind}` vocabulary (`pl_nip`, `eu_vat`,
+   * `other`, widened additively): `1234567890` and `PL1234567890` are the same business, and only the
+   * type tells a domestic identifier from an EU VAT number. It is metadata about `taxId`, never a
+   * displayed field of its own.
+   */
+  phone?: string | null
+  taxId?: string | null
+  taxIdType?: string | null
+}
+
+/**
+ * Tax-id labels keyed by `taxIdType`, for a caller that wants the identifier named correctly rather
+ * than generically.
+ *
+ * The stored scheme is chosen explicitly rather than inferred from the identifier. `other` also
+ * covers an address written before `taxIdType` existed. An unrecognised type takes the `other` route
+ * instead of guessing a domestic scheme.
+ */
+export type TaxIdLabelByType = {
+  plNip: string
+  euVat: string
+  other: string
 }
 
 export type AddressJsonShape = {
@@ -99,6 +127,31 @@ export function formatAddressString(address: AddressValue, format: AddressFormat
   return formatAddressLines(address, format).filter(Boolean).join(separator)
 }
 
+/**
+ * Which member of a label map names which scheme. Private, and deliberately not exhaustive: an
+ * unrecognised type resolves to `other`, so the vocabulary can widen without every caller being
+ * updated in the same release.
+ */
+const TAX_ID_LABEL_KEY_BY_TYPE: Record<string, keyof TaxIdLabelByType> = {
+  pl_nip: 'plNip',
+  eu_vat: 'euVat',
+}
+
+/**
+ * The label a tax identifier should carry, given its type. Exported because the editor renders the
+ * same identifier as an input and must name it the same way this formatter does — two copies of the
+ * mapping is exactly how a foreign number ends up under a domestic scheme's name.
+ */
+export function resolveTaxIdLabel(
+  label: string | TaxIdLabelByType | undefined,
+  taxIdType: string | null | undefined,
+): string | undefined {
+  if (!label) return undefined
+  if (typeof label === 'string') return label
+  const key = TAX_ID_LABEL_KEY_BY_TYPE[typeof taxIdType === 'string' ? taxIdType : ''] ?? 'other'
+  return label[key]
+}
+
 type AddressViewProps = {
   address: AddressValue
   format: AddressFormatStrategy
@@ -106,7 +159,12 @@ type AddressViewProps = {
   lineClassName?: string
 }
 
-export function AddressView({ address, format, className, lineClassName }: AddressViewProps): React.ReactElement | null {
+export function AddressView({
+  address,
+  format,
+  className,
+  lineClassName,
+}: AddressViewProps): React.ReactElement | null {
   const lines = formatAddressLines(address, format)
   if (!lines.length) return null
   return (