@faststore/core 4.3.0-dev.0 → 4.3.0-dev.1

package/.turbo/turbo-generate.log

@@ -1,9 +1,9 @@
 
-> @faststore/core@4.2.0 generate /home/runner/work/faststore/faststore/packages/core
+> @faststore/core@4.3.0-dev.0 generate /home/runner/work/faststore/faststore/packages/core
 > pnpm run gen-types && pnpm run cache-graphql 
 
 
-> @faststore/core@4.2.0 gen-types /home/runner/work/faststore/faststore/packages/core
+> @faststore/core@4.3.0-dev.0 gen-types /home/runner/work/faststore/faststore/packages/core
 > node ../cli/bin/run generate-types .
 
 [STARTED] Parse Configuration
@@ -19,7 +19,7 @@
 [COMPLETED] Generate to /home/runner/work/faststore/faststore/packages/core/@generated/
 [COMPLETED] Generate outputs
 
-> @faststore/core@4.2.0 cache-graphql /home/runner/work/faststore/faststore/packages/core
+> @faststore/core@4.3.0-dev.0 cache-graphql /home/runner/work/faststore/faststore/packages/core
 > node ../cli/bin/run cache-graphql --config=./discovery.config.default.js --queries=./@generated/persisted-documents.json
 
 [Info] - Config file location: /home/runner/work/faststore/faststore/packages/core/discovery.config.default.js

package/.turbo/turbo-test.log

@@ -1,12 +1,10 @@
 
-> @faststore/core@4.2.0 test /home/runner/work/faststore/faststore/packages/core
+> @faststore/core@4.3.0-dev.0 test /home/runner/work/faststore/faststore/packages/core
 > vitest run
 
 
  RUN  v4.0.7 /home/runner/work/faststore/faststore/packages/core
 
- ✓  browser  test/sdk/session/getInitialSession.browser.test.ts (6 tests) 10ms
- ✓  browser  test/sdk/session/installLocaleCorrector.browser.test.ts (7 tests) 43ms
 stderr | test/sdk/localization/store-url.browser.test.ts
 Error in optimistic validation: TypeError: Cannot read properties of undefined (reading 'read')
     at validateCart (/home/runner/work/faststore/faststore/packages/core/src/sdk/cart/index.ts:119:27)
@@ -14,31 +12,79 @@
     at a (/home/runner/work/faststore/faststore/packages/sdk/dist/es/index.mjs:353:23)
     at processTicksAndRejections (node:internal/process/task_queues:103:5)
 
- ✓  node  test/utils/localization/bindingPaths.test.ts (71 tests) 76ms
- ✓  browser  test/utils/isLocalHost.browser.test.ts (3 tests) 7ms
- ✓  node  test/utils/match-url.test.ts (10 tests) 37ms
- ✓  browser  test/sdk/localization/store-url.browser.test.ts (3 tests) 12ms
- ✓  node  test/sdk/localization/bindingSelector.test.ts (18 tests) 28ms
- ✓  node  test/sdk/localization/useBindingSelector.test.tsx (12 tests) 23ms
- ✓  node  test/utils/cookieCacheBusting.test.ts (10 tests) 33ms
- ✓  node  test/utils/multipleTemplates.test.ts (8 tests) 22ms
- ✓  node  test/utils/clearCookies.test.ts (20 tests) 105ms
- ✓  node  test/sdk/search/useSearchHistory.test.ts (13 tests) 203ms
- ✓  node  test/server/cms/global.test.ts (3 tests) 29ms
- ✓  node  test/server/content/service.test.ts (5 tests) 15ms
+ ✓  browser  test/sdk/session/getInitialSession.browser.test.ts (6 tests) 42ms
+ ✓  browser  test/sdk/session/installLocaleCorrector.browser.test.ts (7 tests) 62ms
+ ✓  node  test/utils/localization/bindingPaths.test.ts (71 tests) 74ms
+ ✓  browser  test/sdk/localization/store-url.browser.test.ts (3 tests) 29ms
+ ✓  node  test/utils/match-url.test.ts (10 tests) 38ms
+ ✓  node  test/sdk/localization/bindingSelector.test.ts (18 tests) 23ms
+ ✓  browser  test/utils/isLocalHost.browser.test.ts (3 tests) 15ms
+ ✓  node  test/sdk/localization/useBindingSelector.test.tsx (12 tests) 20ms
+ ✓  node  test/utils/cookieCacheBusting.test.ts (10 tests) 44ms
+ ✓  node  test/sdk/search/useSearchHistory.test.ts (13 tests) 224ms
+ ✓  node  test/utils/multipleTemplates.test.ts (8 tests) 15ms
+ ✓  node  test/utils/clearCookies.test.ts (20 tests) 147ms
+ ✓  node  test/server/content/service.test.ts (5 tests) 12ms
+stderr | test/pages/api/graphql.test.ts > /api/graphql error status propagation > propagates the upstream 400 from a wrapped BadRequestError instead of 500
+Graphql execution returned with error:  [
+  {
+    message: 'O campo CEP (88) é inválido',
+    status: 400,
+    type: 'BadRequestError'
+  }
+]
+
+stderr | test/pages/api/graphql.test.ts > /api/graphql error status propagation > propagates UnauthorizedError status
+Graphql execution returned with error:  [ { message: 'nope', status: 401, type: 'UnauthorizedError' } ]
+
+stderr | test/pages/api/graphql.test.ts > /api/graphql error status propagation > propagates ForbiddenError status
+Graphql execution returned with error:  [ { message: 'nope', status: 403, type: 'ForbiddenError' } ]
+
+stderr | test/pages/api/graphql.test.ts > /api/graphql error status propagation > propagates NotFoundError status
+Graphql execution returned with error:  [ { message: 'nope', status: 404, type: 'NotFoundError' } ]
+
+stderr | test/pages/api/graphql.test.ts > /api/graphql error status propagation > propagates an unmapped upstream status (UnknownError 429)
+Graphql execution returned with error:  [ { message: 'slow down', status: 429, type: 'UnknownError' } ]
+
+stderr | test/pages/api/graphql.test.ts > /api/graphql error status propagation > recovers status when the error itself is a FastStoreError (not wrapped)
+Graphql execution returned with error:  [ { message: 'bad input', status: 400, type: 'BadRequestError' } ]
+
+stderr | test/pages/api/graphql.test.ts > /api/graphql error status propagation > falls back to a body-less 500 for non-FastStore errors
+Graphql execution returned with error:  [
+  {
+    message: 'Sorry, something went wrong.',
+    status: undefined,
+    type: undefined
+  }
+]
+
+stderr | test/pages/api/graphql.test.ts > /api/graphql error status propagation > exposes type, status and message in the body outside production
+Graphql execution returned with error:  [ { message: 'invalid CEP', status: 400, type: 'BadRequestError' } ]
+
+stderr | test/pages/api/graphql.test.ts > /api/graphql error status propagation > omits the free-text message from the body in production
+Graphql execution returned with error:  [ { message: 'invalid CEP', status: 400, type: 'BadRequestError' } ]
+
+stderr | test/pages/api/graphql.test.ts > /api/graphql error status propagation > uses the first recoverable FastStoreError when several errors exist
+Graphql execution returned with error:  [
+  { message: 'plain error', status: undefined, type: undefined },
+  { message: 'missing', status: 404, type: 'NotFoundError' },
+  { message: 'bad', status: 400, type: 'BadRequestError' }
+]
+
+ ✓  node  test/pages/api/graphql.test.ts (10 tests) 72ms
+ ✓  node  test/server/cms/global.test.ts (3 tests) 19ms
+ ✓  node  test/utils/getRequestHostname.test.ts (12 tests) 23ms
  ✓  node  test/sdk/localization/store-url.test.ts (1 test) 12ms
- ✓  node  test/utils/getRequestHostname.test.ts (12 tests) 14ms
  ✓  node  test/utils/validateSessionRefreshToken.test.ts (6 tests) 14ms
- ✓  node  test/pages/api/preview.test.ts (2 tests) 25ms
- ✓  node  test/utils/isLocalHost.test.ts (7 tests) 18ms
- ✓  node  test/server/cms/index.test.ts (2 tests) 18ms
- ✓  node  test/server/index.test.ts (7 tests) 1197ms
-       ✓ should return a valid merged GraphQL schema  392ms
-       ✓ should exist with its plugins  309ms
-       ✓ should handle options and execute  482ms
-
- Test Files  21 passed (21)
-      Tests  226 passed (226)
-   Start at  22:01:31
-   Duration  17.15s (transform 6.17s, setup 0ms, collect 17.85s, tests 1.94s, environment 15.50s, prepare 929ms)
+ ✓  node  test/pages/api/preview.test.ts (2 tests) 18ms
+ ✓  node  test/utils/isLocalHost.test.ts (7 tests) 8ms
+ ✓  node  test/server/cms/index.test.ts (2 tests) 4ms
+ ✓  node  test/server/index.test.ts (7 tests) 1333ms
+       ✓ should return a valid merged GraphQL schema  658ms
+       ✓ should exist with its plugins  390ms
+
+ Test Files  22 passed (22)
+      Tests  236 passed (236)
+   Start at  14:05:33
+   Duration  15.91s (transform 5.65s, setup 0ms, collect 17.89s, tests 2.25s, environment 14.22s, prepare 794ms)
 

package/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [4.3.0-dev.1](https://github.com/vtex/faststore/compare/v4.3.0-dev.0...v4.3.0-dev.1) (2026-06-08)
+
+### Bug Fixes
+
+- **core:** propagate upstream error status instead of always 500 ([#3379](https://github.com/vtex/faststore/issues/3379)) ([c03d3df](https://github.com/vtex/faststore/commit/c03d3dff7f5920e834a318417a4a02cc653453cf))
+
 # [4.3.0-dev.0](https://github.com/vtex/faststore/compare/v4.2.0...v4.3.0-dev.0) (2026-06-01)
 
 **Note:** Version bump only for package @faststore/core

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faststore/core",
-  "version": "4.3.0-dev.0",
+  "version": "4.3.0-dev.1",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -70,11 +70,11 @@
     "style-loader": "^3.3.1",
     "swr": "^2.2.5",
     "use-sync-external-store": "^1.6.0",
-    "@faststore/lighthouse": "4.3.0-dev.0",
-    "@faststore/diagnostics": "4.3.0-dev.0",
-    "@faststore/sdk": "4.3.0-dev.0",
-    "@faststore/ui": "4.3.0-dev.0",
-    "@faststore/api": "4.3.0-dev.0"
+    "@faststore/diagnostics": "4.3.0-dev.1",
+    "@faststore/api": "4.3.0-dev.1",
+    "@faststore/sdk": "4.3.0-dev.1",
+    "@faststore/lighthouse": "4.3.0-dev.1",
+    "@faststore/ui": "4.3.0-dev.1"
   },
   "devDependencies": {
     "@cypress/code-coverage": "^3.12.1",

package/src/pages/api/graphql.ts

@@ -18,6 +18,21 @@ const DEFAULT_MAX_AGE = 5 * 60 // 5 minutes
 const DEFAULT_STALE_WHILE_REVALIDATE = 60 * 60 // 1 hour
 const ALLOWED_HOST_SUFFIXES = ['localhost', '.vtex.app', '.localhost']
 
+/**
+ * Recovers a FastStoreError from an execution error, whether it is the error
+ * itself or wrapped as the `originalError` of a masked GraphQLError.
+ */
+const recoverFastStoreError = (graphqlError: unknown) => {
+  if (isFastStoreError(graphqlError)) {
+    return graphqlError
+  }
+
+  const originalError = (graphqlError as { originalError?: unknown })
+    ?.originalError
+
+  return isFastStoreError(originalError) ? originalError : undefined
+}
+
 // Example: "Set-Cookie: key=value; Domain=example.com; Path=/"
 const MATCH_DOMAIN_REGEXP = /(?:^|;\s*)(?:domain=)([^;]+)/i
 
@@ -186,13 +201,53 @@ const handler: NextApiHandler = async (request, response) => {
       { headers: request.headers }
     )
 
-    const hasErrors = Array.isArray(errors)
+    const hasErrors = Array.isArray(errors) && errors.length > 0
 
     if (hasErrors) {
-      const error = errors.find(isFastStoreError)
-      console.error('Graphql execution returned with error: ', error)
+      // After error masking, entries are GraphQLError instances whose
+      // `name` is "GraphQLError" — the original FastStoreError (carrying the
+      // upstream status) is nested in `originalError`. Recover it so the BFF
+      // propagates the real status instead of collapsing everything to 500.
+      const fastStoreError = errors.map(recoverFastStoreError).find(Boolean)
+
+      console.error(
+        'Graphql execution returned with error: ',
+        errors.map((graphqlError) => {
+          const fsError = recoverFastStoreError(graphqlError)
+
+          return {
+            message: (graphqlError as { message?: string })?.message,
+            status: fsError?.extensions.status,
+            type: fsError?.extensions.type,
+          }
+        })
+      )
+
+      const status = fastStoreError?.extensions.status ?? 500
+
+      // No recoverable FastStoreError: keep the masked, body-less 500.
+      if (!fastStoreError) {
+        response.status(status).end()
+        return
+      }
+
+      // Only FastStoreError-derived details are exposed. `type`/`status` are a
+      // closed enum (safe everywhere); the free-text `message` may echo raw
+      // upstream text, so it is restricted to non-production responses. The
+      // full message is still available server-side via the log above.
+      const responseError = {
+        extensions: {
+          type: fastStoreError.extensions.type,
+          status: fastStoreError.extensions.status,
+        },
+        ...(process.env.NODE_ENV !== 'production'
+          ? { message: fastStoreError.message }
+          : {}),
+      }
 
-      response.status(error?.extensions.status ?? 500).end()
+      response.status(status)
+      response.setHeader('content-type', 'application/json')
+      response.send(JSON.stringify({ errors: [responseError] }))
       return
     }
 

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

@@ -0,0 +1,167 @@
+import {
+  BadRequestError,
+  FastStoreError,
+  ForbiddenError,
+  NotFoundError,
+  UnauthorizedError,
+} from '@faststore/api'
+import { GraphQLError } from 'graphql'
+import type { NextApiRequest, NextApiResponse } from 'next'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import handler from '../../../src/pages/api/graphql'
+import { execute } from '../../../src/server'
+
+vi.mock('../../../src/server', () => ({
+  execute: vi.fn(),
+}))
+
+const mockedExecute = vi.mocked(execute)
+
+const createResponse = () => {
+  const res = {
+    status: vi.fn().mockReturnThis(),
+    setHeader: vi.fn().mockReturnThis(),
+    send: vi.fn().mockReturnThis(),
+    end: vi.fn().mockReturnThis(),
+  }
+
+  return res as unknown as NextApiResponse & typeof res
+}
+
+const createRequest = (operationName = 'ClientShippingSimulationQuery') =>
+  ({
+    method: 'GET',
+    headers: { host: 'localhost:3000' },
+    query: {
+      operationName,
+      operationHash: 'hash',
+      variables: '{}',
+    },
+  }) as unknown as NextApiRequest
+
+const mockExecuteWithErrors = (errors: unknown[]) => {
+  mockedExecute.mockResolvedValue({
+    data: null,
+    errors,
+    extensions: { cookies: new Map(), cacheControl: undefined },
+  } as never)
+}
+
+// Reproduces what `useMaskedErrors` produces: a GraphQLError whose
+// `originalError` is the FastStoreError thrown by a resolver/`fetchAPI`.
+const maskedError = (original: FastStoreError) =>
+  new GraphQLError(original.message, { originalError: original })
+
+describe('/api/graphql error status propagation', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    vi.unstubAllEnvs()
+  })
+
+  it('propagates the upstream 400 from a wrapped BadRequestError instead of 500', async () => {
+    mockExecuteWithErrors([
+      maskedError(new BadRequestError('O campo CEP (88) é inválido')),
+    ])
+
+    const res = createResponse()
+    await handler(createRequest(), res)
+
+    expect(res.status).toHaveBeenCalledWith(400)
+    expect(res.end).not.toHaveBeenCalled()
+  })
+
+  it.each([
+    ['UnauthorizedError', () => new UnauthorizedError('nope'), 401],
+    ['ForbiddenError', () => new ForbiddenError('nope'), 403],
+    ['NotFoundError', () => new NotFoundError('nope'), 404],
+  ])('propagates %s status', async (_name, makeError, expectedStatus) => {
+    mockExecuteWithErrors([maskedError(makeError())])
+
+    const res = createResponse()
+    await handler(createRequest(), res)
+
+    expect(res.status).toHaveBeenCalledWith(expectedStatus)
+  })
+
+  it('propagates an unmapped upstream status (UnknownError 429)', async () => {
+    mockExecuteWithErrors([
+      maskedError(
+        new FastStoreError({ status: 429, type: 'UnknownError' }, 'slow down')
+      ),
+    ])
+
+    const res = createResponse()
+    await handler(createRequest(), res)
+
+    expect(res.status).toHaveBeenCalledWith(429)
+  })
+
+  it('recovers status when the error itself is a FastStoreError (not wrapped)', async () => {
+    mockExecuteWithErrors([new BadRequestError('bad input')])
+
+    const res = createResponse()
+    await handler(createRequest(), res)
+
+    expect(res.status).toHaveBeenCalledWith(400)
+  })
+
+  it('falls back to a body-less 500 for non-FastStore errors', async () => {
+    mockExecuteWithErrors([new GraphQLError('Sorry, something went wrong.')])
+
+    const res = createResponse()
+    await handler(createRequest(), res)
+
+    expect(res.status).toHaveBeenCalledWith(500)
+    expect(res.end).toHaveBeenCalled()
+    expect(res.send).not.toHaveBeenCalled()
+  })
+
+  it('exposes type, status and message in the body outside production', async () => {
+    vi.stubEnv('NODE_ENV', 'development')
+    mockExecuteWithErrors([maskedError(new BadRequestError('invalid CEP'))])
+
+    const res = createResponse()
+    await handler(createRequest(), res)
+
+    const body = JSON.parse(
+      (res.send as ReturnType<typeof vi.fn>).mock.calls[0][0]
+    )
+    expect(body.errors[0]).toEqual({
+      extensions: { type: 'BadRequestError', status: 400 },
+      message: 'invalid CEP',
+    })
+  })
+
+  it('omits the free-text message from the body in production', async () => {
+    vi.stubEnv('NODE_ENV', 'production')
+    mockExecuteWithErrors([maskedError(new BadRequestError('invalid CEP'))])
+
+    const res = createResponse()
+    await handler(createRequest(), res)
+
+    const body = JSON.parse(
+      (res.send as ReturnType<typeof vi.fn>).mock.calls[0][0]
+    )
+    expect(body.errors[0]).toEqual({
+      extensions: { type: 'BadRequestError', status: 400 },
+    })
+    expect(body.errors[0].message).toBeUndefined()
+  })
+
+  it('uses the first recoverable FastStoreError when several errors exist', async () => {
+    mockExecuteWithErrors([
+      new GraphQLError('plain error'),
+      maskedError(new NotFoundError('missing')),
+      maskedError(new BadRequestError('bad')),
+    ])
+
+    const res = createResponse()
+    await handler(createRequest(), res)
+
+    expect(res.status).toHaveBeenCalledWith(404)
+  })
+})