@decocms/apps-nuvemshop 7.74.1

package/src/utils/transform.ts

@@ -0,0 +1,231 @@
+import type {
+  BreadcrumbList,
+  ImageObject,
+  Product,
+  ProductDetailsPage,
+  PropertyValue,
+  UnitPriceSpecification,
+} from "@decocms/apps-commerce/types";
+import type { NuvemshopCategory, NuvemshopProduct, NuvemshopVariant } from "./types";
+
+export interface TransformOptions {
+  /** Storefront origin used to build absolute URLs. */
+  origin: string;
+  /** The API carries no currency; it's a store setting. Default "BRL". */
+  currency?: string;
+}
+
+const IN_STOCK = "https://schema.org/InStock";
+const OUT_OF_STOCK = "https://schema.org/OutOfStock";
+
+// Nuvemshop's URL scheme without the trailing slash: createDecoRouter strips it
+// (TanStack's default), so `/produtos/x/` would answer with a redirect and a
+// canonical pointing at it would never be a 200. Old slashed links still land
+// via that redirect, and the loaders accept both forms.
+export const productPath = (handle: string) => `/produtos/${handle}`;
+
+const money = (v: string | null | undefined) => (v == null || v === "" ? undefined : Number(v));
+
+/** Sale price = promotional_price ?? price; list price = max(compare_at, price). */
+export function variantPrices(v: NuvemshopVariant) {
+  const base = money(v.price) ?? 0;
+  const price = money(v.promotional_price) ?? base;
+  const listPrice = Math.max(money(v.compare_at_price) ?? base, base);
+  return { price, listPrice };
+}
+
+/** `stock: null` means unlimited stock in Nuvemshop. */
+export const isAvailable = (v: NuvemshopVariant) =>
+  !v.stock_management || v.stock == null || v.stock > 0;
+
+/** `?variant=` id when present, else the first available variant, else the first. */
+export function pickVariant(
+  product: NuvemshopProduct,
+  variantId?: string | null,
+): NuvemshopVariant {
+  const variants = product.variants ?? [];
+  if (!variants.length)
+    throw new Error(`Nuvemshop product ${product.id} has no variants (missing "variants" field?)`);
+  return (
+    (variantId && variants.find((v) => String(v.id) === variantId)) ||
+    variants.find(isAvailable) ||
+    variants[0]
+  );
+}
+
+const prop = (name: string, value: string, valueReference: string): PropertyValue => ({
+  "@type": "PropertyValue",
+  name,
+  value,
+  valueReference,
+});
+
+function toImages(product: NuvemshopProduct, variant?: NuvemshopVariant): ImageObject[] {
+  const images = [...(product.images ?? [])];
+  const own = images.findIndex((i) => i.id === variant?.image_id);
+  if (own > 0) images.unshift(...images.splice(own, 1));
+  return images.map((i) => ({
+    "@type": "ImageObject",
+    url: i.src,
+    alternateName: i.alt || product.name,
+    encodingFormat: "image",
+  }));
+}
+
+const stripHtml = (html = "") =>
+  html
+    .replace(/<[^>]*>/g, " ")
+    .replace(/&nbsp;/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+
+export function toProduct(
+  product: NuvemshopProduct,
+  variant: NuvemshopVariant,
+  opts: TransformOptions,
+  level = 0,
+): Product {
+  const { origin, currency = "BRL" } = opts;
+  const attributes = product.attributes ?? [];
+  const groupUrl = `${origin}${productPath(product.handle)}`;
+  const { price, listPrice } = variantPrices(variant);
+  const priceSpecification: UnitPriceSpecification[] = [
+    {
+      "@type": "UnitPriceSpecification",
+      priceType: "https://schema.org/ListPrice",
+      price: listPrice,
+    },
+    { "@type": "UnitPriceSpecification", priceType: "https://schema.org/SalePrice", price },
+  ];
+
+  return {
+    "@type": "Product",
+    productID: String(variant.id),
+    sku: String(variant.id),
+    name: variant.values.join(" / ") || product.name,
+    url: `${groupUrl}?variant=${variant.id}`,
+    description: product.description,
+    gtin: variant.barcode ?? undefined,
+    brand: product.brand ? { "@type": "Brand", name: product.brand } : undefined,
+    category: product.categories?.map((c) => c.name).join(">") || undefined,
+    additionalProperty: variant.values.map((value, i) =>
+      prop(attributes[i] ?? `option${i + 1}`, value, "SPECIFICATION"),
+    ),
+    image: toImages(product, variant),
+    video: product.video_url
+      ? [
+          {
+            "@type": "VideoObject",
+            contentUrl: product.video_url,
+            name: product.name,
+            description: product.name,
+            uploadDate: "",
+            thumbnailUrl: "",
+          },
+        ]
+      : undefined,
+    isVariantOf: {
+      "@type": "ProductGroup",
+      productGroupID: String(product.id),
+      name: product.name,
+      url: groupUrl,
+      model: variant.sku ?? undefined,
+      image: toImages(product),
+      hasVariant:
+        level === 0 ? (product.variants ?? []).map((v) => toProduct(product, v, opts, 1)) : [],
+      additionalProperty: [
+        ...(product.tags ?? "")
+          .split(",")
+          .map((t) => t.trim())
+          .filter(Boolean)
+          .map((t) => prop("TAG", t, "TAG")),
+        ...(product.custom_fields ?? []).map((f) => prop(f.key, f.value, "CUSTOM_FIELD")),
+        ...(product.free_shipping ? [prop("freeShipping", "true", "SHIPPING")] : []),
+      ],
+    },
+    offers: {
+      "@type": "AggregateOffer",
+      priceCurrency: currency,
+      lowPrice: price,
+      highPrice: listPrice,
+      offerCount: 1,
+      offers: [
+        {
+          "@type": "Offer",
+          sku: variant.sku ?? undefined,
+          gtin: variant.barcode ?? undefined,
+          price,
+          availability: isAvailable(variant) ? IN_STOCK : OUT_OF_STOCK,
+          inventoryLevel: { value: variant.stock ?? undefined },
+          priceSpecification,
+        },
+      ],
+    },
+  };
+}
+
+/** Root→leaf chain of a category, following `parent` ids through `all`. */
+export function categoryChain(
+  leaf: NuvemshopCategory,
+  all: NuvemshopCategory[],
+): NuvemshopCategory[] {
+  const byId = new Map(all.map((c) => [c.id, c]));
+  const chain = [leaf];
+  for (let c = leaf; c.parent && byId.has(c.parent) && chain.length < 10; ) {
+    c = byId.get(c.parent)!;
+    chain.unshift(c);
+  }
+  return chain;
+}
+
+export const categoryPath = (chain: NuvemshopCategory[]) =>
+  `/${chain.map((c) => c.handle).join("/")}`;
+
+export function toBreadcrumbList(
+  leaf: NuvemshopCategory | undefined,
+  all: NuvemshopCategory[],
+  origin: string,
+  tail: { name: string; url: string }[] = [],
+): BreadcrumbList {
+  const chain = leaf ? categoryChain(leaf, all) : [];
+  const items = [
+    ...chain.map((_, i) => ({
+      name: chain[i].name,
+      url: `${origin}${categoryPath(chain.slice(0, i + 1))}`,
+    })),
+    ...tail,
+  ];
+  return {
+    "@type": "BreadcrumbList",
+    numberOfItems: items.length,
+    itemListElement: items.map(({ name, url }, i) => ({
+      "@type": "ListItem",
+      name,
+      item: url,
+      position: i + 1,
+    })),
+  };
+}
+
+export function toProductPage(
+  product: NuvemshopProduct,
+  opts: TransformOptions & { variantId?: string | null },
+): ProductDetailsPage {
+  const variant = pickVariant(product, opts.variantId);
+  const url = `${opts.origin}${productPath(product.handle)}`;
+  // The product only carries its category refs; the deepest one wins.
+  const refs = (product.categories ?? []).map((c) => ({ ...c, parent: c.parent ?? null }));
+  const leaf = [...refs].sort(
+    (a, b) => categoryChain(b, refs).length - categoryChain(a, refs).length,
+  )[0];
+  return {
+    "@type": "ProductDetailsPage",
+    product: toProduct(product, variant, opts),
+    breadcrumbList: toBreadcrumbList(leaf, refs, opts.origin, [{ name: product.name, url }]),
+    seo: {
+      title: product.seo_title || product.name,
+      description: product.seo_description || stripHtml(product.description).slice(0, 160),
+      canonical: url,
+    },
+  };
+}

package/src/utils/types.ts

@@ -0,0 +1,141 @@
+/**
+ * Nuvemshop (Tiendanube) Storefront API `v2026-11` response shapes.
+ *
+ * Source of truth: the OpenAPI 0.5.0 document plus real responses captured in
+ * `src/__fixtures__` — the fixtures are assigned to these types in tests, so a
+ * drift between the API and these declarations fails `tsc`.
+ *
+ * Money fields arrive as decimal strings ("189.90"). `compare_at_price` equals
+ * `price` when there's no discount; a sale shows up as `promotional_price`.
+ */
+
+export interface NuvemshopImage {
+  id: number;
+  src: string;
+  alt: string | null;
+  height?: number | null;
+  width?: number | null;
+}
+
+export interface NuvemshopInventoryLevel {
+  id: number;
+  variant_id: number;
+  location_id: string;
+  stock: number | null;
+}
+
+export interface NuvemshopVariant {
+  id: number;
+  product_id: number;
+  image_id: number | null;
+  position: number;
+  price: string | null;
+  price_without_taxes?: string | null;
+  compare_at_price: string | null;
+  promotional_price: string | null;
+  stock_management: boolean;
+  stock: number | null;
+  sku: string | null;
+  /** Aligned by index with the product's `attributes` (e.g. ["P", "Azul"] ↔ ["Tamanho", "Cor"]). */
+  values: string[];
+  barcode: string | null;
+  weight?: string | null;
+  visible?: boolean;
+  created_at?: string;
+  updated_at?: string;
+  /** Returned by the public API — never copy it into commerce types (cost price). */
+  cost?: string | null;
+  mpn?: string | null;
+  age_group?: string | null;
+  gender?: string | null;
+  width?: string | null;
+  height?: string | null;
+  depth?: string | null;
+  inventory_levels?: NuvemshopInventoryLevel[];
+}
+
+export interface NuvemshopCategoryRef {
+  id: number;
+  name: string;
+  handle: string;
+  parent: number | null;
+  google_shopping_category?: string;
+}
+
+export interface NuvemshopCustomField {
+  key: string;
+  value: string;
+}
+
+export interface NuvemshopProduct {
+  id: number;
+  name: string;
+  handle: string;
+  description?: string;
+  images?: NuvemshopImage[];
+  variants?: NuvemshopVariant[];
+  brand?: string | null;
+  /** Comma-separated. */
+  tags?: string;
+  categories?: NuvemshopCategoryRef[];
+  attributes?: string[];
+  seo_title?: string;
+  seo_description?: string;
+  published?: boolean;
+  free_shipping?: boolean;
+  video_url?: string | null;
+  custom_fields?: NuvemshopCustomField[];
+  created_at?: string;
+}
+
+export interface NuvemshopCategory {
+  id: number;
+  name: string;
+  handle: string;
+  parent?: number | null;
+  subcategories?: number[];
+  description?: string;
+  seo_title?: string;
+  seo_description?: string;
+}
+
+export interface NuvemshopPagination {
+  page: number;
+  per_page: number;
+  total: number;
+  total_pages: number;
+}
+
+export interface NuvemshopList<T> {
+  data: T[];
+  pagination: NuvemshopPagination;
+}
+
+export type NuvemshopSort = "best-selling" | "price-ascending" | "price-descending";
+
+export interface NuvemshopShippingOption {
+  code: string;
+  name: string;
+  price: string;
+  detail?: string;
+  date?: string;
+  days_until?: { start: number; end: number; working_start: number; working_end: number };
+}
+
+export interface NuvemshopShippingOptions {
+  shipping_options: NuvemshopShippingOption[];
+}
+
+export interface NuvemshopLineItem {
+  product_id: number;
+  variant_id: number;
+  quantity: number;
+}
+
+export interface NuvemshopCheckout {
+  checkout_url: string;
+}
+
+export interface NuvemshopError {
+  error: { code: string; message: string; details?: unknown };
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist"
+  },
+  "include": ["src/**/*", "src/**/*.json"]
+}