@laioutr/app-shopware 0.14.4

package/dist/runtime/server/orchestr/suggested-search/suggested-search.query.js

@@ -0,0 +1,54 @@
+import { ProductSearchPage } from "@laioutr-core/canonical-types/ecommerce";
+import { SuggestedSearchSearchQuery } from "@laioutr-core/canonical-types/suggested-search";
+import { suggestionResultsFragmentToken } from "../../const/passthroughTokens.js";
+import { defineShopwareQuery } from "../../middleware/defineShopware.js";
+import { createFallbackSlug, entitySlug } from "../../shopware-helper/mappers/slugMapper.js";
+export default defineShopwareQuery(SuggestedSearchSearchQuery, async ({ context, input, passthrough }) => {
+  const { storefrontClient } = context;
+  const { query } = input;
+  const { data } = await storefrontClient.invoke("searchSuggest post /search-suggest", {
+    body: { search: query ?? "" }
+  });
+  const res = data;
+  const querySuggestionsResults = Object.values(res.extensions?.completionResult ?? {}).filter((val) => val !== "array_struct").map((val, index) => ({
+    id: `query_suggestion_${index}`,
+    type: "query-suggestion",
+    title: val,
+    link: { type: "pageType", pageType: ProductSearchPage, params: { q: val } }
+  }));
+  const brandResults = Object.values(res.extensions?.multiSuggestResult?.suggestResults?.product_manufacturer?.elements ?? []).map(
+    (manufacturer) => ({
+      id: manufacturer.id,
+      type: "brand",
+      title: manufacturer.name,
+      link: {
+        type: "reference",
+        reference: { type: "brand", id: manufacturer.id, slug: createFallbackSlug(manufacturer.name, manufacturer.id) }
+      }
+    })
+  );
+  const categoryResults = Object.values(res.extensions?.multiSuggestResult?.suggestResults?.category?.elements ?? []).map((category) => ({
+    id: category.id,
+    type: "category",
+    title: category.name,
+    link: {
+      type: "reference",
+      reference: { type: "category", id: category.id, slug: entitySlug(category) }
+    }
+  }));
+  const productResults = (data.elements ?? []).map((product) => ({
+    id: product.id,
+    type: "product",
+    title: product.name,
+    link: {
+      type: "reference",
+      reference: { type: "product", id: product.id, slug: entitySlug(product) }
+    }
+  }));
+  const id = `search-suggest:${query}`;
+  passthrough.set(suggestionResultsFragmentToken, {
+    id,
+    suggestions: [...querySuggestionsResults, ...brandResults, ...categoryResults, ...productResults]
+  });
+  return { id };
+});

package/dist/runtime/server/orchestr/suggested-search-entry/base.resolver.d.ts

@@ -0,0 +1,2 @@
+declare const _default: any;
+export default _default;

package/dist/runtime/server/orchestr/suggested-search-entry/base.resolver.js

@@ -0,0 +1,22 @@
+import { SuggestedSearchEntryBase } from "@laioutr-core/canonical-types/entity/suggested-search-entry";
+import { suggestionResultsFragmentToken } from "../../const/passthroughTokens.js";
+import { defineShopwareComponentResolver } from "../../middleware/defineShopware.js";
+export default defineShopwareComponentResolver({
+  label: "Shopware Suggested Search Entry Resolver",
+  entityType: "SuggestedSearchEntry",
+  provides: [SuggestedSearchEntryBase],
+  resolve: ({ passthrough, $entity }) => {
+    const results = passthrough.require(suggestionResultsFragmentToken);
+    const entities = results.suggestions.map(
+      ({ id, type, title, link }) => $entity({
+        id,
+        base: () => ({
+          type,
+          title,
+          link
+        })
+      })
+    );
+    return { entities };
+  }
+});

package/dist/runtime/server/orchestr-helper/isLinkSingle.d.ts

@@ -0,0 +1,2 @@
+import { LinkSingle } from '@laioutr-core/orchestr/types';
+export declare const isLinkSingle: (link: unknown) => link is LinkSingle;

package/dist/runtime/server/orchestr-helper/isLinkSingle.js

@@ -0,0 +1 @@
+export const isLinkSingle = (link) => typeof link === "object" && link !== null && typeof link.sourceId === "string" && typeof link.targetId === "string";

package/dist/runtime/server/orchestr-helper/matchAndMap.d.ts

@@ -0,0 +1 @@
+export declare const matchAndMap: <T, U>(entityIds: string[], sourceData: T[] | undefined, matchEntityCb: (id: string, entry: T) => boolean, mapCb: (entity: T) => U) => any;

package/dist/runtime/server/orchestr-helper/matchAndMap.js

@@ -0,0 +1,15 @@
+const isEntry = (obj) => typeof obj !== "undefined";
+export const matchAndMap = (entityIds, sourceData, matchEntityCb, mapCb) => {
+  if (!sourceData || sourceData.length === 0) {
+    return {};
+  }
+  return Object.fromEntries(
+    entityIds.map((id) => {
+      const rawEntity = sourceData.find((entry) => matchEntityCb(id, entry));
+      if (!rawEntity) {
+        return void 0;
+      }
+      return [id, mapCb(rawEntity)];
+    }).filter(isEntry)
+  );
+};

package/dist/runtime/server/orchestr-helper/requestedFields.d.ts

@@ -0,0 +1,18 @@
+export declare const resolveProductFields: ({ loadVariants }: {
+    loadVariants: boolean;
+}) => {
+    associations: {
+        [key: string]: /*elided*/ any;
+    };
+    includes: {
+        [key: string]: string[];
+    };
+};
+export declare const resolveProductVariantFields: () => {
+    associations: {
+        [key: string]: /*elided*/ any;
+    };
+    includes: {
+        [key: string]: string[];
+    };
+};

package/dist/runtime/server/orchestr-helper/requestedFields.js

@@ -0,0 +1,145 @@
+import { ProductVariantsLink } from "@laioutr-core/canonical-types/ecommerce";
+import { MediaIncludes } from "../const/includes.js";
+const unique = (arr) => Array.from(new Set(arr));
+const addAssociation = (name, add, association = {}) => add ? { [name]: association } : {};
+const _resolveRequestedFields = ({
+  requestedComponents,
+  requestedLinks
+}) => {
+  const requestedVariants = requestedLinks[ProductVariantsLink];
+  const variantFields = requestedVariants ? resolveProductVariantFields() : void 0;
+  const associations = {
+    ...requestedComponents.includes("media") ? { cover: { associations: { media: {} } }, media: { associations: { media: {} } } } : {},
+    // gallery images (via product_media -> media)
+    ...requestedComponents.includes("options") ? { options: { associations: { group: {} } } } : {},
+    // variant options like Color/Size + their group names
+    ...requestedVariants ? {
+      children: {
+        associations: variantFields?.associations ?? {}
+      }
+    } : {}
+  };
+  const includes = {
+    product: unique([
+      "id",
+      "parentId",
+      ...requestedComponents.includes("base") ? ["name", "seoUrls"] : [],
+      ...requestedComponents.includes("info") ? ["name", "productNumber", "ean", "translated", "manufacturer", "description", "cover"] : [],
+      ...requestedComponents.includes("description") ? ["translated", "description"] : [],
+      ...requestedComponents.includes("seo") ? ["metaTitle", "metaDescription", "seoUrls"] : [],
+      ...requestedComponents.includes("media") ? ["cover", "media"] : [],
+      ...requestedComponents.includes("prices") ? ["minPurchase", "purchaseSteps", "maxPurchase", "calculatedPrice", "calculatedPrices"] : [],
+      ...requestedLinks["ecommerce/product/variants"] ? ["children"] : [],
+      ...variantFields?.includes?.product ?? []
+    ]),
+    product_media: requestedComponents.includes("media") ? ["id", "mediaId", "media"] : [],
+    media: requestedComponents.includes("media") ? MediaIncludes : [],
+    property_group_option: requestedComponents.includes("availability") ? ["id", "name", "group"] : [],
+    property_group: requestedComponents.includes("availability") ? ["id", "name"] : []
+  };
+  return { associations, includes };
+};
+const mergeIncludes = (includes1, includes2) => {
+  const merged = {};
+  for (const [key, value] of Object.entries(includes1)) {
+    merged[key] = [...value];
+  }
+  for (const [key, value] of Object.entries(includes2)) {
+    merged[key] = [...merged[key] ?? [], ...value];
+  }
+  for (const [key, value] of Object.entries(merged)) {
+    merged[key] = unique([...value]);
+  }
+  return merged;
+};
+export const resolveProductFields = ({ loadVariants }) => {
+  const variantFields = loadVariants ? resolveProductVariantFields() : void 0;
+  const associations = {
+    cover: { associations: { media: {} } },
+    media: { associations: { media: {} } },
+    ...addAssociation("children", loadVariants, variantFields?.associations ? { associations: variantFields?.associations } : {})
+  };
+  const includes = mergeIncludes(
+    {
+      product: [
+        "id",
+        "parentId",
+        "name",
+        "seoUrls",
+        "productNumber",
+        "ean",
+        "translated",
+        "manufacturer",
+        "description",
+        "cover",
+        "metaTitle",
+        "metaDescription",
+        "cover",
+        "media",
+        "minPurchase",
+        "purchaseSteps",
+        "maxPurchase",
+        "calculatedPrice",
+        "calculatedPrices",
+        "children",
+        "ratingAverage",
+        "productReviews"
+      ],
+      product_media: ["id", "mediaId", "media"],
+      media: MediaIncludes
+    },
+    variantFields?.includes ?? {}
+  );
+  return {
+    associations,
+    includes
+  };
+};
+export const resolveProductVariantFields = () => {
+  const associations = {
+    cover: { associations: { media: {} } },
+    // main image
+    media: { associations: { media: {} } },
+    // gallery images (via product_media -> media)
+    options: { associations: { group: {} } },
+    // variant options like Color/Size + their group names
+    manufacturer: {},
+    deliveryTime: {},
+    prices: { associations: { rule: {} } }
+  };
+  const includes = {
+    product: [
+      "id",
+      "parentId",
+      "name",
+      "productNumber",
+      "ean",
+      "available",
+      "availableStock",
+      "stock",
+      "minPurchase",
+      "purchaseSteps",
+      "maxPurchase",
+      "calculatedPrice",
+      "calculatedPrices",
+      "cover",
+      "media",
+      "options",
+      "optionIds",
+      "translated",
+      "manufacturer",
+      "deliveryTime",
+      "prices",
+      "ratingAverage",
+      "productReviews"
+    ],
+    product_media: ["id", "mediaId", "media"],
+    media: MediaIncludes,
+    property_group_option: ["id", "name", "group", "translated"],
+    property_group: ["id", "name", "translated"]
+  };
+  return {
+    associations,
+    includes
+  };
+};

package/dist/runtime/server/routes/adopt-session.post.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Same-origin endpoint the embedded checkout section calls on `laioutr:auth-changed`.
+ * Redeems the single-use code for the customer-bound context token (login) or clears the
+ * token (logout). The token is fetched server-to-server and stored in an httpOnly cookie;
+ * it never reaches the browser.
+ */
+declare const _default: any;
+export default _default;

package/dist/runtime/server/routes/adopt-session.post.js

@@ -0,0 +1,16 @@
+import { defineEventHandler, readBody, useRuntimeConfig } from "#imports";
+import { adoptSessionToken } from "../shopware-helper/adoptSession.js";
+import { clearContextToken, persistContextToken } from "../shopware-helper/persistContextToken.js";
+import { adoptSession } from "../shopware-helper/resolveAdoptSession.js";
+export default defineEventHandler(async (event) => {
+  const config = useRuntimeConfig()["@laioutr/app-shopware"];
+  const body = await readBody(event);
+  const code = typeof body?.code === "string" ? body.code : null;
+  return adoptSession({
+    config: { endpoint: config.endpoint, accessToken: config.accessToken },
+    code,
+    adopt: adoptSessionToken,
+    persist: (token) => persistContextToken(event, token),
+    clear: () => clearContextToken(event)
+  });
+});

package/dist/runtime/server/routes/checkout.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Same-origin checkout handoff route (registered at {@link CHECKOUT_ENDPOINT_PATH}).
+ *
+ * A cart checkout button is a plain anchor to this route. On navigation the browser
+ * sends the `sw-context-token` cookie; {@link resolveCheckout} mints a single-use
+ * handoff code server-to-server and this thin adapter 302s to the storefront's
+ * `connect-session`, which adopts the cart context into the storefront session. The
+ * fail-closed decision matrix lives in `resolveCheckout` (unit-tested); no path mutates the cart.
+ *
+ * A first-time visitor has no `sw-context-token` cookie yet (the cookie is only set by a cart
+ * action or login). Without one, `resolveCheckout` would bounce to the laioutr root and the
+ * embedded storefront would never load. So when the cookie is absent we bootstrap a guest
+ * context token and persist it, giving the storefront a session to adopt (an empty guest cart).
+ */
+declare const _default: any;
+export default _default;

package/dist/runtime/server/routes/checkout.js

@@ -0,0 +1,31 @@
+import { consola } from "consola";
+import { createError, defineEventHandler, getCookie, getRequestURL, sendRedirect, useRuntimeConfig } from "#imports";
+import { CONTEXT_TOKEN_COOKIE } from "../const/cookieKeys.js";
+import { bootstrapGuestContextToken } from "../shopware-helper/bootstrapContextToken.js";
+import { persistContextToken } from "../shopware-helper/persistContextToken.js";
+import { resolveCheckout } from "../shopware-helper/resolveCheckout.js";
+import { mintSessionHandoffCode } from "../shopware-helper/sessionHandoff.js";
+const log = consola.withTag("shopware/checkout");
+export default defineEventHandler(async (event) => {
+  const config = useRuntimeConfig()["@laioutr/app-shopware"];
+  let contextToken = getCookie(event, CONTEXT_TOKEN_COOKIE);
+  if (!contextToken) {
+    try {
+      contextToken = await bootstrapGuestContextToken({ endpoint: config.endpoint, accessToken: config.accessToken });
+      await persistContextToken(event, contextToken);
+    } catch (cause) {
+      log.error("Failed to bootstrap a guest context token", cause);
+    }
+  }
+  const plan = await resolveCheckout({
+    config,
+    contextToken,
+    origin: getRequestURL(event).origin,
+    mint: mintSessionHandoffCode
+  });
+  if (plan.kind === "error") {
+    log.error(plan.statusMessage, plan.cause);
+    throw createError({ statusCode: plan.statusCode, statusMessage: plan.statusMessage });
+  }
+  return sendRedirect(event, plan.url, 302);
+});

package/dist/runtime/server/shopware-helper/adoptSession.d.ts

@@ -0,0 +1,18 @@
+export interface AdoptSessionTokenParams {
+    /** Store-API base URL, e.g. `https://shop.example.com/store-api`. */
+    endpoint: string;
+    /** Sales-channel access key (sent as the `sw-access-key` header). */
+    accessToken: string;
+    /** Single-use handoff code received in a `laioutr:auth-changed` message. */
+    code: string;
+}
+/**
+ * Redeem a single-use handoff code for its customer-bound `sw-context-token` against the
+ * `LaioutrConnector` plugin's `POST /store-api/laioutr/session-adopt` endpoint.
+ *
+ * Called server-to-server after a `laioutr:auth-changed` message: the token is returned to
+ * laioutr's server only and never reaches the browser. The code is single-use and ~60s TTL.
+ *
+ * @throws with the plugin's rejection reason on a non-2xx response, or when no token is returned.
+ */
+export declare const adoptSessionToken: (params: AdoptSessionTokenParams) => Promise<string>;

package/dist/runtime/server/shopware-helper/adoptSession.js

@@ -0,0 +1,23 @@
+const describeAdoptError = (err) => {
+  const e = err;
+  const apiError = e?.data?.errors?.[0];
+  return apiError?.detail ?? apiError?.title ?? e?.data?.message ?? e?.message ?? "unknown error";
+};
+export const adoptSessionToken = async (params) => {
+  const base = params.endpoint.replace(/\/+$/, "");
+  let res;
+  try {
+    res = await $fetch(`${base}/laioutr/session-adopt`, {
+      method: "POST",
+      headers: { "sw-access-key": params.accessToken },
+      body: { code: params.code }
+    });
+  } catch (err) {
+    throw new Error(`session-adopt rejected: ${describeAdoptError(err)}`);
+  }
+  const token = res?.["context-token"];
+  if (!token) {
+    throw new Error("session-adopt returned no context token");
+  }
+  return token;
+};

package/dist/runtime/server/shopware-helper/bootstrapContextToken.d.ts

@@ -0,0 +1,18 @@
+export interface BootstrapContextTokenParams {
+    /** Store-API base URL, e.g. `https://shop.example.com/store-api`. */
+    endpoint: string;
+    /** Sales-channel access key (sent as the `sw-access-key` header). */
+    accessToken: string;
+}
+/**
+ * Mint a fresh guest `sw-context-token` by calling the store-api `GET /context` with only the
+ * sales-channel access key. Shopware creates a new guest context and returns its token in the
+ * `sw-context-token` response header (hence `$fetch.raw`, to read the header). Read-only — it
+ * does not touch the cart.
+ *
+ * Used by the checkout handoff route so a first-time visitor (no context cookie yet) still gets
+ * a session the embedded storefront can adopt, instead of being bounced to the laioutr root.
+ *
+ * @throws when the store-api call fails or returns no context token.
+ */
+export declare const bootstrapGuestContextToken: (params: BootstrapContextTokenParams) => Promise<string>;

package/dist/runtime/server/shopware-helper/bootstrapContextToken.js

@@ -0,0 +1,22 @@
+const describeBootstrapError = (err) => {
+  const e = err;
+  const apiError = e?.data?.errors?.[0];
+  return apiError?.detail ?? apiError?.title ?? e?.data?.message ?? e?.message ?? "unknown error";
+};
+export const bootstrapGuestContextToken = async (params) => {
+  const base = params.endpoint.replace(/\/+$/, "");
+  let token;
+  try {
+    const res = await $fetch.raw(`${base}/context`, {
+      method: "GET",
+      headers: { "sw-access-key": params.accessToken }
+    });
+    token = res.headers.get("sw-context-token");
+  } catch (err) {
+    throw new Error(`guest context bootstrap failed: ${describeBootstrapError(err)}`);
+  }
+  if (!token) {
+    throw new Error("guest context bootstrap returned no context token");
+  }
+  return token;
+};

package/dist/runtime/server/shopware-helper/cartErrors.d.ts

@@ -0,0 +1,11 @@
+import { Schemas } from '../types/storeApiTypes.js';
+/**
+ * Inspect the `errors` of a Shopware cart mutation response.
+ *
+ * Blocking errors (`level: 20`) throw a generic error with the Shopware message.
+ * Notices (`level: 0`) and warnings (`level: 10`) are logged, not dropped, so cart-side
+ * issues stay diagnosable without failing the mutation. (Mapping to canonical
+ * Product* errors is deferred — Shopware's CartError shape carries no reliable
+ * variant reference.)
+ */
+export declare const handleCartMutationErrors: (errors: Schemas["Cart"]["errors"]) => void;

package/dist/runtime/server/shopware-helper/cartErrors.js

@@ -0,0 +1,21 @@
+import { consola } from "consola";
+const logger = consola.withTag("shopware/cart");
+const normalizeCartErrors = (errors) => {
+  if (!errors) return [];
+  if (Array.isArray(errors)) return errors;
+  return Object.values(errors);
+};
+export const handleCartMutationErrors = (errors) => {
+  for (const error of normalizeCartErrors(errors)) {
+    const level = error.level ?? 0;
+    const detail = { key: error.key, messageKey: error.messageKey, message: error.message };
+    if (level >= 20) {
+      throw new Error(`Shopware cart error: ${error.messageKey ?? error.key ?? "unknown"} \u2014 ${error.message ?? ""}`.trim());
+    }
+    if (level >= 10) {
+      logger.warn("Cart warning", detail);
+    } else {
+      logger.info("Cart notice", detail);
+    }
+  }
+};

package/dist/runtime/server/shopware-helper/cartMapper.d.ts

@@ -0,0 +1,14 @@
+import { CartCost } from '@laioutr-core/canonical-types/entity/cart';
+import { CartItemAvailability, CartItemBase, CartItemCost, CartItemProductData, CartItemQuantityRule } from '@laioutr-core/canonical-types/entity/cart-item';
+import { EntityComponentType } from '@laioutr-core/core-types/orchestr';
+import { Schemas } from '../types/storeApiTypes.js';
+/** Map a Shopware cart's aggregate price into the canonical nested `CartCost`. */
+export declare const mapCartCost: (cart: Schemas["Cart"], currency: string) => EntityComponentType<typeof CartCost>;
+/** Map a Shopware product line item into the canonical `CartItem` component values. */
+export declare const mapCartItem: (lineItem: Schemas["LineItem"], currency: string) => {
+    base: EntityComponentType<typeof CartItemBase>;
+    cost: EntityComponentType<typeof CartItemCost>;
+    availability: EntityComponentType<typeof CartItemAvailability>;
+    quantityRule: EntityComponentType<typeof CartItemQuantityRule>;
+    productData: EntityComponentType<typeof CartItemProductData>;
+};

package/dist/runtime/server/shopware-helper/cartMapper.js

@@ -0,0 +1,83 @@
+import { Money } from "@screeny05/ts-money";
+import { createFallbackSlug, getEntitySeoSlug } from "./mappers/slugMapper.js";
+import { mapMedia } from "./mediaMapper.js";
+export const mapCartCost = (cart, currency) => {
+  const money = (value) => Money.fromDecimal(value, currency);
+  const lineItems = cart.lineItems ?? [];
+  const deliveries = cart.deliveries ?? [];
+  const price = cart.price;
+  const subtotalValue = price?.positionPrice ?? lineItems.reduce((sum, li) => sum + (li.price?.totalPrice ?? 0), 0);
+  const totalValue = price?.totalPrice ?? subtotalValue;
+  const shippingValue = deliveries.reduce((sum, d) => sum + (d.shippingCosts?.totalPrice ?? 0), 0);
+  const itemTaxValue = (price?.calculatedTaxes ?? []).reduce((sum, t) => sum + (t.tax ?? 0), 0);
+  const shippingTaxValue = deliveries.reduce(
+    (sum, d) => sum + (d.shippingCosts?.calculatedTaxes ?? []).reduce((s, t) => s + (t.tax ?? 0), 0),
+    0
+  );
+  const taxIncluded = price?.taxStatus === "gross";
+  const taxes = (price?.calculatedTaxes ?? []).map((t) => ({
+    rate: (t.taxRate ?? 0) / 100,
+    amount: money(t.tax ?? 0)
+  }));
+  return {
+    subtotal: money(subtotalValue),
+    subtotalIsEstimated: false,
+    total: money(totalValue),
+    totalIsEstimated: false,
+    ...deliveries.length > 0 ? { shipping: { total: money(shippingValue), isEstimated: false } } : {},
+    tax: { total: money(itemTaxValue + shippingTaxValue), isEstimated: false, isIncluded: taxIncluded },
+    ...taxes.length > 0 ? { taxes } : {}
+  };
+};
+export const mapCartItem = (lineItem, currency) => {
+  const money = (value) => Money.fromDecimal(value, currency);
+  const price = lineItem.price;
+  const qtyInfo = lineItem.quantityInformation;
+  const payload = lineItem.payload ?? {};
+  const unit = price?.unitPrice ?? 0;
+  const total = price?.totalPrice ?? 0;
+  const listPrice = price?.listPrice?.price;
+  const parentId = payload.parentId ?? lineItem.referencedId ?? lineItem.id;
+  const slug = getEntitySeoSlug(payload) ?? createFallbackSlug(lineItem.label ?? "", lineItem.referencedId ?? lineItem.id);
+  const availableStock = payload.availableStock;
+  const inStock = availableStock === void 0 ? payload.available !== false : availableStock > 0;
+  return {
+    base: {
+      type: "product",
+      quantity: lineItem.quantity,
+      title: lineItem.label ?? "",
+      code: payload.productNumber,
+      // Cart covers are product images (never video), so the narrowing cast is safe.
+      cover: lineItem.cover?.media ? mapMedia(lineItem.cover.media) : void 0,
+      link: {
+        type: "reference",
+        reference: { type: "Product", id: parentId, slug }
+      }
+    },
+    cost: {
+      single: money(unit),
+      singleStrikethrough: listPrice && listPrice > unit ? money(listPrice) : void 0,
+      subtotal: money(total),
+      total: money(total)
+    },
+    availability: {
+      // `quantity` is Shopware's own purchasable quantity: `quantityInformation.maxPurchase`
+      // is the product's `calculatedMaxPurchase` — stock-clamped (`min(cap, availableStock)`)
+      // for closeout products, and the configured cap for backorder products. This is the
+      // number Shopware's storefront quantity selector uses. Physical stock is not surfaced
+      // here on purpose (Shopware doesn't put `availableStock` on the cart line's
+      // `quantityInformation`); expose true stock via a product association if a low-stock UI
+      // ever needs it. The purchase cap is also carried in `quantityRule.max` below.
+      quantity: qtyInfo?.maxPurchase ?? availableStock ?? lineItem.quantity,
+      status: inStock ? "inStock" : "outOfStock"
+    },
+    quantityRule: {
+      min: qtyInfo?.minPurchase ?? 1,
+      max: qtyInfo?.maxPurchase,
+      increment: qtyInfo?.purchaseSteps ?? 1,
+      canChange: true
+    },
+    // Shopware referencePrice → canonical UnitPrice mapping is deferred; productData is optional.
+    productData: void 0
+  };
+};

package/dist/runtime/server/shopware-helper/categoryFlattener.d.ts

@@ -0,0 +1,75 @@
+import type { ShopwareCategory } from '../types/shopware.js';
+/**
+ * Returns a flat list of shopware categories
+ *
+ * Order is left as the navigation route returned it: that route nests and sorts each level
+ * server-side, so re-sorting here would only risk diverging from the shop's own order.
+ *
+ * **Warning**: This function mutates the input categories by overwriting their parentId property.
+ */
+export declare const flattenCategories: (categories: ShopwareCategory[], parent?: ShopwareCategory) => {
+    active?: boolean;
+    afterCategoryId?: string;
+    afterCategoryVersionId?: string;
+    apiAlias: "category";
+    breadcrumb: string[];
+    childCount: number;
+    children: import("../types/storeApiTypes.js").components["schemas"]["Category"][];
+    cmsPage?: import("../types/storeApiTypes.js").components["schemas"]["CmsPage"];
+    cmsPageId?: string;
+    cmsPageIdSwitched?: boolean;
+    cmsPageVersionId?: string;
+    createdAt: string;
+    customEntityTypeId?: string;
+    customFields?: import("../types/storeApiTypes.js").GenericRecord;
+    description?: string;
+    displayNestedProducts: boolean;
+    externalLink?: string;
+    id: string;
+    internalLink?: string;
+    keywords?: string;
+    level?: number;
+    linkNewTab?: boolean;
+    linkType?: string;
+    media?: import("../types/storeApiTypes.js").components["schemas"]["Media"];
+    mediaId?: string;
+    metaDescription?: string;
+    metaTitle?: string;
+    name: string;
+    parent?: import("../types/storeApiTypes.js").components["schemas"]["Category"];
+    parentId?: string;
+    parentVersionId?: string;
+    path?: string;
+    productAssignmentType: string;
+    seoUrls?: import("../types/storeApiTypes.js").components["schemas"]["SeoUrl"][];
+    tags?: import("../types/storeApiTypes.js").components["schemas"]["Tag"][];
+    translated: {
+        afterCategoryId?: string;
+        afterCategoryVersionId?: string;
+        apiAlias?: string;
+        breadcrumb: string[];
+        cmsPageId?: string;
+        cmsPageVersionId?: string;
+        customEntityTypeId?: string;
+        description?: string;
+        externalLink?: string;
+        internalLink?: string;
+        keywords?: string;
+        linkType?: string;
+        mediaId?: string;
+        metaDescription?: string;
+        metaTitle?: string;
+        name?: string;
+        parentId?: string;
+        parentVersionId?: string;
+        path?: string;
+        productAssignmentType?: string;
+        type?: string;
+        versionId?: string;
+    };
+    type: string;
+    updatedAt?: string;
+    versionId?: string;
+    visible?: boolean;
+    visibleChildCount?: number;
+}[];

package/dist/runtime/server/shopware-helper/categoryFlattener.js

@@ -0,0 +1,11 @@
+export const flattenCategories = (categories, parent) => {
+  const flattenedCategories = [];
+  for (const category of categories) {
+    category.parentId = parent?.id;
+    flattenedCategories.push(category);
+    if (category.children) {
+      flattenedCategories.push(...flattenCategories(category.children, category));
+    }
+  }
+  return flattenedCategories;
+};