@jdevalk/seo-graph-core 0.5.1 → 0.6.0

package/README.md

@@ -1,5 +1,8 @@
 # @jdevalk/seo-graph-core
 
+[![npm version](https://img.shields.io/npm/v/@jdevalk/seo-graph-core)](https://www.npmjs.com/package/@jdevalk/seo-graph-core)
+[![license](https://img.shields.io/npm/l/@jdevalk/seo-graph-core)](https://github.com/jdevalk/seo-graph/blob/main/LICENSE)
+
 Pure schema.org JSON-LD graph builders. Runtime-agnostic core for agent-ready SEO.
 
 ## What this is
@@ -32,6 +35,15 @@ npm install @jdevalk/seo-graph-core
 | `assembleGraph(pieces)`            | Wraps pieces in a `{ @context, @graph }` envelope with first-wins deduplication by `@id`. |
 | `deduplicateByGraphId(entities)`   | The dedup engine on its own, in case you need custom assembly.                            |
 
+### IndexNow
+
+| API                          | Purpose                                                                       |
+| ---------------------------- | ----------------------------------------------------------------------------- |
+| `submitToIndexNow`           | POST URLs to the IndexNow aggregator. Filters by host, dedupes, chunks at 10k. |
+| `generateIndexNowKey`        | Generate a random hex key (Web Crypto).                                       |
+| `validateIndexNowKey`        | Verify a key is 8–128 hex chars.                                              |
+| `getIndexNowKeyFileContent`  | Body to serve at `/<key>.txt` for host verification.                          |
+
 ### Piece builders
 
 All builders take an input object and the `IdFactory`, and return a plain
@@ -120,18 +132,41 @@ const graph = assembleGraph([
 // graph === { '@context': 'https://schema.org', '@graph': [...] }
 ```
 
-## Why
+## IndexNow
+
+Runtime-agnostic helpers for the [IndexNow](https://www.indexnow.org) protocol.
+Submit URLs to participating search engines (Bing, Yandex, Seznam, Naver, Yep)
+through the neutral aggregator at `api.indexnow.org`.
+
+```ts
+import {
+    generateIndexNowKey,
+    getIndexNowKeyFileContent,
+    submitToIndexNow,
+    validateIndexNowKey,
+} from '@jdevalk/seo-graph-core';
 
-The [agent-ready web](https://joost.blog/tag/agent-ready/) needs every
-publisher to expose a rich, linked knowledge graph for their content. Hand-
-writing JSON-LD is error-prone; writing it once per framework is worse.
-`@jdevalk/seo-graph-core` is the shared engine behind two downstream packages,
-both in production:
+const key = generateIndexNowKey(); // 32-char hex, persist this
 
-- [`@jdevalk/astro-seo-graph`](https://www.npmjs.com/package/@jdevalk/astro-seo-graph) — the Astro integration (`<Seo>` + route factories). Used in production by [joost.blog](https://joost.blog) and [limonaia.house](https://limonaia.house).
-- [`@jdevalk/emdash-plugin-seo`](https://www.npmjs.com/package/@jdevalk/emdash-plugin-seo) — the EmDash CMS plugin. Uses `assembleGraph` directly (EmDash contributes metadata through hooks, not through templates, so it doesn't go through the `<Seo>` component).
+// Serve this body at https://example.com/<key>.txt
+const keyFileBody = getIndexNowKeyFileContent(key);
+
+const results = await submitToIndexNow({
+    host: 'example.com',
+    key,
+    urls: ['https://example.com/blog/new-post/'],
+});
+```
+
+URLs not on `host` and duplicates are filtered automatically. Bulk submissions
+are chunked at 10,000 URLs per request. `submitToIndexNow` never throws on
+network errors — it returns one result per chunk with `ok`, `status`, and
+`message`. Pass `endpoint` to override the default aggregator, `keyLocation`
+to point at a non-default key-file path, or `fetch` for testing.
+
+## Why
 
-Two different integration runtimes, one graph engine.
+Read more about [why this project exists](https://joost.blog/seo-graph/).
 
 ## License
 

package/dist/index.d.ts

@@ -20,4 +20,6 @@ export type { ImageObjectInput } from './pieces/image.js';
 export { buildVideoObject } from './pieces/video.js';
 export type { VideoObjectInput } from './pieces/video.js';
 export { buildPiece } from './pieces/custom.js';
+export { submitToIndexNow, validateIndexNowKey, generateIndexNowKey, getIndexNowKeyFileContent, DEFAULT_INDEXNOW_ENDPOINT, INDEXNOW_MAX_URLS_PER_REQUEST, } from './indexnow.js';
+export type { SubmitToIndexNowOptions, IndexNowSubmitResult } from './indexnow.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC1F,OAAO,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACpG,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAG1D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AACpE,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElF,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAErE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAErE,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElF,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC1F,OAAO,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACpG,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAG1D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AACpE,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElF,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAErE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAErE,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElF,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGhD,OAAO,EACH,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,yBAAyB,EACzB,yBAAyB,EACzB,6BAA6B,GAChC,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -12,4 +12,6 @@ export { buildBreadcrumbList } from './pieces/breadcrumb.js';
 export { buildImageObject } from './pieces/image.js';
 export { buildVideoObject } from './pieces/video.js';
 export { buildPiece } from './pieces/custom.js';
+// IndexNow protocol
+export { submitToIndexNow, validateIndexNowKey, generateIndexNowKey, getIndexNowKeyFileContent, DEFAULT_INDEXNOW_ENDPOINT, INDEXNOW_MAX_URLS_PER_REQUEST, } from './indexnow.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAG3E,OAAO,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEpG,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG9C,iBAAiB;AACjB,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,OAAO,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AAGpE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAG7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAGrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAGrD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAG3E,OAAO,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEpG,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG9C,iBAAiB;AACjB,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,OAAO,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AAGpE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAG7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAGrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAGrD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD,oBAAoB;AACpB,OAAO,EACH,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,yBAAyB,EACzB,yBAAyB,EACzB,6BAA6B,GAChC,MAAM,eAAe,CAAC"}

package/dist/indexnow.d.ts

@@ -0,0 +1,53 @@
+/** Default aggregator endpoint. Fans out to every participating engine. */
+export declare const DEFAULT_INDEXNOW_ENDPOINT = "https://api.indexnow.org/IndexNow";
+/** IndexNow accepts up to 10,000 URLs per bulk request. */
+export declare const INDEXNOW_MAX_URLS_PER_REQUEST = 10000;
+export interface SubmitToIndexNowOptions {
+    /** Bare host, e.g. `example.com`. No scheme, no trailing slash. */
+    host: string;
+    /** 8–128 hex-character key. Must match the key file served on the host. */
+    key: string;
+    /**
+     * Optional absolute URL where the key file is hosted. Defaults to
+     * `https://<host>/<key>.txt`. Supply this when the key file lives at
+     * a non-default path.
+     */
+    keyLocation?: string;
+    /** URLs to submit. Must all be on `host`. Empty list is a no-op. */
+    urls: readonly string[];
+    /** Override the endpoint. Defaults to {@link DEFAULT_INDEXNOW_ENDPOINT}. */
+    endpoint?: string;
+    /** Injectable fetch for testing. Defaults to global `fetch`. */
+    fetch?: typeof fetch;
+}
+export interface IndexNowSubmitResult {
+    /** HTTP status from the IndexNow server. `0` when the request failed. */
+    status: number;
+    /** Whether the submission was accepted (200 or 202). */
+    ok: boolean;
+    /** Response body text if any, or error message on network failure. */
+    message: string;
+    /** Number of URLs actually submitted after filtering/dedup. */
+    submitted: number;
+}
+/**
+ * Submit URLs to IndexNow. Filters out URLs not on `host`, deduplicates,
+ * and chunks at {@link INDEXNOW_MAX_URLS_PER_REQUEST}. Returns one result
+ * per chunk; a single-chunk submission returns a one-element array.
+ */
+export declare function submitToIndexNow(options: SubmitToIndexNowOptions): Promise<IndexNowSubmitResult[]>;
+/** Returns true when `key` is 8–128 hexadecimal characters. */
+export declare function validateIndexNowKey(key: string): boolean;
+/**
+ * Generate a cryptographically random IndexNow key of `length` hex
+ * characters. Default 32. Uses Web Crypto, available in Node 20+,
+ * browsers, and edge/worker runtimes.
+ */
+export declare function generateIndexNowKey(length?: number): string;
+/**
+ * Plain-text body to serve at `https://<host>/<key>.txt`. IndexNow
+ * verifies ownership by fetching this file and comparing to the
+ * submitted key.
+ */
+export declare function getIndexNowKeyFileContent(key: string): string;
+//# sourceMappingURL=indexnow.d.ts.map

package/dist/indexnow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexnow.d.ts","sourceRoot":"","sources":["../src/indexnow.ts"],"names":[],"mappings":"AAIA,2EAA2E;AAC3E,eAAO,MAAM,yBAAyB,sCAAsC,CAAC;AAE7E,2DAA2D;AAC3D,eAAO,MAAM,6BAA6B,QAAS,CAAC;AAOpD,MAAM,WAAW,uBAAuB;IACpC,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACjC,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,EAAE,EAAE,OAAO,CAAC;IACZ,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAClC,OAAO,EAAE,uBAAuB,GACjC,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAgDjC;AA0BD,+DAA+D;AAC/D,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAIxD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,SAAK,GAAG,MAAM,CAWvD;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO7D"}

package/dist/indexnow.js

@@ -0,0 +1,124 @@
+// IndexNow protocol support. Submits URLs to participating search engines
+// (Bing, Yandex, Seznam, Naver, Yep) through the neutral aggregator
+// endpoint at api.indexnow.org. Spec: https://www.indexnow.org/documentation
+/** Default aggregator endpoint. Fans out to every participating engine. */
+export const DEFAULT_INDEXNOW_ENDPOINT = 'https://api.indexnow.org/IndexNow';
+/** IndexNow accepts up to 10,000 URLs per bulk request. */
+export const INDEXNOW_MAX_URLS_PER_REQUEST = 10_000;
+/** Key length constraints per the spec. */
+const MIN_KEY_LENGTH = 8;
+const MAX_KEY_LENGTH = 128;
+const HEX_KEY_RE = /^[a-f0-9]+$/i;
+/**
+ * Submit URLs to IndexNow. Filters out URLs not on `host`, deduplicates,
+ * and chunks at {@link INDEXNOW_MAX_URLS_PER_REQUEST}. Returns one result
+ * per chunk; a single-chunk submission returns a one-element array.
+ */
+export async function submitToIndexNow(options) {
+    const { host, key, urls } = options;
+    if (!validateIndexNowKey(key)) {
+        throw new Error(`IndexNow key must be ${MIN_KEY_LENGTH}–${MAX_KEY_LENGTH} hex characters.`);
+    }
+    if (!host || host.includes('/') || host.includes(':')) {
+        throw new Error(`IndexNow host must be a bare host (got: ${host}).`);
+    }
+    const filtered = filterUrlsForHost(urls, host);
+    if (filtered.length === 0)
+        return [];
+    const endpoint = options.endpoint ?? DEFAULT_INDEXNOW_ENDPOINT;
+    const keyLocation = options.keyLocation ?? `https://${host}/${key}.txt`;
+    const doFetch = options.fetch ?? fetch;
+    const results = [];
+    for (let i = 0; i < filtered.length; i += INDEXNOW_MAX_URLS_PER_REQUEST) {
+        const chunk = filtered.slice(i, i + INDEXNOW_MAX_URLS_PER_REQUEST);
+        const body = JSON.stringify({ host, key, keyLocation, urlList: chunk });
+        try {
+            const res = await doFetch(endpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json; charset=utf-8',
+                    Accept: 'application/json',
+                },
+                body,
+            });
+            const text = await res.text().catch(() => '');
+            results.push({
+                status: res.status,
+                ok: res.status === 200 || res.status === 202,
+                message: text,
+                submitted: chunk.length,
+            });
+        }
+        catch (err) {
+            results.push({
+                status: 0,
+                ok: false,
+                message: err instanceof Error ? err.message : String(err),
+                submitted: chunk.length,
+            });
+        }
+    }
+    return results;
+}
+/**
+ * Keep only URLs whose hostname matches `host` (case-insensitive) and
+ * deduplicate while preserving first-seen order.
+ */
+function filterUrlsForHost(urls, host) {
+    const lowerHost = host.toLowerCase();
+    const seen = new Set();
+    const out = [];
+    for (const raw of urls) {
+        let parsed;
+        try {
+            parsed = new URL(raw);
+        }
+        catch {
+            continue;
+        }
+        if (parsed.hostname.toLowerCase() !== lowerHost)
+            continue;
+        const normalized = parsed.toString();
+        if (seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        out.push(normalized);
+    }
+    return out;
+}
+/** Returns true when `key` is 8–128 hexadecimal characters. */
+export function validateIndexNowKey(key) {
+    if (typeof key !== 'string')
+        return false;
+    if (key.length < MIN_KEY_LENGTH || key.length > MAX_KEY_LENGTH)
+        return false;
+    return HEX_KEY_RE.test(key);
+}
+/**
+ * Generate a cryptographically random IndexNow key of `length` hex
+ * characters. Default 32. Uses Web Crypto, available in Node 20+,
+ * browsers, and edge/worker runtimes.
+ */
+export function generateIndexNowKey(length = 32) {
+    if (length < MIN_KEY_LENGTH || length > MAX_KEY_LENGTH || length % 2 !== 0) {
+        throw new Error(`IndexNow key length must be an even number between ${MIN_KEY_LENGTH} and ${MAX_KEY_LENGTH}.`);
+    }
+    const bytes = new Uint8Array(length / 2);
+    crypto.getRandomValues(bytes);
+    let hex = '';
+    for (const b of bytes)
+        hex += b.toString(16).padStart(2, '0');
+    return hex;
+}
+/**
+ * Plain-text body to serve at `https://<host>/<key>.txt`. IndexNow
+ * verifies ownership by fetching this file and comparing to the
+ * submitted key.
+ */
+export function getIndexNowKeyFileContent(key) {
+    if (!validateIndexNowKey(key)) {
+        throw new Error(`IndexNow key must be ${MIN_KEY_LENGTH}–${MAX_KEY_LENGTH} hex characters.`);
+    }
+    return key;
+}
+//# sourceMappingURL=indexnow.js.map

package/dist/indexnow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexnow.js","sourceRoot":"","sources":["../src/indexnow.ts"],"names":[],"mappings":"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"}

package/dist/pieces/breadcrumb.d.ts

@@ -5,6 +5,8 @@ export interface BreadcrumbItem {
     name: string;
     /** URL for this crumb. */
     url: string;
+    /** Optional @id override. When set, the `item` value uses this @id instead of the URL. */
+    id?: string;
 }
 interface BreadcrumbListCoreFields {
     /** The URL of the page this breadcrumb belongs to. */

package/dist/pieces/breadcrumb.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"breadcrumb.d.ts","sourceRoot":"","sources":["../../src/pieces/breadcrumb.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAG3C,MAAM,WAAW,cAAc;IAC3B,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,GAAG,EAAE,MAAM,CAAC;CACf;AAED,UAAU,wBAAwB;IAC9B,sDAAsD;IACtD,GAAG,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;CACpC;AAED,MAAM,MAAM,mBAAmB,GAAG,wBAAwB,GACtD,IAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,EAAE,MAAM,wBAAwB,GAAG,OAAO,CAAC,CAAC;AAIhF;;GAEG;AACH,wBAAgB,mBAAmB,CAC/B,KAAK,EAAE,mBAAmB,EAC1B,GAAG,EAAE,SAAS,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkBzB"}
+{"version":3,"file":"breadcrumb.d.ts","sourceRoot":"","sources":["../../src/pieces/breadcrumb.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAG3C,MAAM,WAAW,cAAc;IAC3B,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,0FAA0F;IAC1F,EAAE,CAAC,EAAE,MAAM,CAAC;CACf;AAED,UAAU,wBAAwB;IAC9B,sDAAsD;IACtD,GAAG,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;CACpC;AAED,MAAM,MAAM,mBAAmB,GAAG,wBAAwB,GACtD,IAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,EAAE,MAAM,wBAAwB,GAAG,OAAO,CAAC,CAAC;AAIhF;;GAEG;AACH,wBAAgB,mBAAmB,CAC/B,KAAK,EAAE,mBAAmB,EAC1B,GAAG,EAAE,SAAS,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAsBzB"}

package/dist/pieces/breadcrumb.js

@@ -9,7 +9,11 @@ export function buildBreadcrumbList(input, ids) {
         '@type': 'ListItem',
         position: index + 1,
         name: item.name,
-        item: index === lastIndex ? { '@id': ids.webPage(item.url) } : item.url,
+        item: item.id
+            ? { '@id': item.id }
+            : index === lastIndex
+                ? { '@id': ids.webPage(item.url) }
+                : item.url,
     }));
     const piece = {
         '@type': 'BreadcrumbList',

package/dist/pieces/breadcrumb.js.map

@@ -1 +1 @@
-{"version":3,"file":"breadcrumb.js","sourceRoot":"","sources":["../../src/pieces/breadcrumb.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAmBxD,MAAM,YAAY,GAAG,IAAI,GAAG,CAAS,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;AAEvD;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAC/B,KAA0B,EAC1B,GAAc;IAEd,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;IACzC,MAAM,eAAe,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;QACtD,OAAO,EAAE,UAAU;QACnB,QAAQ,EAAE,KAAK,GAAG,CAAC;QACnB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,IAAI,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG;KAC1E,CAAC,CAAC,CAAC;IAEJ,MAAM,KAAK,GAA4B;QACnC,OAAO,EAAE,gBAAgB;QACzB,KAAK,EAAE,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC;QAChC,eAAe;KAClB,CAAC;IAEF,yBAAyB,CAAC,KAAK,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;IAEtD,OAAO,KAAK,CAAC;AACjB,CAAC"}
+{"version":3,"file":"breadcrumb.js","sourceRoot":"","sources":["../../src/pieces/breadcrumb.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAqBxD,MAAM,YAAY,GAAG,IAAI,GAAG,CAAS,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;AAEvD;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAC/B,KAA0B,EAC1B,GAAc;IAEd,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;IACzC,MAAM,eAAe,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;QACtD,OAAO,EAAE,UAAU;QACnB,QAAQ,EAAE,KAAK,GAAG,CAAC;QACnB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,IAAI,EAAE,IAAI,CAAC,EAAE;YACT,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,EAAE;YACpB,CAAC,CAAC,KAAK,KAAK,SAAS;gBACnB,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE;gBAClC,CAAC,CAAC,IAAI,CAAC,GAAG;KACnB,CAAC,CAAC,CAAC;IAEJ,MAAM,KAAK,GAA4B;QACnC,OAAO,EAAE,gBAAgB;QACzB,KAAK,EAAE,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC;QAChC,eAAe;KAClB,CAAC;IAEF,yBAAyB,CAAC,KAAK,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;IAEtD,OAAO,KAAK,CAAC;AACjB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jdevalk/seo-graph-core",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Pure schema.org JSON-LD graph builders. Runtime-agnostic core for agent-ready SEO.",
   "keywords": [
     "schema.org",