Structured data

/**
 * Code Kit: the sitewide @graph composer.
 * Implements checks: schema-graph-anchors, schema-single-script, schema-no-duplicates
 *
 * One <script type="application/ld+json"> per page holding one @graph array.
 * Nodes cross-reference each other by @id instead of duplicating themselves,
 * which is what stops a site from shipping the same Organization object 2,000
 * times and lets a crawler resolve one entity across every page.
 */

import { compact } from "../constants";
import { organization, website, type OrganizationOptions, type WebSiteOptions } from "./organization";
import { product, type ProductOptions } from "./commerce";
import { type JsonLdObject, SCHEMA_CONTEXT, nodeId, ref } from "./types";

export type SiteGraphOptions = {
  siteUrl: string;
  organization: Omit<OrganizationOptions, "siteUrl">;
  website: Omit<WebSiteOptions, "siteUrl" | "publisher">;
  /** Omit on sites that do not sell a product. */
  product?: Omit<ProductOptions, "siteUrl">;
  /** Page-level nodes: WebPage, BreadcrumbList, Article, FAQPage, and so on. */
  additionalNodes?: Array<JsonLdObject | undefined>;
};

/**
 * Compose the sitewide graph.
 *
 * The three anchors are stable and cross-referenced:
 *   #organization  is the publisher of #website and the brand of #product
 *   #website       is the isPartOf target for every page node
 *   #product       is the thing being sold
 */
export function siteGraph(opts: SiteGraphOptions): JsonLdObject {
  const orgId = nodeId(opts.siteUrl, "#organization");

  const nodes: Array<JsonLdObject | undefined> = [
    organization({ siteUrl: opts.siteUrl, ...opts.organization }),
    website({ siteUrl: opts.siteUrl, publisher: ref(orgId), ...opts.website }),
    opts.product
      ? product({
          siteUrl: opts.siteUrl,
          ...opts.product,
          brandName: opts.product.brandName,
        })
      : undefined,
    ...(opts.additionalNodes ?? []),
  ];

  return {
    "@context": SCHEMA_CONTEXT,
    "@graph": dedupeById(nodes.filter(isPresent)) as unknown as JsonLdObject[],
  } as unknown as JsonLdObject;
}

/**
 * Build a page-level graph that references the sitewide anchors without
 * repeating them. Use on every page that is not the home page.
 */
export function pageGraph(opts: {
  siteUrl: string;
  nodes: Array<JsonLdObject | undefined>;
}): JsonLdObject {
  return {
    "@context": SCHEMA_CONTEXT,
    "@graph": dedupeById(opts.nodes.filter(isPresent)) as unknown as JsonLdObject[],
  } as unknown as JsonLdObject;
}

function isPresent<T>(value: T | undefined | null): value is T {
  return value !== undefined && value !== null;
}

/** Two nodes with the same @id in one graph is a validation error. Last write wins. */
function dedupeById(nodes: JsonLdObject[]): JsonLdObject[] {
  const seen = new Map<string, JsonLdObject>();
  const anonymous: JsonLdObject[] = [];
  for (const node of nodes) {
    const id = typeof node["@id"] === "string" ? node["@id"] : undefined;
    if (id) seen.set(id, node);
    else anonymous.push(node);
  }
  return [...seen.values(), ...anonymous];
}

/**
 * Collect every @id declared in a graph and every @id referenced by it, so a
 * test can assert that no reference dangles.
 *
 * The distinction that matters: an object carrying `@id` plus other properties
 * DECLARES a node, at any nesting depth. An object carrying nothing but `@id`
 * REFERENCES one. A nested ImageObject with its own `@id` is a declaration, and
 * treating it as a dangling reference would be a false positive.
 */
export function graphIdIntegrity(graph: JsonLdObject): {
  declared: Set<string>;
  referenced: Set<string>;
  dangling: string[];
} {
  const declared = new Set<string>();
  const referenced = new Set<string>();
  const nodes = (graph["@graph"] as unknown as JsonLdObject[]) ?? [];

  const walk = (value: unknown): void => {
    if (Array.isArray(value)) {
      for (const item of value) walk(item);
      return;
    }
    if (!value || typeof value !== "object") return;

    const obj = value as Record<string, unknown>;
    const keys = Object.keys(obj);
    const id = typeof obj["@id"] === "string" ? obj["@id"] : undefined;

    if (id) {
      if (keys.length === 1) referenced.add(id);
      else declared.add(id);
    }

    for (const [key, val] of Object.entries(obj)) {
      if (key === "@id") continue;
      walk(val);
    }
  };

  for (const node of nodes) walk(node);

  return {
    declared,
    referenced,
    dangling: [...referenced].filter((id) => !declared.has(id)),
  };
}

export { compact };

/**
 * Code Kit: navigation and list schema factories.
 * Implements checks: schema-breadcrumb, schema-itemlist, nav-breadcrumb-visible
 */

import { compact } from "../constants";
import { type JsonLdObject } from "./types";

export type BreadcrumbItem = { name: string; url: string };

/**
 * BreadcrumbList.
 *
 * The last item is the current page and carries no `item` URL, per Google's
 * documented shape. A breadcrumb in schema without a matching visible
 * <nav aria-label="Breadcrumb"> is a mismatch between markup and page, so the
 * kit's page template renders both from the same array.
 */
export function breadcrumbList(opts: {
  url: string;
  items: BreadcrumbItem[];
}): JsonLdObject | undefined {
  if (opts.items.length === 0) return undefined;
  const lastIndex = opts.items.length - 1;
  return {
    "@type": "BreadcrumbList",
    "@id": `${opts.url}#breadcrumb`,
    itemListElement: opts.items.map((item, index) =>
      compact({
        "@type": "ListItem",
        position: index + 1,
        name: item.name,
        item: index === lastIndex ? undefined : item.url,
      }),
    ),
  };
}

export type ItemListEntry = {
  name: string;
  url: string;
  description?: string;
  position?: number;
};

export function itemList(opts: {
  url: string;
  name?: string;
  items: ItemListEntry[];
  /** Use "ItemList" for a ranked list, omit ordering for an unranked set. */
  ordered?: boolean;
}): JsonLdObject | undefined {
  if (opts.items.length === 0) return undefined;
  return compact({
    "@type": "ItemList",
    "@id": `${opts.url}#itemlist`,
    name: opts.name,
    numberOfItems: opts.items.length,
    itemListOrder: opts.ordered
      ? "https://schema.org/ItemListOrderAscending"
      : "https://schema.org/ItemListUnordered",
    itemListElement: opts.items.map((item, index) =>
      compact({
        "@type": "ListItem",
        position: item.position ?? index + 1,
        name: item.name,
        url: item.url,
        description: item.description,
      }),
    ),
  }) as JsonLdObject;
}

export type SiteNavigationOptions = {
  url: string;
  items: Array<{ name: string; url: string }>;
};

export function siteNavigationElement(opts: SiteNavigationOptions): JsonLdObject | undefined {
  if (opts.items.length === 0) return undefined;
  return {
    "@type": "SiteNavigationElement",
    "@id": `${opts.url}#navigation`,
    name: opts.items.map((item) => item.name),
    url: opts.items.map((item) => item.url),
  };
}

/**
 * Code Kit: content schema factories.
 * Implements checks: schema-article, schema-faqpage, schema-howto,
 *                    schema-speakable, content-faq-visible
 */

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

export type ArticleOptions = {
  type?: "Article" | "BlogPosting" | "TechArticle";
  url: string;
  headline: string;
  description: string;
  datePublished: string | Date;
  dateModified?: string | Date;
  author: JsonLdObject | NodeRef;
  publisher: NodeRef;
  imageUrl?: string;
  imageWidth?: number;
  imageHeight?: number;
  wordCount?: number;
  articleSection?: string;
  keywords?: string[];
  inLanguage?: string;
  isPartOf?: NodeRef;
  about?: { name: string; description?: string };
};

export function article(opts: ArticleOptions): JsonLdObject {
  // Google truncates headlines past 110 characters in rich results.
  const headline = opts.headline.length > 110 ? `${opts.headline.slice(0, 107)}...` : opts.headline;

  return compact({
    "@type": opts.type ?? "Article",
    "@id": `${opts.url}#article`,
    url: opts.url,
    mainEntityOfPage: { "@type": "WebPage", "@id": opts.url },
    headline,
    description: opts.description,
    datePublished: isoDate(opts.datePublished),
    dateModified: isoDate(opts.dateModified ?? opts.datePublished),
    author: opts.author,
    publisher: opts.publisher,
    image: opts.imageUrl
      ? compact({
          "@type": "ImageObject",
          url: opts.imageUrl,
          width: opts.imageWidth,
          height: opts.imageHeight,
        })
      : undefined,
    wordCount: opts.wordCount,
    articleSection: opts.articleSection,
    keywords: opts.keywords?.length ? opts.keywords.join(", ") : undefined,
    inLanguage: opts.inLanguage ?? "en-US",
    isPartOf: opts.isPartOf,
    about: opts.about
      ? compact({
          "@type": "Thing",
          name: opts.about.name,
          description: opts.about.description,
        })
      : undefined,
  }) as JsonLdObject;
}

export type FaqEntry = { question: string; answer: string };

/**
 * FAQPage.
 *
 * Every question and answer passed here MUST also be visible in the rendered
 * HTML. Schema-only FAQs are a manual action risk, and since 2023 Google shows
 * FAQ rich results for a narrow set of sites anyway. The value now is answer
 * extraction by AI engines, which read the visible text as well.
 */
export function faqPage(opts: { url: string; faqs: FaqEntry[] }): JsonLdObject | undefined {
  if (opts.faqs.length === 0) return undefined;
  return compact({
    "@type": "FAQPage",
    "@id": `${opts.url}#faq`,
    mainEntity: opts.faqs.map((faq) => ({
      "@type": "Question",
      name: faq.question,
      acceptedAnswer: { "@type": "Answer", text: faq.answer },
    })),
  }) as JsonLdObject;
}

export type HowToStep = {
  name: string;
  text: string;
  url?: string;
  imageUrl?: string;
};

export function howTo(opts: {
  url: string;
  name: string;
  description: string;
  steps: HowToStep[];
  totalTime?: string;
  tools?: string[];
  supplies?: string[];
}): JsonLdObject | undefined {
  if (opts.steps.length === 0) return undefined;
  return compact({
    "@type": "HowTo",
    "@id": `${opts.url}#howto`,
    name: opts.name,
    description: opts.description,
    totalTime: opts.totalTime,
    tool: opts.tools?.map((name) => ({ "@type": "HowToTool", name })),
    supply: opts.supplies?.map((name) => ({ "@type": "HowToSupply", name })),
    step: opts.steps.map((step, index) =>
      compact({
        "@type": "HowToStep",
        position: index + 1,
        name: step.name,
        text: step.text,
        url: step.url,
        image: step.imageUrl,
      }),
    ),
  }) as JsonLdObject;
}

/**
 * SpeakableSpecification.
 *
 * Names the CSS selectors that hold the canonical answer on a page. Voice
 * surfaces and some answer engines read it. Point it at short, self-contained
 * sentences that restate their subject, never at a heading alone.
 */
export function speakable(cssSelectors: string[]): JsonLdObject | undefined {
  if (cssSelectors.length === 0) return undefined;
  return {
    "@type": "SpeakableSpecification",
    cssSelector: cssSelectors,
  };
}

export type WebPageOptions = {
  url: string;
  name: string;
  description: string;
  isPartOf: NodeRef;
  breadcrumb?: NodeRef;
  primaryImageUrl?: string;
  datePublished?: string | Date;
  dateModified?: string | Date;
  inLanguage?: string;
  speakableSelectors?: string[];
  about?: NodeRef;
};

export function webPage(opts: WebPageOptions): JsonLdObject {
  return compact({
    "@type": "WebPage",
    "@id": `${opts.url}#webpage`,
    url: opts.url,
    name: opts.name,
    description: opts.description,
    isPartOf: opts.isPartOf,
    breadcrumb: opts.breadcrumb,
    primaryImageOfPage: opts.primaryImageUrl
      ? { "@type": "ImageObject", url: opts.primaryImageUrl }
      : undefined,
    datePublished: isoDate(opts.datePublished),
    dateModified: isoDate(opts.dateModified),
    inLanguage: opts.inLanguage ?? "en-US",
    about: opts.about,
    speakable: opts.speakableSelectors?.length
      ? speakable(opts.speakableSelectors)
      : undefined,
  }) as JsonLdObject;
}

export type CollectionPageOptions = {
  url: string;
  name: string;
  description: string;
  isPartOf: NodeRef;
  breadcrumb?: NodeRef;
  itemList?: JsonLdObject;
  dateModified?: string | Date;
};

export function collectionPage(opts: CollectionPageOptions): JsonLdObject {
  return compact({
    "@type": "CollectionPage",
    "@id": `${opts.url}#collection`,
    url: opts.url,
    name: opts.name,
    description: opts.description,
    isPartOf: opts.isPartOf,
    breadcrumb: opts.breadcrumb,
    dateModified: isoDate(opts.dateModified),
    mainEntity: opts.itemList,
  }) as JsonLdObject;
}

export { ref };