Content and E-E-A-T

/**
 * Code Kit: commerce schema factories.
 * Implements checks: schema-product, schema-offer, schema-softwareapplication,
 *                    schema-service, pricing-single-source
 */

import { compact } from "../constants";
import { type JsonLdObject, type NodeRef, nodeId, ref } from "./types";

export type OfferOptions = {
  url: string;
  priceCents: number;
  currency?: string;
  name?: string;
  description?: string;
  availability?: "InStock" | "OutOfStock" | "PreOrder" | "LimitedAvailability";
  /** ISO date. Google warns when a price has no validity window. */
  priceValidUntil?: string;
  seller?: NodeRef;
  /** One-time purchase by default. Set for anything recurring. */
  billingDuration?: { value: number; unit: "MON" | "ANN" };
};

function formatPrice(cents: number): string {
  return (cents / 100).toFixed(2);
}

export function offer(opts: OfferOptions): JsonLdObject {
  const price = formatPrice(opts.priceCents);
  const currency = opts.currency ?? "USD";
  return compact({
    "@type": "Offer",
    url: opts.url,
    name: opts.name,
    description: opts.description,
    price,
    priceCurrency: currency,
    availability: `https://schema.org/${opts.availability ?? "InStock"}`,
    priceValidUntil: opts.priceValidUntil,
    seller: opts.seller,
    priceSpecification: compact({
      "@type": "UnitPriceSpecification",
      price,
      priceCurrency: currency,
      valueAddedTaxIncluded: true,
      billingDuration: opts.billingDuration?.value,
      billingIncrement: opts.billingDuration ? 1 : undefined,
      unitCode: opts.billingDuration?.unit,
    }),
  }) as JsonLdObject;
}

export type AggregateOfferOptions = {
  url: string;
  lowPriceCents: number;
  highPriceCents: number;
  currency?: string;
  offerCount: number;
  offers?: JsonLdObject[];
  seller?: NodeRef;
};

export function aggregateOffer(opts: AggregateOfferOptions): JsonLdObject {
  return compact({
    "@type": "AggregateOffer",
    url: opts.url,
    lowPrice: formatPrice(opts.lowPriceCents),
    highPrice: formatPrice(opts.highPriceCents),
    priceCurrency: opts.currency ?? "USD",
    offerCount: opts.offerCount,
    availability: "https://schema.org/InStock",
    seller: opts.seller,
    offers: opts.offers?.length ? opts.offers : undefined,
  }) as JsonLdObject;
}

export type ProductOptions = {
  siteUrl: string;
  name: string;
  description: string;
  url: string;
  imageUrl?: string;
  brandName?: string;
  category?: string;
  sku?: string;
  offers?: JsonLdObject;
  /**
   * Ratings are omitted entirely until real, verifiable reviews exist.
   * Inventing an aggregateRating is a manual action risk and a lie.
   */
  aggregateRating?: { ratingValue: number; reviewCount: number };
  id?: string;
};

export function product(opts: ProductOptions): JsonLdObject {
  return compact({
    "@type": "Product",
    "@id": opts.id ?? nodeId(opts.siteUrl, "#product"),
    name: opts.name,
    description: opts.description,
    url: opts.url,
    image: opts.imageUrl,
    sku: opts.sku,
    category: opts.category,
    brand: opts.brandName
      ? { "@type": "Brand", name: opts.brandName }
      : ref(nodeId(opts.siteUrl, "#organization")),
    offers: opts.offers,
    aggregateRating: opts.aggregateRating
      ? {
          "@type": "AggregateRating",
          ratingValue: opts.aggregateRating.ratingValue,
          reviewCount: opts.aggregateRating.reviewCount,
        }
      : undefined,
  }) as JsonLdObject;
}

export type SoftwareApplicationOptions = {
  name: string;
  description: string;
  url: string;
  applicationCategory?: string;
  operatingSystem?: string;
  /** Pass a free Offer for a free tool; omit for a paid product. */
  offers?: JsonLdObject;
  featureList?: string[];
  softwareVersion?: string;
  id?: string;
};

export function softwareApplication(opts: SoftwareApplicationOptions): JsonLdObject {
  return compact({
    "@type": "SoftwareApplication",
    "@id": opts.id ?? `${opts.url}#software`,
    name: opts.name,
    description: opts.description,
    url: opts.url,
    applicationCategory: opts.applicationCategory ?? "DeveloperApplication",
    operatingSystem: opts.operatingSystem ?? "Web browser",
    softwareVersion: opts.softwareVersion,
    featureList: opts.featureList?.length ? opts.featureList : undefined,
    offers: opts.offers,
  }) as JsonLdObject;
}

export type ServiceOptions = {
  name: string;
  description: string;
  url: string;
  serviceType?: string;
  areaServed?: string;
  provider?: NodeRef;
  offers?: JsonLdObject;
};

export function service(opts: ServiceOptions): JsonLdObject {
  return compact({
    "@type": "Service",
    "@id": `${opts.url}#service`,
    name: opts.name,
    description: opts.description,
    url: opts.url,
    serviceType: opts.serviceType,
    areaServed: opts.areaServed,
    provider: opts.provider,
    offers: opts.offers,
  }) as JsonLdObject;
}