@manta-eu/react 0.1.9 → 0.2.0

package/src/lib/rdf/index.ts

@@ -0,0 +1,560 @@
+import { expandPrefix } from "@manta-eu/client/shared/rdf-namespaces";
+import type { JsonLdGraphDocument, JsonLdNode } from "@manta-eu/client/types/jsonld";
+import { getStringValue, getNumberValue, getRefId, getNodeTypes } from "@manta-eu/client/types/jsonld";
+import { isPresent } from "@manta-eu/lib/present";
+import { isNotNil } from "ramda";
+import type {
+  CampaignChannelMixData,
+  CampaignGridData,
+  CampaignPerformanceSummaryData,
+  DailyPerformanceData,
+  KpiSnapshot,
+  KpiValues,
+  MetaDailyInsightsData,
+  Product,
+  ProductProfitabilityData,
+  ProductSalesRankingData,
+  ProductVariant,
+  ProductVariantsData,
+  RoasBenchmarkData,
+} from "./types";
+
+export * from "@manta-eu/client/shared/rdf-namespaces";
+
+export function getString(node: JsonLdNode, predicate: string): string | null {
+  const expandedPredicate = expandPrefix(predicate);
+  return getStringValue(node, expandedPredicate) || getStringValue(node, predicate);
+}
+
+function getNumber(node: JsonLdNode, predicate: string): number | null {
+  const expandedPredicate = expandPrefix(predicate);
+  return getNumberValue(node, expandedPredicate) ?? getNumberValue(node, predicate);
+}
+
+function getRef(node: JsonLdNode, predicate: string): string | null {
+  const expandedPredicate = expandPrefix(predicate);
+  return getRefId(node, expandedPredicate) || getRefId(node, predicate);
+}
+
+function findNodesByType(nodes: JsonLdNode[], rdfType: string): JsonLdNode[] {
+  const typeUri = expandPrefix(rdfType);
+  return nodes.filter((node) => {
+    const nodeTypes = getNodeTypes(node).map(expandPrefix);
+    return nodeTypes.includes(typeUri);
+  });
+}
+
+function findNodeById(nodes: JsonLdNode[], id: string): JsonLdNode | undefined {
+  return nodes.find((node) => node["@id"] === id);
+}
+
+function parseTags(tagString: string | null): string[] | null {
+  if (!tagString) return null;
+
+  try {
+    const parsed = JSON.parse(tagString);
+    return Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function getProductName(productNode: JsonLdNode | undefined): string | null {
+  if (!productNode) return null;
+  return (
+    getString(productNode, "rdfs:label") || getString(productNode, ":title") || getString(productNode, "schema:name")
+  );
+}
+
+function getVariantName(variantNode: JsonLdNode | undefined): string | null {
+  if (!variantNode) return null;
+  return getString(variantNode, "schema:name") || getString(variantNode, ":title");
+}
+
+function getCampaignName(campaignNode: JsonLdNode | undefined): string | null {
+  if (!campaignNode) return null;
+  return (
+    getString(campaignNode, "schema:name") || getString(campaignNode, "rdfs:label") || getString(campaignNode, ":name")
+  );
+}
+
+export function readCurrency(node: JsonLdNode | undefined): string | null {
+  return node ? getString(node, "schema:currency") : null;
+}
+
+export function sharedCurrency(currencies: Array<string | null>): string | null {
+  const distinct = new Set(currencies);
+  return distinct.size === 1 ? (currencies[0] ?? null) : null;
+}
+
+export function extractProduct(jsonLd: JsonLdGraphDocument): Product | null {
+  const nodes = jsonLd["@graph"];
+
+  const productNodes = findNodesByType(nodes, ":Product");
+  const productNode = productNodes[0];
+
+  if (!productNode) {
+    return null;
+  }
+
+  const uri = productNode["@id"];
+
+  if (!uri) return null;
+
+  const name = getProductName(productNode);
+
+  if (!name) {
+    return null;
+  }
+
+  const tagsRaw = getString(productNode, "shopify:tags");
+
+  return {
+    uri,
+    name,
+    vendor: getString(productNode, ":vendor"),
+    url: getString(productNode, "schema:url"),
+    tags: parseTags(tagsRaw),
+    availability: getString(productNode, ":availability"),
+    quantity: getNumber(productNode, ":quantity"),
+  } as Product;
+}
+
+export function extractProductVariant(jsonLd: JsonLdGraphDocument, productUri: string): ProductVariant | null {
+  const nodes = jsonLd["@graph"];
+  const variantNodes = findNodesByType(nodes, ":ProductVariant");
+
+  for (const variantNode of variantNodes) {
+    const linkedProductUri = getRef(variantNode, ":product");
+    if (linkedProductUri === productUri) {
+      const uri = variantNode["@id"];
+      if (!uri) continue;
+
+      return {
+        uri,
+        currency: readCurrency(variantNode),
+        price: getNumber(variantNode, ":price"),
+        cost: getNumber(variantNode, ":cost"),
+        title: getVariantName(variantNode),
+      } as ProductVariant;
+    }
+  }
+
+  return null;
+}
+
+function kpiValues(node: JsonLdNode): KpiValues {
+  return {
+    spend: getNumber(node, ":totalSpend"),
+    revenue: getNumber(node, ":totalRevenue"),
+    purchases: getNumber(node, ":totalPurchases"),
+    roas: getNumber(node, ":roas"),
+    cpa: getNumber(node, ":cpa"),
+    aov: getNumber(node, ":aov"),
+  };
+}
+
+export function extractKpiSnapshots(jsonLd: JsonLdGraphDocument): KpiSnapshot[] | null {
+  const nodes = findNodesByType(jsonLd["@graph"], ":KPISnapshot");
+  const inWindow = (window: string) => nodes.filter((node) => getString(node, ":window") === window);
+  const previous = inWindow("prev-30d");
+
+  const snapshots = inWindow("last-30d")
+    .map((node) => {
+      const currency = readCurrency(node);
+      if (!currency) return null;
+      const previousNode = previous.find((prev) => readCurrency(prev) === currency);
+      return {
+        currency,
+        startDate: getString(node, "schema:startDate"),
+        endDate: getString(node, "schema:endDate"),
+        current: kpiValues(node),
+        previous: previousNode ? kpiValues(previousNode) : null,
+      };
+    })
+    .filter(isNotNil)
+    .sort((a, b) => a.currency.localeCompare(b.currency));
+
+  return isPresent(snapshots) ? snapshots : null;
+}
+
+export function extractDailyPerformance(jsonLd: JsonLdGraphDocument): DailyPerformanceData | null {
+  const nodes = jsonLd["@graph"];
+
+  const snapshotNodes = findNodesByType(nodes, ":BlendedPerformanceDaily");
+
+  if (!isPresent(snapshotNodes)) {
+    return null;
+  }
+
+  const days = snapshotNodes
+    .map((node) => {
+      const date = getString(node, ":date");
+      const revenue = getNumber(node, ":shopifyRevenueUsd");
+      const spend = getNumber(node, ":metaSpendUsd");
+      const orders = getNumber(node, ":shopifyOrders");
+
+      if (!date || revenue === null || spend === null || orders === null) {
+        return null;
+      }
+
+      return { date, revenue, spend, orders };
+    })
+    .filter(isNotNil)
+    .sort((a, b) => a.date.localeCompare(b.date));
+
+  if (!isPresent(days)) {
+    return null;
+  }
+
+  // The daily blend is kept in USD: its predicates are the converted :…Usd ones.
+  return { currency: "USD", days };
+}
+
+export function extractProductProfitability(jsonLd: JsonLdGraphDocument): ProductProfitabilityData | null {
+  const nodes = jsonLd["@graph"];
+
+  const profitabilityNodes = findNodesByType(nodes, ":ProductProfitability");
+
+  if (!isPresent(profitabilityNodes)) {
+    return null;
+  }
+
+  const products = profitabilityNodes
+    .map((node) => {
+      const uri = node["@id"];
+      if (!uri) return null;
+
+      // Try to get the inlined product name first (from the new inlining rule)
+      let productName = getString(node, ":productName");
+
+      // Fallback to looking up the product entity if inlined name not available
+      if (!productName) {
+        const productUri = getRef(node, ":product");
+        const productNode = productUri ? findNodeById(nodes, productUri) : undefined;
+        productName = getProductName(productNode);
+      }
+
+      return {
+        uri,
+        productName,
+        revenueUsd: getNumber(node, ":revenueUsd") || 0,
+        cogsUsd: getNumber(node, ":cogsUsd") || 0,
+        grossProfitUsd: getNumber(node, ":grossProfitUsd") || 0,
+        grossMarginPct: getNumber(node, ":grossMarginPct") || 0,
+        profitPerUnitUsd: getNumber(node, ":profitPerUnitUsd"),
+        marginEfficiencyScore: getNumber(node, ":marginEfficiencyScore"),
+      };
+    })
+    .filter(isNotNil)
+    .filter((p) => p.revenueUsd > 0);
+
+  return isPresent(products) ? ({ products } as ProductProfitabilityData) : null;
+}
+
+export function extractCampaignPerformanceSummary(jsonLd: JsonLdGraphDocument): CampaignPerformanceSummaryData | null {
+  const nodes = jsonLd["@graph"];
+
+  const summaryNodes = findNodesByType(nodes, ":CampaignPerformanceSummary");
+
+  if (!isPresent(summaryNodes)) {
+    return null;
+  }
+
+  const campaigns = summaryNodes
+    .map((node) => {
+      const uri = node["@id"];
+      if (!uri) return null;
+
+      const campaignUri = getRef(node, ":campaign");
+      const campaignNode = campaignUri ? findNodeById(nodes, campaignUri) : undefined;
+      const campaignName = getCampaignName(campaignNode);
+      const status = campaignNode ? getString(campaignNode, ":status") : null;
+
+      return {
+        uri,
+        campaignName,
+        status,
+        spendUsd: getNumber(node, ":spendUsd") || 0,
+        revenueUsd: getNumber(node, ":revenueUsd") || 0,
+        roas: getNumber(node, ":roas") || 0,
+        impressions: getNumber(node, ":impressions"),
+        clicks: getNumber(node, ":clicks"),
+        ctr: getNumber(node, ":ctr"),
+        conversions: getNumber(node, ":conversions"),
+        costPerConversion: getNumber(node, ":costPerConversion"),
+      };
+    })
+    .filter(isNotNil)
+    .filter((c) => c.spendUsd > 0 || c.revenueUsd > 0);
+
+  return isPresent(campaigns) ? ({ campaigns } as CampaignPerformanceSummaryData) : null;
+}
+
+export function extractProductSalesRanking(jsonLd: JsonLdGraphDocument): ProductSalesRankingData | null {
+  const nodes = jsonLd["@graph"];
+
+  const rankingNodes = findNodesByType(nodes, ":ProductSalesRanking");
+
+  if (!isPresent(rankingNodes)) {
+    return null;
+  }
+
+  const products = rankingNodes
+    .map((node) => {
+      const uri = node["@id"];
+      const rank = getNumber(node, ":rank");
+
+      if (!uri || rank === null) {
+        return null;
+      }
+
+      // Try to get the inlined product name first (from the new inlining rule)
+      let productName = getString(node, ":productName");
+
+      // Fallback to looking up the product entity if inlined name not available
+      if (!productName) {
+        const productUri = getRef(node, ":product");
+        const productNode = productUri ? findNodeById(nodes, productUri) : undefined;
+        productName = getProductName(productNode);
+      }
+
+      return {
+        uri,
+        rank,
+        productName,
+        totalRevenueUsd: getNumber(node, ":totalRevenueUsd") || 0,
+        orderCount: getNumber(node, ":orderCount") || 0,
+        avgOrderValueUsd: getNumber(node, ":avgOrderValueUsd"),
+        revenueSharePct: getNumber(node, ":revenueSharePct"),
+      };
+    })
+    .filter(isNotNil)
+    .filter((p) => p.totalRevenueUsd > 0)
+    .sort((a, b) => {
+      // Primary sort: by rank
+      if (a.rank !== b.rank) {
+        return a.rank - b.rank;
+      }
+      // Secondary sort: by revenue descending (in case ranks are the same)
+      return b.totalRevenueUsd - a.totalRevenueUsd;
+    })
+    .map((product, index) => ({
+      ...product,
+      rank: index + 1, // Re-assign ranks to ensure sequential numbering
+    }));
+
+  return isPresent(products) ? { products } : null;
+}
+
+export function extractRoasBenchmark(jsonLd: JsonLdGraphDocument): RoasBenchmarkData | null {
+  const nodes = jsonLd["@graph"];
+
+  const benchmarkNodes = findNodesByType(nodes, ":CampaignChannelBenchmark");
+
+  if (!isPresent(benchmarkNodes)) {
+    return null;
+  }
+
+  const benchmarks = benchmarkNodes
+    .map((node) => {
+      const uri = node["@id"];
+      if (!uri) return null;
+
+      return {
+        uri,
+        campaignChannel: getString(node, ":campaignChannel"),
+        avgRoas: getNumber(node, ":avgRoas"),
+        medianRoas: getNumber(node, ":medianRoas"),
+        stddevRoas: getNumber(node, ":stddevRoas"),
+        percentile25Roas: getNumber(node, ":percentile25Roas"),
+        percentile75Roas: getNumber(node, ":percentile75Roas"),
+        avgBlendedRoas: getNumber(node, ":avgBlendedRoas"),
+        medianBlendedRoas: getNumber(node, ":medianBlendedRoas"),
+      };
+    })
+    .filter(isNotNil);
+
+  return isPresent(benchmarks) ? { benchmarks } : null;
+}
+
+export function extractMetaDailyInsights(jsonLd: JsonLdGraphDocument): MetaDailyInsightsData | null {
+  const nodes = jsonLd["@graph"];
+
+  const insightNodes = findNodesByType(nodes, "meta:CampaignDailyCumulativeInsights");
+
+  if (!isPresent(insightNodes)) {
+    return null;
+  }
+
+  const firstInsight = insightNodes[0];
+  if (!firstInsight) {
+    return null;
+  }
+  const campaignUri = getRef(firstInsight, "meta:belongsToCampaign") || "";
+  const campaignNode = campaignUri ? findNodeById(nodes, campaignUri) : undefined;
+  const campaignName = getCampaignName(campaignNode);
+
+  const days = insightNodes
+    .map((node) => {
+      const date = getString(node, "schema:dateCreated");
+      const spend = getNumber(node, "meta:spend");
+      const revenue = getNumber(node, "meta:grossRevenue");
+      const roas = getNumber(node, "meta:reportedRoas");
+      const impressions = getNumber(node, "meta:impressions");
+      const clicks = getNumber(node, "meta:clicks");
+      const ctr = getNumber(node, "meta:ctr");
+      const purchases = getNumber(node, "meta:reportedPurchases");
+
+      if (!date || spend === null || revenue === null || roas === null) {
+        return null;
+      }
+
+      return { date, spend, revenue, roas, impressions, clicks, ctr, purchases };
+    })
+    .filter(isNotNil)
+    .sort((a, b) => a.date.localeCompare(b.date));
+
+  if (!isPresent(days)) {
+    return null;
+  }
+
+  const currency = readCurrency(campaignNode) ?? readCurrency(firstInsight);
+
+  return { campaignUri, campaignName, currency, days };
+}
+
+export function extractCampaignChannelMix(jsonLd: JsonLdGraphDocument): CampaignChannelMixData | null {
+  const nodes = jsonLd["@graph"];
+
+  const campaignNodes = findNodesByType(nodes, "meta:Campaign");
+
+  if (!isPresent(campaignNodes)) {
+    return null;
+  }
+
+  const channelMap = new Map<
+    string,
+    { count: number; spend: number; revenue: number; currencies: Array<string | null> }
+  >();
+
+  campaignNodes.forEach((node) => {
+    const channel = getString(node, "meta:campaignChannel") || "Meta";
+    const spend = getNumber(node, "meta:totalSpend") || 0;
+    const revenue = getNumber(node, "meta:totalRevenue") || 0;
+
+    const existing = channelMap.get(channel) || { count: 0, spend: 0, revenue: 0, currencies: [] };
+    channelMap.set(channel, {
+      count: existing.count + 1,
+      spend: existing.spend + spend,
+      revenue: existing.revenue + revenue,
+      currencies: [...existing.currencies, readCurrency(node)],
+    });
+  });
+
+  const totalCampaigns = campaignNodes.length;
+  const channels = Array.from(channelMap.entries()).map(([channel, data]) => ({
+    channel,
+    currency: sharedCurrency(data.currencies),
+    campaignCount: data.count,
+    totalSpend: data.spend,
+    totalRevenue: data.revenue,
+    percentage: (data.count / totalCampaigns) * 100,
+  }));
+
+  return isPresent(channels) ? { currency: sharedCurrency(campaignNodes.map(readCurrency)), channels } : null;
+}
+
+export function extractProductVariants(jsonLd: JsonLdGraphDocument): ProductVariantsData | null {
+  const nodes = jsonLd["@graph"];
+
+  const variantNodes = findNodesByType(nodes, ":ProductVariant");
+
+  if (!isPresent(variantNodes)) {
+    return null;
+  }
+
+  const variants = variantNodes
+    .map((node) => {
+      const uri = node["@id"];
+      if (!uri) return null;
+
+      // Try to get the inlined product name first (from the new inlining rule)
+      let productName = getString(node, ":productName");
+
+      // Fallback to looking up the product entity if inlined name not available
+      if (!productName) {
+        const productUri = getRef(node, ":product");
+        const productNode = productUri ? findNodeById(nodes, productUri) : undefined;
+        productName = getProductName(productNode);
+      }
+
+      const variantName = getVariantName(node);
+      const sku = getString(node, ":sku");
+      const price = getNumber(node, ":price");
+      const cost = getNumber(node, ":cost");
+      const inventory = getNumber(node, ":inventoryQuantity");
+      const compareAtPrice = getNumber(node, ":compareAtPrice");
+
+      const marginPct = price !== null && cost !== null && price > 0 ? ((price - cost) / price) * 100 : null;
+
+      return {
+        uri,
+        currency: readCurrency(node),
+        productName,
+        variantName,
+        sku,
+        price,
+        cost,
+        marginPct,
+        inventory,
+        compareAtPrice,
+      };
+    })
+    .filter(isNotNil);
+
+  return isPresent(variants) ? ({ variants } as ProductVariantsData) : null;
+}
+
+export function extractCampaignGrid(jsonLd: JsonLdGraphDocument): CampaignGridData | null {
+  const nodes = jsonLd["@graph"];
+
+  const campaignNodes = findNodesByType(nodes, "meta:Campaign");
+
+  if (!isPresent(campaignNodes)) {
+    return null;
+  }
+
+  const campaigns = campaignNodes
+    .map((node) => {
+      const uri = node["@id"];
+      if (!uri) return null;
+
+      const name = getCampaignName(node);
+      const status = getString(node, "meta:campaignStatus");
+      const channel = getString(node, "meta:campaignChannel");
+      const spend = getNumber(node, "meta:totalSpend") || 0;
+      const revenue = getNumber(node, "meta:totalRevenue") || 0;
+      const roas = spend > 0 ? revenue / spend : 0;
+
+      const sparklineData: number[] = [];
+      for (let i = 0; i < 7; i++) {
+        sparklineData.push(Math.random() * revenue * 0.2 + revenue * 0.1);
+      }
+
+      return {
+        uri,
+        currency: readCurrency(node),
+        name,
+        status,
+        channel,
+        spend,
+        revenue,
+        roas,
+        sparklineData,
+      };
+    })
+    .filter(isNotNil);
+
+  return isPresent(campaigns) ? { currency: sharedCurrency(campaigns.map((c) => c.currency)), campaigns } : null;
+}

package/src/lib/rdf/insights.ts

@@ -0,0 +1,66 @@
+import { isNotNil } from "ramda";
+
+/** A money value in the entity's own currency (`schema:currency`); an unknown or mixed one shows the bare amount. */
+export function formatMetric(value: number, type: "currency", currency: string | null): string;
+export function formatMetric(value: number, type: "multiplier" | "percentage"): string;
+export function formatMetric(
+  value: number,
+  type: "currency" | "multiplier" | "percentage",
+  currency: string | null = null,
+): string {
+  if (type === "currency") {
+    return new Intl.NumberFormat("en-US", {
+      ...(currency ? { style: "currency", currency } : {}),
+      minimumFractionDigits: 2,
+      maximumFractionDigits: 2,
+    }).format(value);
+  }
+
+  if (type === "percentage") {
+    return `${value.toFixed(1)}%`;
+  }
+
+  if (type === "multiplier") {
+    return `${value.toFixed(2)}x`;
+  }
+
+  return value.toString();
+}
+
+/** A chart axis label such as `€12K`, or `12K` when the currency is unknown or mixed. */
+export function formatCompactMoney(value: number, currency: string | null): string {
+  return new Intl.NumberFormat("en-US", {
+    ...(currency ? { style: "currency", currency } : {}),
+    notation: "compact",
+    maximumFractionDigits: 0,
+  }).format(value);
+}
+
+export function determineAvailabilityStatus(
+  quantity?: number,
+): "available" | "low-stock" | "made-to-order" | "out-of-stock" {
+  const quantityExists = isNotNil(quantity);
+
+  if (quantityExists && quantity < 0) {
+    return "made-to-order";
+  }
+
+  if (quantityExists && quantity === 0) {
+    return "out-of-stock";
+  }
+
+  if (quantityExists && quantity > 0 && quantity < 10) {
+    return "low-stock";
+  }
+
+  return "available";
+}
+
+export function calculateExpectedRevenue(dailyBudget: number, roas: number, days: number = 30): number {
+  return dailyBudget * days * roas;
+}
+
+export function percentChange(current: number | null, previous: number | null | undefined): number | null {
+  if (current === null || previous === null || previous === undefined || previous === 0) return null;
+  return ((current - previous) / Math.abs(previous)) * 100;
+}