@open-mercato/core 0.4.11-develop.1398.4cf8d121e7 → 0.4.11-develop.1409.b9a9ec6681

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/core",
-  "version": "0.4.11-develop.1398.4cf8d121e7",
+  "version": "0.4.11-develop.1409.b9a9ec6681",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -230,10 +230,10 @@
     "ts-pattern": "^5.0.0"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.4.11-develop.1398.4cf8d121e7"
+    "@open-mercato/shared": "0.4.11-develop.1409.b9a9ec6681"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.4.11-develop.1398.4cf8d121e7",
+    "@open-mercato/shared": "0.4.11-develop.1409.b9a9ec6681",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.1",

package/src/helpers/integration/auth.ts

@@ -72,6 +72,18 @@ async function acknowledgeGlobalNotices(page: Page): Promise<void> {
       url: baseUrl,
       sameSite: 'Lax',
     },
+    {
+      name: 'om_feedback_suppress',
+      value: '1',
+      url: baseUrl,
+      sameSite: 'Lax',
+    },
+    {
+      name: 'om_feedback_shown',
+      value: new Date().toISOString().slice(0, 10),
+      url: baseUrl,
+      sameSite: 'Lax',
+    },
   ]);
 }
 
@@ -89,6 +101,16 @@ async function dismissGlobalNoticesIfPresent(page: Page): Promise<void> {
       await dismissButton.click();
     }
   }
+
+  const feedbackDialog = page.getByRole('dialog', { name: /Talk to Open Mercato team/i }).first();
+  if (await feedbackDialog.isVisible().catch(() => false)) {
+    const closeButton = feedbackDialog.getByRole('button', { name: /close/i }).first();
+    if (await closeButton.isVisible().catch(() => false)) {
+      await closeButton.click().catch(() => {});
+    } else {
+      await page.keyboard.press('Escape').catch(() => {});
+    }
+  }
 }
 
 async function recoverClientSideErrorPageIfPresent(page: Page): Promise<void> {

package/src/helpers/integration/salesUi.ts

@@ -8,6 +8,7 @@ type CreateDocumentOptions = {
   customerQuery?: string;
   channelQuery?: string;
   preferApi?: boolean;
+  token?: string;
 };
 
 type ChannelListItem = {
@@ -17,6 +18,53 @@ type ChannelListItem = {
   isActive?: boolean | null;
 };
 
+type CustomerAddressListItem = {
+  id?: string | null;
+  name?: string | null;
+  purpose?: string | null;
+  company_name?: string | null;
+  companyName?: string | null;
+  address_line1?: string | null;
+  addressLine1?: string | null;
+  address_line2?: string | null;
+  addressLine2?: string | null;
+  building_number?: string | null;
+  buildingNumber?: string | null;
+  flat_number?: string | null;
+  flatNumber?: string | null;
+  city?: string | null;
+  region?: string | null;
+  postal_code?: string | null;
+  postalCode?: string | null;
+  country?: string | null;
+};
+
+type DocumentAddressPayload = {
+  customerAddressId?: string;
+  name?: string;
+  purpose?: string;
+  companyName?: string;
+  addressLine1: string;
+  addressLine2?: string;
+  buildingNumber?: string;
+  flatNumber?: string;
+  city?: string;
+  region?: string;
+  postalCode?: string;
+  country?: string;
+};
+
+type SalesOrderLineListItem = {
+  id?: string | null;
+};
+
+type PaymentMethodListItem = {
+  id?: string | null;
+  name?: string | null;
+  code?: string | null;
+  isActive?: boolean | null;
+};
+
 type AddLineOptions = {
   name: string;
   quantity: number;
@@ -66,15 +114,38 @@ function readId(payload: unknown, keys: string[]): string | null {
   return null;
 }
 
+function readListItems<T>(payload: { result?: { items?: T[] }; items?: T[] } | null): T[] {
+  return Array.isArray(payload?.result?.items)
+    ? payload.result.items
+    : Array.isArray(payload?.items)
+      ? payload.items
+      : [];
+}
+
+function resolveOrderIdFromPage(page: Page): string | null {
+  const match = page.url().match(/\/backend\/sales\/(?:documents|orders)\/([0-9a-f-]{36})/i);
+  return match?.[1] ?? null;
+}
+
 async function ensureSalesDocumentFixtures(
   page: Page,
   options: CreateDocumentOptions,
-): Promise<{ customerQuery: string; channelQuery: string }> {
+): Promise<{
+  customerQuery: string;
+  channelQuery: string;
+  customerEntityId?: string | null;
+  channelId?: string | null;
+  customerAddressId?: string | null;
+  authToken?: string | null;
+}> {
   let customerQuery = options.customerQuery;
   let channelQuery = options.channelQuery;
+  let customerEntityId: string | null = null;
+  let channelId: string | null = null;
+  let customerAddressId: string | null = null;
 
   if (customerQuery && channelQuery) {
-    return { customerQuery, channelQuery };
+    return { customerQuery, channelQuery, authToken: options.token ?? null };
   }
 
   const token = await getAuthToken(page.request, 'admin').catch(() => null);
@@ -102,6 +173,7 @@ async function ensureSalesDocumentFixtures(
     return {
       customerQuery,
       channelQuery,
+      authToken: options.token ?? null,
     };
   }
 
@@ -113,12 +185,12 @@ async function ensureSalesDocumentFixtures(
     }).catch(() => null);
     if (companyResponse && companyResponse.ok()) {
       const companyBody = (await companyResponse.json().catch(() => null)) as unknown;
-      const companyId = readId(companyBody, ['id', 'entityId', 'companyId']);
-      if (companyId) {
+      customerEntityId = readId(companyBody, ['id', 'entityId', 'companyId']);
+      if (customerEntityId) {
         await apiRequest(page.request, 'POST', '/api/customers/addresses', {
           token,
           data: {
-            entityId: companyId,
+            entityId: customerEntityId,
             name: 'Primary',
             purpose: 'Shipping',
             addressLine1: '100 QA Street',
@@ -127,6 +199,9 @@ async function ensureSalesDocumentFixtures(
             country: 'US',
             isPrimary: true,
           },
+        }).then(async (response) => {
+          const body = (await response.json().catch(() => null)) as unknown;
+          customerAddressId = readId(body, ['id', 'addressId']);
         }).catch(() => {});
         customerQuery = companyName;
       }
@@ -150,6 +225,7 @@ async function ensureSalesDocumentFixtures(
       existingChannels.find((item) => item.isActive !== false);
     if (preferredExistingChannel?.name) {
       channelQuery = preferredExistingChannel.name;
+      channelId = preferredExistingChannel.id ?? null;
     } else {
       const timestamp = Date.now();
       const channelName = `QA Sales Channel ${timestamp}`;
@@ -163,6 +239,8 @@ async function ensureSalesDocumentFixtures(
       }).catch(() => null);
       if (channelResponse && channelResponse.ok()) {
         channelQuery = channelName;
+        const channelBody = (await channelResponse.json().catch(() => null)) as unknown;
+        channelId = readId(channelBody, ['id', 'channelId']);
       } else {
         channelQuery = 'online';
       }
@@ -172,6 +250,10 @@ async function ensureSalesDocumentFixtures(
   return {
     customerQuery: customerQuery ?? 'Copperleaf',
     channelQuery: channelQuery ?? 'online',
+    customerEntityId,
+    channelId,
+    customerAddressId,
+    authToken: token,
   };
 }
 
@@ -284,8 +366,15 @@ async function resolveCustomerEntityId(
 ): Promise<string | null> {
   const params = new URLSearchParams({ page: '1', pageSize: '5', search: customerQuery });
   const response = await apiRequest(page.request, 'GET', `/api/customers/companies?${params.toString()}`, { token }).catch(() => null);
-  const body = (await response?.json().catch(() => null)) as { result?: { items?: Array<Record<string, unknown>> } } | null;
-  const items = Array.isArray(body?.result?.items) ? body.result.items : [];
+  const body = (await response?.json().catch(() => null)) as {
+    result?: { items?: Array<Record<string, unknown>> };
+    items?: Array<Record<string, unknown>>;
+  } | null;
+  const items = Array.isArray(body?.result?.items)
+    ? body.result.items
+    : Array.isArray(body?.items)
+      ? body.items
+      : [];
   const exactMatch = items.find((item) => {
     const displayName = typeof item.displayName === 'string'
       ? item.displayName
@@ -297,6 +386,103 @@ async function resolveCustomerEntityId(
   return exactMatch ? readId(exactMatch, ['id', 'entityId', 'companyId']) : null;
 }
 
+function toDocumentAddressPayload(address: CustomerAddressListItem): DocumentAddressPayload | null {
+  const addressLine1 = typeof address.addressLine1 === 'string'
+    ? address.addressLine1
+    : typeof address.address_line1 === 'string'
+      ? address.address_line1
+      : null;
+  if (!addressLine1) return null;
+  return {
+    customerAddressId: typeof address.id === 'string' ? address.id : undefined,
+    name: typeof address.name === 'string' ? address.name : undefined,
+    purpose: typeof address.purpose === 'string' ? address.purpose : undefined,
+    companyName: typeof address.companyName === 'string'
+      ? address.companyName
+      : typeof address.company_name === 'string'
+        ? address.company_name
+        : undefined,
+    addressLine1,
+    addressLine2: typeof address.addressLine2 === 'string'
+      ? address.addressLine2
+      : typeof address.address_line2 === 'string'
+        ? address.address_line2
+        : undefined,
+    buildingNumber: typeof address.buildingNumber === 'string'
+      ? address.buildingNumber
+      : typeof address.building_number === 'string'
+        ? address.building_number
+        : undefined,
+    flatNumber: typeof address.flatNumber === 'string'
+      ? address.flatNumber
+      : typeof address.flat_number === 'string'
+        ? address.flat_number
+        : undefined,
+    city: typeof address.city === 'string' ? address.city : undefined,
+    region: typeof address.region === 'string' ? address.region : undefined,
+    postalCode: typeof address.postalCode === 'string'
+      ? address.postalCode
+      : typeof address.postal_code === 'string'
+        ? address.postal_code
+        : undefined,
+    country: typeof address.country === 'string' ? address.country : undefined,
+  };
+}
+
+async function ensureCustomerAddressFixture(
+  page: Page,
+  token: string,
+  customerEntityId: string,
+  preferredAddressId?: string | null,
+): Promise<DocumentAddressPayload | null> {
+  const existingResponse = await apiRequest(
+    page.request,
+    'GET',
+    `/api/customers/addresses?page=1&pageSize=20&entityId=${customerEntityId}`,
+    { token },
+  ).catch(() => null);
+  const existingBody = (await existingResponse?.json().catch(() => null)) as {
+    result?: { items?: CustomerAddressListItem[] };
+    items?: CustomerAddressListItem[];
+  } | null;
+  const existingItems = Array.isArray(existingBody?.result?.items)
+    ? existingBody.result.items
+    : Array.isArray(existingBody?.items)
+      ? existingBody.items
+      : [];
+  const preferredAddress = existingItems.find((item) => item.id === preferredAddressId)
+    ?? existingItems.find((item) => item.purpose?.toLowerCase() === 'shipping')
+    ?? existingItems[0];
+  const preferredPayload = preferredAddress ? toDocumentAddressPayload(preferredAddress) : null;
+  if (preferredPayload) return preferredPayload;
+
+  const createResponse = await apiRequest(page.request, 'POST', '/api/customers/addresses', {
+    token,
+    data: {
+      entityId: customerEntityId,
+      name: 'Primary',
+      purpose: 'Shipping',
+      addressLine1: '100 QA Street',
+      city: 'Austin',
+      postalCode: '78701',
+      country: 'US',
+      isPrimary: true,
+    },
+  }).catch(() => null);
+  const createBody = (await createResponse?.json().catch(() => null)) as unknown;
+  const createdAddressId = readId(createBody, ['id', 'addressId']);
+  if (!createResponse?.ok() || !createdAddressId) return null;
+  return {
+    customerAddressId: createdAddressId,
+    name: 'Primary',
+    purpose: 'Shipping',
+    addressLine1: '100 QA Street',
+    city: 'Austin',
+    postalCode: '78701',
+    country: 'US',
+  };
+}
+
 async function resolveSalesChannelId(page: Page, token: string, channelQuery: string): Promise<string | null> {
   const resolveItems = async (search?: string): Promise<ChannelListItem[]> => {
     const params = new URLSearchParams({ page: '1', pageSize: '5', isActive: 'true' });
@@ -321,15 +507,126 @@ async function resolveSalesChannelId(page: Page, token: string, channelQuery: st
   return exactMatch?.id ?? null;
 }
 
+async function resolveOrderLineId(page: Page, token: string, orderId: string): Promise<string | null> {
+  const response = await apiRequest(page.request, 'GET', `/api/sales/order-lines?page=1&pageSize=20&orderId=${orderId}`, {
+    token,
+  }).catch(() => null);
+  const body = (await response?.json().catch(() => null)) as {
+    result?: { items?: SalesOrderLineListItem[] };
+    items?: SalesOrderLineListItem[];
+  } | null;
+  const items = readListItems(body);
+  return items.find((item) => typeof item.id === 'string' && item.id.length > 0)?.id ?? null;
+}
+
+async function resolveShippingMethodId(page: Page, token: string): Promise<string | null> {
+  const response = await apiRequest(
+    page.request,
+    'GET',
+    '/api/sales/shipping-methods?page=1&pageSize=20&isActive=true',
+    { token },
+  ).catch(() => null);
+  const body = (await response?.json().catch(() => null)) as {
+    result?: { items?: ChannelListItem[] };
+    items?: ChannelListItem[];
+  } | null;
+  const items = readListItems(body);
+  const preferred = items.find((item) => item.code === 'standard-ground')
+    ?? items.find((item) => item.name?.toLowerCase().includes('standard'))
+    ?? items[0];
+  return preferred?.id ?? null;
+}
+
+async function resolvePaymentMethodId(page: Page, token: string): Promise<string | null> {
+  const response = await apiRequest(
+    page.request,
+    'GET',
+    '/api/sales/payment-methods?page=1&pageSize=20&isActive=true',
+    { token },
+  ).catch(() => null);
+  const body = (await response?.json().catch(() => null)) as {
+    result?: { items?: PaymentMethodListItem[] };
+    items?: PaymentMethodListItem[];
+  } | null;
+  const items = readListItems(body);
+  const preferred = items.find((item) => item.code === 'bank-transfer')
+    ?? items.find((item) => item.name?.toLowerCase().includes('bank'))
+    ?? items[0];
+  return preferred?.id ?? null;
+}
+
+async function refreshSalesDocumentPage(page: Page, activeTabName: 'Shipments' | 'Payments'): Promise<void> {
+  await page.reload({ waitUntil: 'domcontentloaded' }).catch(() => {});
+  await ensureSalesDocumentReady(page);
+  const tab = page.getByRole('button', { name: new RegExp(`^${activeTabName}$`, 'i') }).first();
+  await waitForStableVisibility(tab, TEST_WAIT_TIMEOUT_MS).catch(() => {});
+  await tab.click().catch(() => {});
+}
+
+async function addShipmentViaApi(
+  page: Page,
+  shipmentNumber: string,
+  trackingNumber: string,
+): Promise<boolean> {
+  const token = await getAuthToken(page.request, 'admin').catch(() => null);
+  const orderId = resolveOrderIdFromPage(page);
+  if (!token || !orderId) return false;
+  const [orderLineId, shippingMethodId] = await Promise.all([
+    resolveOrderLineId(page, token, orderId),
+    resolveShippingMethodId(page, token),
+  ]);
+  if (!orderLineId) return false;
+  const response = await apiRequest(page.request, 'POST', '/api/sales/shipments', {
+    token,
+    data: {
+      orderId,
+      shipmentNumber,
+      ...(shippingMethodId ? { shippingMethodId } : {}),
+      trackingNumbers: [trackingNumber],
+      shippedAt: new Date().toISOString(),
+      currencyCode: 'USD',
+      items: [{ orderLineId, quantity: '1' }],
+    },
+  }).catch(() => null);
+  if (!response?.ok()) return false;
+  await refreshSalesDocumentPage(page, 'Shipments');
+  return true;
+}
+
+async function addPaymentViaApi(page: Page, amount: number): Promise<boolean> {
+  const token = await getAuthToken(page.request, 'admin').catch(() => null);
+  const orderId = resolveOrderIdFromPage(page);
+  if (!token || !orderId) return false;
+  const paymentMethodId = await resolvePaymentMethodId(page, token);
+  const response = await apiRequest(page.request, 'POST', '/api/sales/payments', {
+    token,
+    data: {
+      orderId,
+      ...(paymentMethodId ? { paymentMethodId } : {}),
+      amount: amount.toFixed(2),
+      currencyCode: 'USD',
+      receivedAt: new Date().toISOString(),
+    },
+  }).catch(() => null);
+  if (!response?.ok()) return false;
+  await refreshSalesDocumentPage(page, 'Payments');
+  return true;
+}
+
 async function createSalesDocumentFixture(
   page: Page,
   token: string,
   kind: DocumentKind,
   customerQuery: string,
   channelQuery: string,
+  ids?: { customerEntityId?: string | null; channelId?: string | null; customerAddressId?: string | null },
 ): Promise<string> {
-  const customerEntityId = await resolveCustomerEntityId(page, token, customerQuery);
-  const channelId = await resolveSalesChannelId(page, token, channelQuery);
+  const customerEntityId =
+    ids?.customerEntityId ??
+    await resolveCustomerEntityId(page, token, customerQuery);
+  const channelId =
+    ids?.channelId ??
+    await resolveSalesChannelId(page, token, channelQuery);
   const payload: Record<string, unknown> = {
     currencyCode: 'USD',
   };
@@ -348,6 +645,21 @@ async function createSalesDocumentFixture(
   if (!id) {
     throw new Error(`Missing sales ${kind} id in API fallback response.`);
   }
+
+  if (customerEntityId) {
+    const address = await ensureCustomerAddressFixture(page, token, customerEntityId, ids?.customerAddressId);
+    if (address) {
+      await apiRequest(page.request, 'POST', '/api/sales/document-addresses', {
+        token,
+        data: {
+          documentId: id,
+          documentKind: kind,
+          ...address,
+        },
+      }).catch(() => {});
+    }
+  }
+
   return id;
 }
 
@@ -471,10 +783,16 @@ export async function createSalesDocument(page: Page, options: CreateDocumentOpt
   const fixtureContext = await ensureSalesDocumentFixtures(page, options);
   const customerQuery = fixtureContext.customerQuery;
   const channelQuery = fixtureContext.channelQuery;
+  let fallbackToken: string | null = options.token ?? fixtureContext.authToken ?? null;
+  const resolveFallbackToken = async (): Promise<string> => {
+    if (fallbackToken) return fallbackToken;
+    fallbackToken = await getAuthToken(page.request, 'admin');
+    return fallbackToken;
+  };
 
   if (options.preferApi) {
-    const token = await getAuthToken(page.request, 'admin');
-    const id = await createSalesDocumentFixture(page, token, options.kind, customerQuery, channelQuery);
+    const token = await resolveFallbackToken();
+    const id = await createSalesDocumentFixture(page, token, options.kind, customerQuery, channelQuery, fixtureContext);
     await openSalesDocumentPage(page, id, options.kind);
     return id;
   }
@@ -496,8 +814,8 @@ export async function createSalesDocument(page: Page, options: CreateDocumentOpt
     }
   }
   if (!createPageReady) {
-    const token = await getAuthToken(page.request, 'admin');
-    const id = await createSalesDocumentFixture(page, token, options.kind, customerQuery, channelQuery);
+    const token = await resolveFallbackToken();
+    const id = await createSalesDocumentFixture(page, token, options.kind, customerQuery, channelQuery, fixtureContext);
     await openSalesDocumentPage(page, id, options.kind);
     return id;
   }
@@ -510,7 +828,6 @@ export async function createSalesDocument(page: Page, options: CreateDocumentOpt
   const hasGenerateButton = (await generateButton.count()) > 0;
   if (hasGenerateButton) {
     await expect(generateButton).toBeVisible({ timeout: 10_000 });
-    await expect(generateButton).toBeEnabled({ timeout: 30_000 });
   }
 
   await page.getByText('Document type').click();
@@ -519,20 +836,24 @@ export async function createSalesDocument(page: Page, options: CreateDocumentOpt
     customerQuery,
     new RegExp(escapeRegExp(customerQuery), 'i'),
   );
-  if (!customerSelected) throw new Error(`Could not select customer "${customerQuery}" while creating sales ${options.kind}.`);
-
-  await selectLookupValue(
+  const channelSelected = await selectLookupValue(
     page.getByRole('textbox', { name: /Select a channel/i }).first(),
     channelQuery,
     new RegExp(escapeRegExp(channelQuery), 'i'),
   );
+  if (!customerSelected || !channelSelected) {
+    const token = await resolveFallbackToken();
+    const id = await createSalesDocumentFixture(page, token, options.kind, customerQuery, channelQuery, fixtureContext);
+    await openSalesDocumentPage(page, id, options.kind);
+    return id;
+  }
 
   await selectFirstAddressIfAvailable(page);
 
   const createEnabled = await createButton.isEnabled().catch(() => false);
   if (!createEnabled) {
-    const token = await getAuthToken(page.request, 'admin');
-    const id = await createSalesDocumentFixture(page, token, options.kind, customerQuery, channelQuery);
+    const token = await resolveFallbackToken();
+    const id = await createSalesDocumentFixture(page, token, options.kind, customerQuery, channelQuery, fixtureContext);
     await openSalesDocumentPage(page, id, options.kind);
     return id;
   }
@@ -546,8 +867,8 @@ export async function createSalesDocument(page: Page, options: CreateDocumentOpt
     { timeout: TEST_WAIT_TIMEOUT_MS },
   ).then(() => true).catch(() => false);
   if (!navigated) {
-    const token = await getAuthToken(page.request, 'admin');
-    const id = await createSalesDocumentFixture(page, token, options.kind, customerQuery, channelQuery);
+    const token = await resolveFallbackToken();
+    const id = await createSalesDocumentFixture(page, token, options.kind, customerQuery, channelQuery, fixtureContext);
     await openSalesDocumentPage(page, id, options.kind);
     return id;
   }
@@ -857,7 +1178,10 @@ export async function addPayment(page: Page, amount: number): Promise<{ amountLa
     await dialog.waitFor({ state: 'hidden', timeout: 1_500 }).catch(() => {});
   }
   await operationMessage.waitFor({ state: 'visible', timeout: 2_500 }).catch(() => {});
-  const added = await operationMessage.isVisible().catch(() => false);
+  let added = await operationMessage.isVisible().catch(() => false);
+  if (!added) {
+    added = await addPaymentViaApi(page, amount);
+  }
   return { amountLabel, added };
 }
 
@@ -869,14 +1193,58 @@ export async function addShipment(page: Page): Promise<{ trackingNumber: string;
   await shipmentsTab.click();
   const trackingNumber = `SHIP-${Date.now()}`;
   const shipmentNumber = String(Date.now());
-  const addShipmentButton = page.getByRole('button', { name: /Add shipment/i }).first();
-  await waitForStableVisibility(addShipmentButton, TEST_WAIT_TIMEOUT_MS);
-  await expect(addShipmentButton).toBeEnabled({ timeout: TEST_WAIT_TIMEOUT_MS });
-  await addShipmentButton.click();
-
   const dialog = page.getByRole('dialog', { name: /Add shipment/i });
-  const shipmentNumberInput = dialog.getByRole('textbox').first();
-  await waitForDialogFieldReady(dialog, shipmentNumberInput, /Loading shipments…|Loading shipments\.\.\./i);
+  const openShipmentDialog = async (): Promise<boolean> => {
+    const addShipmentButtons = page.getByRole('button', { name: /Add shipment/i });
+    const buttonCount = await addShipmentButtons.count();
+    for (let index = buttonCount - 1; index >= 0; index -= 1) {
+      const button = addShipmentButtons.nth(index);
+      if (!(await button.isVisible().catch(() => false))) continue;
+      if (!(await button.isEnabled().catch(() => false))) continue;
+      await waitForStableVisibility(button, TEST_WAIT_TIMEOUT_MS).catch(() => {});
+      await button.scrollIntoViewIfNeeded().catch(() => {});
+      await button.click().catch(() => {});
+      const visible = await dialog.waitFor({ state: 'visible', timeout: 2_500 }).then(() => true).catch(() => false);
+      if (visible) return true;
+    }
+    return false;
+  };
+
+  let dialogReady = false;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    const opened = await openShipmentDialog();
+    if (!opened) break;
+    await dialog
+      .getByText(/Loading shipments…|Loading shipments\.\.\./i)
+      .first()
+      .waitFor({ state: 'hidden', timeout: 5_000 })
+      .catch(() => {});
+    const shipmentNumberInput = dialog.locator('input, textarea').first();
+    if (await shipmentNumberInput.isVisible().catch(() => false)) {
+      await waitForStableVisibility(shipmentNumberInput, TEST_WAIT_TIMEOUT_MS).catch(() => {});
+      dialogReady = true;
+      break;
+    }
+    await dialog.getByRole('button', { name: /Close/i }).first().click().catch(() => {});
+    await dialog.waitFor({ state: 'hidden', timeout: 2_000 }).catch(() => {});
+  }
+  if (!dialogReady) {
+    const added = await addShipmentViaApi(page, shipmentNumber, trackingNumber);
+    if (!added) {
+      await openShipmentDialog();
+      const shipmentNumberInput = dialog.locator('input, textarea').first();
+      await waitForDialogFieldReady(dialog, shipmentNumberInput, /Loading shipments…|Loading shipments\.\.\./i);
+    } else {
+      const shipmentLabel = page.getByText(new RegExp(`Shipment\\s+${escapeRegExp(shipmentNumber)}`, 'i')).first();
+      const visible = await shipmentLabel
+        .waitFor({ state: 'visible', timeout: TEST_WAIT_TIMEOUT_MS })
+        .then(() => true)
+        .catch(() => false);
+      return { trackingNumber, shipmentNumber, added: visible };
+    }
+  }
+
+  const shipmentNumberInput = dialog.locator('input, textarea').first();
   await fillShipmentNumber(dialog, shipmentNumber);
   const trackingInput = dialog.getByPlaceholder(/One per line or comma separated/i).first();
   await waitForStableVisibility(trackingInput, 4_000).catch(() => {});

package/src/modules/api_docs/frontend/docs/api/page.tsx

@@ -1,8 +1,7 @@
 import ApiDocsExplorer from './Explorer'
-import { getModules } from '@open-mercato/shared/lib/i18n/server'
-import { buildOpenApiDocument } from '@open-mercato/shared/lib/openapi'
 import { resolveApiDocsBaseUrl } from '@open-mercato/core/modules/api_docs/lib/resources'
 import { APP_VERSION } from '@open-mercato/shared/lib/version'
+import type { OpenApiDocument } from '@open-mercato/shared/lib/openapi'
 
 type ExplorerOperation = {
   id: string
@@ -52,15 +51,19 @@ function buildTagOrder(doc: any, operations: ExplorerOperation[]): string[] {
 
 export default async function ApiDocsViewerPage() {
   const baseUrl = resolveApiDocsBaseUrl()
-  const modules = getModules()
-  const doc = buildOpenApiDocument(modules, {
-    title: 'Open Mercato API',
-    version: APP_VERSION,
-    description: 'Auto-generated OpenAPI definition for all enabled modules.',
-    servers: [{ url: baseUrl, description: 'Default environment' }],
-    baseUrlForExamples: baseUrl,
-    defaultSecurity: ['bearerAuth'],
-  })
+  const response = await fetch(`${baseUrl}/docs/openapi`, { cache: 'no-store' })
+  const doc = response.ok
+    ? await response.json() as OpenApiDocument
+    : {
+        openapi: '3.1.0',
+        info: {
+          title: 'Open Mercato API',
+          version: APP_VERSION,
+          description: 'Auto-generated OpenAPI definition for all enabled modules.',
+        },
+        servers: [{ url: baseUrl, description: 'Default environment' }],
+        paths: {},
+      } satisfies OpenApiDocument
 
   const operations = collectOperations(doc)
   const tagOrder = buildTagOrder(doc, operations)