@teleporthq/teleport-plugin-next-data-source 0.43.55 → 0.43.59

package/src/transformations/ecommerce-product.ts

@@ -1,4 +1,32 @@
 import type { UIDLEcommerceCategory } from '@teleporthq/teleport-types'
+import { StorefrontTax } from '@teleporthq/teleport-shared'
+
+/**
+ * Everything the product transform needs baked in at export time, beyond the
+ * row itself. An options OBJECT rather than positional parameters: the list has
+ * already grown twice and every caller in the chain has to forward it verbatim.
+ */
+export interface EcommerceProductTransformOptions {
+  /** Category taxonomy — lives only in the UIDL, there is no DB table for it. */
+  categories?: UIDLEcommerceCategory[]
+  /**
+   * Percentage to ADD on top of every stored (NET) price for DISPLAY, or 0.
+   * Resolved by the caller through `StorefrontTax.resolveStorefrontTaxRate`.
+   */
+  storefrontTaxRate?: number
+  /**
+   * TRUE when stock levels must never gate purchasability in the storefront:
+   * the merchant disabled stock management entirely OR opted into backorders
+   * (`stockManagementConfig.allowBackorders`). Resolved by the caller through
+   * `buildProductTransformOptions`. Baked into the generated transform as
+   * `ALLOW_BACKORDERS`: `outOfStock` then always reads 'false' and every
+   * EXISTING variant combination counts as in stock — a combination that does
+   * not exist at all stays unavailable (there is nothing to backorder).
+   * Mirrors the GUI rule in
+   * `apps/gui/app/project-page/features/e-commerce/utils/product-variants.ts`.
+   */
+  allowBackorders?: boolean
+}
 
 /**
  * Flattens the nested category tree (`ecommerceSettings.categories`, baked at
@@ -47,11 +75,22 @@ const flattenCategoriesById = (
  * that UIDL components expect.
  */
 export const generateEcommerceProductTransformationCode = (
-  categories?: UIDLEcommerceCategory[]
+  options: EcommerceProductTransformOptions = {}
 ): string => {
-  const categoriesByIdJson = JSON.stringify(flattenCategoriesById(categories))
+  const categoriesByIdJson = JSON.stringify(flattenCategoriesById(options.categories))
+  const taxHelperCode = StorefrontTax.generateStorefrontTaxHelperCode(
+    options.storefrontTaxRate ?? 0
+  )
+  const allowBackordersLiteral = options.allowBackorders === true ? 'true' : 'false'
 
   return `
+${taxHelperCode}
+
+// Baked from the merchant's stock settings: TRUE when stock never blocks a
+// purchase (stock management off OR backorders allowed). Regenerating the
+// project refreshes it — do not hand-edit. See EcommerceProductTransformOptions.
+var ALLOW_BACKORDERS = ${allowBackordersLiteral}
+
 // Category taxonomy (id -> {name, slug, translations}), baked in at export
 // time — see flattenCategoriesById in ecommerce-product.ts. Empty when the
 // store has no category taxonomy, or products.category_ids simply resolves
@@ -69,6 +108,50 @@ function resolveCategoryName(categoryInfo, currentLang, mainLang) {
   return categoryInfo.name
 }
 
+// The merchant's "Show 3D model by default" toggle, as every backend may hand
+// it back: a real boolean, 1/0, 'true'/'false'/'t'/'f' strings — and NULL /
+// absent / '' as ON, because a product that has a model shows it unless the
+// merchant switched it off. MUST mirror normalizeShowModelFlag in the GUI's
+// features/e-commerce/constants/product-model.ts.
+function normalizeShowModelFlag(raw) {
+  if (raw === null || raw === undefined || raw === '') return true
+  if (typeof raw === 'boolean') return raw
+  if (typeof raw === 'number') return raw !== 0
+  if (typeof raw === 'string') {
+    var token = raw.trim().toLowerCase()
+    return !(token === 'false' || token === 'f' || token === '0' || token === 'no' || token === 'off')
+  }
+  return true
+}
+
+// The product's media gallery in display order, HERO FIRST: the model when it
+// is shown by default, otherwise the images with the model last. Each entry is
+// { kind: 'image' | 'model', src, poster, thumbnail, alt }; 'thumbnail' is what
+// a strip draws and is never empty for an entry that can appear in one. MUST
+// mirror buildProductGalleryMedia in the GUI's
+// features/e-commerce/utils/product-gallery-media.ts.
+function buildProductGalleryMedia(params) {
+  var imageItems = []
+  for (var gi = 0; gi < params.images.length; gi++) {
+    imageItems.push({
+      kind: 'image',
+      src: params.images[gi],
+      poster: '',
+      thumbnail: params.images[gi],
+      alt: params.imageAlt || params.name,
+    })
+  }
+  if (!params.modelUrl) return imageItems
+  var modelItem = {
+    kind: 'model',
+    src: params.modelUrl,
+    poster: params.modelPoster || '',
+    thumbnail: params.modelPoster || params.mainImage || params.images[0] || '',
+    alt: params.name,
+  }
+  return params.showModel === 'true' ? [modelItem].concat(imageItems) : imageItems.concat([modelItem])
+}
+
 // ============================================================
 // E-Commerce Product Transformation
 // ============================================================
@@ -294,6 +377,36 @@ function buildEcommerceProduct(record, options) {
   // Step 7: images = full resolved deduplicated array
   var images = resolvedImages
 
+  // -------------------------------------------------------
+  // 3D model (one per product; GUI: constants/product-model.ts)
+  // -------------------------------------------------------
+  // model_url / model_poster_url hold an asset id OR a raw URL like image_url.
+  // A poster the merchant never got (capture failed, plan cap) falls back to
+  // the main image so <model-viewer> always has something to paint first.
+  var modelUrl = resolveMediaUrl(record.model_url, assetMap)
+  var modelPoster = modelUrl ? resolveMediaUrl(record.model_poster_url, assetMap) || mainImage : null
+  var hasModel = modelUrl ? 'true' : 'false'
+  // STRING gate ('true'/'false') like outOfStock: whether the model replaces the
+  // main image on the card / details hero. A product whose only media is the
+  // model always shows it. An absent field must read as the IMAGE branch, so the
+  // builders gate the viewer on = 'true' and the image on != 'true'.
+  var showModel =
+    modelUrl && (normalizeShowModelFlag(record.show_model_by_default) || images.length === 0)
+      ? 'true'
+      : 'false'
+  var galleryMedia = buildProductGalleryMedia({
+    images: images,
+    mainImage: mainImage,
+    modelUrl: modelUrl,
+    modelPoster: modelPoster,
+    showModel: showModel,
+    imageAlt: imageAlt,
+    name: name,
+  })
+  // Everything that is not the hero — the details thumbnail strip. When the
+  // model is the hero the main image moves in here, so the modal stays reachable.
+  var galleryThumbnails = galleryMedia.slice(1)
+
   // Timestamps
   var rawCreatedAt = pickFirst(record.created_at, record.createdAt, record.created)
   var createdAt = normalizeTimestamp(rawCreatedAt)
@@ -311,7 +424,9 @@ function buildEcommerceProduct(record, options) {
   // string), leaving the Add to Cart button visible on out-of-stock
   // products. NULL/NaN quantity → 'false' (treated as "unlimited
   // stock", same as the upstream cart-availability rewriter).
-  var outOfStock = (quantity !== null && !isNaN(quantity) && quantity <= 0) ? 'true' : 'false'
+  // With ALLOW_BACKORDERS the merchant sells past zero (or does not track
+  // stock at all), so nothing is ever presented as out of stock.
+  var outOfStock = (!ALLOW_BACKORDERS && quantity !== null && !isNaN(quantity) && quantity <= 0) ? 'true' : 'false'
 
   // Per-value availability + default-selection flags, derived from the
   // purchasable combinations, so the storefront picker renders its
@@ -349,6 +464,32 @@ function buildEcommerceProduct(record, options) {
   var hasInStockCombination = !!(firstVariant && isVariantInStock(firstVariant))
   var defaultVariantId = hasInStockCombination ? firstVariant.id : ''
   var defaultVariantPrice = firstVariant ? formatVariantPrice(firstVariant.price, price) : ''
+  // Gross (tax-inclusive) counterparts of the three price fields the STOREFRONT
+  // renders. \`price\` / \`defaultVariantPrice\` / \`variantsJson\` deliberately stay
+  // NET: the same transform feeds the merchant's admin panel, and every write
+  // path (add-to-cart, checkout, the invoice route) re-reads the raw row and
+  // must keep seeing the price the merchant typed. Only these three are safe to
+  // gross, because nothing writes them back.
+  //
+  // MUST mirror packages/renderer/src/utils/ecommerce-products.ts.
+  var displayPrice = grossMoney(price)
+  var defaultVariantDisplayPrice = firstVariant
+    ? grossMoney(formatVariantPrice(firstVariant.price, price))
+    : ''
+  var variantsDisplay = []
+  for (var dv = 0; dv < variants.length; dv++) {
+    var dvRow = variants[dv]
+    variantsDisplay.push({
+      id: dvRow.id,
+      options: dvRow.options,
+      // A null variant price INHERITS the product price, so gross the RESOLVED
+      // value — otherwise an inheriting combination would fall back to the net
+      // base price in the picker while an overriding one showed gross.
+      price: applyStorefrontTax(dvRow.price == null ? price : dvRow.price),
+      quantity: dvRow.quantity,
+      image_url: dvRow.image_url,
+    })
+  }
   // Can this product be added to the cart at all, before the shopper touches the
   // picker? A STRING, same convention as outOfStock/requiresVariantSelection.
   //
@@ -373,6 +514,7 @@ function buildEcommerceProduct(record, options) {
   // combinations + axes from these JSON strings via getAttribute.
   var variantOptionsJson = safeStringifyJson(variantOptions)
   var variantsJson = safeStringifyJson(variants)
+  var variantsDisplayJson = safeStringifyJson(variantsDisplay)
 
   return {
     id: id,
@@ -409,6 +551,12 @@ function buildEcommerceProduct(record, options) {
     image_url: mainImage,
     galleryImages: galleryImages,
     images: images,
+    modelUrl: modelUrl,
+    modelPoster: modelPoster,
+    hasModel: hasModel,
+    showModel: showModel,
+    galleryMedia: galleryMedia,
+    galleryThumbnails: galleryThumbnails,
     createdAt: createdAt,
     updatedAt: updatedAt,
     created: created,
@@ -418,16 +566,24 @@ function buildEcommerceProduct(record, options) {
     variants: variants,
     variantOptionsJson: variantOptionsJson,
     variantsJson: variantsJson,
+    variantsDisplayJson: variantsDisplayJson,
     defaultVariantId: defaultVariantId,
     defaultVariantPrice: defaultVariantPrice,
+    displayPrice: displayPrice,
+    defaultVariantDisplayPrice: defaultVariantDisplayPrice,
     hasPurchasableVariant: hasPurchasableVariant,
   }
 }
 
 // --- Variant availability helpers (mirror packages/renderer ecommerce-products) ---
-// A variant is in stock when its quantity is null (unlimited) or > 0.
+// A variant is in stock when its quantity is null (unlimited) or > 0. With
+// ALLOW_BACKORDERS every EXISTING combination is purchasable regardless of its
+// quantity — but a missing combination (null) is still not in stock: there is
+// no variant row to backorder.
 function isVariantInStock(v) {
-  return !v ? false : v.quantity == null || v.quantity > 0
+  if (!v) return false
+  if (ALLOW_BACKORDERS) return true
+  return v.quantity == null || v.quantity > 0
 }
 function variantCoversAllAxes(v, axisKeys) {
   if (!v || !v.options) return false

package/src/transformations/index.ts

@@ -1,7 +1,46 @@
-import type { UIDLEcommerceCategory } from '@teleporthq/teleport-types'
+import type { GeneratorOptions } from '@teleporthq/teleport-types'
+import { StorefrontTax } from '@teleporthq/teleport-shared'
 import { generateSharedTransformationCode } from './shared-utils'
 import { generateBlogPostTransformationCode } from './blog-post'
-import { generateEcommerceProductTransformationCode } from './ecommerce-product'
+import {
+  generateEcommerceProductTransformationCode,
+  type EcommerceProductTransformOptions,
+} from './ecommerce-product'
+
+export type { EcommerceProductTransformOptions }
+
+/**
+ * Stock never gates purchasability when the merchant disabled stock management
+ * entirely or opted into backorders. Mirrors the GUI rule in
+ * `apps/gui/app/project-page/features/e-commerce/utils/product-variants.ts`
+ * (`isVariantInStock`). A project without e-commerce settings keeps the
+ * strict default (stock gates apply) — same behaviour as before the flag.
+ */
+const resolveAllowBackorders = (
+  settings: GeneratorOptions['ecommerceSettings'] | undefined
+): boolean => {
+  if (!settings) {
+    return false
+  }
+  return !settings.stockManagement || settings.stockManagementConfig?.allowBackorders === true
+}
+
+/**
+ * Collects everything the product transform bakes in from the generator
+ * options, in ONE place so every fetcher-emitting call site stays in step.
+ *
+ * `storefrontTaxRate` is what turns a NET catalogue price into the price the
+ * shopper is quoted; `resolveStorefrontTaxRate` returns 0 (a no-op) for
+ * tax-inclusive or untaxed stores. `allowBackorders` is the effective
+ * "stock never blocks a purchase" flag — see `resolveAllowBackorders`.
+ */
+export const buildProductTransformOptions = (
+  options: Pick<GeneratorOptions, 'ecommerceSettings' | 'invoiceSettings'>
+): EcommerceProductTransformOptions => ({
+  categories: options.ecommerceSettings?.categories,
+  storefrontTaxRate: StorefrontTax.resolveStorefrontTaxRate(options.invoiceSettings),
+  allowBackorders: resolveAllowBackorders(options.ecommerceSettings),
+})
 
 export type TransformationType = 'blog-post' | 'ecommerce-product' | null
 
@@ -51,7 +90,7 @@ export const detectTransformationType = (tableName: string): TransformationType
  */
 export const getTransformationCode = (
   tableName: string,
-  categories?: UIDLEcommerceCategory[]
+  options: EcommerceProductTransformOptions = {}
 ): string => {
   const type = detectTransformationType(tableName)
   if (!type) {
@@ -64,7 +103,7 @@ export const getTransformationCode = (
     case 'blog-post':
       return shared + generateBlogPostTransformationCode()
     case 'ecommerce-product':
-      return shared + generateEcommerceProductTransformationCode(categories)
+      return shared + generateEcommerceProductTransformationCode(options)
     default:
       return ''
   }

package/src/transformations/shared-utils.ts

@@ -234,6 +234,20 @@ function resolveAssetUrl(value, assetMap) {
   return value
 }
 
+// Whether an asset-id resolution produced a real URL. resolveAssetUrl returns
+// an UNKNOWN id verbatim (asset deleted, teleport_assets not mirrored yet) and
+// a bare 'TQ_...' must never reach a <model-viewer src> or a poster.
+function isResolvedMediaUrl(value) {
+  return typeof value === 'string' && (isUrl(value) || value.charAt(0) === '/')
+}
+
+// resolveAssetUrl for MEDIA that has no safe fallback: a value that did not
+// resolve to a URL is reported as absent (null) instead of passed through.
+function resolveMediaUrl(value, assetMap) {
+  var resolved = resolveAssetUrl(value, assetMap)
+  return isResolvedMediaUrl(resolved) ? resolved : null
+}
+
 function resolveAssetUrls(values, assetMap) {
   if (!Array.isArray(values)) return []
   return values

package/src/utils.ts

@@ -7,12 +7,12 @@ import {
   UIDLDataSource,
   DataSourceType,
   ChunkType,
-  UIDLEcommerceCategory,
 } from '@teleporthq/teleport-types'
 import * as types from '@babel/types'
 import { ASTUtils } from '@teleporthq/teleport-plugin-common'
 import { StringUtils } from '@teleporthq/teleport-shared'
 import { generateDataSourceFetcherWithCore } from './data-source-fetchers'
+import type { EcommerceProductTransformOptions } from './transformations'
 import { DATA_SOURCE_ISR_REVALIDATE_SECONDS } from './isr'
 
 const VALID_DATA_SOURCE_TYPES: DataSourceType[] = [
@@ -192,7 +192,7 @@ export const extractDataSourceIntoNextAPIFolder = (
   dataSources: Record<string, UIDLDataSource>,
   componentChunk: ChunkDefinition,
   extractedResources: GeneratorOptions['extractedResources'],
-  categories?: UIDLEcommerceCategory[]
+  transformOptions: EcommerceProductTransformOptions = {}
 ) => {
   try {
     // Validate node content structure
@@ -446,7 +446,12 @@ export default dataSourceModule.handler
     // Generate fetcher code for API route (exports just the handler)
     let fetcherCode: string
     try {
-      fetcherCode = generateDataSourceFetcherWithCore(dataSource, tableName || '', true, categories)
+      fetcherCode = generateDataSourceFetcherWithCore(
+        dataSource,
+        tableName || '',
+        true,
+        transformOptions
+      )
     } catch (error) {
       return
     }
@@ -896,7 +901,7 @@ export const extractDataSourceIntoGetStaticProps = (
   dependencies: Record<string, any>,
   dynamicRouteAttr?: string,
   folderPath?: string[],
-  categories?: UIDLEcommerceCategory[]
+  transformOptions: EcommerceProductTransformOptions = {}
 ): { success: boolean; chunk?: any } => {
   try {
     // Validate node content
@@ -1224,7 +1229,7 @@ export const extractDataSourceIntoGetStaticProps = (
         dataSource,
         tableName || '',
         false,
-        categories
+        transformOptions
       )
     } catch (error) {
       // tslint:disable-next-line:no-console