Core API - AgentShop

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.

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.

​Fetch helpers

​Meta builders

​Serialization

​Validation

​Types

Fetch helpers

Meta builders

Serialization

Validation

Types