Next.js + commercetools Storefront

// WRONG — one BU's orders appear for every other BU
return useSWR(KEY_ORDERS, fetcher);

// lib/cache-keys.ts
export const KEY_ORDERS = 'orders';
export function keyOrder(id: string) { return `order-${id}`; }

// BU-scoped: orders, quotes, approval flows, purchase lists
export function keyOrdersByBU(buKey: string) {
  return [KEY_ORDERS, buKey] as const;
}

// Store-scoped: prices, inventory, product selections differ per store
export function keyProductsByStore(buKey: string, storeKey: string) {
  return [KEY_PRODUCTS, buKey, storeKey] as const;
}

// hooks/useOrders.ts
export function useOrders() {
  const { currentBusinessUnit } = useBusinessUnit();
  const buKey = currentBusinessUnit?.key ?? null;

  return useSWR<Order[]>(
    buKey ? [KEY_ORDERS, buKey] : null,   // null = skip fetch when no BU selected
    ([, bk]) => ordersFetcher(bk),
    { revalidateOnFocus: false }
  );
}

export function useOrderMutations() {
  const { mutate } = useSWRConfig();
  const { currentBusinessUnit } = useBusinessUnit();

  async function cancelOrder(orderId: string) {
    const updated = await cancelOrderRequest(orderId); // throws on error
    const buKey = currentBusinessUnit?.key;
    if (buKey) mutate([KEY_ORDERS, buKey]);                          // invalidate list
    mutate(keyOrder(orderId), updated.order, { revalidate: false }); // update detail
  }

  return { cancelOrder };
}

// WRONG — bypasses B2B permission model; commercetools will not check associate roles
const { body } = await apiRoot.orders().get(...).execute();

// lib/ct/orders.ts
export async function getOrders(
  associateId: string,
  businessUnitKey: string
): Promise<Order[]> {
  const { body } = await apiRoot
    .asAssociate()
    .withAssociateIdValue({ associateId })
    .inBusinessUnitKeyWithBusinessUnitKeyValue({ businessUnitKey })
    .orders()
    .get({ queryArgs: { sort: 'createdAt desc', limit: 20 } })
    .execute();
  return body.results.map(mapOrder); // always map before returning
}

// WRONG
if (!session.customerId) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });

// app/api/orders/route.ts
export async function GET() {
  const session = await getSession();
  if (!session.customerId || !session.businessUnitKey) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }
  try {
    const orders = await getOrders(session.customerId, session.businessUnitKey);
    return NextResponse.json({ orders });
  } catch (e: unknown) {
    const msg = e instanceof Error ? e.message : 'Failed to fetch orders';
    return NextResponse.json({ error: msg }, { status: 500 });
  }
}

// WRONG — commercetools requires the nested tiers/and/or structure
approvers: [{ associateRole: { key: 'approver', typeId: 'associate-role' } }]

// lib/ct/approval-rules.ts
export async function createApprovalRule(
  associateId: string,
  businessUnitKey: string,
  draft: {
    name: string;
    description?: string;
    status: 'Active' | 'Inactive';
    predicate: string;
    requesters: Array<{ associateRole: { key: string; typeId: 'associate-role' } }>;
    approvers: {
      tiers: Array<{
        and: Array<{
          or: Array<{ associateRole: { key: string; typeId: 'associate-role' } }>;
        }>;
      }>;
    };
  }
) {
  const { body } = await apiRoot
    .asAssociate()
    .withAssociateIdValue({ associateId })
    .inBusinessUnitKeyWithBusinessUnitKeyValue({ businessUnitKey })
    .approvalRules()
    .post({ body: draft })
    .execute();
  return body;
}

const draft = {
  name: 'Large Order Approval',
  status: 'Active',
  predicate: 'totalPrice.centAmount > 500000',
  requesters: [{ associateRole: { key: 'buyer', typeId: 'associate-role' } }],
  approvers: {
    tiers: [
      {
        // Tier 1: any associate with 'approver' role must approve first
        and: [{ or: [{ associateRole: { key: 'approver', typeId: 'associate-role' } }] }],
      },
      {
        // Tier 2: any associate with 'admin' role must approve after tier 1
        and: [{ or: [{ associateRole: { key: 'admin', typeId: 'associate-role' } }] }],
      },
    ],
  },
};

// WRONG — version may be stale if another approver acted concurrently
await performApprovalAction(flowId, cachedFlow.version, 'approve');

// lib/ct/approval-flows.ts
async function fetchApprovalFlowRaw(
  associateId: string, businessUnitKey: string, flowId: string
) {
  const { body } = await apiRoot
    .asAssociate()
    .withAssociateIdValue({ associateId })
    .inBusinessUnitKeyWithBusinessUnitKeyValue({ businessUnitKey })
    .approvalFlows()
    .withId({ ID: flowId })
    .get()
    .execute();
  return body; // raw commercetools response — has current .version
}

export async function approveFlow(
  associateId: string, businessUnitKey: string, flowId: string
) {
  // Read-then-write: get current version before posting
  const raw = await fetchApprovalFlowRaw(associateId, businessUnitKey, flowId);
  const { body } = await apiRoot
    .asAssociate()
    .withAssociateIdValue({ associateId })
    .inBusinessUnitKeyWithBusinessUnitKeyValue({ businessUnitKey })
    .approvalFlows()
    .withId({ ID: flowId })
    .post({ body: { version: raw.version, actions: [{ action: 'approve' }] } })
    .execute();
  return mapApprovalFlow(body);
}

export async function rejectFlow(
  associateId: string, businessUnitKey: string, flowId: string, reason?: string
) {
  const raw = await fetchApprovalFlowRaw(associateId, businessUnitKey, flowId);
  const { body } = await apiRoot
    .asAssociate()
    .withAssociateIdValue({ associateId })
    .inBusinessUnitKeyWithBusinessUnitKeyValue({ businessUnitKey })
    .approvalFlows()
    .withId({ ID: flowId })
    .post({ body: { version: raw.version, actions: [{ action: 'reject', reason }] } })
    .execute();
  return mapApprovalFlow(body);
}

// WRONG — shows buttons to associates who are not eligible or not in the active tier
{flow.status === 'Pending' && (
  <Button onClick={handleApprove}>Approve</Button>
)}

// app/[locale]/dashboard/orders/[id]/page.tsx
const { roleKeys } = usePermissions();

// Check 1: user's role is listed as eligible for this flow
const isEligibleApprover = flow.eligibleApprovers.some(
  (a) => roleKeys.has(a.associateRole.key)
);

// Check 2: user's role is in the currently active tier (not a future tier)
const canActOnCurrentTier = flow.currentTierPendingApprovers.some(
  (a) => roleKeys.has(a.associateRole.key)
);

// Only show buttons when BOTH conditions are true
{isEligibleApprover && canActOnCurrentTier && flow.status === 'Pending' && (
  <>
    <Button onClick={() => handleAction('approve')}>Approve</Button>
    <Button variant="danger" onClick={() => setShowRejectModal(true)}>Reject</Button>
  </>
)}

// WRONG — causes an error page for associates who just can't see flows
if (response.status === 403) {
  return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
}

// app/api/approval-flows/route.ts
export async function GET() {
  const session = await getSession();
  if (!session.customerId || !session.businessUnitKey) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  try {
    const flows = await getApprovalFlows(session.customerId, session.businessUnitKey);
    return NextResponse.json({ results: flows, total: flows.length });
  } catch (error: unknown) {
    const statusCode = (error as { statusCode?: number }).statusCode;
    // commercetools 403 = associate lacks UpdateApprovalFlows — return empty list, not an error
    if (statusCode === 403) {
      return NextResponse.json({ results: [], total: 0 });
    }
    return NextResponse.json({ error: 'Failed to fetch approval flows' }, { status: 500 });
  }
}

// lib/ct/cart.ts
function asAssociateInStore(associateId: string, businessUnitKey: string) {
  return apiRoot
    .asAssociate()
    .withAssociateIdValue({ associateId })
    .inBusinessUnitKeyWithBusinessUnitKeyValue({ businessUnitKey })
    .carts();
}

// lib/ct/cart.ts
export async function createCart(
  customerId: string,
  associateId: string,
  businessUnitKey: string,
  storeKey: string,
  currency = 'USD',
  country = 'US'
) {
  const { body } = await asAssociateInStore(associateId, businessUnitKey)
    .post({
      body: {
        currency,
        country,
        customerId,
        businessUnit: { key: businessUnitKey, typeId: 'business-unit' },
        store: { key: storeKey, typeId: 'store' },
      },
    })
    .execute();
  return mapCart(body);
}

// lib/ct/cart.ts
export async function addLineItem(
  cartId: string, version: number,
  productId: string, variantId: number, quantity: number,
  associateId: string, businessUnitKey: string, storeKey: string,
  distributionChannelId?: string,
  locale?: string
) {
  const action: CartAddLineItemAction = {
    action: 'addLineItem',
    productId,
    variantId,
    quantity,
    ...(distributionChannelId
      ? { distributionChannel: { id: distributionChannelId, typeId: 'channel' } }
      : {}),
  };

  const { body } = await asAssociateInStore(associateId, businessUnitKey)
    .withId({ ID: cartId })
    .post({ body: { version, actions: [action] } })
    .execute();
  return mapCart(body, locale);
}

addresses (shipping + billing) → shipping method → payment (commercetools checkout SDK) → confirmation

addresses (shipping + billing) → shipping method → comment → submit

/checkout/quote-request-confirmation?quoteRequestId=<id>

// WRONG — stale data persists when user switches business units
return useSWR(KEY_ORDERS, ordersFetcher, { revalidateOnFocus: false });

// hooks/useOrders.ts
export function useOrders() {
  const { currentBusinessUnit } = useBusinessUnit();
  const buKey = currentBusinessUnit?.key ?? null;

  return useSWR(
    buKey ? [KEY_ORDERS, buKey] : null,  // null = skip fetch until BU is selected
    ([, bk]) => fetchOrders(bk),
    { revalidateOnFocus: false }
  );
}

// hooks/useMyStats.ts
const KEY_MY_STATS = 'my-stats';

export function useMyStats() {
  const { currentBusinessUnit } = useBusinessUnit();
  const buKey = currentBusinessUnit?.key ?? null;
  return useSWR(
    buKey ? [KEY_MY_STATS, buKey] : null,
    ([, bk]) => fetch(`/api/my-stats?buKey=${bk}`).then(r => r.json()),
    { revalidateOnFocus: false }
  );
}

const { data: myStats } = useMyStats();
const { can } = usePermissions();

const statCards = [
  // ... existing cards
  {
    label: t('myMetric'),
    value: myStats?.total ?? 0,
    href: '/dashboard/my-section',
    enabled: can('SomePermission'),  // disabled cards show lock icon + opacity-50
  },
];

// app/[locale]/dashboard/my-section/page.tsx
'use client';

import { Suspense } from 'react';
import { useTranslations } from 'next-intl';
import { usePermissions } from '@/hooks/usePermissions';
import { useMyData } from '@/hooks/useMyData';

function MySectionContent() {
  const t = useTranslations('mySection');
  const { can } = usePermissions();
  const { data, isLoading } = useMyData();

  // Gate the entire page — shows nothing if permission is missing
  if (!can('SomePermission')) return null;
  if (isLoading) return <div>{t('loading')}</div>;

  return (
    <div>
      <h1 className="mb-6 text-2xl font-bold">{t('title')}</h1>
      <div className="rounded-xl border border-gray-100 bg-white p-6">
        {/* content */}
      </div>
    </div>
  );
}

// Always wrap in Suspense — required when useSearchParams is used inside
export default function MySectionPage() {
  return (
    <Suspense>
      <MySectionContent />
    </Suspense>
  );
}

const NAV_ITEMS = [
  // existing items...
  {
    label: t('mySection'),              // from 'nav' translation namespace
    href: '/dashboard/my-section',      // locale prefix added by Link automatically
    requiredPermissions: ['SomePermission', 'AnotherPermission'],
    // omit requiredPermissions to show always
  },
];

{ "nav": { "mySection": "My Section" } }

return useSWR<Order[]>(
  buKey ? [KEY_ORDERS, buKey] : null,
  ordersFetcher,
  { revalidateOnFocus: false }
);

where: businessUnit(key="${businessUnitKey}")

expand: ['originOrder']

originOrder.obj?.lineItems?.find(li => li.recurrenceInfo?.recurrencePolicy?.id)
  ?.recurrenceInfo?.recurrencePolicy?.id

{
  originOrder: { typeId: 'order', id: orderId },
  cart: { typeId: 'cart', id: cartId },
  customer: { typeId: 'customer', id: customerId },
  startsAt?: string,    // ISO 8601 — optional
  expiresAt?: string,   // ISO 8601 — optional
}

// app/api/auth/login/route.ts  (after fetching businessUnits)
const SUPERUSER_ROLE_KEY = 'superuser';
const isSuperuser = businessUnits.some(bu =>
  bu.associates?.some(associate =>
    associate.customer.id === customer.id &&
    associate.associateRoleAssignments.some(a => a.associateRole.key === SUPERUSER_ROLE_KEY)
  )
);

await setSession(response, {
  customerId: customer.id,
  isSuperuser,
  // ... other session fields
});

export async function getAllSuperuserCarts(businessUnitKey: string, storeKey: string): Promise<Cart[]> {
  const response = await apiRoot
    .carts()
    .get({
      queryArgs: {
        where: [`cartState="Active"`, `store(key="${storeKey}")`, `businessUnit(key="${businessUnitKey}")`],
        limit: 20,
        sort: 'createdAt desc',
        expand: ['createdBy.customer'],  // avoids N+1 — creator info in one request
      },
    })
    .execute();

  return response.body.results.map(ct => ({
    id: ct.id,
    version: ct.version,
    origin: ct.origin,
    createdByEmail: (ct.createdBy as any)?.customer?.email,
    createdByName: [(ct.createdBy as any)?.customer?.firstName, (ct.createdBy as any)?.customer?.lastName]
      .filter(Boolean).join(' '),
    // ... rest of cart fields
  }));
}

export async function createSuperuserCart(associateId, businessUnitKey, storeKey, currency = 'USD', country = 'US') {
  const response = await apiRoot
    .asAssociate()
    .withAssociateIdValue({ associateId })
    .inBusinessUnitKeyWithBusinessUnitKeyValue({ businessUnitKey })
    .carts()
    .post({
      body: {
        currency, country,
        origin: 'Merchant',  // commercetools-native way to mark merchant-created carts
        businessUnit: { key: businessUnitKey, typeId: 'business-unit' },
        store: { key: storeKey, typeId: 'store' },
      },
    })
    .execute();
  return response.body;
}

export async function reassignCart(cartId, version, associateId, businessUnitKey, targetCustomerId) {
  const response = await apiRoot
    .asAssociate()
    .withAssociateIdValue({ associateId })
    .inBusinessUnitKeyWithBusinessUnitKeyValue({ businessUnitKey })
    .carts()
    .withId({ ID: cartId })
    .post({ body: { version, actions: [{ action: 'setCustomerId', customerId: targetCustomerId }] } })
    .execute();
  return response.body;
}

// context/SuperuserContext.tsx
export function SuperuserProvider({ children }) {
  const { data } = useSWR(KEY_SUPERUSER_STATUS, superuserStatusFetcher, { revalidateOnFocus: false });
  const superuserStatus = data ?? { isSuperuser: false, carts: [] };

  const switchCart = useCallback(async (cartId: string) => {
    const res = await fetch('/api/superuser/carts/switch', { method: 'POST', body: JSON.stringify({ cartId }) });
    if (!res.ok) throw new Error('Failed to switch cart');
    mutateGlobal(KEY_CART);         // force CartContext to refetch
    window.location.replace(window.location.pathname);  // full reload
  }, [...]);

  const createMerchantCart = useCallback(async () => {
    await fetch('/api/superuser/carts', { method: 'POST' });
    await mutate();    // refresh cart list
    invalidateCart();  // refresh CartContext
  }, [...]);
}

export function useSuperuser() { ... }

// app/[locale]/layout.tsx
<AuthProvider>
  <SuperuserProvider>
    <BusinessUnitProvider>
      <CartProvider>
        <Header />
        <SuperuserBanner />   {/* amber banner shown only to superusers */}
        <main>{children}</main>
      </CartProvider>
    </BusinessUnitProvider>
  </SuperuserProvider>
</AuthProvider>

// WRONG — duplicates commercetools enforcement; also fragile since it must be maintained manually
export async function POST() {
  const session = await getSession();
  const bu = await getBusinessUnitByKey(session.businessUnitKey!);
  const associate = bu.associates.find(a => a.customer.id === session.customerId);
  const hasPermission = associate?.associateRoleAssignments.some(r => r.key === 'CreateMyCarts');
  if (!hasPermission) return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
  // ...
}

// app/api/cart/route.ts
export async function POST() {
  const session = await getSession();
  // Only check: is the user logged in with a valid BU?
  if (!session.customerId || !session.businessUnitKey) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }
  // commercetools will 403 automatically if the associate lacks CreateMyCarts
  const cart = await createCart(
    session.customerId,
    session.customerId,   // associateId
    session.businessUnitKey,
    session.storeKey!,
    session.currency,
    session.country
  );
  return NextResponse.json({ cart });
}

// WRONG — role definitions live in commercetools, not in code
const BUYER_PERMISSIONS = ['CreateMyCarts', 'ViewMyOrders'];
const isBuyer = currentUser.roles.includes('buyer');
const canCreateCart = isBuyer;

// hooks/usePermissions.ts
// Resolution logic (simplified):
// 1. Fetch all AssociateRole objects from /api/associate-roles (commercetools source of truth)
// 2. Find current associate in currentBusinessUnit.associates by customerId
// 3. Collect their role keys from associateRoleAssignments
// 4. Collect all permissions from those roles
// 5. Expose can(), hasAnyPermission(), roleKeys

export function usePermissions() {
  const { user } = useAuth();
  const { currentBusinessUnit } = useBusinessUnit();
  const [permissions, setPermissions] = useState<Set<string>>(new Set());
  const [roleKeys, setRoleKeys] = useState<Set<string>>(new Set());

  useEffect(() => {
    if (!user || !currentBusinessUnit) return;

    // Find the current user's associate record in the BU
    const associate = currentBusinessUnit.associates.find(
      (a) => a.customer.id === user.id
    );
    if (!associate) return;

    // Collect the associate's role keys
    const keys = new Set(associate.associateRoleAssignments.map((r) => r.associateRole.key));
    setRoleKeys(keys);

    // Fetch all roles from commercetools (module-level cache, fetched once per tab)
    fetchAssociateRoles().then((roles) => {
      const perms = new Set<string>();
      for (const role of roles) {
        if (keys.has(role.key)) {
          for (const p of role.permissions) perms.add(p);
        }
      }
      setPermissions(perms);
    });
  }, [user, currentBusinessUnit]);

  const can = (permission: string) => permissions.has(permission);
  const hasAnyPermission = (ps: string[]) => ps.some((p) => permissions.has(p));
  const hasAllPermissions = (ps: string[]) => ps.every((p) => permissions.has(p));

  return { can, hasAnyPermission, hasAllPermissions, roleKeys, permissions };
}

const { can } = usePermissions();
if (!can('CreateApprovalRules')) return null;

const { hasAnyPermission } = usePermissions();
const canViewOrders = hasAnyPermission(['ViewMyOrders', 'ViewOthersOrders']);
if (!canViewOrders) return null;

const { can } = usePermissions();
const { user } = useAuth();

const isOwnQuote = quote.customer.id === user?.id;
const canAccept = isOwnQuote ? can('AcceptMyQuotes') : can('AcceptOthersQuotes');

{canAccept && <Button onClick={handleAccept}>Accept Quote</Button>}

const { roleKeys } = usePermissions();

const isEligibleApprover = flow.eligibleApprovers.some(
  (a) => roleKeys.has(a.associateRole.key)
);
const canActOnCurrentTier = flow.currentTierPendingApprovers.some(
  (a) => roleKeys.has(a.associateRole.key)
);

{isEligibleApprover && canActOnCurrentTier && (
  <>
    <Button onClick={handleApprove}>Approve</Button>
    <Button onClick={handleReject}>Reject</Button>
  </>
)}

// WRONG — user sees the link, clicks it, then gets an error
<Link href="/dashboard/approval-rules">Approval Rules</Link>

// components/layout/DashboardNav.tsx
const NAV_ITEMS = [
  { label: t('orders'), href: '/dashboard/orders',
    requiredPermissions: ['ViewMyOrders', 'ViewOthersOrders'] },
  { label: t('quotes'), href: '/dashboard/quotes',
    requiredPermissions: ['ViewMyQuotes', 'ViewOthersQuotes'] },
  { label: t('approvalRules'), href: '/dashboard/approval-rules',
    requiredPermissions: ['CreateApprovalRules', 'UpdateApprovalRules'] },
  { label: t('company'), href: '/dashboard/company',
    requiredPermissions: ['UpdateBusinessUnitDetails', 'UpdateAssociates'] },
];

// In the component:
{NAV_ITEMS
  .filter(item =>
    !item.requiredPermissions ||
    hasAnyPermission(item.requiredPermissions)
  )
  .map(item => <NavLink key={item.href} {...item} />)
}

const channelStock = variant.availability?.channels?.[supplyChannelId];
// channelStock.availableQuantity → correct
// variant.availability.isOnStock  → never use in B2B

// WRONG — no channel context; commercetools returns unscoped prices or "Price on request"
const results = await searchProducts({ query: searchTerm, locale: 'en-US' });

// app/api/products/route.ts
export async function POST(request: NextRequest) {
  const session = await getSession();
  const body = await request.json();

  // searchProducts reads businessUnitKey, storeKey, distributionChannelId,
  // supplyChannelId, accountGroupIds from session internally
  const results = await searchProducts(body, session);
  return NextResponse.json(results);
}

// lib/ct/products.ts — thin wrapper over ProductApi
export async function searchProducts(
  query: ProductQuery,
  session?: Partial<SessionData>
): Promise<ProductPaginatedResult> {
  const s = session ?? (await getSession());
  return new ProductApi(s).query(query);
}

// WRONG — prices not scoped to the customer's distribution channel
productProjectionParameters: {
  priceCurrency: currency,
  priceCountry: country,
}

// lib/ct/product-api.ts (key excerpt)
private buildProjectionParams(
  locale: Locale,
  distributionChannelId?: string,
  storeKey?: string,
  accountGroupIds?: string[]
): ProductSearchProjectionParams {
  return {
    priceCurrency: locale.currency,
    priceCountry: locale.country,
    expand: PRODUCT_PROJECTION_EXPANDS,
    // Channel-scoped pricing — customer's negotiated prices for this distribution channel
    ...(distributionChannelId ? { priceChannel: distributionChannelId } : {}),
    // Store projection — restricts to products in this store's product selection
    ...(storeKey ? { storeProjection: storeKey } : {}),
    // Customer group pricing — B2B contract prices for this customer group
    ...(accountGroupIds?.length ? { priceCustomerGroupAssignments: accountGroupIds } : {}),
  };
}

// WRONG — shows categories that have no products in the active store
const categories = await getCategories();

// lib/ct/product-api.ts (key excerpt)
async queryCategories(categoryQuery: CategoryQuery) {
  const storeKey = categoryQuery.storeKey ?? this.session.storeKey;
  if (storeKey) {
    const { storeId } = await getStoreChannelData(storeKey);
    if (storeId) {
      // Get category IDs that have at least one product in this store
      const categoryIds = await this.getCategoryIdsForStore(storeId);
      if (categoryIds?.length) {
        where.push(`id in ("${categoryIds.join('","')}")`);
      }
    }
  }
  // ...
}

// getCategoryIdsForStore uses the categoriesSubTree facet —
// one Product Search API call returns all category IDs with products in the store
private async getCategoryIdsForStore(storeId: string): Promise<string[] | undefined> {
  const response = await apiRoot.products().search().post({
    body: {
      query: { exact: { field: 'stores', value: storeId } },
      facets: [{
        distinct: {
          name: 'categoriesSubTree',
          field: 'categoriesSubTree',
          level: 'products',
          limit: 200,
        },
      }],
    },
  }).execute();
  // Returns only category IDs that have > 0 products in this store
  return facet.buckets.filter((b) => b.count > 0).map((b) => b.key);
}

// WRONG — shows availability without considering the store's supply channel
const inStock = product.variants[0].availability?.isOnStock;

// lib/ct/product-api.ts (in query method)
const items = searchResults.map((r) =>
  mapProduct(
    r.productProjection!,
    matchingIds,
    locale, // Always use BCP-47
    this.session.supplyChannelId  // ← inventory display for this supply channel
  )
);

// lib/mappers/product.ts
export function mapProduct(
  projection: ProductProjection,
  matchingVariantIds: Set<number> | null,
  locale: string,
  supplyChannelId?: string
): Product {
  // For each variant, check inventory for this specific supply channel
  const availability = supplyChannelId
    ? variant.availability?.channels?.[supplyChannelId]
    : variant.availability;

  return {
    // ...
    variants: variants.map((v) => ({
      // ...
      availability: {
        isOnStock: availability?.isOnStock ?? false,
        availableQty: availability?.availableQuantity,
      },
    })),
  };
}

// WRONG — commercetools 400 on invalid facet expression leaves the user with an error page
const results = await searchProducts({ facetConfigurations });

// app/api/products/route.ts
export async function POST(request: NextRequest) {
  const session = await getSession();
  const body = await request.json();

  try {
    const results = await searchProducts(body, session);
    return NextResponse.json(results);
  } catch (error) {
    // Retry without facets — products always render even if facets fail
    console.warn('Product search failed with facets, retrying without:', error);
    try {
      const results = await searchProducts({ ...body, facetConfigurations: [] }, session);
      return NextResponse.json(results);
    } catch (fallbackError) {
      return NextResponse.json({ error: 'Product search failed' }, { status: 500 });
    }
  }
}

QuoteRequest  →  StagedQuote  →  Quote (round 1)
                                  ↓ renegotiate
                              Quote (round 2)  [same StagedQuote]

apiRoot.asAssociate().withAssociateIdValue(associateId)
  .inBusinessUnitKeyWithBusinessUnitKeyValue(buKey)
  .quotes()

// WRONG — missing B2B fields; product prices and cart scoping will be wrong
await setSession(response, {
  customerId: customer.id,
  cartId: undefined,
  locale: 'en-US', // BCP-47 locale must come with currency and country
});

// lib/types.ts — the full SessionData interface
export interface SessionData {
  // Auth
  customerId?: string;
  customerEmail?: string;
  customerFirstName?: string;
  customerLastName?: string;

  // Active cart
  cartId?: string;

  // B2B context — resolved from the active store at login / BU-select
  businessUnitKey?: string;         // commercetools Business Unit key — used as associateId context
  storeKey?: string;                // commercetools Store key — scopes product visibility
  supplyChannelId?: string;         // commercetools Channel ID — used for inventory display
  distributionChannelId?: string;   // commercetools Channel ID — used for price scoping
  productSelectionId?: string;      // commercetools ProductSelection ID — restricts visible products

  /** Customer group IDs for priceCustomerGroupAssignments in product search */
  accountGroupIds?: string[];

  // Locale (always write all three together)
  locale?: string;      // BCP-47, e.g. 'de-DE' — used for both Next.js routing and all commercetools API calls
  currency?: string;    // ISO 4217, e.g. 'EUR'
  country?: string;     // ISO 3166-1 alpha-2, e.g. 'DE'
}

// WRONG — called on every cart add, every product search
const store = await apiRoot.stores().withKey({ key: storeKey }).get().execute();
const distributionChannelId = store.body.distributionChannels?.[0]?.id;

// lib/ct/stores.ts
export interface StoreChannelData {
  storeId: string | undefined;
  supplyChannelId: string | undefined;
  distributionChannelId: string | undefined;
  productSelectionId: string | undefined;
}

const storeDataCache = new Map<string, StoreChannelData>();

export async function getStoreChannelData(storeKey: string): Promise<StoreChannelData> {
  if (storeDataCache.has(storeKey)) return storeDataCache.get(storeKey)!;
  try {
    const { body } = await apiRoot.stores().withKey({ key: storeKey }).get().execute();
    const data: StoreChannelData = {
      storeId: body.id,
      supplyChannelId: body.supplyChannels?.[0]?.id,
      distributionChannelId: body.distributionChannels?.[0]?.id,
      productSelectionId: body.productSelections?.[0]?.productSelection?.id,
    };
    storeDataCache.set(storeKey, data);
    return data;
  } catch {
    return { storeId: undefined, supplyChannelId: undefined, distributionChannelId: undefined, productSelectionId: undefined };
  }
}

// WRONG — products will return unscoped prices; cart creation will fail
await setSession(response, { ...session, businessUnitKey, storeKey });