facets.ts

/**
 * Faceted-navigation indexability policy.
 *
 * Category pages multiply into near-infinite URL variants once you add color,
 * size, sort, view, and tracking params. Indexing them all is how headless
 * sites drown in duplicate/thin pages. This module encodes ONE deterministic
 * tier policy that decides, per request, what the canonical and robots
 * directives should be:
 *
 *   - base (no facets, no sort)                  -> indexable, self-canonical
 *   - single CURATED facet (e.g. ?color=red)     -> indexable, self-canonical
 *   - sort/view variants (e.g. ?sort=price)      -> indexable but canonical -> base
 *   - single UNCURATED facet (e.g. ?color=lime)  -> noindex, self-canonical
 *   - multiple facets (e.g. ?color=red&size=9)   -> noindex, self-canonical
 *   - tracking/session params (utm_*, gclid, ...)-> excluded from canonical
 *     entirely (a robots/crawl-budget concern, never an indexable signal)
 *
 * A noindex tier is always kept self-canonical — never cross-canonicalized to
 * base — because noindex + a canonical to a different URL are conflicting
 * signals.
 */

export type FacetTier =
  | 'base'
  | 'curated-facet'
  | 'sort-variant'
  | 'uncurated-facet'
  | 'multi-facet';

export interface FacetDecision {
  tier: FacetTier;
  /** Robots index directive for this URL. */
  index: boolean;
  /**
   * The retained facet params that belong in the canonical (already filtered to
   * curated facets; sort/view/tracking never appear here).
   */
  canonicalParams: Record<string, string>;
  /**
   * Whether the canonical should point at the BASE category path (dropping the
   * current facet/sort selection). When false, the canonical is self.
   */
  canonicalToBase: boolean;
}

export interface FacetPolicyInput {
  /** Which query params are facets (e.g. `['color', 'size']`). */
  facetKeys: string[];
  /** Curated facet values that are allowed to be indexable on their own. */
  curatedFacets: Record<string, string[]>;
  /** The raw query params from the request. */
  params: Record<string, string | string[] | undefined>;
  /** Param keys treated as sort/view variants. Defaults to `sort`, `view`. */
  sortKeys?: string[];
}

const DEFAULT_SORT_KEYS = ['sort', 'view'];

/** Tracking/session params that must never influence the canonical. */
const TRACKING_PARAM_PATTERNS = [
  /^utm_/i,
  /^gclid$/i,
  /^fbclid$/i,
  /^msclkid$/i,
  /^mc_/i,
  /^ref$/i,
  /^sessionid$/i,
  /^sid$/i,
];

export function isTrackingParam(key: string): boolean {
  return TRACKING_PARAM_PATTERNS.some((re) => re.test(key));
}

function firstValue(value: string | string[] | undefined): string | undefined {
  if (Array.isArray(value)) return value[0];
  return value ?? undefined;
}

/**
 * Decide the indexability tier for a faceted category request.
 */
export function decideFacetPolicy(input: FacetPolicyInput): FacetDecision {
  const sortKeys = new Set(input.sortKeys ?? DEFAULT_SORT_KEYS);
  const facetKeySet = new Set(input.facetKeys);

  // Active facets: facet keys that carry a non-empty value.
  const activeFacets: Array<{ key: string; value: string }> = [];
  let hasSortVariant = false;

  for (const [key, rawValue] of Object.entries(input.params)) {
    if (isTrackingParam(key)) continue; // always excluded
    const value = firstValue(rawValue);
    if (value === undefined || value === '') continue;

    if (facetKeySet.has(key)) {
      activeFacets.push({ key, value });
    } else if (sortKeys.has(key)) {
      hasSortVariant = true;
    }
    // Unknown params: ignored for tier purposes (also excluded from canonical).
  }

  // More than one facet selection -> noindex, self-canonical.
  if (activeFacets.length > 1) {
    return {
      tier: 'multi-facet',
      index: false,
      canonicalParams: {},
      canonicalToBase: false,
    };
  }

  if (activeFacets.length === 1) {
    const { key, value } = activeFacets[0];
    const curated = input.curatedFacets[key]?.includes(value) ?? false;

    if (!curated) {
      // Uncurated single facet -> noindex, self-canonical.
      return {
        tier: 'uncurated-facet',
        index: false,
        canonicalParams: {},
        canonicalToBase: false,
      };
    }

    // Curated single facet. A sort/view on top of it canonicalizes back to the
    // curated facet page (dropping the sort); otherwise it is self-canonical.
    return {
      tier: hasSortVariant ? 'sort-variant' : 'curated-facet',
      index: true,
      canonicalParams: { [key]: value },
      canonicalToBase: false,
    };
  }

  // No facets. A sort/view variant on the bare base canonicalizes to base.
  if (hasSortVariant) {
    return {
      tier: 'sort-variant',
      index: true,
      canonicalParams: {},
      canonicalToBase: true,
    };
  }

  // Plain base.
  return {
    tier: 'base',
    index: true,
    canonicalParams: {},
    canonicalToBase: false,
  };
}