@vendure-platform/create 0.5.1 → 1.0.0-major.202609160652.120.4

package/dist/assets/storefront/src/i18n/server.ts

@@ -1,16 +1,44 @@
 import { hasLocale } from 'next-intl';
-import { getLocale } from 'next-intl/server';
+import { getLocale, setRequestLocale } from 'next-intl/server';
+import { locale as rootLocale } from 'next/root-params';
 import { routing, type Locale } from './routing';
 
 /**
- * Resolve the current locale from request context with validation.
+ * Resolve the current locale from the `[locale]` root param, with validation.
+ * Falls back to defaultLocale if the segment isn't in routing config.
+ *
+ * This is the default on the server, including 'use cache' scopes. Root params
+ * carry no request state, so a component that resolves the locale this way
+ * still prerenders.
+ */
+export async function getRootLocale(): Promise<Locale> {
+    const loc = await rootLocale();
+    return hasLocale(routing.locales, loc) ? (loc as Locale) : routing.defaultLocale;
+}
+
+/**
+ * Resolve the current locale from request context, with validation.
  * Falls back to defaultLocale if the resolved locale isn't in routing config.
  *
- * Use this in non-cached server components and server actions.
- * For 'use cache' scopes or route files (layout/page), prefer rootLocale()
- * from 'next/root-params' directly (the SWC transform only works in route files).
+ * Only for scopes root params cannot reach: Client Components, Server Actions
+ * and Route Handlers, plus server code that already renders dynamically.
+ * Reading request state blocks prerendering, so a Server Component that calls
+ * this serves no static shell — call `getRootLocale()` there instead.
  */
 export async function getRouteLocale(): Promise<Locale> {
     const loc = await getLocale();
     return hasLocale(routing.locales, loc) ? (loc as Locale) : routing.defaultLocale;
 }
+
+/**
+ * Pin the `[locale]` root param as next-intl's request locale.
+ *
+ * Call this before the first next-intl call in a Server Component that does not
+ * already pin the locale from `params`. Without it, `getTranslations()` resolves
+ * the locale through next-intl's request scope, which under `cacheComponents` is
+ * uncached request state: the route then fails `next build --debug-prerender`
+ * and serves no static shell.
+ */
+export async function pinRootLocale(): Promise<void> {
+    setRequestLocale(await getRootLocale());
+}

package/dist/assets/storefront/src/lib/backend-health.ts

@@ -10,12 +10,20 @@ const HEALTH_CHECK_TIMEOUT_MS = 3000;
  * on Vercel) but every API call fails, leaving the user with a branded but
  * empty shell. When this returns false we render a "Demo Paused" page instead.
  *
- * Cached for 15s (cacheLife('seconds')) so a stop/start of the backend is
- * reflected quickly without hammering the API on every request.
+ * This is cacheLife('seconds') with one field changed: `expire` goes from 60 to
+ * 300. The preset's 60s expire is too short for Next 16.3's build-time cache,
+ * which drops the entry between the cache-warming phase and the final prerender
+ * phase, and every prerendered page that mounts this gate then logs an
+ * "Unexpected cache miss" during `next build`. Measured on 16.3: expire 300 is
+ * retained, 120 is not.
+ *
+ * `stale` and `revalidate` keep the preset's values, so how fast a stop/start of
+ * the backend is picked up is unchanged. `expire` only bounds how long a stale
+ * value may be served when revalidation never runs.
  */
 export async function isBackendReachable(): Promise<boolean> {
     'use cache';
-    cacheLife('seconds');
+    cacheLife({ stale: 30, revalidate: 1, expire: 300 });
 
     const apiUrl = process.env.VENDURE_SHOP_API_URL || process.env.NEXT_PUBLIC_VENDURE_SHOP_API_URL;
     if (!apiUrl) return true;

package/dist/assets/storefront/src/lib/vendure/api.ts

@@ -1,6 +1,8 @@
 import type { RequestMiddleware } from '@vendure-platform/storefront-client';
 import { createClient } from '@vendure-platform/storefront-client';
 
+import { capabilityDriftMiddleware } from './capability-drift';
+
 const DRAFT_MODE_SECRET = process.env.DRAFT_MODE_SECRET;
 
 /**
@@ -119,7 +121,7 @@ const currencyMiddleware: RequestMiddleware = async (req, next) => {
     return next(req);
 };
 
-const middleware = [draftModeMiddleware, currencyMiddleware];
+const middleware = [draftModeMiddleware, currencyMiddleware, capabilityDriftMiddleware];
 
 export const client = createClient({
     ...sharedConfig,
@@ -138,12 +140,13 @@ export const client = createClient({
 });
 
 /**
- * Client without providers or middleware — for 'use cache' functions that fetch public data.
+ * Client without providers — for 'use cache' functions that fetch public data.
  * Next.js 'use cache' forbids Dynamic APIs (cookies/headers), so this client must not
- * access cookies, headers, or draftMode. Pass languageCode and currencyCode explicitly
+ * access cookies, headers, or draftMode. Its one middleware, the capability drift
+ * check, reads only the response. Pass languageCode and currencyCode explicitly
  * as query options from the calling function.
  */
-export const publicClient = createClient({ ...sharedConfig });
+export const publicClient = createClient({ ...sharedConfig, middleware: [capabilityDriftMiddleware] });
 
 /**
  * Pre-resolved context for use at cache boundaries where cookies() is not available.

package/dist/assets/storefront/src/lib/vendure/capability-documents.ts

@@ -0,0 +1,252 @@
+import { hasCapability } from '@/config/capabilities';
+import type {
+    DefinitionNode,
+    DocumentNode,
+    FieldNode,
+    FragmentDefinitionNode,
+    SelectionNode,
+    SelectionSetNode,
+} from 'graphql';
+import { visit } from 'graphql';
+
+/**
+ * A selection to drop, written as the path of field names from the root of the
+ * operation or fragment definition that holds it: for example
+ * `['product', 'customFields', 'configuratorSystemCode']` in an operation, or
+ * `['isPublic']` inside `fragment ShoppingListFields`. Every path is tried on
+ * every definition, so a path only matches in the definitions it starts in.
+ */
+export type FieldPath = readonly string[];
+
+export interface CapabilityDocumentRule {
+    capability: string;
+    paths: readonly FieldPath[];
+}
+
+export interface CapabilityDocumentRegistration<T extends DocumentNode = DocumentNode> {
+    name: string;
+    fullDocument: T;
+    rules: readonly CapabilityDocumentRule[];
+}
+
+/**
+ * Capability-owned storefront documents, used by the schema composition tests
+ * and by the drift check in `capability-drift.ts`.
+ */
+export const STOREFRONT_CAPABILITY_DOCUMENTS: CapabilityDocumentRegistration[] = [];
+
+function isField(selection: SelectionNode): selection is FieldNode {
+    return selection.kind === 'Field';
+}
+
+function fieldName(field: FieldNode): string {
+    return field.name.value;
+}
+
+function addOperationFallback<T extends DocumentNode>(document: T): T {
+    return {
+        ...document,
+        definitions: document.definitions.map((definition) => {
+            if (definition.kind !== 'OperationDefinition') return definition;
+            if (
+                definition.selectionSet.selections.some(
+                    (selection) => isField(selection) && fieldName(selection) === '__typename',
+                )
+            ) {
+                return definition;
+            }
+            return {
+                ...definition,
+                selectionSet: {
+                    ...definition.selectionSet,
+                    selections: [
+                        ...definition.selectionSet.selections,
+                        { kind: 'Field', name: { kind: 'Name', value: '__typename' } },
+                    ],
+                },
+            };
+        }),
+    } as T;
+}
+
+function fragmentSpreads(selectionSet: SelectionSetNode): string[] {
+    const names: string[] = [];
+    for (const selection of selectionSet.selections) {
+        if (selection.kind === 'FragmentSpread') {
+            names.push(selection.name.value);
+        } else if (selection.kind === 'Field' && selection.selectionSet) {
+            names.push(...fragmentSpreads(selection.selectionSet));
+        } else if (selection.kind === 'InlineFragment') {
+            names.push(...fragmentSpreads(selection.selectionSet));
+        }
+    }
+    return names;
+}
+
+function removeUnusedFragments(definitions: readonly DefinitionNode[]): readonly DefinitionNode[] {
+    const fragments = new Map<string, FragmentDefinitionNode>();
+    for (const definition of definitions) {
+        if (definition.kind === 'FragmentDefinition') {
+            fragments.set(definition.name.value, definition);
+        }
+    }
+
+    const used = new Set<string>();
+    const pending = definitions
+        .filter((definition) => definition.kind === 'OperationDefinition')
+        .flatMap((definition) => fragmentSpreads(definition.selectionSet));
+    while (pending.length > 0) {
+        const name = pending.pop()!;
+        if (used.has(name)) continue;
+        used.add(name);
+        const fragment = fragments.get(name);
+        if (fragment) pending.push(...fragmentSpreads(fragment.selectionSet));
+    }
+
+    return definitions.filter(
+        (definition) => definition.kind !== 'FragmentDefinition' || used.has(definition.name.value),
+    );
+}
+
+function removeUnusedVariables(definitions: readonly DefinitionNode[]): readonly DefinitionNode[] {
+    const used = new Set<string>();
+    visit({ kind: 'Document', definitions } as DocumentNode, {
+        VariableDefinition() {
+            return false;
+        },
+        Variable(node) {
+            used.add(node.name.value);
+        },
+    });
+
+    return definitions.map((definition) => {
+        if (definition.kind !== 'OperationDefinition' || !definition.variableDefinitions) {
+            return definition;
+        }
+        return {
+            ...definition,
+            variableDefinitions: definition.variableDefinitions.filter((variable) =>
+                used.has(variable.variable.name.value),
+            ),
+        };
+    });
+}
+
+/**
+ * Returns `selectionSet` with `path` removed, or `null` when removing it would
+ * leave an empty selection set — GraphQL has no syntax for one, so the caller
+ * drops the parent field instead.
+ */
+function stripPath(selectionSet: SelectionSetNode, path: FieldPath): SelectionSetNode | null {
+    const [head, ...rest] = path;
+    const selections: SelectionNode[] = [];
+
+    for (const selection of selectionSet.selections) {
+        if (!isField(selection) || fieldName(selection) !== head) {
+            selections.push(selection);
+            continue;
+        }
+        if (rest.length === 0) {
+            // Leaf reached: drop it by not re-adding it.
+            continue;
+        }
+        if (!selection.selectionSet) {
+            selections.push(selection);
+            continue;
+        }
+        const nested = stripPath(selection.selectionSet, rest);
+        if (nested) {
+            selections.push({ ...selection, selectionSet: nested });
+        }
+    }
+
+    return selections.length > 0 ? { ...selectionSet, selections } : null;
+}
+
+/**
+ * Removes capability-gated selections from a GraphQL document.
+ *
+ * The server composes its schema from the capability modules the deployment is
+ * entitled to, so selecting a field owned by an absent module fails validation
+ * on every request. Rather than maintaining a hand-written copy of each
+ * document per composition, the full document stays the single typed source of
+ * truth and the selections a composition cannot serve are pruned from it here.
+ *
+ * The returned document keeps the input's TypeScript type: a pruned field is
+ * `undefined` at runtime, so consumers must treat capability-gated data as
+ * optional. That is the same contract they already need for a field the server
+ * may legitimately return as null.
+ */
+export function stripCapabilityFields<T extends DocumentNode>(document: T, paths: FieldPath[]): T {
+    if (paths.length === 0) {
+        return document;
+    }
+    let definitions = document.definitions;
+    for (const path of paths) {
+        definitions = definitions.map((definition) => {
+            if (definition.kind !== 'OperationDefinition' && definition.kind !== 'FragmentDefinition') {
+                return definition;
+            }
+            const stripped = stripPath(definition.selectionSet, path);
+            if (!stripped) {
+                // Every selection collapsed, which GraphQL cannot express. A
+                // prune list that empties a whole operation is a mistake in the
+                // capability mapping, not something to paper over by keeping
+                // the field that was supposed to be removed.
+                throw new Error(
+                    `Pruning "${path.join('.')}" would leave an empty selection set. ` +
+                        'Split the document instead of pruning its only selection.',
+                );
+            }
+            return { ...definition, selectionSet: stripped };
+        });
+    }
+    const usedDefinitions = removeUnusedFragments(definitions);
+    return { ...document, definitions: removeUnusedVariables(usedDefinitions) } as T;
+}
+
+/**
+ * Convenience wrapper: prunes `paths` only when `granted` is false.
+ */
+export function whenGranted<T extends DocumentNode>(granted: boolean, document: T, paths: FieldPath[]): T {
+    return granted ? document : stripCapabilityFields(addOperationFallback(document), paths);
+}
+
+/**
+ * Registers and composes one typed storefront document from capability rules.
+ * The full typed document remains the source of truth. Missing grants prune
+ * only the selections that their modules own.
+ */
+export function composeCapabilityDocument<T extends DocumentNode>(
+    document: T,
+    rules: readonly CapabilityDocumentRule[],
+): T {
+    const operation = document.definitions.find((definition) => definition.kind === 'OperationDefinition');
+    const name = operation?.name?.value;
+    if (!name) {
+        throw new Error('Capability-composed storefront documents must use a named operation.');
+    }
+    STOREFRONT_CAPABILITY_DOCUMENTS.push({ name, fullDocument: document, rules });
+    return composeCapabilityDocumentFor(document, rules, (capability) => hasCapability(capability));
+}
+
+/** Compose a registered document for an explicit grant set in tests. */
+export function composeCapabilityDocumentFor<T extends DocumentNode>(
+    document: T,
+    rules: readonly CapabilityDocumentRule[],
+    granted: (capability: string) => boolean,
+): T {
+    return rules.reduce(
+        (composed, rule) => whenGranted(granted(rule.capability), composed, [...rule.paths]),
+        document,
+    );
+}
+
+/** Registers a document owned by one capability. */
+export function forCapability<T extends DocumentNode>(
+    capability: string,
+    document: T,
+    paths: readonly FieldPath[],
+): T {
+    return composeCapabilityDocument(document, [{ capability, paths }]);
+}

package/dist/assets/storefront/src/lib/vendure/capability-drift.ts

@@ -0,0 +1,187 @@
+import {
+    VendureGraphQLError,
+    type GraphQLErrorEntry,
+    type RequestMiddleware,
+} from '@vendure-platform/storefront-client';
+import { getLocation, Kind, parse, visit, type ASTNode, type DocumentNode, type FieldNode } from 'graphql';
+
+import { hasCapability } from '@/config/capabilities';
+
+import {
+    STOREFRONT_CAPABILITY_DOCUMENTS,
+    type CapabilityDocumentRule,
+    type FieldPath,
+} from './capability-documents';
+
+/** The code Apollo Server gives every validation failure. It answers them with HTTP 400. */
+const VALIDATION_FAILED = 'GRAPHQL_VALIDATION_FAILED';
+
+/** A selection the server rejected that belongs to a capability this build claims. */
+export interface CapabilityDrift {
+    capability: string;
+    /** From the root of the operation or fragment definition that holds the field. */
+    path: FieldPath;
+}
+
+interface ErrorLocation {
+    line: number;
+    column: number;
+}
+
+/**
+ * Finds the rejected selections that belong to a capability the storefront was
+ * built with.
+ *
+ * Reads structured data only: the validation error code, the error locations,
+ * and the document that was sent. Each location is resolved to the field it
+ * points at, and that field's path is compared with the capability rules the
+ * document was registered with, the same way `stripCapabilityFields` applies
+ * them. An error that is not a validation failure, that points at a field whose
+ * owning capability the build does not claim, or that comes from an
+ * unregistered document is not drift.
+ *
+ * The check sees one direction only: a build that claims a capability the
+ * server does not compose. A build that claims fewer capabilities than the
+ * server composes sends valid documents and only hides features, so no response
+ * shows it.
+ */
+export function findCapabilityDrift(
+    query: string,
+    errors: readonly GraphQLErrorEntry[],
+    granted: (capability: string) => boolean,
+): CapabilityDrift[] {
+    const locations = errors
+        .filter(isValidationFailure)
+        .flatMap((error) => error.locations as ErrorLocation[]);
+    if (locations.length === 0) return [];
+
+    let document: DocumentNode;
+    try {
+        document = parse(query);
+    } catch {
+        return [];
+    }
+    const operation = document.definitions.find(
+        (definition) => definition.kind === Kind.OPERATION_DEFINITION,
+    );
+    const registration = STOREFRONT_CAPABILITY_DOCUMENTS.find(
+        (candidate) => candidate.name === operation?.name?.value,
+    );
+    if (!registration) return [];
+
+    const drift: CapabilityDrift[] = [];
+    for (const path of rejectedFieldPaths(document, locations)) {
+        for (const capability of owners(registration.rules, path)) {
+            if (granted(capability)) drift.push({ capability, path });
+        }
+    }
+    return drift;
+}
+
+/**
+ * The capabilities whose most specific rule path contains `path`.
+ *
+ * Rules nest: `quote.requests` owns `myQuote` and `quote.negotiation` owns
+ * `myQuote.versions`, so a rejected `myQuote.versions` belongs to negotiation
+ * only.
+ */
+function owners(rules: readonly CapabilityDocumentRule[], path: FieldPath): string[] {
+    let longest = 0;
+    let found: string[] = [];
+    for (const rule of rules) {
+        for (const rulePath of rule.paths) {
+            if (rulePath.length < longest || !rulePath.every((name, index) => path[index] === name)) continue;
+            if (rulePath.length > longest) {
+                longest = rulePath.length;
+                found = [];
+            }
+            if (!found.includes(rule.capability)) found.push(rule.capability);
+        }
+    }
+    return found;
+}
+
+function isValidationFailure(error: GraphQLErrorEntry): boolean {
+    const code = (error.extensions as { code?: unknown } | undefined)?.code;
+    return code === VALIDATION_FAILED && Array.isArray(error.locations);
+}
+
+/** The field-name path of every field that starts at one of `locations`. */
+function rejectedFieldPaths(document: DocumentNode, locations: readonly ErrorLocation[]): FieldPath[] {
+    const paths: FieldPath[] = [];
+    visit(document, {
+        Field(node, _key, _parent, _path, ancestors) {
+            if (!node.loc) return;
+            const { line, column } = getLocation(node.loc.source, node.loc.start);
+            if (!locations.some((location) => location.line === line && location.column === column)) return;
+            const parents = (ancestors as ReadonlyArray<ASTNode | readonly ASTNode[]>).filter(
+                (ancestor): ancestor is FieldNode => 'kind' in ancestor && ancestor.kind === Kind.FIELD,
+            );
+            paths.push([...parents.map((field) => field.name.value), node.name.value]);
+        },
+    });
+    return paths;
+}
+
+/**
+ * The Shop API rejected a selection because this storefront was built for a
+ * capability its server does not compose.
+ *
+ * Extends the error the client reports for GraphQL errors, and keeps the
+ * server's errors unchanged in `errors`.
+ */
+export class CapabilityDriftError extends VendureGraphQLError {
+    readonly drift: CapabilityDrift[];
+
+    constructor(errors: GraphQLErrorEntry[], response: Response, drift: CapabilityDrift[]) {
+        super(errors, response);
+        // The base class types `name` as its own literal, so a field override
+        // does not compile. Replace the value it set instead.
+        Object.defineProperty(this, 'name', { value: 'CapabilityDriftError' });
+        this.drift = drift;
+        const capabilities = [...new Set(drift.map((entry) => entry.capability))];
+        const fields = drift.map((entry) => entry.path.join('.'));
+        const subject = capabilities.length === 1 ? 'that capability' : 'those capabilities';
+        const serverErrors = errors.map((error) => error.message).join(', ');
+        this.message =
+            `Storefront capability drift: this storefront was built with NEXT_PUBLIC_VENDURE_CAPABILITIES ` +
+            `granting ${capabilities.join(', ')}, but the Shop API rejected ${fields.join(', ')}. ` +
+            `The server does not compose ${subject}. Rebuild the storefront with the capability keys ` +
+            `of the server's capability profile. Server errors: ${serverErrors}`;
+    }
+}
+
+/**
+ * Reports a validation failure on a claimed capability's field as a
+ * {@link CapabilityDriftError}.
+ *
+ * Apollo Server answers a validation failure with HTTP 400, which the client
+ * otherwise reports only as "HTTP error 400". Only those responses are read
+ * here. Every other response passes through untouched.
+ */
+export const capabilityDriftMiddleware: RequestMiddleware = async (request, next) => {
+    const response = await next(request);
+    if (response.status !== 400) return response;
+
+    // A body can be read once. Middleware outside this one gets the same read,
+    // including its failure when the body is not JSON.
+    const body = response.json();
+    const payload = (await body.catch(() => undefined)) as { errors?: GraphQLErrorEntry[] } | undefined;
+    const query = sentQuery(request.body);
+    const errors = payload?.errors ?? [];
+    const drift = query === undefined ? [] : findCapabilityDrift(query, errors, hasCapability);
+    if (drift.length > 0) {
+        throw new CapabilityDriftError(errors, response.response, drift);
+    }
+    return { ...response, json: () => body };
+};
+
+/** The GraphQL document in a request body, when the body is the JSON the client sends. */
+function sentQuery(body: string): string | undefined {
+    try {
+        const { query } = JSON.parse(body) as { query?: unknown };
+        return typeof query === 'string' ? query : undefined;
+    } catch {
+        return undefined;
+    }
+}