Core API

The core entry point (@agentshop/seo) has zero runtime dependencies and works in any server environment with global fetch (Node ≥ 18, edge runtimes, workerd). All fetch helpers follow the never-throw contract: null on any failure, never an exception.

Fetch helpers

function fetchProductBundle(handle: string, cfg?: SeoClientConfig): Promise<SeoBundle | null>

Fetches the product bundle for a product handle.

function fetchCollectionBundle(handle: string, cfg?: SeoClientConfig): Promise<SeoBundle | null>

Fetches the collection bundle. Structurally identical to a product bundle; openGraph.type is "website".

function fetchSiteBundle(cfg?: SeoClientConfig): Promise<SeoSiteBundle | null>

Fetches the site-level JSON-LD graph (Organization + WebSite + optional FAQPage).

function fetchSitemapXml(cfg?: SeoClientConfig): Promise<string | null>

Fetches the product sitemap as an XML string.

function fetchPixelConfig(cfg?: SeoClientConfig): Promise<PixelConfig | null>

Fetches where to load the storefront analytics script from — { scriptUrl, token, eventsUrl, shopDomain }. Resolve it per render rather than storing the values: the pixel token can change, and one frozen in a deployed build stops working silently. See Storefront analytics.

function reportIfCrawler(
  request: Request,
  cfg?: SeoClientConfig & { statusCode?: number },
): Promise<boolean>

Bot-checks a standard Request and reports it if it’s a crawler — the whole recipe in one call: the isbot gate, stripping url and referrer to origin + pathname, and the POST. Resolves false when the request isn’t a bot, the URL is unreportable, or delivery failed; it never throws and never blocks the response. Pass statusCode on a runtime that performed the fetch itself (a Cloudflare Worker). The Next.js proxy wrapper omits it deliberately — see AI crawler visibility.

Meta builders

function buildProductMetaDescriptors(seo: SeoBundle | null | undefined): MetaDescriptor[]

Builds the Remix/Hydrogen v2 meta descriptor array from a bundle: title, description, canonical, Open Graph (including og:type=product), Twitter tags, and the JSON-LD via a "script:ld+json" descriptor. Returns [] for a null bundle. For the bundle → Next.js Metadata mapper, use toNextMetadata. It is not a core export — it ships only from @agentshop/seo/next, so non-Next consumers (Remix, Hydrogen, plain Node) aren’t forced to install next to typecheck.

Serialization

function serializeJsonLd(jsonLd: unknown): string

Serializes JSON-LD for embedding inside a <script type="application/ld+json"> tag, escaping every < to its JSON unicode form (\u003c) so a data field containing </script> (product titles, vendor names, FAQ answers…) can’t break out of the script block. The result is still valid JSON. Always use this instead of JSON.stringify when writing your own script tags — see Security.

Validation

function resolveConfig(cfg?: SeoClientConfig): ResolvedConfig

The throwing configuration validator — see Configuration.

Types

interface SeoBundle {
  /** schema.org JSON-LD, e.g. { "@context", "@graph": [Product, BreadcrumbList] } */
  jsonLd: unknown;
  title: string;
  description: string;
  canonical: string;
  openGraph: SeoOpenGraph;
  twitter: SeoTwitter;
}

interface SeoSiteBundle {
  /** schema.org JSON-LD { "@context", "@graph": [Organization, WebSite, FAQPage?] } */
  jsonLd: unknown;
}

interface SeoOpenGraph {
  title: string;
  description: string;
  /** "product" for product pages, "website" for collection pages */
  type: "product" | "website";
  url: string;
  siteName?: string;
  image?: string;
}

interface SeoTwitter {
  card: "summary" | "summary_large_image";
  title: string;
  description: string;
  image?: string;
}

/**
 * A Remix v2 meta descriptor. Loosely typed to avoid a hard @remix-run
 * dependency; structurally compatible with Remix's MetaDescriptor.
 */
type MetaDescriptor = Record<string, unknown>;

SeoClientConfig is documented in Configuration.

Headless SEO SDK

Framework guides

Analytics

Artifacts

Reference

Security & troubleshooting

Fetch helpers

Meta builders

Serialization

Validation

Types

​Fetch helpers

​Meta builders

​Serialization

​Validation

​Types

Fetch helpers

Meta builders

Serialization

Validation

Types