@faststore/core 4.5.1 → 4.6.0-dev.0

package/src/server/index.ts

@@ -16,6 +16,7 @@ import {
   GraphqlVtexSchema,
   isFastStoreError,
 } from '@faststore/api'
+import { OTELAPI } from '@faststore/diagnostics'
 import { loadFilesSync } from '@graphql-tools/load-files'
 import { mergeTypeDefs } from '@graphql-tools/merge'
 import { makeExecutableSchema } from '@graphql-tools/schema'
@@ -28,7 +29,7 @@ import thirdPartyResolvers from '../customizations/src/graphql/thirdParty/resolv
 import vtexExtensionsResolvers from '../customizations/src/graphql/vtex/resolvers'
 
 import type { Operation } from '../sdk/graphql/request'
-import { apiOptions, withTraceClient } from './options'
+import { apiOptions } from './options'
 
 interface ExecuteOptions<V = Record<string, unknown>> {
   operation: Operation
@@ -70,8 +71,7 @@ export function getFinalAPISchema() {
 }
 
 export const getEnvelop = async () => {
-  const options = await withTraceClient(apiOptions)
-  const apiContextFactory = await GraphqlVtexContextFactory(options)
+  const apiContextFactory = await GraphqlVtexContextFactory(apiOptions)
 
   return envelop({
     plugins: [
@@ -136,13 +136,17 @@ export const execute = async <V extends Maybe<{ [key: string]: unknown }>, D>(
     contextValue.storage.locale = locale
   }
 
-  const { data, errors } = (await run({
-    schema,
-    document: parse(query),
-    variableValues: variables,
-    contextValue,
-    operationName,
-  })) as { data: D; errors: unknown[] }
+  const { data, errors } = await withRootSpan(
+    `graphql ${operationName ?? 'operation'}`,
+    () =>
+      run({
+        schema,
+        document: parse(query),
+        variableValues: variables,
+        contextValue,
+        operationName,
+      }) as Promise<{ data: D; errors: unknown[] }>
+  )
 
   return {
     data,
@@ -153,3 +157,27 @@ export const execute = async <V extends Maybe<{ [key: string]: unknown }>, D>(
     },
   }
 }
+
+/**
+ * Runs an operation inside a per-request root span, made the active context so
+ * the resolver spans emitted by `@faststore/api` parent to it. Resolves to a
+ * plain call when telemetry is disabled.
+ */
+async function withRootSpan<T>(name: string, run: () => Promise<T>) {
+  if (!apiOptions.OTEL_ENABLED) {
+    return run()
+  }
+
+  const span = OTELAPI.trace.getTracer('@faststore/core').startSpan(name)
+  const otelContext = OTELAPI.trace.setSpan(OTELAPI.context.active(), span)
+
+  try {
+    return await OTELAPI.context.with(otelContext, run)
+  } catch (error) {
+    span.setStatus({ code: OTELAPI.SpanStatusCode.ERROR })
+    span.recordException(error as Error)
+    throw error
+  } finally {
+    span.end()
+  }
+}

package/src/server/options.ts

@@ -1,9 +1,8 @@
 import type { APIOptions } from '@faststore/api'
-import { getTraceClient } from '@faststore/diagnostics'
 import storeConfig from '../../discovery.config'
 import pkgJSON from '../../package.json'
 
-const { name, version } = pkgJSON
+const { version } = pkgJSON
 
 export const apiOptions: APIOptions = {
   platform: storeConfig.platform as APIOptions['platform'],
@@ -23,25 +22,7 @@ export const apiOptions: APIOptions = {
       storeConfig.api?.enableUnavailableItemsOnCart ?? false,
   },
   version,
-  OTEL: {
-    enabled: storeConfig.analytics.otelEnabled,
-  },
+  // feature flag default to false as it should not emit traces/logs yet
+  OTEL_ENABLED: false,
   discoveryConfig: storeConfig,
 }
-
-export async function withTraceClient<T extends APIOptions = typeof apiOptions>(
-  apiOptions: T
-): Promise<T> {
-  const OTEL = {}
-  getTraceClient(
-    apiOptions?.discoveryConfig?.analytics?.serviceName ?? name
-  )?.inject(OTEL)
-
-  return {
-    ...apiOptions,
-    OTEL: {
-      ...OTEL,
-      enabled: storeConfig.analytics?.otelEnabled?.toString() === 'true',
-    },
-  } as T
-}

package/src/styles/global/index.scss

@@ -3,18 +3,6 @@
 // Establish a layer order up-front, FS UI base styles have the lowest priority
 @layer base, components, theme;
 
-// Hide painted pixels during PLP scroll restore so the footer does not flash
-// at the top before the viewport jumps back to the saved product card.
-html.fs-restoring-scroll {
-  overflow-x: hidden;
-
-  body {
-    // Hide from hit-testing and the accessibility tree while scroll jumps —
-    // opacity: 0 would keep the page interactive/AT-visible.
-    visibility: hidden;
-  }
-}
-
 // FastStore UI's base styles
 @include meta.load-css("~@faststore/ui/src/styles/global.scss");
 

package/test/instrumentation.test.ts

@@ -0,0 +1,27 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { register } from '../src/instrumentation'
+
+const getTelemetryClient = vi.hoisted(() => vi.fn())
+
+vi.mock('@faststore/diagnostics', () => ({ getTelemetryClient }))
+
+beforeEach(() => {
+  vi.clearAllMocks()
+})
+
+afterEach(() => {
+  vi.unstubAllEnvs()
+})
+
+describe('register', () => {
+  it.each(['nodejs', 'edge', undefined])(
+    'does not boot telemetry on the %s runtime while the feature is off',
+    async (runtime) => {
+      vi.stubEnv('NEXT_RUNTIME', runtime)
+
+      await expect(register()).resolves.toBeUndefined()
+      expect(getTelemetryClient).not.toHaveBeenCalled()
+    }
+  )
+})

package/test/pages/api/graphql.test.ts

@@ -29,9 +29,13 @@ const createResponse = () => {
   return res as unknown as NextApiResponse & typeof res
 }
 
-const createRequest = (operationName = 'ClientShippingSimulationQuery') =>
+const createRequest = (
+  operationName = 'ClientShippingSimulationQuery',
+  method = 'GET'
+) =>
   ({
-    method: 'GET',
+    method,
+    url: '/api/graphql',
     headers: { host: 'localhost:3000' },
     query: {
       operationName,
@@ -165,3 +169,37 @@ describe('/api/graphql error status propagation', () => {
     expect(res.status).toHaveBeenCalledWith(404)
   })
 })
+
+describe('/api/graphql request handling', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it.each(['PUT', 'DELETE', 'PATCH', 'OPTIONS'])(
+    'rejects %s with 405 without reaching the GraphQL layer',
+    async (method) => {
+      const res = createResponse()
+      await handler(createRequest(undefined, method), res)
+
+      expect(res.status).toHaveBeenCalledWith(405)
+      expect(mockedExecute).not.toHaveBeenCalled()
+    }
+  )
+
+  it.each([
+    ['BadRequestError', () => new BadRequestError('malformed'), 400],
+    ['UnauthorizedError', () => new UnauthorizedError('expired'), 401],
+    ['an unexpected failure', () => new Error('socket hang up'), 500],
+  ])(
+    'maps %s thrown by execute to its status',
+    async (_name, makeError, status) => {
+      mockedExecute.mockRejectedValue(makeError())
+
+      const res = createResponse()
+      await handler(createRequest(), res)
+
+      expect(res.status).toHaveBeenCalledWith(status)
+      expect(res.end).toHaveBeenCalled()
+    }
+  )
+})

package/test/server/rootSpan.test.ts

@@ -0,0 +1,90 @@
+import { OTELAPI } from '@faststore/diagnostics'
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from 'vitest'
+
+import { execute } from '../../src/server'
+import { apiOptions } from '../../src/server/options'
+
+const span = {
+  end: vi.fn(),
+  setStatus: vi.fn(),
+  recordException: vi.fn(),
+}
+
+const startSpan = vi.fn(() => span)
+
+const otelEnabledByDefault = apiOptions.OTEL_ENABLED
+
+// `__typename` resolves inside GraphQL itself, so these run the whole envelop
+// pipeline without reaching the VTEX platform.
+const runOperation = (query: string, operationName?: string) =>
+  execute({
+    operation: { __meta__: { operationName, operationHash: 'not-persisted' } },
+    variables: {},
+    query,
+  })
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  vi.spyOn(OTELAPI.trace, 'getTracer').mockReturnValue({ startSpan } as never)
+  apiOptions.OTEL_ENABLED = true
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+afterAll(() => {
+  apiOptions.OTEL_ENABLED = otelEnabledByDefault
+})
+
+describe('execute root span', () => {
+  it('wraps the operation in a span named after it', async () => {
+    const { data } = await runOperation(
+      'query RootSpanQuery { __typename }',
+      'RootSpanQuery'
+    )
+
+    expect(data).toEqual({ __typename: 'Query' })
+    expect(startSpan).toHaveBeenCalledWith('graphql RootSpanQuery')
+    expect(span.end).toHaveBeenCalledTimes(1)
+    expect(span.setStatus).not.toHaveBeenCalled()
+  })
+
+  it('names the span generically when the operation is anonymous', async () => {
+    await runOperation('{ __typename }')
+
+    expect(startSpan).toHaveBeenCalledWith('graphql operation')
+  })
+
+  it('marks the span as failed and ends it when the operation throws', async () => {
+    await expect(
+      runOperation('this is not graphql', 'BrokenQuery')
+    ).rejects.toThrow(/Syntax Error/)
+
+    expect(span.setStatus).toHaveBeenCalledWith({
+      code: OTELAPI.SpanStatusCode.ERROR,
+    })
+    expect(span.recordException).toHaveBeenCalledWith(expect.any(Error))
+    expect(span.end).toHaveBeenCalledTimes(1)
+  })
+
+  it('skips instrumentation entirely when telemetry is disabled', async () => {
+    apiOptions.OTEL_ENABLED = false
+
+    const { data } = await runOperation(
+      'query RootSpanQuery { __typename }',
+      'RootSpanQuery'
+    )
+
+    expect(data).toEqual({ __typename: 'Query' })
+    expect(startSpan).not.toHaveBeenCalled()
+  })
+})

package/src/components/ui/ProductGallery/GalleryPageHeightLock.tsx

@@ -1,238 +0,0 @@
-import {
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-  type CSSProperties,
-  type PropsWithChildren,
-} from 'react'
-import { useSearch } from '@faststore/sdk'
-
-/** Coarse layout buckets — page height differs a lot across these. */
-export function getGalleryViewportBucket() {
-  if (globalThis.window === undefined) return 'ssr'
-  const width = globalThis.innerWidth
-  if (width <= 420) return 'mobile'
-  if (width <= 768) return 'tablet'
-  if (width < 1280) return 'notebook'
-  return 'desktop'
-}
-
-/** 32-bit string hash — avoids truncating long facet/path keys into collisions. */
-export function hashGalleryPageHeightKey(value: string) {
-  let hash = 0
-  for (const char of value) {
-    hash = Math.trunc(Math.imul(31, hash) + (char.codePointAt(0) ?? 0))
-  }
-  return (hash >>> 0).toString(36)
-}
-
-export function buildGalleryPageHeightKey(
-  page: number,
-  search: {
-    path: string
-    term: string | null
-    sort: string | null
-    selectedFacets: unknown
-    viewport?: string
-  }
-) {
-  const viewport = search.viewport ?? getGalleryViewportBucket()
-  const raw = JSON.stringify({
-    path: search.path,
-    term: search.term,
-    sort: search.sort,
-    selectedFacets: search.selectedFacets ?? [],
-    page,
-    viewport,
-  })
-  // Hash the full payload so long paths/facets never truncate page/viewport away.
-  return `__fs_gallery_page_h_p${page}_${viewport}_${hashGalleryPageHeightKey(raw)}`
-}
-
-export function readGalleryPageHeight(key: string): number | null {
-  try {
-    const raw = sessionStorage.getItem(key)
-    if (!raw) return null
-    const height = Number(raw)
-    return Number.isFinite(height) && height > 0 ? height : null
-  } catch {
-    return null
-  }
-}
-
-function writeGalleryPageHeight(key: string, height: number) {
-  try {
-    sessionStorage.setItem(key, String(Math.round(height)))
-  } catch {
-    // ignore quota / private mode
-  }
-}
-
-/**
- * Sum of last-measured heights for the active infinite-scroll pages.
- * Used to reserve space for the whole gallery before individual pages mount.
- */
-export function getReservedGalleryHeight(
-  pages: number[],
-  search: {
-    path: string
-    term: string | null
-    sort: string | null
-    selectedFacets: unknown
-    viewport?: string
-  }
-) {
-  return pages.reduce((sum, page) => {
-    const height = readGalleryPageHeight(
-      buildGalleryPageHeightKey(page, search)
-    )
-    return sum + (height ?? 0)
-  }, 0)
-}
-
-/** Client-only reserved height for the results column while products load. */
-export function resolveReservedGalleryHeight(
-  hasProductsLoaded: boolean,
-  pages: number[],
-  search: {
-    path: string
-    term: string | null
-    sort: string | null
-    selectedFacets: unknown
-    viewport?: string
-  }
-) {
-  if (hasProductsLoaded) return 0
-  return getReservedGalleryHeight(pages, search)
-}
-
-type Props = PropsWithChildren<{
-  page: number
-}>
-
-/**
- * Locks the gallery page slot to the last measured height **only while the
- * skeleton is showing**. Once real product cards are mounted, the lock is
- * released so a viewport resize cannot leave huge empty gaps between pages.
- */
-function GalleryPageHeightLock({ page, children }: Props) {
-  const {
-    state: { term, sort, selectedFacets },
-  } = useSearch()
-
-  const [viewport, setViewport] = useState(getGalleryViewportBucket)
-
-  useEffect(() => {
-    const onResize = () => setViewport(getGalleryViewportBucket())
-    globalThis.addEventListener('resize', onResize)
-    return () => globalThis.removeEventListener('resize', onResize)
-  }, [])
-
-  const storageKey = useMemo(() => {
-    const path =
-      globalThis.window === undefined ? '' : globalThis.location.pathname
-    return buildGalleryPageHeightKey(page, {
-      path,
-      term: term ?? null,
-      sort: sort ?? null,
-      selectedFacets,
-      viewport,
-    })
-  }, [term, sort, selectedFacets, page, viewport])
-
-  const ref = useRef<HTMLDivElement>(null)
-  /** Height applied only while this page has no product cards yet. */
-  // Start null on SSR and first client paint; storageKey effect applies the
-  // sessionStorage value after mount to avoid hydration mismatches.
-  const [pendingMinHeight, setPendingMinHeight] = useState<number | null>(null)
-  const [isLocked, setIsLocked] = useState(true)
-
-  useEffect(() => {
-    setPendingMinHeight(readGalleryPageHeight(storageKey))
-    // Re-lock briefly when the viewport bucket / search key changes so back-nav
-    // skeletons on a new breakpoint still get the right reserved height.
-    setIsLocked(true)
-  }, [storageKey])
-
-  useEffect(() => {
-    const el = ref.current
-    if (!el) return
-
-    const syncFromDom = () => {
-      const hasProducts = Boolean(
-        el.querySelector(
-          '[data-fs-product-card], a[data-testid="product-link"]'
-        )
-      )
-
-      if (!hasProducts) {
-        // Skeleton / empty — keep (or restore) the reserved minHeight.
-        setIsLocked(true)
-        return
-      }
-
-      // Products are visible: drop the lock so natural height can shrink on
-      // resize, then persist the unconstrained content height for next back-nav.
-      setIsLocked(false)
-
-      // Measure after minHeight is cleared (next frame).
-      requestAnimationFrame(() => {
-        const height = el.getBoundingClientRect().height
-        if (height < 80) return
-        const rounded = Math.round(height)
-        writeGalleryPageHeight(storageKey, rounded)
-        setPendingMinHeight(rounded)
-      })
-    }
-
-    syncFromDom()
-
-    const mutationObserver = new MutationObserver(syncFromDom)
-    mutationObserver.observe(el, { childList: true, subtree: true })
-
-    let resizeObserver: ResizeObserver | null = null
-    if (typeof ResizeObserver !== 'undefined') {
-      resizeObserver = new ResizeObserver(() => {
-        // Only persist when unlocked (real layout). Observing while locked
-        // would re-read the artificial minHeight and never shrink.
-        if (
-          !el.querySelector(
-            '[data-fs-product-card], a[data-testid="product-link"]'
-          )
-        ) {
-          return
-        }
-        const height = el.getBoundingClientRect().height
-        if (height < 80) return
-        const rounded = Math.round(height)
-        writeGalleryPageHeight(storageKey, rounded)
-        setPendingMinHeight(rounded)
-      })
-      resizeObserver.observe(el)
-    }
-
-    return () => {
-      mutationObserver.disconnect()
-      resizeObserver?.disconnect()
-    }
-    // Re-sync when children swap (e.g. skeleton → product grid). MutationObserver
-    // alone is not reliable across React rerenders in jsdom/CI.
-  }, [storageKey, children])
-
-  const style: CSSProperties | undefined =
-    isLocked && pendingMinHeight ? { minHeight: pendingMinHeight } : undefined
-
-  return (
-    <div
-      ref={ref}
-      data-fs-gallery-page-height-lock
-      data-fs-gallery-page={page}
-      style={style}
-    >
-      {children}
-    </div>
-  )
-}
-
-export default GalleryPageHeightLock

package/test/components/skeletons/ProductGridSkeleton.browser.test.tsx

@@ -1,32 +0,0 @@
-/**
- * @vitest-environment jsdom
- */
-
-import { render, screen } from '@testing-library/react'
-import { describe, expect, it, vi } from 'vitest'
-
-vi.mock('src/components/skeletons/ProductCardSkeleton', () => ({
-  __esModule: true,
-  default: () => <div data-testid="product-card-skeleton" />,
-}))
-
-import ProductGridSkeleton from '../../../src/components/skeletons/ProductGridSkeleton/ProductGridSkeleton'
-
-describe('ProductGridSkeleton', () => {
-  it('renders the requested number of placeholder cards', () => {
-    render(<ProductGridSkeleton loading count={4} />)
-
-    expect(screen.getAllByTestId('product-card-skeleton')).toHaveLength(4)
-  })
-
-  it('renders children when not loading', () => {
-    render(
-      <ProductGridSkeleton loading={false}>
-        <div data-testid="grid-content">products</div>
-      </ProductGridSkeleton>
-    )
-
-    expect(screen.getByTestId('grid-content')).toBeTruthy()
-    expect(screen.queryByTestId('product-card-skeleton')).toBeNull()
-  })
-})