@abhi1693/medusa-nextjs-jsonld 0.0.0-stage → 0.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 abhi1693
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,194 @@
-# Temporary Holding Version
+# Medusa Next.js JSON-LD
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/abhi1693/medusa-nextjs-jsonld/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/abhi1693/medusa-nextjs-jsonld/actions/workflows/ci.yml)
+[![Node.js >=20](https://img.shields.io/badge/Node.js-%E2%89%A520-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![ES modules](https://img.shields.io/badge/modules-ESM-blue)](https://nodejs.org/api/esm.html)
+[![MIT license](https://img.shields.io/github/license/abhi1693/medusa-nextjs-jsonld)](LICENSE)
+[![Sponsor](https://img.shields.io/badge/Sponsor-abhi1693-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/abhi1693)
+
+Server-rendered Schema.org structured data for **Medusa v2** storefronts. ESM TypeScript package with no runtime dependency in the core; optional React 18/19 component for Next.js App Router. Supports Product/Offer, WebSite/Organization, CollectionPage/ItemList, BreadcrumbList and informational WebPage types.
+
+Install this library in the **storefront** and add its component to the corresponding server pages. Storefronts own their HTML, routing, pricing context and canonical URLs. The optional Admin preview is a copy-in example for the backend. The library uses no tracking, external service, API key or database migration.
+
+[Install](#install) · [Capabilities](#capabilities) · [Product pages](#product-page-minimum-integration) · [Other pages](#coverage-beyond-products) · [Pagination](#reusable-pagination-helpers) · [Development](#development)
+
+## Capabilities
+
+| Capability | Behavior |
+| --- | --- |
+| Product and offers | Build Product/Offer data from supplied Medusa v2 calculated prices and explicit inventory state, including valid zero prices. |
+| Site identity | Build WebSite and optional Organization data from configured public facts. |
+| Listing pages | Build CollectionPage/ItemList data for the visible page subset in its actual order. |
+| Navigation and information | Build BreadcrumbList and supported informational WebPage types from caller-supplied routes and content. |
+| Server rendering | Render escaped JSON-LD with the optional React component, including a CSP nonce, without client effects or data fetching. |
+| Pagination | Parse bounded page numbers and build same-origin pagination URLs while preserving other query parameters. |
+| Integration | ESM TypeScript exports for the core and optional React component; optional copy-in Admin preview example. |
+
+## Install
+
+The scoped package release version is `0.0.3`. Once that version is available on npm, install it in your storefront:
+
+```sh
+npm install @abhi1693/medusa-nextjs-jsonld@0.0.3
+```
+
+To install a reviewed source checkout, build and pack it first:
+
+```sh
+npm ci
+npm run check
+npm pack
+# In your storefront, install the resulting local tarball:
+npm install /path/to/abhi1693-medusa-nextjs-jsonld-0.0.3.tgz
+```
+
+Requires Node 20+, React 18/19 for the `/react` export. Core imports do not load React or Next. The package is currently ESM-only. Licensed under [MIT](LICENSE).
+
+## Product page (minimum integration)
+
+```tsx
+import { buildProductJsonLd } from "@abhi1693/medusa-nextjs-jsonld"
+import { JsonLd } from "@abhi1693/medusa-nextjs-jsonld/react"
+
+// Keep config in your storefront's server code. Use your actual public origin.
+const config = {
+  baseUrl: "https://shop.example.com",
+  productDefaults: { brand: "Your actual brand" },
+}
+
+// After your existing region-aware listProducts call and notFound checks:
+const url = `/${countryCode}/products/${encodeURIComponent(product.handle)}`
+const data = buildProductJsonLd(product, config, { url })
+return <>
+  <JsonLd id="product-jsonld" data={data} />
+  <ProductTemplate product={product} region={region} countryCode={countryCode} />
+</>
+```
+
+Use your existing page component and props rather than replacing its metadata, variant-image handling or static params. A copyable adapter is in `examples/nextjs/product-page.tsx`. The official starter has promise-valued route params in Next 15, so await `props.params` before building URLs. Keep canonical metadata and JSON-LD URL consistent.
+
+Fetch `*variants.calculated_price,+variants.inventory_quantity,+metadata` with the same region/currency and customer context as the visible product. Do not separately fetch anonymous prices if the page shows customer-specific prices. Medusa v2 `calculated_amount` is already in major units: **10 means 10, not 0.10**. Zero-price offers are valid. Currency codes must be three letters; this is format validation, not a currency registry lookup. Supply the actual active ISO currency. Raw price lists and uncalculated prices are not used. Variants without a valid calculated price and currency do not produce offers. Do not use this adapter for Medusa v1's cents-based pricing.
+
+Pass `variantUrls` keyed by variant ID only if those URLs really select and render that variant. Without a mapping offers point to the product page; the library does not invent a query parameter or a variant route. A selected variant URL, filtered variants, and visible content must remain consistent. A Product with multiple offers is supported, but this release does not model ProductGroup variant families or promise Google's variant-specific features.
+
+### Configuration and precedence
+
+Type declarations in `dist/types.d.ts` are the complete API contract. For supported static product properties, precedence is:
+
+1. `config.productDefaults` (store-wide fallback)
+2. Product title/description from the supplied Medusa product
+3. `product.metadata.jsonld` (per-product, explicitly allowlisted)
+4. `options.overrides` (per-page)
+
+Only supply facts that apply to this product and are visible or verifiable. Static fields do not replace calculated prices, availability, canonical identity, or arbitrary JSON-LD. Supported keys: name, description, brand (string or `{name}`), sku, mpn, gtin, gtin8, gtin12, gtin13, gtin14, color, material, size, category, model. These are caller assertions, not verified catalog identifiers. Unknown metadata keys are ignored; raw HTML/script injection is not supported. Do not put secrets in public JSON-LD.
+
+Availability comes only from explicit inventory flags/quantity: unmanaged inventory is in stock; managed stock with a positive quantity is in stock; depleted managed stock with backorders enabled is backorder; depleted managed stock with backorders disabled is out of stock. Incomplete inventory data is omitted instead of guessed. No ratings, reviews, GTINs, shipping policies or return policies are invented. Missing required data for a particular Google rich result remains a validation warning to resolve with truthful data, not a fabricated default.
+
+## Coverage beyond products
+
+```tsx
+import {
+  buildHomeJsonLd, buildListingJsonLd, buildBreadcrumbJsonLd, buildPageJsonLd,
+} from "@abhi1693/medusa-nextjs-jsonld"
+
+// Put on the actual localized homepage, not every layout or checkout page.
+const home = buildHomeJsonLd({
+  baseUrl: "https://shop.example.com",
+  organization: { name: "Your legal/store name", url: "https://shop.example.com" },
+}, { url: "/us", name: "Your storefront" })
+
+// Collections, categories, and store/catalog pages use their REAL visible items.
+const listing = buildListingJsonLd({
+  name: "Summer collection",
+  products: visibleProducts.map((p) => ({
+    name: p.title,
+    url: `/us/products/${encodeURIComponent(p.handle)}`,
+  })),
+}, { baseUrl: "https://shop.example.com" }, { url: "/us/collections/summer" })
+
+const crumbs = buildBreadcrumbJsonLd([
+  { name: "Home", url: "https://shop.example.com/us" },
+  { name: "Summer", url: "https://shop.example.com/us/collections/summer" },
+])
+
+const about = buildPageJsonLd({
+  name: "About us", url: "/us/about", type: "AboutPage",
+}, { baseUrl: "https://shop.example.com" })
+```
+
+Render each with `<JsonLd data={...} />`. Use `CollectionPage` for collection/category pages without claiming a Google product carousel. ItemList describes only products actually shown on that page, in display order. Paginated and filtered pages should use their actual canonical URL and visible page subset, not every product in the collection. Do not guess nested category paths from one handle. The official starter's category route is `[...category]`; construct it from the resolved ancestor path. Breadcrumbs must match the navigable hierarchy. `buildPageJsonLd` also supports other explicitly typed informational pages according to its type declaration.
+
+Do not add Product markup to cart, checkout, account, or order-confirmation pages. Avoid duplicating schemas from other SEO plugins. This package deliberately does not invent SearchAction endpoints, FAQ answers, articles, authors, product review aggregates or business addresses.
+
+## Admin preview
+
+See [the optional product details widget](examples/medusa-admin/README.md). It uses the same builder but is **a preview**, not proof of the regional storefront output. Admin products do not normally contain storefront calculated prices. The widget does not scrape your storefront, persist settings, or transmit catalog data to another service. Configuration remains explicit in your storefront code; the copy-in widget is not auto-discovered by installing the storefront package.
+
+## Security, rendering and validation
+
+`JsonLd` is server-component compatible and renders an ordinary `application/ld+json` script, without effects or client-only hydration. It accepts a CSP `nonce` and optional `id`. `stringifyJsonLd` escapes HTML-significant characters and Unicode line separators, preventing product text such as `</script>` from breaking out of the script. Use this serializer rather than raw JSON.stringify with dangerouslySetInnerHTML. Invalid mandatory canonical URLs throw; supply a trusted configured base URL rather than request headers. Malformed optional product image URLs are omitted so bad catalog assets do not break rendering. Invalid canonical, variant, organization, listing and breadcrumb URLs throw; validate configuration before deployment. URL validation does not prove same-origin, public reachability or canonical correctness: callers own those choices, including any fragment or query string. Don't fetch arbitrary storefront URLs from an admin/backend endpoint.
+
+## Development
+
+```sh
+npm ci
+npm run check
+```
+
+Tests cover builders, unsafe strings, missing prices, stock behavior, and the rendered React script. CI runs Node 20/22/24. Before production:
+
+1. Render a real product server page in each region/currency, including zero price, out-of-stock, unknown inventory and variant states. Inspect **View Source** or the actual HTML response for `application/ld+json`; an admin preview is not this test.
+2. Check offers against the visible price, currency, stock and canonical URL. Test cache invalidation after product/price/inventory edits. This package introduces no cache or webhook; use your storefront's existing Medusa revalidation.
+3. Test the page with Google's [Rich Results Test](https://search.google.com/test/rich-results) and [Schema.org validator](https://validator.schema.org/). They serve different purposes; valid Schema.org data does not guarantee a Google rich result.
+4. Verify production crawler access, canonical/noindex policy, script presence with CSP, and any existing SEO plugin duplication. Monitor Search Console after deployment.
+
+No live store credentials or deployment are needed for unit tests. Local tests are not claims that Google crawled a store or that a rich result will appear.
+
+## Integration basis
+
+The implementation was based on the official [Medusa Next.js starter](https://github.com/medusajs/nextjs-starter-medusa/tree/9818886f06e493cb2249733d114d339aa216ef00): product server page, region-aware product fetch, money formatting and inventory UI. That snapshot uses Next 15.3.9, React 19, and Medusa v2. Other Next App Router versions may work, but have not been exercised in a full deployed storefront here. Follow [Next.js JSON-LD guidance](https://nextjs.org/docs/app/guides/json-ld) and [Google's Product guidance](https://developers.google.com/search/docs/appearance/structured-data/product).
+
+## Reusable pagination helpers
+
+Both helpers and their option interfaces are exported from the package root. They
+have no Medusa, Next.js, or React dependency and do not invent merchant routes or
+filter parameters.
+
+```ts
+import { parsePageNumber, buildPaginatedUrl } from '@abhi1693/medusa-nextjs-jsonld'
+
+const config = { baseUrl: 'https://shop.example.com' } // trusted server configuration
+const page = parsePageNumber(searchParams.page, { max: 10000, fallback: 1 })
+const url = buildPaginatedUrl('/catalog?color=blue&sort=new', page, config)
+// Page 2: https://shop.example.com/catalog?color=blue&sort=new&page=2
+// Page 1: https://shop.example.com/catalog?color=blue&sort=new
+const customUrl = buildPaginatedUrl('/catalog?color=blue', page, config, {
+  pageParameter: 'p',
+})
+```
+
+- `parsePageNumber(input: unknown, options?: ParsePageNumberOptions): number`
+  accepts decimal digit strings representing positive safe integers (leading
+  zeros are accepted). Missing values, arrays, numbers, whitespace, signs,
+  fractions, exponent notation, unsafe integers, and values exceeding `max`
+  return `fallback`. Defaults are `max: Number.MAX_SAFE_INTEGER` and
+  `fallback: 1`. Both options must be positive safe integers and fallback must
+  not exceed max; invalid options throw `RangeError`.
+- `buildPaginatedUrl(path: string, page: number, config: Pick<JsonLdConfig, 'baseUrl'>,
+  options?: PaginatedUrlOptions): string` resolves relative paths using standard
+  URL semantics against the configured base URL. The default `pageParameter`
+  is `page`; other query parameters, repeated filter values and fragments are
+  retained. All instances of the selected page parameter are removed on page 1,
+  or replaced by one value otherwise. URLSearchParams may normalize query
+  encoding while preserving its decoded values. Pass actual route/filter
+  parameters from the page, not fabricated facets.
+- The URL helper requires a positive safe integer page, a nonempty query key
+  without whitespace/control characters, and an absolute HTTP(S) base URL
+  without credentials. Cross-origin URLs and credential-bearing URLs are
+  rejected. Configure baseUrl on the server, never from request headers.
+  These helpers do not impose an SEO filter/canonical policy: callers decide
+  which real filters belong in canonical metadata and JSON-LD.
+
+## License
+
+[MIT](LICENSE) © 2026 abhi1693.

package/dist/core.d.ts

@@ -0,0 +1,9 @@
+import type { BreadcrumbItem, HomeJsonLdOptions, JsonLdConfig, JsonLdDocument, JsonValue, ListingInput, ListingJsonLdOptions, MedusaProduct, PageInput, ProductJsonLdOptions } from './types.js';
+/** Build Product from a priced Medusa v2 response. Unknown prices and stock are omitted. */
+export declare function buildProductJsonLd(product: MedusaProduct, config: JsonLdConfig, options: ProductJsonLdOptions): JsonLdDocument;
+export declare function buildHomeJsonLd(config: JsonLdConfig, options?: HomeJsonLdOptions): JsonLdDocument;
+export declare function buildBreadcrumbJsonLd(items: BreadcrumbItem[]): JsonLdDocument;
+export declare function buildListingJsonLd(listing: ListingInput, config: JsonLdConfig, options: ListingJsonLdOptions): JsonLdDocument;
+export declare function buildPageJsonLd(page: PageInput, config: JsonLdConfig): JsonLdDocument;
+/** Escape HTML-significant characters to make JSON safe inside an inline script element. */
+export declare function stringifyJsonLd(value: JsonValue): string;

package/dist/core.js

@@ -0,0 +1,209 @@
+const CONTEXT = 'https://schema.org';
+const PRODUCT_TEXT_FIELDS = [
+    'name', 'description', 'sku', 'mpn', 'gtin', 'gtin8', 'gtin12', 'gtin13',
+    'gtin14', 'color', 'material', 'size', 'category', 'model',
+];
+function nonempty(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+/** Only HTTP(S) URLs without embedded credentials may reach the output. */
+function absoluteUrl(value, base) {
+    if (!nonempty(value))
+        throw new TypeError('A nonempty HTTP(S) URL is required.');
+    let parsed;
+    try {
+        parsed = base ? new URL(value, base) : new URL(value);
+    }
+    catch {
+        throw new TypeError(`Invalid URL: ${value}`);
+    }
+    if (!['https:', 'http:'].includes(parsed.protocol) || parsed.username || parsed.password) {
+        throw new TypeError('URLs must use HTTP(S) and must not contain credentials.');
+    }
+    return parsed.href;
+}
+function baseUrl(config) {
+    return absoluteUrl(config.baseUrl);
+}
+function idFor(url, fragment) {
+    const result = new URL(url);
+    result.hash = fragment;
+    return result.href;
+}
+function text(target, key, value) {
+    if (nonempty(value))
+        target[key] = value;
+}
+function productFields(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        return {};
+    const source = input;
+    const fields = {};
+    for (const key of PRODUCT_TEXT_FIELDS)
+        text(fields, key, source[key]);
+    const brand = source.brand;
+    if (nonempty(brand))
+        fields.brand = { '@type': 'Brand', name: brand };
+    else if (brand && typeof brand === 'object' && !Array.isArray(brand)) {
+        const name = brand.name;
+        if (nonempty(name))
+            fields.brand = { '@type': 'Brand', name };
+    }
+    return fields;
+}
+function availability(variant) {
+    if (variant.manage_inventory === false)
+        return `${CONTEXT}/InStock`;
+    if (variant.manage_inventory !== true)
+        return undefined;
+    const count = variant.inventory_quantity;
+    if (typeof count !== 'number' || !Number.isFinite(count))
+        return undefined;
+    if (count > 0)
+        return `${CONTEXT}/InStock`;
+    if (variant.allow_backorder === true)
+        return `${CONTEXT}/BackOrder`;
+    if (variant.allow_backorder === false)
+        return `${CONTEXT}/OutOfStock`;
+    return undefined;
+}
+/** Build Product from a priced Medusa v2 response. Unknown prices and stock are omitted. */
+export function buildProductJsonLd(product, config, options) {
+    const base = baseUrl(config);
+    const url = absoluteUrl(options.url, base);
+    const result = {
+        '@context': CONTEXT, '@type': 'Product', '@id': idFor(url, 'product'), url,
+    };
+    Object.assign(result, productFields(config.productDefaults));
+    text(result, 'name', product.title);
+    text(result, 'description', product.description);
+    Object.assign(result, productFields(product.metadata?.jsonld), productFields(options.overrides));
+    // Catalog assets are optional: a malformed image must not break the page.
+    const images = [product.thumbnail, ...(product.images ?? []).map((image) => image.url)]
+        .filter(nonempty).flatMap((image) => {
+        try {
+            return [absoluteUrl(image, base)];
+        }
+        catch {
+            return [];
+        }
+    });
+    if (images.length)
+        result.image = [...new Set(images)];
+    const offers = [];
+    for (const variant of product.variants ?? []) {
+        const price = variant.calculated_price?.calculated_amount;
+        const currency = variant.calculated_price?.currency_code;
+        if (typeof price !== 'number' || !Number.isFinite(price) || price < 0 ||
+            typeof currency !== 'string' || !/^[a-z]{3}$/i.test(currency))
+            continue;
+        const suppliedUrl = variant.id && options.variantUrls &&
+            Object.prototype.hasOwnProperty.call(options.variantUrls, variant.id)
+            ? options.variantUrls[variant.id] : undefined;
+        const offer = {
+            '@type': 'Offer', url: suppliedUrl === undefined ? url : absoluteUrl(suppliedUrl, base),
+            price, priceCurrency: currency.toUpperCase(),
+        };
+        text(offer, 'sku', variant.sku);
+        text(offer, 'name', variant.title);
+        const stock = availability(variant);
+        if (stock)
+            offer.availability = stock;
+        offers.push(offer);
+    }
+    if (offers.length)
+        result.offers = offers;
+    if (options.breadcrumbs?.length) {
+        return { '@context': CONTEXT, '@graph': [withoutContext(result), withoutContext(buildBreadcrumbJsonLd(options.breadcrumbs))] };
+    }
+    return result;
+}
+function withoutContext(document) {
+    const { '@context': _context, ...node } = document;
+    return node;
+}
+export function buildHomeJsonLd(config, options = {}) {
+    const base = baseUrl(config);
+    const url = absoluteUrl(options.url ?? base, base);
+    const website = { '@type': 'WebSite', '@id': idFor(url, 'website'), url };
+    text(website, 'name', options.name ?? config.siteName);
+    text(website, 'description', options.description);
+    text(website, 'inLanguage', options.inLanguage);
+    if (!config.organization)
+        return { '@context': CONTEXT, ...website };
+    const organizationUrl = absoluteUrl(config.organization.url ?? base, base);
+    if (!nonempty(config.organization.name))
+        throw new TypeError('Organization name is required.');
+    const organization = {
+        '@type': 'Organization', '@id': idFor(organizationUrl, 'organization'),
+        name: config.organization.name, url: organizationUrl,
+    };
+    if (config.organization.logo)
+        organization.logo = absoluteUrl(config.organization.logo, base);
+    if (config.organization.sameAs?.length) {
+        organization.sameAs = config.organization.sameAs.map((link) => absoluteUrl(link));
+    }
+    website.publisher = { '@id': organization['@id'] };
+    return { '@context': CONTEXT, '@graph': [website, organization] };
+}
+export function buildBreadcrumbJsonLd(items) {
+    return {
+        '@context': CONTEXT, '@type': 'BreadcrumbList',
+        itemListElement: items.map((item, index) => {
+            if (!nonempty(item.name))
+                throw new TypeError('Breadcrumb name is required.');
+            return { '@type': 'ListItem', position: index + 1, name: item.name, item: absoluteUrl(item.url) };
+        }),
+    };
+}
+export function buildListingJsonLd(listing, config, options) {
+    const base = baseUrl(config);
+    const url = absoluteUrl(options.url, base);
+    if (!nonempty(listing.name))
+        throw new TypeError('Listing name is required.');
+    const result = {
+        '@context': CONTEXT, '@type': 'CollectionPage', '@id': idFor(url, 'webpage'),
+        url, name: listing.name,
+        mainEntity: {
+            '@type': 'ItemList', numberOfItems: listing.products.length,
+            itemListElement: listing.products.map((product, index) => {
+                const item = { '@type': 'ListItem', position: index + 1, url: absoluteUrl(product.url, base) };
+                text(item, 'name', product.name);
+                return item;
+            }),
+        },
+    };
+    text(result, 'description', listing.description);
+    text(result, 'inLanguage', options.inLanguage);
+    const breadcrumbs = options.breadcrumbs ?? listing.breadcrumbs;
+    if (breadcrumbs?.length)
+        result.breadcrumb = withoutContext(buildBreadcrumbJsonLd(breadcrumbs));
+    return result;
+}
+export function buildPageJsonLd(page, config) {
+    const base = baseUrl(config);
+    const url = absoluteUrl(page.url, base);
+    if (!nonempty(page.name))
+        throw new TypeError('Page name is required.');
+    const type = page.type ?? 'WebPage';
+    if (!['WebPage', 'AboutPage', 'ContactPage'].includes(type))
+        throw new TypeError('Unsupported page type.');
+    const result = {
+        '@context': CONTEXT, '@type': type, '@id': idFor(url, 'webpage'), url, name: page.name,
+    };
+    text(result, 'description', page.description);
+    text(result, 'inLanguage', page.inLanguage);
+    if (page.breadcrumbs?.length)
+        result.breadcrumb = withoutContext(buildBreadcrumbJsonLd(page.breadcrumbs));
+    return result;
+}
+/** Escape HTML-significant characters to make JSON safe inside an inline script element. */
+export function stringifyJsonLd(value) {
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined)
+        throw new TypeError('A JSON value is required.');
+    const escapes = {
+        '<': '\\u003c', '>': '\\u003e', '&': '\\u0026', '\u2028': '\\u2028', '\u2029': '\\u2029',
+    };
+    return serialized.replace(/[<>&\u2028\u2029]/g, (character) => escapes[character]);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./core.js";
+export * from "./pagination.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./core.js";
+export * from "./pagination.js";

package/dist/pagination.d.ts

@@ -0,0 +1,18 @@
+import type { JsonLdConfig } from './types.js';
+export interface ParsePageNumberOptions {
+    /** Largest accepted page (inclusive). Defaults to Number.MAX_SAFE_INTEGER. */
+    max?: number;
+    /** Returned for invalid input. Defaults to 1 and must be within [1, max]. */
+    fallback?: number;
+}
+export interface PaginatedUrlOptions {
+    /** Query parameter to replace or remove. Defaults to "page". */
+    pageParameter?: string;
+}
+/** Parse a decimal digit string. Invalid input, including arrays, uses fallback. */
+export declare function parsePageNumber(input: unknown, options?: ParsePageNumberOptions): number;
+/**
+ * Resolve a path against a trusted configured base URL, preserving other query
+ * parameters and fragments. Absolute URLs must have the configured origin.
+ */
+export declare function buildPaginatedUrl(path: string, page: number, config: Pick<JsonLdConfig, 'baseUrl'>, options?: PaginatedUrlOptions): string;

package/dist/pagination.js

@@ -0,0 +1,51 @@
+function positiveInteger(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
+}
+/** Parse a decimal digit string. Invalid input, including arrays, uses fallback. */
+export function parsePageNumber(input, options = {}) {
+    const max = options.max ?? Number.MAX_SAFE_INTEGER;
+    const fallback = options.fallback ?? 1;
+    if (!positiveInteger(max) || !positiveInteger(fallback) || fallback > max) {
+        throw new RangeError('max and fallback must be positive safe integers, with fallback <= max.');
+    }
+    if (typeof input !== 'string' || !/^[0-9]+$/.test(input))
+        return fallback;
+    const page = Number(input);
+    return positiveInteger(page) && page <= max ? page : fallback;
+}
+/**
+ * Resolve a path against a trusted configured base URL, preserving other query
+ * parameters and fragments. Absolute URLs must have the configured origin.
+ */
+export function buildPaginatedUrl(path, page, config, options = {}) {
+    if (!positiveInteger(page))
+        throw new RangeError('page must be a positive safe integer.');
+    const parameter = options.pageParameter ?? 'page';
+    if (typeof parameter !== 'string' || !parameter.trim() || /[\s\u0000-\u001f\u007f]/.test(parameter)) {
+        throw new TypeError('pageParameter must be a nonempty query key without whitespace or control characters.');
+    }
+    if (typeof config?.baseUrl !== 'string' || !config.baseUrl.trim()) {
+        throw new TypeError('A trusted absolute HTTP(S) baseUrl is required.');
+    }
+    let base;
+    let url;
+    try {
+        base = new URL(config.baseUrl);
+        if (typeof path !== 'string' || !path.trim())
+            throw new TypeError();
+        url = new URL(path, base);
+    }
+    catch {
+        throw new TypeError('A valid path and absolute HTTP(S) baseUrl are required.');
+    }
+    if (!['http:', 'https:'].includes(base.protocol) || base.username || base.password ||
+        url.origin !== base.origin || url.username || url.password ||
+        !['http:', 'https:'].includes(url.protocol)) {
+        throw new TypeError('Pagination URLs must use the configured HTTP(S) origin without credentials.');
+    }
+    if (page === 1)
+        url.searchParams.delete(parameter);
+    else
+        url.searchParams.set(parameter, String(page));
+    return url.href;
+}

package/dist/react.d.ts

@@ -0,0 +1,14 @@
+import { stringifyJsonLd } from "./core.js";
+/** Render in a server page, next to the visible content. No client effect or fetch. */
+export declare function JsonLd({ data, id, nonce }: {
+    data: Parameters<typeof stringifyJsonLd>[0] | null | undefined;
+    id?: string;
+    nonce?: string;
+}): import("react").DetailedReactHTMLElement<{
+    type: string;
+    id: string | undefined;
+    nonce: string | undefined;
+    dangerouslySetInnerHTML: {
+        __html: string;
+    };
+}, HTMLElement> | null;

package/dist/react.js

@@ -0,0 +1,13 @@
+import { createElement } from "react";
+import { stringifyJsonLd } from "./core.js";
+/** Render in a server page, next to the visible content. No client effect or fetch. */
+export function JsonLd({ data, id, nonce }) {
+    if (data == null)
+        return null;
+    return createElement("script", {
+        type: "application/ld+json",
+        id,
+        nonce,
+        dangerouslySetInnerHTML: { __html: stringifyJsonLd(data) },
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,109 @@
+/** Values that can be safely represented in JSON. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export interface JsonLdObject {
+    [key: string]: JsonValue;
+}
+export type JsonLdDocument = JsonLdObject;
+/** A structural subset of Medusa v2 StoreProduct; no Medusa runtime dependency. */
+export interface MedusaProductVariant {
+    id?: string;
+    title?: string | null;
+    sku?: string | null;
+    barcode?: string | null;
+    manage_inventory?: boolean | null;
+    allow_backorder?: boolean | null;
+    inventory_quantity?: number | null;
+    calculated_price?: {
+        /** Medusa v2 calculated amounts are major currency units. Do not divide by 100. */
+        calculated_amount?: number | null;
+        currency_code?: string | null;
+    } | null;
+}
+export interface MedusaProduct {
+    id?: string;
+    handle?: string | null;
+    title?: string | null;
+    description?: string | null;
+    thumbnail?: string | null;
+    images?: Array<{
+        url?: string | null;
+    }> | null;
+    variants?: MedusaProductVariant[] | null;
+    metadata?: Record<string, unknown> | null;
+}
+/** Deliberately excludes ratings, reviews, offers, availability, and JSON-LD control keys. */
+export interface ProductFields {
+    name?: string;
+    description?: string;
+    brand?: string | {
+        name: string;
+    };
+    sku?: string;
+    mpn?: string;
+    gtin?: string;
+    gtin8?: string;
+    gtin12?: string;
+    gtin13?: string;
+    gtin14?: string;
+    color?: string;
+    material?: string;
+    size?: string;
+    category?: string;
+    model?: string;
+}
+export interface OrganizationConfig {
+    name: string;
+    url?: string;
+    logo?: string;
+    sameAs?: string[];
+}
+export interface JsonLdConfig {
+    /** Absolute HTTP(S) public store root. Never derived from request headers. */
+    baseUrl: string;
+    siteName?: string;
+    organization?: OrganizationConfig;
+    productDefaults?: ProductFields;
+}
+export interface BreadcrumbItem {
+    name: string; /** Absolute HTTP(S) URL. */
+    url: string;
+}
+export interface ProductJsonLdOptions {
+    /** Actual canonical product URL, including locale when applicable. Relative URLs resolve against baseUrl. */
+    url: string;
+    /** Actual URLs for individual variants, keyed by variant ID. No variant routes are invented. */
+    variantUrls?: Record<string, string>;
+    overrides?: ProductFields;
+    breadcrumbs?: BreadcrumbItem[];
+}
+export interface HomeJsonLdOptions {
+    url?: string;
+    name?: string;
+    description?: string;
+    inLanguage?: string;
+}
+export interface ListingProduct {
+    name?: string; /** Actual visible product destination. */
+    url: string;
+}
+export interface ListingInput {
+    name: string;
+    description?: string;
+    products: ListingProduct[];
+    breadcrumbs?: BreadcrumbItem[];
+}
+export interface ListingJsonLdOptions {
+    url: string;
+    inLanguage?: string;
+    breadcrumbs?: BreadcrumbItem[];
+}
+export interface PageInput {
+    name: string;
+    url: string;
+    description?: string;
+    type?: 'WebPage' | 'AboutPage' | 'ContactPage';
+    inLanguage?: string;
+    breadcrumbs?: BreadcrumbItem[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/examples/medusa-admin/README.md

@@ -0,0 +1,96 @@
+# Optional Medusa Admin preview
+
+This is a **copy-in Medusa v2 Admin widget**, not an installable backend plugin.
+The storefront JSON-LD package does not need this widget to work. Installing it
+only provides a local, read-only Product preview on the Admin product details
+page. It does not inject scripts into a Next.js storefront.
+
+## Install
+
+1. Build/package this repository with `npm pack`. Install the resulting
+   `abhi1693-medusa-nextjs-jsonld-0.0.2.tgz` in your **Medusa application** (in addition to
+   installing it in the separate Next.js storefront), for example:
+
+   ```sh
+   npm install /absolute/path/to/abhi1693-medusa-nextjs-jsonld-0.0.2.tgz
+   ```
+
+   Use the tarball filename actually generated by your reviewed source checkout
+   if the version changes.
+
+2. Copy `widgets/product-jsonld.tsx` to
+   `src/admin/widgets/product-jsonld.tsx` in your Medusa application.
+3. The example uses `product.details`, the current injection zone for Medusa
+   **2.17.2+**. For older Medusa v2 installations, replace that zone with
+   `product.details.after`. Follow your installed Medusa release's documentation.
+4. Restart the application/Admin dev server, or rebuild your deployed Admin.
+   Open a product details page and enter the public storefront base URL and
+   actual canonical product path. Correct the suggested `/products/{handle}`
+   path if your storefront uses country/locale prefixes or a different router.
+
+The host Medusa application supplies React, `@medusajs/admin-sdk`,
+`@medusajs/framework`, and `@medusajs/ui`. Keep those packages aligned with your
+Medusa installation rather than independently upgrading them for this widget.
+
+## What the preview means
+
+- The widget calls the **same `buildProductJsonLd` implementation** as the
+  storefront. It passes the current Admin product's title, description,
+  thumbnail, images, and metadata, plus the URLs entered locally.
+- Admin variants are deliberately omitted. An Admin product record does not
+  establish the visitor's region, current calculated prices, tax context, or
+  sellable inventory context. Therefore this preview has **no offers** and is
+  **not a complete product-rich-result eligibility test**.
+- Saved `metadata.jsonld` is shown separately as read-only source data. Only
+  supported, validated fields are used by the builder. Arbitrary raw JSON-LD,
+  ratings, reviews, offers, availability, and JSON-LD control keys are not
+  accepted as overrides. Consult the package README for the supported fields.
+- This example passes only `baseUrl` as global config. To match a real store,
+  pass your public `productDefaults` too. Do not import a server config module
+  that contains secrets into the Admin browser bundle. Storefront per-page
+  overrides, breadcrumbs, and region-specific prices can change the final
+  output; inspect the actual storefront page for the authoritative result.
+- The suggested URL is a convenience, not a claim that the product is published
+  or that the route exists. Nothing checks availability at that address.
+
+## Safety and scope
+
+URLs and preview state stay in the current browser component. They are reset
+when switching products or reloading. There is no network fetch, metadata write,
+backend endpoint, persistent setting, or server-side URL fetch in this example.
+React renders preview JSON as text in a `pre` element; it is never inserted as
+HTML or as an executable script. The widget is not a metadata editor.
+
+If you change saved product metadata through your existing Medusa workflow,
+refresh the details page if its data has not updated. Adding a dedicated editor
+would require normal authenticated Admin API writes and explicit handling of
+validation, concurrent changes, and permissions; this example does not implement
+that API or imply that saving metadata alone installs storefront rendering.
+
+## Validation and references
+
+The widget was strict-TypeScript-checked against actual installed packages:
+`@medusajs/admin-sdk@2.22.4`, `@medusajs/framework@2.22.4`, React 18 types, and
+`@medusajs/ui@4.2.11`, using this repository's builder types. No running Medusa instance
+or browser end-to-end integration was available, so test placement and styling
+in your own application before deploying.
+
+Official sources checked:
+
+- [Admin widgets, props, and placement](https://docs.medusajs.com/learn/fundamentals/admin/widgets)
+- [Medusa Admin customization](https://docs.medusajs.com/learn/fundamentals/admin)
+
+The widget guide documents `defineWidgetConfig`, arrow-function default widget
+components, `DetailWidgetProps<AdminProduct>`, and the 2.17.2 placement change.
+
+Manual acceptance checks:
+
+1. Product details shows the widget and the saved `metadata.jsonld` value.
+2. Valid public base/product URLs produce a Product preview without offers.
+3. Unsupported protocols and URLs with embedded credentials show a message.
+4. Changing URL inputs changes only the preview; it sends no requests and does
+   not change product metadata.
+5. Navigating to another product resets the local URL inputs.
+6. Validate the deployed storefront page using Google's Rich Results Test and
+   Schema.org's validator. Their results apply to the real page, not this Admin
+   preview, and valid markup does not guarantee a search enhancement.

package/examples/medusa-admin/widgets/product-jsonld.tsx

@@ -0,0 +1,109 @@
+import { defineWidgetConfig } from "@medusajs/admin-sdk"
+import type { AdminProduct, DetailWidgetProps } from "@medusajs/framework/types"
+import { Container, Heading } from "@medusajs/ui"
+import { useId, useMemo, useState } from "react"
+import { buildProductJsonLd } from "@abhi1693/medusa-nextjs-jsonld"
+
+// Copy into src/admin/widgets in your Medusa application. See ../README.md.
+// This is a local preview, not a metadata editor or storefront injector.
+const ProductJsonLdPreview = ({ product }: { product: AdminProduct }) => {
+  const id = useId()
+  const [baseUrl, setBaseUrl] = useState("")
+  const [productPath, setProductPath] = useState(
+    `/products/${encodeURIComponent(product.handle || product.id)}`
+  )
+  const preview = useMemo(() => {
+    if (!baseUrl.trim()) return { message: "Enter your storefront base URL to preview." }
+    try {
+      const base = new URL(baseUrl.trim())
+      if (!["https:", "http:"].includes(base.protocol) || base.username || base.password) {
+        throw new Error("Use an HTTP(S) storefront URL without credentials.")
+      }
+      if (!productPath.trim()) throw new Error("Enter the canonical product URL or path.")
+      const url = new URL(productPath.trim(), base)
+      if (!["https:", "http:"].includes(url.protocol) || url.username || url.password) {
+        throw new Error("Use an HTTP(S) product URL without credentials.")
+      }
+      // Deliberately omit admin variants. They do not establish the active
+      // storefront region, calculated prices, or sellable inventory context.
+      const value = buildProductJsonLd(
+        {
+          id: product.id,
+          title: product.title,
+          description: product.description,
+          thumbnail: product.thumbnail,
+          images: product.images,
+          metadata: product.metadata,
+        },
+        { baseUrl: base.href },
+        { url: url.href }
+      )
+      return { json: JSON.stringify(value, null, 2) }
+    } catch (error) {
+      return { message: error instanceof Error ? error.message : "Unable to build this preview." }
+    }
+  }, [baseUrl, productPath, product])
+
+  return (
+    <Container className="flex flex-col gap-4">
+      <Heading level="h2">Product structured data preview</Heading>
+      <p className="text-ui-fg-subtle text-sm">
+        Local preview using product details and supported metadata.jsonld overrides.
+        Offers are omitted: this admin record has no active storefront region or
+        calculated prices. These inputs are not saved and no URLs are fetched.
+      </p>
+      <label className="flex flex-col gap-1 text-sm" htmlFor={`${id}-base`}>
+        Storefront base URL
+        <input
+          id={`${id}-base`}
+          type="url"
+          placeholder="https://store.example.com"
+          value={baseUrl}
+          onChange={(event) => setBaseUrl(event.target.value)}
+          className="rounded border p-2"
+          autoComplete="off"
+          spellCheck={false}
+        />
+      </label>
+      <label className="flex flex-col gap-1 text-sm" htmlFor={`${id}-product`}>
+        Canonical product URL or path (include your country or locale prefix)
+        <input
+          id={`${id}-product`}
+          type="text"
+          value={productPath}
+          onChange={(event) => setProductPath(event.target.value)}
+          className="rounded border p-2"
+          autoComplete="off"
+          spellCheck={false}
+        />
+      </label>
+      {preview.message ? <p role="status" className="text-sm">{preview.message}</p> : null}
+      {preview.json ? (
+        <pre aria-label="Product JSON-LD preview" className="max-h-96 overflow-auto rounded bg-ui-bg-subtle p-3 text-xs">
+          {preview.json}
+        </pre>
+      ) : null}
+      <details>
+        <summary className="cursor-pointer text-sm">Saved metadata.jsonld (read-only)</summary>
+        <pre className="max-h-64 overflow-auto rounded bg-ui-bg-subtle p-3 text-xs">
+          {JSON.stringify(product.metadata?.jsonld ?? null, null, 2)}
+        </pre>
+      </details>
+      <p className="text-ui-fg-subtle text-sm">
+        This is not a Google eligibility check. Validate the actual public product
+        page after installing the storefront component. Storefront config defaults
+        and explicit overrides can also change the final output.
+      </p>
+    </Container>
+  )
+}
+
+// Key by product ID so navigating between products resets the local URL inputs.
+const ProductJsonLdWidget = ({ data }: DetailWidgetProps<AdminProduct>) => (
+  <ProductJsonLdPreview key={data.id} product={data} />
+)
+
+// Medusa 2.17.2+. For older v2 releases, use "product.details.after".
+export const config = defineWidgetConfig({ zone: "product.details" })
+
+export default ProductJsonLdWidget

package/examples/nextjs/product-page.tsx

@@ -0,0 +1,20 @@
+// Adapt inside the existing App Router product page; keep your own metadata,
+// static params, region lookup, 404 handling, and visible ProductTemplate.
+import { buildProductJsonLd } from "@abhi1693/medusa-nextjs-jsonld"
+import { JsonLd } from "@abhi1693/medusa-nextjs-jsonld/react"
+
+// In ProductPage, after loading pricedProduct with the SAME region/customer
+// context used by the visible page and checking it exists:
+export function ProductStructuredData({ product, countryCode, baseUrl }: {
+  product: Parameters<typeof buildProductJsonLd>[0]
+  countryCode: string
+  baseUrl: string
+}) {
+  if (!product.handle) return null
+  const url = `/${encodeURIComponent(countryCode)}/products/${encodeURIComponent(product.handle)}`
+  const data = buildProductJsonLd(product, { baseUrl }, { url })
+  return <JsonLd id="product-jsonld" data={data} />
+}
+// Render <ProductStructuredData product={pricedProduct} countryCode={params.countryCode}
+// baseUrl={process.env.NEXT_PUBLIC_BASE_URL!} /> alongside <ProductTemplate ... />.
+// Set baseUrl to your real public store origin, never a request Host header.

package/package.json

@@ -1,6 +1,94 @@
 {
   "name": "@abhi1693/medusa-nextjs-jsonld",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.3",
+  "description": "Safe server-rendered structured data builders for Medusa v2 storefronts",
+  "type": "module",
+  "files": [
+    "dist",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    }
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "check": "npm test && npm pack --dry-run",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.8.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abhi1693/medusa-nextjs-jsonld.git"
+  },
+  "license": "MIT",
+  "typesVersions": {
+    "*": {
+      "react": [
+        "dist/react.d.ts"
+      ]
+    }
+  },
+  "homepage": "https://github.com/abhi1693/medusa-nextjs-jsonld#readme",
+  "bugs": {
+    "url": "https://github.com/abhi1693/medusa-nextjs-jsonld/issues"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/abhi1693"
+  },
+  "keywords": [
+    "medusa",
+    "medusa-v2",
+    "ecommerce",
+    "typescript",
+    "nextjs",
+    "json-ld",
+    "schema-org",
+    "structured-data",
+    "seo",
+    "react",
+    "medusa-plugin",
+    "medusa-plugin-other"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "config": {
+    "release": {
+      "requiredFiles": [
+        "dist/core.js",
+        "dist/pagination.js",
+        "dist/types.d.ts"
+      ]
+    }
+  }
+}