@amjadiqbal/start-seo-kit 0.0.0-stage → 0.1.0

package/dist/commerce.js

@@ -0,0 +1,315 @@
+import { t as jsonLd } from "./json-ld-BkYFVGHw.js";
+// src/commerce.ts
+const CONTEXT = "https://schema.org";
+const SCHEMA = "https://schema.org/";
+/** Product JSON-LD (with Offer or AggregateOffer, ratings, reviews, shipping and returns) for Google product rich results. */
+function productJsonLd(p) {
+	return clean({
+		"@context": CONTEXT,
+		"@type": "Product",
+		"@id": p.id,
+		name: p.name,
+		description: p.description,
+		image: p.image,
+		url: p.url,
+		sku: p.sku,
+		mpn: p.mpn,
+		gtin: p.gtin,
+		brand: p.brand ? {
+			"@type": "Brand",
+			name: p.brand
+		} : void 0,
+		category: p.category,
+		color: p.color,
+		size: p.size,
+		material: p.material,
+		inProductGroupWithID: p.groupId,
+		offers: p.offers === void 0 ? void 0 : offersLd(p.offers),
+		aggregateRating: p.rating ? aggregateRatingLd(p.rating) : void 0,
+		review: p.reviews?.length ? p.reviews.map(reviewLd) : void 0
+	});
+}
+function offersLd(o) {
+	if (Array.isArray(o)) return o.map(offerLd);
+	return "lowPrice" in o ? aggregateOfferLd(o) : offerLd(o);
+}
+/** One `Offer`. */
+function offerLd(o) {
+	const shipping = o.shipping === void 0 ? void 0 : Array.isArray(o.shipping) ? o.shipping : [o.shipping];
+	return clean({
+		"@type": "Offer",
+		price: o.price,
+		priceCurrency: o.currency,
+		availability: o.availability ? SCHEMA + o.availability : void 0,
+		itemCondition: o.condition ? SCHEMA + o.condition : void 0,
+		url: o.url,
+		priceValidUntil: dateOnly(o.priceValidUntil),
+		sku: o.sku,
+		seller: o.seller ? {
+			"@type": "Organization",
+			name: o.seller
+		} : void 0,
+		shippingDetails: shipping?.length ? shipping.map(shippingLd) : void 0,
+		hasMerchantReturnPolicy: o.returnPolicy ? returnPolicyLd(o.returnPolicy) : void 0
+	});
+}
+/** An `AggregateOffer` (price range across sellers or variants). */
+function aggregateOfferLd(o) {
+	return clean({
+		"@type": "AggregateOffer",
+		lowPrice: o.lowPrice,
+		highPrice: o.highPrice,
+		priceCurrency: o.currency,
+		offerCount: o.offerCount,
+		availability: o.availability ? SCHEMA + o.availability : void 0
+	});
+}
+function aggregateRatingLd(r) {
+	return clean({
+		"@type": "AggregateRating",
+		ratingValue: r.value,
+		ratingCount: r.count,
+		reviewCount: r.reviewCount,
+		bestRating: r.best,
+		worstRating: r.worst
+	});
+}
+function reviewLd(r) {
+	const notes = (items) => items?.length ? {
+		"@type": "ItemList",
+		itemListElement: items.map((name, i) => ({
+			"@type": "ListItem",
+			position: i + 1,
+			name
+		}))
+	} : void 0;
+	return clean({
+		"@type": "Review",
+		author: {
+			"@type": "Person",
+			name: r.author
+		},
+		reviewRating: clean({
+			"@type": "Rating",
+			ratingValue: r.rating,
+			bestRating: r.best ?? 5,
+			worstRating: r.worst
+		}),
+		name: r.name,
+		reviewBody: r.body,
+		datePublished: dateOnly(r.datePublished),
+		positiveNotes: notes(r.positiveNotes),
+		negativeNotes: notes(r.negativeNotes)
+	});
+}
+/** `OfferShippingDetails`. */
+function shippingLd(s) {
+	const countries = Array.isArray(s.country) ? s.country : [s.country];
+	const region = (country) => clean({
+		"@type": "DefinedRegion",
+		addressCountry: country,
+		addressRegion: s.regions
+	});
+	const range = (days) => days ? {
+		"@type": "QuantitativeValue",
+		minValue: days[0],
+		maxValue: days[1],
+		unitCode: "DAY"
+	} : void 0;
+	return clean({
+		"@type": "OfferShippingDetails",
+		shippingRate: {
+			"@type": "MonetaryAmount",
+			value: s.rate,
+			currency: s.currency
+		},
+		shippingDestination: countries.length === 1 ? region(countries[0]) : countries.map(region),
+		deliveryTime: s.handlingDays || s.transitDays ? clean({
+			"@type": "ShippingDeliveryTime",
+			handlingTime: range(s.handlingDays),
+			transitTime: range(s.transitDays)
+		}) : void 0
+	});
+}
+/** `MerchantReturnPolicy`. Also usable on an Organization (`hasMerchantReturnPolicy`). */
+function returnPolicyLd(r) {
+	if (!("country" in r)) return {
+		"@type": "MerchantReturnPolicy",
+		merchantReturnLink: r.url
+	};
+	const category = {
+		finite: "MerchantReturnFiniteReturnWindow",
+		unlimited: "MerchantReturnUnlimitedWindow",
+		notPermitted: "MerchantReturnNotPermitted"
+	}[r.category];
+	const fees = r.fees === void 0 ? {} : r.fees === "free" ? { returnFees: `${SCHEMA}FreeReturn` } : r.fees === "customer" ? { returnFees: `${SCHEMA}ReturnFeesCustomerResponsibility` } : {
+		returnFees: `${SCHEMA}ReturnShippingFees`,
+		returnShippingFeesAmount: {
+			"@type": "MonetaryAmount",
+			value: r.fees.amount,
+			currency: r.fees.currency
+		}
+	};
+	const methods = {
+		mail: "ReturnByMail",
+		store: "ReturnInStore",
+		kiosk: "ReturnAtKiosk"
+	};
+	return clean({
+		"@type": "MerchantReturnPolicy",
+		applicableCountry: r.country,
+		returnPolicyCategory: SCHEMA + category,
+		merchantReturnDays: r.category === "finite" ? r.days : void 0,
+		returnMethod: r.method?.length ? r.method.map((m) => SCHEMA + methods[m]) : void 0,
+		merchantReturnLink: r.url,
+		...fees
+	});
+}
+const OG_AVAILABILITY = {
+	InStock: "in stock",
+	OutOfStock: "out of stock",
+	PreOrder: "preorder",
+	PreSale: "preorder",
+	BackOrder: "available for order",
+	Discontinued: "discontinued",
+	LimitedAvailability: "in stock",
+	InStoreOnly: "in stock",
+	OnlineOnly: "in stock",
+	SoldOut: "out of stock"
+};
+const OG_CONDITION = {
+	NewCondition: "new",
+	UsedCondition: "used",
+	RefurbishedCondition: "refurbished",
+	DamagedCondition: "used"
+};
+/** Open Graph product tags: `product:price:amount`, `product:price:currency`, availability, condition, brand, item id. */
+function productOpenGraph(p) {
+	const meta = [];
+	const first = p.offers === void 0 ? void 0 : Array.isArray(p.offers) ? p.offers[0] : p.offers;
+	if (first) {
+		const amount = "lowPrice" in first ? first.lowPrice : first.price;
+		meta.push({
+			property: "product:price:amount",
+			content: String(amount)
+		});
+		meta.push({
+			property: "product:price:currency",
+			content: first.currency
+		});
+		if (first.availability) meta.push({
+			property: "product:availability",
+			content: OG_AVAILABILITY[first.availability]
+		});
+		if ("condition" in first && first.condition) meta.push({
+			property: "product:condition",
+			content: OG_CONDITION[first.condition]
+		});
+	}
+	if (p.brand) meta.push({
+		property: "product:brand",
+		content: p.brand
+	});
+	if (p.sku) meta.push({
+		property: "product:retailer_item_id",
+		content: p.sku
+	});
+	if (p.groupId) meta.push({
+		property: "product:item_group_id",
+		content: p.groupId
+	});
+	return meta;
+}
+/**
+* Everything a product page needs, as `seo()` options: `og:type` product, the product Open Graph tags
+* and the Product JSON-LD. Spread it into your call:
+*
+* ```ts
+* head: ({ loaderData: p }) => seo({ title: p.name, path: `/p/${p.slug}`, image: p.images[0], ...productSeo(p) })
+* ```
+*/
+function productSeo(p) {
+	return {
+		type: "product",
+		meta: productOpenGraph(p),
+		jsonLd: productJsonLd(p)
+	};
+}
+/**
+* Check a product against Google's product snippet and merchant listing requirements
+* (as documented on 2026-10-22). Use it in tests or development; it does not throw.
+*/
+function checkProduct(p, options = {}) {
+	const errors = [];
+	const warnings = [];
+	const offers = p.offers === void 0 ? [] : Array.isArray(p.offers) ? p.offers : [p.offers];
+	if (!p.name?.trim()) errors.push("name is required");
+	if (!offers.length && !p.rating && !p.reviews?.length) errors.push("one of offers, rating or reviews is required for product snippets");
+	if (options.merchantListing) {
+		if (!p.image || Array.isArray(p.image) && !p.image.length) errors.push("image is required for merchant listings");
+		if (!offers.length) errors.push("offers is required for merchant listings");
+	}
+	if (!p.offers && (p.rating || p.reviews?.length)) warnings.push("offers is recommended: the Rich Results Test warns without it");
+	offers.forEach((o, i) => {
+		const at = offers.length > 1 ? `offers[${i}]` : "offers";
+		if ("lowPrice" in o) {
+			checkPrice(o.lowPrice, `${at}.lowPrice`, errors);
+			if (o.highPrice !== void 0) checkPrice(o.highPrice, `${at}.highPrice`, errors);
+			if (options.merchantListing) warnings.push(`${at}: use Offer rather than AggregateOffer for merchant listings and price-drop results`);
+		} else {
+			checkPrice(o.price, `${at}.price`, errors);
+			if (!o.availability) warnings.push(`${at}.availability is recommended`);
+			(o.shipping === void 0 ? [] : Array.isArray(o.shipping) ? o.shipping : [o.shipping]).forEach((s, j) => {
+				if (s.currency !== o.currency) errors.push(`${at}.shipping[${j}].currency must match the offer currency (${o.currency})`);
+				if (!s.handlingDays && !s.transitDays) errors.push(`${at}.shipping[${j}] needs handlingDays or transitDays (deliveryTime)`);
+				checkPrice(s.rate, `${at}.shipping[${j}].rate`, errors);
+			});
+			if (o.returnPolicy && "country" in o.returnPolicy && o.returnPolicy.category === "finite" && !o.returnPolicy.days) errors.push(`${at}.returnPolicy.days is required for a finite return window`);
+		}
+		if (!/^[A-Z]{3}$/.test(o.currency)) errors.push(`${at}.currency must be a 3-letter ISO 4217 code`);
+	});
+	if (p.rating) {
+		if (p.rating.count === void 0 && p.rating.reviewCount === void 0) errors.push("rating needs count or reviewCount");
+		const best = p.rating.best ?? 5;
+		if (p.rating.value > best || p.rating.value < (p.rating.worst ?? 1)) errors.push("rating.value is outside best/worst");
+	}
+	p.reviews?.forEach((r, i) => {
+		if (!r.author.trim()) errors.push(`reviews[${i}].author is required`);
+		if ((r.positiveNotes?.length ?? 0) + (r.negativeNotes?.length ?? 0) === 1) warnings.push(`reviews[${i}]: pros and cons need at least two statements in total`);
+	});
+	if (!p.brand) warnings.push("brand is recommended");
+	if (!p.gtin && !p.mpn && !p.sku) warnings.push("a gtin, mpn or sku is recommended");
+	if (!p.description) warnings.push("description is recommended");
+	return {
+		errors,
+		warnings
+	};
+}
+/** Map your products to sitemap entries (with image entries) for a `createSitemap` source. */
+function productSitemapEntries(items, options) {
+	const out = [];
+	for (const item of items) {
+		const lastmod = options.lastmod?.(item);
+		const images = options.images?.(item);
+		out.push(clean({
+			loc: options.path(item),
+			lastmod,
+			images: images?.length ? images : void 0,
+			changefreq: options.changefreq,
+			priority: options.priority
+		}));
+	}
+	return out;
+}
+function checkPrice(value, at, errors) {
+	if (!(typeof value === "number" ? Number.isFinite(value) && value >= 0 : /^\d+(\.\d+)?$/.test(value))) errors.push(`${at} must be a non-negative number without currency symbols or separators`);
+}
+function dateOnly(value) {
+	return value instanceof Date ? value.toISOString().slice(0, 10) : value;
+}
+function clean(obj) {
+	const out = {};
+	for (const [k, v] of Object.entries(obj)) if (v !== void 0) out[k] = v;
+	return out;
+}
+export { aggregateOfferLd, aggregateRatingLd, checkProduct, jsonLd, offerLd, productJsonLd, productOpenGraph, productSeo, productSitemapEntries, returnPolicyLd, reviewLd, shippingLd };

package/dist/head-D2pPoGNP.d.ts

@@ -0,0 +1,218 @@
+import { g as TrailingSlash } from "./sitemap-DbEixSCi.js";
+/** Any JSON value allowed inside a JSON-LD document. */
+type JsonLdValue = string | number | boolean | null | JsonLdValue[] | {
+  [key: string]: JsonLdValue | undefined;
+};
+/** A JSON-LD node: an object with `@type` (and usually `@context`). */
+interface JsonLdObject {
+  '@context'?: string | Record<string, JsonLdValue>;
+  '@type'?: string | string[];
+  '@id'?: string;
+  '@graph'?: JsonLdObject[];
+  [key: string]: JsonLdValue | JsonLdObject | JsonLdObject[] | undefined;
+}
+type Ref = string | JsonLdObject;
+interface PersonInput {
+  name: string;
+  url?: string;
+  image?: string;
+  jobTitle?: string;
+  sameAs?: string[];
+  id?: string;
+}
+interface OrganizationInput {
+  name: string;
+  url?: string;
+  logo?: string;
+  sameAs?: string[];
+  email?: string;
+  telephone?: string;
+  id?: string;
+  /** `Organization` (default) or a subtype such as `Corporation` or `LocalBusiness`. */
+  type?: string;
+}
+interface WebSiteInput {
+  name: string;
+  url: string;
+  /** Enables the sitelinks search box: a URL with `{search_term_string}`, e.g. `https://acme.dev/search?q={search_term_string}`. */
+  searchUrlTemplate?: string;
+  publisher?: Ref;
+  inLanguage?: string;
+  id?: string;
+}
+interface ArticleLdInput {
+  /** `Article` (default), `BlogPosting`, `NewsArticle` or `TechArticle`. */
+  type?: 'Article' | 'BlogPosting' | 'NewsArticle' | 'TechArticle';
+  headline: string;
+  description?: string;
+  url?: string;
+  image?: string | string[];
+  datePublished?: string | Date;
+  dateModified?: string | Date;
+  author?: Ref | Ref[];
+  publisher?: Ref;
+  keywords?: string[];
+  id?: string;
+}
+interface BreadcrumbItem {
+  name: string;
+  /** Absolute URL. Leave it out on the last (current) item if you like. */
+  url?: string;
+}
+interface FaqItem {
+  question: string;
+  /** Plain text or simple HTML. */
+  answer: string;
+}
+/**
+ * Typed builders for common schema.org types. Each returns a JSON-LD object with `@context`.
+ * Product, Offer, Review and return/shipping policies live in `@amjadiqbal/start-seo-kit/commerce`.
+ */
+declare const jsonLd: {
+  person(p: PersonInput): JsonLdObject;
+  organization(o: OrganizationInput): JsonLdObject;
+  website(w: WebSiteInput): JsonLdObject;
+  article(a: ArticleLdInput): JsonLdObject;
+  breadcrumbs(items: BreadcrumbItem[]): JsonLdObject;
+  faq(items: FaqItem[]): JsonLdObject;
+  /** Combine several nodes into one `@graph` document (their own `@context` is dropped). */
+  graph(...nodes: JsonLdObject[]): JsonLdObject;
+};
+/**
+ * One entry of a route's `head().meta` array, in the shapes TanStack Router renders.
+ * The JSON-LD shape carries an optional `content?: undefined` so it stays assignable to
+ * React's `<meta>` props type, which Router's React adapter uses for `meta`.
+ */
+type MetaTag = {
+  title: string;
+} | {
+  name: string;
+  content: string;
+} | {
+  property: string;
+  content: string;
+} | {
+  'script:ld+json': JsonLdObject;
+  content?: undefined;
+};
+/** One entry of a route's `head().links` array. */
+type LinkTag = {
+  rel: string;
+  href: string;
+  hrefLang?: string;
+  type?: string;
+  title?: string;
+};
+interface HeadTags {
+  meta: MetaTag[];
+  links: LinkTag[];
+}
+type ImageInput = string | {
+  url: string;
+  width?: number;
+  height?: number;
+  alt?: string;
+  type?: string;
+};
+type RobotsInput = string | {
+  index?: boolean;
+  follow?: boolean;
+  noarchive?: boolean;
+  nosnippet?: boolean;
+  noimageindex?: boolean;
+  notranslate?: boolean;
+  maxSnippet?: number;
+  maxImagePreview?: 'none' | 'standard' | 'large';
+  maxVideoPreview?: number;
+  unavailableAfter?: string | Date;
+};
+type TwitterCard = 'summary' | 'summary_large_image' | 'app' | 'player';
+interface TwitterInput {
+  card?: TwitterCard;
+  /** `@handle` of the site. */
+  site?: string;
+  /** `@handle` of the author. */
+  creator?: string;
+}
+interface ArticleInput {
+  publishedTime?: string | Date;
+  modifiedTime?: string | Date;
+  expirationTime?: string | Date;
+  /** Author profile URL or name. Router keeps one tag per property, so only one author is emitted. */
+  author?: string;
+  section?: string;
+}
+interface SiteConfig {
+  /** Absolute origin (plus optional base path) of the site, e.g. `https://example.com`. */
+  url: string;
+  /** Site name, used for `og:site_name`. */
+  name?: string;
+  /** Title template; `%s` is replaced by the page title, e.g. `%s | Acme`. */
+  titleTemplate?: string;
+  /** Title used when a route passes none (not templated). */
+  defaultTitle?: string;
+  description?: string;
+  /** Default share image. Relative paths are resolved against `url`. */
+  image?: ImageInput;
+  /** `og:locale`, e.g. `en_US`. */
+  locale?: string;
+  twitter?: TwitterInput;
+  robots?: RobotsInput;
+  /** Match your router's `trailingSlash` option. Default `never`. */
+  trailingSlash?: TrailingSlash;
+}
+interface SeoInput {
+  title?: string;
+  /** Override the site template for this page, or `false` to use the title as is. */
+  titleTemplate?: string | false;
+  description?: string;
+  /** Path of this page (e.g. `/posts/${params.slug}`): sets the canonical link and `og:url`. */
+  path?: string;
+  /** Absolute or relative canonical URL, or `false` for none. Defaults to `path`. */
+  canonical?: string | false;
+  /** Share image, or `false` to drop the site default. */
+  image?: ImageInput | false;
+  /** `og:type`. Default `website`, or `article` when `article` is set. */
+  type?: string;
+  article?: ArticleInput;
+  robots?: RobotsInput;
+  /** Shorthand for `robots: { index: false, follow: true }`. */
+  noindex?: boolean;
+  /** hreflang alternates: `{ en: '/en/about', de: '/de/about', 'x-default': '/about' }`. */
+  alternates?: Record<string, string>;
+  locale?: string;
+  twitter?: TwitterInput;
+  /** Title for `og:title`/`twitter:title`. Default: the page title without the template. */
+  socialTitle?: string;
+  /** One or more JSON-LD objects (see the `jsonLd` helpers). */
+  jsonLd?: JsonLdObject | JsonLdObject[];
+  /** Extra meta tags, appended as given. */
+  meta?: MetaTag[];
+  /** Extra link tags, appended as given. */
+  links?: LinkTag[];
+}
+interface Seo {
+  /** Build the `meta` and `links` for a route's `head()`. */
+  (input?: SeoInput): HeadTags;
+  /** The site config with a normalized `url`. */
+  readonly site: Readonly<SiteConfig>;
+  /** Absolute URL of a page path, with the site's trailing-slash rule. */
+  url(path: string): string;
+}
+/**
+ * Create a typed head builder bound to your site's defaults.
+ *
+ * ```ts
+ * export const seo = defineSeo({ url: 'https://acme.dev', name: 'Acme', titleTemplate: '%s | Acme' })
+ * // in a route
+ * head: ({ loaderData }) => seo({ title: loaderData.post.title, path: `/posts/${loaderData.post.slug}` })
+ * ```
+ */
+declare function defineSeo(config: SiteConfig): Seo;
+/** Build head tags without a site config. Relative URLs are not allowed here. */
+declare function seo(input: SeoInput & {
+  siteUrl?: string;
+}): HeadTags;
+/** Serialize robots directives, e.g. `{ index: false, maxImagePreview: 'large' }` -> `noindex, follow, max-image-preview:large`. */
+declare function robotsContent(robots: RobotsInput | undefined): string | undefined;
+export { jsonLd as C, WebSiteInput as S, FaqItem as _, MetaTag as a, OrganizationInput as b, SeoInput as c, TwitterInput as d, defineSeo as f, BreadcrumbItem as g, ArticleLdInput as h, LinkTag as i, SiteConfig as l, seo as m, HeadTags as n, RobotsInput as o, robotsContent as p, ImageInput as r, Seo as s, ArticleInput as t, TwitterCard as u, JsonLdObject as v, PersonInput as x, JsonLdValue as y };

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import { C as jsonLd, S as WebSiteInput, _ as FaqItem, a as MetaTag, b as OrganizationInput, c as SeoInput, d as TwitterInput, f as defineSeo, g as BreadcrumbItem, h as ArticleLdInput, i as LinkTag, l as SiteConfig, m as seo, n as HeadTags, o as RobotsInput, p as robotsContent, r as ImageInput, s as Seo, t as ArticleInput, u as TwitterCard, v as JsonLdObject, x as PersonInput, y as JsonLdValue } from "./head-D2pPoGNP.js";
+import { _ as absoluteUrl, a as ServerHandler, c as SitemapImage, d as UrlOptions, f as createSitemap, g as TrailingSlash, h as sitemapXml, i as RoutesFromTreeOptions, l as SitemapIndexEntry, m as sitemapIndexXml, n as CreateSitemapOptions, o as SitemapEntry, p as routesFromTree, r as HandlerContext, s as SitemapHandlers, t as ChangeFreq, u as SitemapSource } from "./sitemap-DbEixSCi.js";
+type Awaitable<T> = T | Promise<T>;
+interface RobotsRule {
+  userAgent: string | string[];
+  allow?: string | string[];
+  disallow?: string | string[];
+  crawlDelay?: number;
+}
+interface RobotsConfig {
+  /** Default: one rule allowing everything for every user agent. */
+  rules?: RobotsRule[];
+  /** Sitemap paths or URLs. Paths need `siteUrl`. */
+  sitemaps?: string[];
+  siteUrl?: string;
+  /** Block every crawler (`Disallow: /`), e.g. on staging or preview deployments. Overrides `rules`. */
+  disallowAll?: boolean;
+}
+/** Render a robots.txt body. */
+export declare function robotsTxt(config?: RobotsConfig): string;
+/**
+ * `GET` handler for a `/robots.txt` server route. Pass a function to decide per request
+ * (for example, `disallowAll` when the host is a preview deployment).
+ */
+export declare function createRobotsHandler(config: RobotsConfig | ((ctx: HandlerContext) => Awaitable<RobotsConfig>), init?: {
+  cacheControl?: string;
+}): ServerHandler;
+export { type ArticleInput, type ArticleLdInput, type BreadcrumbItem, type ChangeFreq, type CreateSitemapOptions, type FaqItem, type HandlerContext, type HeadTags, type ImageInput, type JsonLdObject, type JsonLdValue, type LinkTag, type MetaTag, type OrganizationInput, type PersonInput, type RobotsConfig, type RobotsInput, type RobotsRule, type RoutesFromTreeOptions, type Seo, type SeoInput, type ServerHandler, type SiteConfig, type SitemapEntry, type SitemapHandlers, type SitemapImage, type SitemapIndexEntry, type SitemapSource, type TrailingSlash, type TwitterCard, type TwitterInput, type UrlOptions, type WebSiteInput, absoluteUrl, createSitemap, defineSeo, jsonLd, robotsContent, routesFromTree, seo, sitemapIndexXml, sitemapXml };