@reactionary/magento 0.0.1 → 0.10.19

package/src/utils/magento-product.d.ts

@@ -0,0 +1,36 @@
+import { type Image, type ProductSearchResultItem, type ProductSearchResultItemVariant } from '@reactionary/core';
+import type { MagentoConfiguration } from '../schema/configuration.schema.js';
+import type { MagentoProduct } from '../schema/magento.types.js';
+export declare function getCustomAttribute(product: MagentoProduct, code: string): string | undefined;
+/**
+ * The `external_id` carries the identifier the surrounding commerce landscape
+ * uses. Depending on how it was added to Magento it surfaces either as an
+ * extension attribute or as a plain EAV (custom) attribute, so both are checked.
+ */
+export declare function getProductExternalId(product: MagentoProduct): string | undefined;
+export declare function getProductKey(product: MagentoProduct): string;
+/**
+ * `original_dam_reference` holds the PIM-sorted DAM imagery. Order is
+ * significant: the first entry is the primary image.
+ *
+ * Expected attribute value:
+ * ```json
+ * {
+ *   "images": [
+ *     {
+ *       "url": "https://dam.example/a.jpg",
+ *       "altText": "Front view",
+ *       "dimensions": { "width": 400, "height": 600 }
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+export declare function parseDamImages(raw: string | undefined, fallbackAltText: string): Image[];
+export declare function buildMagentoImageUrl(config: MagentoConfiguration, file: string): string;
+export declare function buildProductSearchResultItemVariant(config: MagentoConfiguration, variant: MagentoProduct, product: MagentoProduct): ProductSearchResultItemVariant;
+/**
+ * Builds the search-result representation used by the association and
+ * recommendation capabilities, which key products by their `external_id`.
+ */
+export declare function buildProductSearchResultItem(config: MagentoConfiguration, product: MagentoProduct): ProductSearchResultItem;

package/src/utils/magento-review.d.ts

@@ -0,0 +1,20 @@
+import type { MagentoProductReview } from '../schema/magento.types.js';
+/**
+ * Magento expresses ratings as a percentage (0-100) — `rating_summary` on the
+ * product and `average_rating` on the individual review — while reactionary
+ * normalizes everything onto a 0-5 star scale.
+ */
+export declare function ratingPercentToStars(percent: number | null | undefined): number;
+/**
+ * Magento emits timestamps as MySQL datetimes in UTC ("2024-05-04 12:00:00"),
+ * whereas the reactionary models expose ISO8601. Unparseable values are passed
+ * through rather than replaced with a fabricated date.
+ */
+export declare function toIsoTimestamp(value: string): string;
+/**
+ * Magento's GraphQL review payload carries no identifier of its own, so the key
+ * is derived from the fields that together identify a review. Deriving it
+ * deterministically (rather than from the position in the page) keeps the key
+ * stable across pages, requests and cache entries.
+ */
+export declare function buildProductReviewKey(sku: string, review: MagentoProductReview): string;

package/utils/magento-product-lookup.js

@@ -0,0 +1,76 @@
+function singleFilter(field, value, conditionType = "eq") {
+  const params = new URLSearchParams();
+  params.set("searchCriteria[filterGroups][0][filters][0][field]", field);
+  params.set("searchCriteria[filterGroups][0][filters][0][value]", value);
+  params.set(
+    "searchCriteria[filterGroups][0][filters][0][condition_type]",
+    conditionType
+  );
+  return params;
+}
+async function resolveProductSku(magentoApi, key) {
+  const byExternalId = singleFilter("external_id", key);
+  byExternalId.set("searchCriteria[pageSize]", "1");
+  try {
+    const result = await magentoApi.searchProducts(byExternalId);
+    const product = result.items?.[0];
+    if (product?.sku) {
+      return product.sku;
+    }
+  } catch {
+  }
+  if (/^\d+$/.test(key)) {
+    const byEntityId = singleFilter("entity_id", key);
+    byEntityId.set("searchCriteria[pageSize]", "1");
+    try {
+      const result = await magentoApi.searchProducts(byEntityId);
+      const product = result.items?.[0];
+      if (product?.sku) {
+        return product.sku;
+      }
+    } catch {
+      return null;
+    }
+  }
+  return key;
+}
+async function fetchProductsBySkus(magentoApi, skus) {
+  if (skus.length === 0) {
+    return [];
+  }
+  const params = singleFilter("sku", skus.join(","), "in");
+  params.set("searchCriteria[pageSize]", String(skus.length));
+  const result = await magentoApi.searchProducts(params);
+  const found = result.items ?? [];
+  const bySku = new Map(found.map((product) => [product.sku, product]));
+  return skus.map((sku) => bySku.get(sku)).filter((product) => product !== void 0);
+}
+async function fetchProductsInCategory(magentoApi, categoryId, limit) {
+  const params = singleFilter("category_id", categoryId);
+  params.set("searchCriteria[pageSize]", String(limit));
+  params.set("searchCriteria[currentPage]", "1");
+  const result = await magentoApi.searchProducts(params);
+  return result.items ?? [];
+}
+async function findCategoryByName(magentoApi, collectionName) {
+  const client = await magentoApi.getClient();
+  for (const field of ["external_id", "url_key", "name"]) {
+    const params = singleFilter(field, collectionName);
+    params.set("searchCriteria[pageSize]", "1");
+    try {
+      const response = await client.store.category.list(params);
+      const category = response.items?.[0];
+      if (category) {
+        return category;
+      }
+    } catch {
+    }
+  }
+  return null;
+}
+export {
+  fetchProductsBySkus,
+  fetchProductsInCategory,
+  findCategoryByName,
+  resolveProductSku
+};

package/utils/magento-product.js

@@ -0,0 +1,110 @@
+import {
+  ImageSchema,
+  ProductSearchResultItemVariantSchema,
+  ProductVariantIdentifierSchema
+} from "@reactionary/core";
+import createDebug from "debug";
+const debug = createDebug("reactionary:magento:product-media");
+function getCustomAttribute(product, code) {
+  if (!product.custom_attributes) return void 0;
+  const found = product.custom_attributes.find((a) => a.attribute_code === code);
+  if (found?.value === null || found?.value === void 0) return void 0;
+  return String(found.value);
+}
+function getProductExternalId(product) {
+  const fromExtension = product.extension_attributes?.["external_id"];
+  if (typeof fromExtension === "string" || typeof fromExtension === "number") {
+    return String(fromExtension);
+  }
+  return getCustomAttribute(product, "external_id");
+}
+function getProductKey(product) {
+  return getProductExternalId(product) ?? (product.id !== void 0 ? String(product.id) : product.sku);
+}
+function parseDamImages(raw, fallbackAltText) {
+  const trimmed = (raw ?? "").trim();
+  if (trimmed.length === 0) {
+    return [];
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    debug("original_dam_reference is not valid JSON: %s", trimmed);
+    return [];
+  }
+  if (!isRecord(parsed) || !Array.isArray(parsed["images"])) {
+    debug('original_dam_reference has no "images" array: %s', trimmed);
+    return [];
+  }
+  return parsed["images"].map((entry) => parseDamImage(entry, fallbackAltText)).filter((image) => image !== null);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toPixelSize(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function parseDamImage(entry, fallbackAltText) {
+  if (!isRecord(entry)) {
+    return null;
+  }
+  const url = entry["url"];
+  if (typeof url !== "string" || url.trim().length === 0) {
+    return null;
+  }
+  const altText = entry["altText"];
+  const dimensions = isRecord(entry["dimensions"]) ? entry["dimensions"] : void 0;
+  return ImageSchema.parse({
+    sourceUrl: url.trim(),
+    altText: typeof altText === "string" && altText.trim().length > 0 ? altText.trim() : fallbackAltText,
+    width: toPixelSize(dimensions?.["width"]),
+    height: toPixelSize(dimensions?.["height"])
+  });
+}
+function normalizeBaseUrl(baseUrl) {
+  return baseUrl.replace(/\/+$/, "");
+}
+function buildMagentoImageUrl(config, file) {
+  const mediaUrl = config.mediaUrl;
+  if (mediaUrl) {
+    return `${mediaUrl.replace(/\/+$/, "")}${file.startsWith("/") ? "" : "/"}${file}`;
+  }
+  const storeBase = normalizeBaseUrl(config.baseUrl);
+  return `${storeBase}/media/catalog/product${file.startsWith("/") ? "" : "/"}${file}`;
+}
+function buildProductSearchResultItemVariant(config, variant, product) {
+  const media = product.media_gallery_entries;
+  const firstImage = media && media.length > 0 ? media[0].file : null;
+  const img = ImageSchema.parse({
+    sourceUrl: firstImage ? buildMagentoImageUrl(config, firstImage) : "",
+    altText: product.name || void 0
+  });
+  return ProductSearchResultItemVariantSchema.parse({
+    variant: ProductVariantIdentifierSchema.parse({
+      sku: variant.sku
+    }),
+    image: img
+  });
+}
+function buildProductSearchResultItem(config, product) {
+  const variants = [];
+  if (product.sku) {
+    variants.push(buildProductSearchResultItemVariant(config, product, product));
+  }
+  return {
+    identifier: { key: getProductKey(product) },
+    name: product.name || product.sku,
+    slug: getCustomAttribute(product, "url_key") ?? getCustomAttribute(product, "url_path") ?? "",
+    variants
+  };
+}
+export {
+  buildMagentoImageUrl,
+  buildProductSearchResultItem,
+  buildProductSearchResultItemVariant,
+  getCustomAttribute,
+  getProductExternalId,
+  getProductKey,
+  parseDamImages
+};

package/utils/magento-review.js

@@ -0,0 +1,34 @@
+function ratingPercentToStars(percent) {
+  if (percent === null || percent === void 0 || Number.isNaN(percent)) {
+    return 0;
+  }
+  const stars = percent / 100 * 5;
+  return Math.min(5, Math.max(0, Math.round(stars * 100) / 100));
+}
+function toIsoTimestamp(value) {
+  const normalized = value.includes("T") ? value : `${value.replace(" ", "T")}Z`;
+  const parsed = new Date(normalized);
+  return Number.isNaN(parsed.getTime()) ? value : parsed.toISOString();
+}
+function hashToken(value) {
+  let hash = 5381;
+  for (let i = 0; i < value.length; i++) {
+    hash = (hash << 5) + hash + value.charCodeAt(i) | 0;
+  }
+  return (hash >>> 0).toString(36);
+}
+function buildProductReviewKey(sku, review) {
+  const source = [
+    sku,
+    review.created_at,
+    review.nickname,
+    review.summary,
+    review.text
+  ].join("|");
+  return `${sku}-${hashToken(source)}`;
+}
+export {
+  buildProductReviewKey,
+  ratingPercentToStars,
+  toIsoTimestamp
+};