@jdevalk/astro-seo-graph 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joost de Valk
+
+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

@@ -0,0 +1,154 @@
+# @jdevalk/astro-seo-graph
+
+Astro integration for [`@jdevalk/seo-graph-core`](../seo-graph-core). Ships a
+`<Seo>` component, route factories for agent-ready schema endpoints, a
+content-collection aggregator, and Zod helpers for content schemas.
+
+> **Status:** pre-v1, alpha track. The API may still shift. See the
+> [roadmap](https://github.com/jdevalk/seo-graph#roadmap) in the monorepo root.
+
+## What's in v0.1
+
+| API                            | Purpose                                                                                                                                                                                                          |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`<Seo>`** (`./Seo.astro`)    | Single head component covering `<title>`, meta description, canonical, Open Graph, Twitter card, and optional JSON-LD `@graph`. Wraps [`astro-seo`](https://github.com/jonasmerlin/astro-seo) for the meta tags. |
+| **`createSchemaEndpoint`**     | Factory returning an Astro `APIRoute` handler that serves a corpus-wide JSON-LD `@graph` for a content collection.                                                                                               |
+| **`createSchemaMap`**          | Factory returning an `APIRoute` handler that emits a sitemap-style XML listing of your site's schema endpoints — the discovery point for agent crawlers.                                                         |
+| **`aggregate`**                | Shared engine behind the endpoint factories. Walks a list of entries, runs a caller-supplied mapper, deduplicates by `@id`.                                                                                      |
+| **`seoSchema`, `imageSchema`** | Zod schemas for the `seo` and `image` fields on content collections. Import them into `src/content.config.ts`.                                                                                                   |
+| **`buildAstroSeoProps`**       | Pure-TS logic that powers `<Seo>` — exported for users who want to feed a different head component.                                                                                                              |
+
+## Not in v0.1 (deferred to v0.2)
+
+- **`createOgRenderer`** — a themeable `satori` + `sharp` wrapper for generating
+  Open Graph images at build time. Pulled out of v0.1 to keep the dep tree
+  free of native binaries. Keep using your own `og-image.ts` for now.
+
+## Installation
+
+```sh
+pnpm add @jdevalk/astro-seo-graph @jdevalk/seo-graph-core
+```
+
+`@jdevalk/seo-graph-core` is a direct dep of this package so it's installed
+transitively, but depending on it explicitly lets you pin the version and
+import piece builders directly.
+
+## `<Seo>` component
+
+```astro
+---
+import Seo from '@jdevalk/astro-seo-graph/Seo.astro';
+import { buildSchemaGraph } from '../utils/schema';
+
+const graph = buildSchemaGraph({
+    pageType: 'blogPost',
+    canonicalUrl: Astro.url.href,
+    title: 'My Post',
+    description: '…',
+    publishDate: new Date('2026-04-07'),
+});
+---
+
+<html>
+    <head>
+        <Seo
+            title="My Post"
+            titleTemplate="%s | Example"
+            description="…"
+            ogType="article"
+            ogImage="https://example.com/og/my-post.jpg"
+            ogImageAlt="My Post"
+            ogImageWidth={1200}
+            ogImageHeight={675}
+            siteName="Example"
+            twitter={{ site: '@example', creator: '@author' }}
+            article={{ publishedTime: new Date('2026-04-07'), tags: ['tech'] }}
+            graph={graph}
+            extraLinks={[
+                { rel: 'icon', type: 'image/svg+xml', href: '/favicon.svg' },
+                { rel: 'sitemap', href: '/sitemap-index.xml' },
+            ]}
+        />
+    </head>
+    <body>...</body>
+</html>
+```
+
+## Schema endpoints
+
+```ts
+// src/pages/schema/post.json.ts
+import { getCollection } from 'astro:content';
+import { createSchemaEndpoint } from '@jdevalk/astro-seo-graph';
+import { buildArticle, buildWebPage, makeIds } from '@jdevalk/seo-graph-core';
+
+const ids = makeIds({ siteUrl: 'https://example.com' });
+
+export const GET = createSchemaEndpoint({
+    entries: () => getCollection('blog'),
+    mapper: (post) => {
+        const url = `https://example.com/${post.id}/`;
+        return [
+            buildWebPage(
+                {
+                    url,
+                    name: post.data.title,
+                    isPartOf: { '@id': ids.website },
+                    breadcrumb: { '@id': ids.breadcrumb(url) },
+                    datePublished: post.data.publishDate,
+                },
+                ids,
+            ),
+            buildArticle(
+                {
+                    url,
+                    isPartOf: { '@id': ids.webPage(url) },
+                    author: { '@id': ids.person },
+                    publisher: { '@id': ids.person },
+                    headline: post.data.title,
+                    description: post.data.excerpt ?? '',
+                    datePublished: post.data.publishDate,
+                },
+                ids,
+            ),
+        ];
+    },
+});
+```
+
+## Schema map discovery
+
+```ts
+// src/pages/schemamap.xml.ts
+import { createSchemaMap } from '@jdevalk/astro-seo-graph';
+
+export const GET = createSchemaMap({
+    siteUrl: 'https://example.com',
+    entries: [
+        { path: '/schema/post.json', lastModified: new Date('2026-04-07') },
+        { path: '/schema/video.json', lastModified: new Date('2026-03-13') },
+    ],
+});
+```
+
+## Zod content helpers
+
+```ts
+// src/content.config.ts
+import { defineCollection, z } from 'astro:content';
+import { seoSchema } from '@jdevalk/astro-seo-graph';
+
+const blog = defineCollection({
+    schema: ({ image }) =>
+        z.object({
+            title: z.string(),
+            publishDate: z.coerce.date(),
+            seo: seoSchema(image).optional(),
+        }),
+});
+```
+
+## License
+
+MIT © Joost de Valk

package/dist/aggregator.d.ts

@@ -0,0 +1,27 @@
+import { type GraphEntity } from '@jdevalk/seo-graph-core';
+export interface AggregatorOptions<Entry> {
+    /** Content entries to walk, typically from Astro's `getCollection`. */
+    entries: readonly Entry[];
+    /**
+     * Map a single entry to an array of schema.org pieces. Return an
+     * empty array to skip the entry entirely (e.g. drafts). Pieces
+     * returned here are concatenated across entries; the aggregator
+     * deduplicates by `@id` with first-occurrence-wins semantics.
+     */
+    mapper: (entry: Entry) => ReadonlyArray<GraphEntity>;
+}
+export interface AggregatedGraph {
+    '@context': 'https://schema.org';
+    '@graph': GraphEntity[];
+}
+/**
+ * Walk a list of content entries, run the caller-supplied mapper over
+ * each one, concatenate all resulting pieces, and deduplicate by
+ * `@id`. Returns a ready-to-serialize `@graph` envelope.
+ *
+ * This is the shared engine behind `createSchemaEndpoint` — use it
+ * directly if you need custom wrapping, caching, or multiple-collection
+ * merging that the endpoint factories don't expose.
+ */
+export declare function aggregate<Entry>(options: AggregatorOptions<Entry>): AggregatedGraph;
+//# sourceMappingURL=aggregator.d.ts.map

package/dist/aggregator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregator.d.ts","sourceRoot":"","sources":["../src/aggregator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEjF,MAAM,WAAW,iBAAiB,CAAC,KAAK;IACpC,uEAAuE;IACvE,OAAO,EAAE,SAAS,KAAK,EAAE,CAAC;IAC1B;;;;;OAKG;IACH,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,aAAa,CAAC,WAAW,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,eAAe;IAC5B,UAAU,EAAE,oBAAoB,CAAC;IACjC,QAAQ,EAAE,WAAW,EAAE,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAAG,eAAe,CAWnF"}

package/dist/aggregator.js

@@ -0,0 +1,23 @@
+import { deduplicateByGraphId } from '@jdevalk/seo-graph-core';
+/**
+ * Walk a list of content entries, run the caller-supplied mapper over
+ * each one, concatenate all resulting pieces, and deduplicate by
+ * `@id`. Returns a ready-to-serialize `@graph` envelope.
+ *
+ * This is the shared engine behind `createSchemaEndpoint` — use it
+ * directly if you need custom wrapping, caching, or multiple-collection
+ * merging that the endpoint factories don't expose.
+ */
+export function aggregate(options) {
+    const pieces = [];
+    for (const entry of options.entries) {
+        for (const piece of options.mapper(entry)) {
+            pieces.push(piece);
+        }
+    }
+    return {
+        '@context': 'https://schema.org',
+        '@graph': deduplicateByGraphId(pieces),
+    };
+}
+//# sourceMappingURL=aggregator.js.map

package/dist/aggregator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregator.js","sourceRoot":"","sources":["../src/aggregator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAoB,MAAM,yBAAyB,CAAC;AAmBjF;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAQ,OAAiC;IAC9D,MAAM,MAAM,GAAkB,EAAE,CAAC;IACjC,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QAClC,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YACxC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;IACL,CAAC;IACD,OAAO;QACH,UAAU,EAAE,oBAAoB;QAChC,QAAQ,EAAE,oBAAoB,CAAC,MAAM,CAAC;KACzC,CAAC;AACN,CAAC"}

package/dist/components/Seo.astro

@@ -0,0 +1,14 @@
+---
+import { SEO } from 'astro-seo';
+import { buildAstroSeoProps, type SeoProps } from './seo-props.js';
+
+const props = Astro.props as SeoProps;
+const astroSeo = buildAstroSeoProps(props, Astro.url.href);
+---
+
+<SEO {...astroSeo} />
+{
+    props.graph && (
+        <script type="application/ld+json" set:html={JSON.stringify(props.graph)} />
+    )
+}

package/dist/components/seo-props.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Pure TypeScript layer for the <Seo> component. The .astro file is a
+ * thin template that calls `buildAstroSeoProps` with the user's input
+ * and an Astro context (mostly `Astro.url.href`). Keeping the logic
+ * here makes it unit-testable with vitest — Astro's renderer isn't
+ * easily accessible from vitest.
+ */
+/** Public props surface of the <Seo> component. */
+export interface SeoProps {
+    /** Page title. Required. */
+    title: string;
+    /**
+     * Template for composing the full `<title>`. Use `%s` where the
+     * title should be substituted. Defaults to the raw `title`.
+     *
+     * @example `"%s | Joost.blog"` → `"My Post | Joost.blog"`
+     */
+    titleTemplate?: string;
+    /** Meta description. */
+    description?: string;
+    /** Canonical URL. Defaults to the current page URL (`Astro.url.href`). */
+    canonical?: string | URL;
+    /** Open Graph type. Defaults to `'website'`. */
+    ogType?: 'website' | 'article' | 'profile' | 'book';
+    /** Absolute URL of the share image. */
+    ogImage?: string;
+    /** Alt text for the share image. */
+    ogImageAlt?: string;
+    /** Width of the share image in pixels. */
+    ogImageWidth?: number;
+    /** Height of the share image in pixels. */
+    ogImageHeight?: number;
+    /** Site name shown in OG tags, e.g. `"Joost.blog"`. */
+    siteName?: string;
+    /** OG locale. Defaults to `'en_US'`. */
+    locale?: string;
+    /** Twitter card metadata. */
+    twitter?: {
+        /** Twitter handle of the site owner, e.g. `'@jdevalk'`. */
+        site?: string;
+        /** Twitter handle of the author. */
+        creator?: string;
+        /** Card type. Defaults to `'summary_large_image'`. */
+        card?: 'summary' | 'summary_large_image' | 'app' | 'player';
+    };
+    /**
+     * Article-specific OG metadata. Only emitted when `ogType` is
+     * `'article'`.
+     */
+    article?: {
+        publishedTime?: Date | string;
+        modifiedTime?: Date | string;
+        expirationTime?: Date | string;
+        authors?: readonly string[];
+        tags?: readonly string[];
+        section?: string;
+    };
+    /** Emit `<meta name="robots" content="noindex, follow">` when `true`. */
+    noindex?: boolean;
+    /**
+     * JSON-LD `@graph` envelope to inject as
+     * `<script type="application/ld+json">`. Typically the output of
+     * `buildSchemaGraph(...)` or `assembleGraph(...)` from
+     * `@jdevalk/seo-graph-core`. Pass `null` or omit to skip JSON-LD.
+     */
+    graph?: Record<string, unknown> | null;
+    /** Extra `<link>` tags (icons, sitemap, RSS alternate, etc.). */
+    extraLinks?: ReadonlyArray<Record<string, string>>;
+    /** Extra `<meta>` tags (author, custom fields). */
+    extraMeta?: ReadonlyArray<Record<string, string>>;
+}
+/**
+ * Shape consumed by `astro-seo`'s `<SEO>` component. We expose it as a
+ * type so tests can assert on exact keys / nesting rather than having
+ * to parse rendered HTML.
+ */
+export interface AstroSeoProps {
+    title: string;
+    description?: string;
+    canonical: string;
+    noindex?: boolean;
+    openGraph: {
+        basic: {
+            title: string;
+            type: string;
+            image: string;
+            url: string;
+        };
+        optional?: {
+            description?: string;
+            siteName?: string;
+            locale?: string;
+        };
+        image?: {
+            alt?: string;
+            width?: number;
+            height?: number;
+        };
+        article?: {
+            publishedTime?: string;
+            modifiedTime?: string;
+            expirationTime?: string;
+            authors?: string[];
+            tags?: string[];
+            section?: string;
+        };
+    };
+    twitter?: {
+        card: 'summary' | 'summary_large_image' | 'app' | 'player';
+        site?: string;
+        creator?: string;
+        title: string;
+        description?: string;
+        image?: string;
+        imageAlt?: string;
+    };
+    extend?: {
+        link?: Array<Record<string, string>>;
+        meta?: Array<Record<string, string>>;
+    };
+}
+/**
+ * Project the public `SeoProps` onto the shape `astro-seo`'s `<SEO>`
+ * component expects. Pure function; no Astro runtime access.
+ *
+ * @param props      Props as provided by the user.
+ * @param pageUrl    The current page URL — usually `Astro.url.href`.
+ *                   Used as the canonical URL when `props.canonical` is
+ *                   not provided, and as the base for the OG `url`.
+ */
+export declare function buildAstroSeoProps(props: SeoProps, pageUrl: string): AstroSeoProps;
+//# sourceMappingURL=seo-props.d.ts.map

package/dist/components/seo-props.d.ts.map

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

package/dist/components/seo-props.js

@@ -0,0 +1,115 @@
+/**
+ * Pure TypeScript layer for the <Seo> component. The .astro file is a
+ * thin template that calls `buildAstroSeoProps` with the user's input
+ * and an Astro context (mostly `Astro.url.href`). Keeping the logic
+ * here makes it unit-testable with vitest — Astro's renderer isn't
+ * easily accessible from vitest.
+ */
+function toIsoString(value) {
+    if (value === undefined)
+        return undefined;
+    return value instanceof Date ? value.toISOString() : value;
+}
+/**
+ * Project the public `SeoProps` onto the shape `astro-seo`'s `<SEO>`
+ * component expects. Pure function; no Astro runtime access.
+ *
+ * @param props      Props as provided by the user.
+ * @param pageUrl    The current page URL — usually `Astro.url.href`.
+ *                   Used as the canonical URL when `props.canonical` is
+ *                   not provided, and as the base for the OG `url`.
+ */
+export function buildAstroSeoProps(props, pageUrl) {
+    const fullTitle = props.titleTemplate
+        ? props.titleTemplate.replace('%s', props.title)
+        : props.title;
+    const canonical = props.canonical !== undefined ? props.canonical.toString() : pageUrl;
+    const ogType = props.ogType ?? 'website';
+    const ogImage = props.ogImage ?? '';
+    const openGraph = {
+        basic: {
+            title: fullTitle,
+            type: ogType,
+            image: ogImage,
+            url: canonical,
+        },
+    };
+    const optional = {};
+    if (props.description !== undefined)
+        optional.description = props.description;
+    if (props.siteName !== undefined)
+        optional.siteName = props.siteName;
+    optional.locale = props.locale ?? 'en_US';
+    openGraph.optional = optional;
+    const hasImageMeta = props.ogImageAlt !== undefined ||
+        props.ogImageWidth !== undefined ||
+        props.ogImageHeight !== undefined;
+    if (ogImage && hasImageMeta) {
+        const image = {};
+        if (props.ogImageAlt !== undefined)
+            image.alt = props.ogImageAlt;
+        if (props.ogImageWidth !== undefined)
+            image.width = props.ogImageWidth;
+        if (props.ogImageHeight !== undefined)
+            image.height = props.ogImageHeight;
+        openGraph.image = image;
+    }
+    if (ogType === 'article' && props.article) {
+        const article = {};
+        const published = toIsoString(props.article.publishedTime);
+        if (published !== undefined)
+            article.publishedTime = published;
+        const modified = toIsoString(props.article.modifiedTime);
+        if (modified !== undefined)
+            article.modifiedTime = modified;
+        const expiration = toIsoString(props.article.expirationTime);
+        if (expiration !== undefined)
+            article.expirationTime = expiration;
+        if (props.article.authors !== undefined)
+            article.authors = [...props.article.authors];
+        if (props.article.tags !== undefined)
+            article.tags = [...props.article.tags];
+        if (props.article.section !== undefined)
+            article.section = props.article.section;
+        openGraph.article = article;
+    }
+    const astroSeo = {
+        title: fullTitle,
+        canonical,
+        openGraph,
+    };
+    if (props.description !== undefined)
+        astroSeo.description = props.description;
+    if (props.noindex)
+        astroSeo.noindex = true;
+    if (props.twitter !== undefined) {
+        const twitter = {
+            card: props.twitter.card ?? 'summary_large_image',
+            title: fullTitle,
+        };
+        if (props.twitter.site !== undefined)
+            twitter.site = props.twitter.site;
+        if (props.twitter.creator !== undefined)
+            twitter.creator = props.twitter.creator;
+        if (props.description !== undefined)
+            twitter.description = props.description;
+        if (ogImage)
+            twitter.image = ogImage;
+        if (props.ogImageAlt !== undefined)
+            twitter.imageAlt = props.ogImageAlt;
+        astroSeo.twitter = twitter;
+    }
+    if ((props.extraLinks !== undefined && props.extraLinks.length > 0) ||
+        (props.extraMeta !== undefined && props.extraMeta.length > 0)) {
+        const extend = {};
+        if (props.extraLinks !== undefined && props.extraLinks.length > 0) {
+            extend.link = props.extraLinks.map((link) => ({ ...link }));
+        }
+        if (props.extraMeta !== undefined && props.extraMeta.length > 0) {
+            extend.meta = props.extraMeta.map((meta) => ({ ...meta }));
+        }
+        astroSeo.extend = extend;
+    }
+    return astroSeo;
+}
+//# sourceMappingURL=seo-props.js.map

package/dist/components/seo-props.js.map

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

package/dist/content-helpers.d.ts

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+/**
+ * Astro content-collection `image` function signature, captured as `any`
+ * to avoid importing from the `astro:content` virtual module (which
+ * only resolves inside an Astro project, not in a standalone package).
+ * Users pass through their own `image` from Astro's schema callback.
+ */
+type AstroImageFunction = any;
+/**
+ * Zod schema for an image field on a content entry. Pair with Astro's
+ * `image()` from the collection schema factory so the image is processed
+ * through Astro's asset pipeline.
+ *
+ * @example
+ * ```ts
+ * import { defineCollection, z } from 'astro:content';
+ * import { imageSchema } from '@jdevalk/astro-seo-graph';
+ *
+ * const blog = defineCollection({
+ *   schema: ({ image }) =>
+ *     z.object({
+ *       title: z.string(),
+ *       featureImage: imageSchema(image).optional(),
+ *     }),
+ * });
+ * ```
+ */
+export declare function imageSchema(image: AstroImageFunction): z.ZodObject<{
+    src: any;
+    alt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    src?: any;
+    alt?: string | undefined;
+}, {
+    src?: any;
+    alt?: string | undefined;
+}>;
+/**
+ * Zod schema for a nested `seo` field holding per-entry SEO overrides:
+ * title, description, share image, and page type. Enforces reasonable
+ * length limits (5–120 chars for title, 15–160 for description) as a
+ * lint.
+ *
+ * @example
+ * ```ts
+ * const blog = defineCollection({
+ *   schema: ({ image }) =>
+ *     z.object({
+ *       title: z.string(),
+ *       seo: seoSchema(image).optional(),
+ *     }),
+ * });
+ * ```
+ */
+export declare function seoSchema(image: AstroImageFunction): z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    image: z.ZodOptional<z.ZodObject<{
+        src: any;
+        alt: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        src?: any;
+        alt?: string | undefined;
+    }, {
+        src?: any;
+        alt?: string | undefined;
+    }>>;
+    pageType: z.ZodDefault<z.ZodEnum<["website", "article"]>>;
+}, "strip", z.ZodTypeAny, {
+    pageType: "website" | "article";
+    title?: string | undefined;
+    description?: string | undefined;
+    image?: {
+        src?: any;
+        alt?: string | undefined;
+    } | undefined;
+}, {
+    title?: string | undefined;
+    description?: string | undefined;
+    image?: {
+        src?: any;
+        alt?: string | undefined;
+    } | undefined;
+    pageType?: "website" | "article" | undefined;
+}>;
+export {};
+//# sourceMappingURL=content-helpers.d.ts.map

package/dist/content-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-helpers.d.ts","sourceRoot":"","sources":["../src/content-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AAEH,KAAK,kBAAkB,GAAG,GAAG,CAAC;AAE9B;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,kBAAkB;;;;;;;;;GAKpD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAOlD"}

package/dist/content-helpers.js

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+/**
+ * Zod schema for an image field on a content entry. Pair with Astro's
+ * `image()` from the collection schema factory so the image is processed
+ * through Astro's asset pipeline.
+ *
+ * @example
+ * ```ts
+ * import { defineCollection, z } from 'astro:content';
+ * import { imageSchema } from '@jdevalk/astro-seo-graph';
+ *
+ * const blog = defineCollection({
+ *   schema: ({ image }) =>
+ *     z.object({
+ *       title: z.string(),
+ *       featureImage: imageSchema(image).optional(),
+ *     }),
+ * });
+ * ```
+ */
+export function imageSchema(image) {
+    return z.object({
+        src: image(),
+        alt: z.string().optional(),
+    });
+}
+/**
+ * Zod schema for a nested `seo` field holding per-entry SEO overrides:
+ * title, description, share image, and page type. Enforces reasonable
+ * length limits (5–120 chars for title, 15–160 for description) as a
+ * lint.
+ *
+ * @example
+ * ```ts
+ * const blog = defineCollection({
+ *   schema: ({ image }) =>
+ *     z.object({
+ *       title: z.string(),
+ *       seo: seoSchema(image).optional(),
+ *     }),
+ * });
+ * ```
+ */
+export function seoSchema(image) {
+    return z.object({
+        title: z.string().min(5).max(120).optional(),
+        description: z.string().min(15).max(160).optional(),
+        image: imageSchema(image).optional(),
+        pageType: z.enum(['website', 'article']).default('website'),
+    });
+}
+//# sourceMappingURL=content-helpers.js.map

package/dist/content-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-helpers.js","sourceRoot":"","sources":["../src/content-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,WAAW,CAAC,KAAyB;IACjD,OAAO,CAAC,CAAC,MAAM,CAAC;QACZ,GAAG,EAAE,KAAK,EAAE;QACZ,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAC7B,CAAC,CAAC;AACP,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,SAAS,CAAC,KAAyB;IAC/C,OAAO,CAAC,CAAC,MAAM,CAAC;QACZ,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;QAC5C,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;QACnD,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE;QACpC,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;KAC9D,CAAC,CAAC;AACP,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { aggregate } from './aggregator.js';
+export type { AggregatorOptions, AggregatedGraph } from './aggregator.js';
+export { createSchemaEndpoint, createSchemaMap } from './routes.js';
+export type { SchemaEndpointOptions, SchemaMapEntry, SchemaMapOptions } from './routes.js';
+export { seoSchema, imageSchema } from './content-helpers.js';
+export { buildAstroSeoProps } from './components/seo-props.js';
+export type { SeoProps, AstroSeoProps } from './components/seo-props.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAE1E,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACpE,YAAY,EAAE,qBAAqB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE3F,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAE9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+// @jdevalk/astro-seo-graph — Astro integration for agent-ready schema.org SEO.
+//
+// The `<Seo>` component lives at `./Seo.astro` and must be imported via
+// the subpath export: `import Seo from '@jdevalk/astro-seo-graph/Seo.astro'`.
+// Its props surface is `SeoProps`, re-exported below.
+export { aggregate } from './aggregator.js';
+export { createSchemaEndpoint, createSchemaMap } from './routes.js';
+export { seoSchema, imageSchema } from './content-helpers.js';
+export { buildAstroSeoProps } from './components/seo-props.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,EAAE;AACF,wEAAwE;AACxE,8EAA8E;AAC9E,sDAAsD;AAEtD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG5C,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGpE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAE9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/routes.d.ts

@@ -0,0 +1,94 @@
+import type { APIRoute } from 'astro';
+import type { GraphEntity } from '@jdevalk/seo-graph-core';
+export interface SchemaEndpointOptions<Entry> {
+    /**
+     * Async source of content entries. Usually a thin wrapper around
+     * Astro's `getCollection`, e.g. `() => getCollection('blog')`, or
+     * a filtered variant: `() => (await getCollection('blog')).filter(isPublished)`.
+     */
+    entries: () => Promise<readonly Entry[]>;
+    /**
+     * Map a single entry to an array of schema.org pieces. The pieces
+     * are assembled into a single `@graph` via the aggregator and
+     * deduplicated by `@id`.
+     */
+    mapper: (entry: Entry) => ReadonlyArray<GraphEntity>;
+    /**
+     * `Cache-Control` header value. Defaults to `max-age=300` (5 min).
+     * Pass `null` to omit the header entirely.
+     */
+    cacheControl?: string | null;
+    /**
+     * `Content-Type` header value. Defaults to `application/ld+json`.
+     */
+    contentType?: string;
+    /**
+     * JSON output indentation. Defaults to `2`. Pass `0` for compact
+     * output.
+     */
+    indent?: number;
+}
+/**
+ * Returns an Astro `APIRoute` that serves a corpus-wide schema.org
+ * `@graph` for a content collection as JSON-LD. Drop the returned
+ * handler into an `.ts` file under `src/pages/`.
+ *
+ * @example
+ * ```ts
+ * // src/pages/schema/post.json.ts
+ * import { getCollection } from 'astro:content';
+ * import { createSchemaEndpoint } from '@jdevalk/astro-seo-graph';
+ * import { buildArticle, buildWebPage } from '@jdevalk/seo-graph-core';
+ *
+ * export const GET = createSchemaEndpoint({
+ *   entries: () => getCollection('blog'),
+ *   mapper: (post) => [
+ *     buildWebPage({ url: `https://example.com/${post.id}/`, ... }, ids),
+ *     buildArticle({ url: `https://example.com/${post.id}/`, ... }, ids),
+ *   ],
+ * });
+ * ```
+ */
+export declare function createSchemaEndpoint<Entry>(options: SchemaEndpointOptions<Entry>): APIRoute;
+export interface SchemaMapEntry {
+    /**
+     * URL path relative to the site root, e.g. `/schema/post.json`.
+     * May start with or without a leading slash.
+     */
+    path: string;
+    /** When the resource at this path was last modified. */
+    lastModified: Date;
+    /** Defaults to `'daily'`. */
+    changeFreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+    /** 0.0–1.0. Defaults to `0.8`. */
+    priority?: number;
+}
+export interface SchemaMapOptions {
+    /** Canonical site URL. Trailing slash is stripped. */
+    siteUrl: string;
+    /** One entry per schema endpoint. */
+    entries: readonly SchemaMapEntry[];
+    /** Defaults to `max-age=300`. Pass `null` to omit. */
+    cacheControl?: string | null;
+}
+/**
+ * Returns an Astro `APIRoute` that serves a sitemap-style XML listing
+ * of the site's schema.org endpoints. Agent crawlers can use this as
+ * a discovery point for a site's JSON-LD knowledge graph.
+ *
+ * @example
+ * ```ts
+ * // src/pages/schemamap.xml.ts
+ * import { createSchemaMap } from '@jdevalk/astro-seo-graph';
+ *
+ * export const GET = createSchemaMap({
+ *   siteUrl: 'https://example.com',
+ *   entries: [
+ *     { path: '/schema/post.json', lastModified: new Date('2026-04-07') },
+ *     { path: '/schema/video.json', lastModified: new Date('2026-03-13') },
+ *   ],
+ * });
+ * ```
+ */
+export declare function createSchemaMap(options: SchemaMapOptions): APIRoute;
+//# sourceMappingURL=routes.d.ts.map

package/dist/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAG3D,MAAM,WAAW,qBAAqB,CAAC,KAAK;IACxC;;;;OAIG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,SAAS,KAAK,EAAE,CAAC,CAAC;IACzC;;;;OAIG;IACH,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,aAAa,CAAC,WAAW,CAAC,CAAC;IACrD;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,qBAAqB,CAAC,KAAK,CAAC,GAAG,QAAQ,CAY3F;AAED,MAAM,WAAW,cAAc;IAC3B;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,YAAY,EAAE,IAAI,CAAC;IACnB,6BAA6B;IAC7B,UAAU,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;IACvF,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC7B,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IACnC,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAWD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,QAAQ,CA8BnE"}

package/dist/routes.js

@@ -0,0 +1,92 @@
+import { aggregate } from './aggregator.js';
+/**
+ * Returns an Astro `APIRoute` that serves a corpus-wide schema.org
+ * `@graph` for a content collection as JSON-LD. Drop the returned
+ * handler into an `.ts` file under `src/pages/`.
+ *
+ * @example
+ * ```ts
+ * // src/pages/schema/post.json.ts
+ * import { getCollection } from 'astro:content';
+ * import { createSchemaEndpoint } from '@jdevalk/astro-seo-graph';
+ * import { buildArticle, buildWebPage } from '@jdevalk/seo-graph-core';
+ *
+ * export const GET = createSchemaEndpoint({
+ *   entries: () => getCollection('blog'),
+ *   mapper: (post) => [
+ *     buildWebPage({ url: `https://example.com/${post.id}/`, ... }, ids),
+ *     buildArticle({ url: `https://example.com/${post.id}/`, ... }, ids),
+ *   ],
+ * });
+ * ```
+ */
+export function createSchemaEndpoint(options) {
+    const cacheControl = options.cacheControl === undefined ? 'max-age=300' : options.cacheControl;
+    const contentType = options.contentType ?? 'application/ld+json';
+    const indent = options.indent ?? 2;
+    return async () => {
+        const entries = await options.entries();
+        const graph = aggregate({ entries, mapper: options.mapper });
+        const headers = { 'Content-Type': contentType };
+        if (cacheControl !== null)
+            headers['Cache-Control'] = cacheControl;
+        return new Response(JSON.stringify(graph, null, indent), { headers });
+    };
+}
+function escapeXml(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+/**
+ * Returns an Astro `APIRoute` that serves a sitemap-style XML listing
+ * of the site's schema.org endpoints. Agent crawlers can use this as
+ * a discovery point for a site's JSON-LD knowledge graph.
+ *
+ * @example
+ * ```ts
+ * // src/pages/schemamap.xml.ts
+ * import { createSchemaMap } from '@jdevalk/astro-seo-graph';
+ *
+ * export const GET = createSchemaMap({
+ *   siteUrl: 'https://example.com',
+ *   entries: [
+ *     { path: '/schema/post.json', lastModified: new Date('2026-04-07') },
+ *     { path: '/schema/video.json', lastModified: new Date('2026-03-13') },
+ *   ],
+ * });
+ * ```
+ */
+export function createSchemaMap(options) {
+    const cacheControl = options.cacheControl === undefined ? 'max-age=300' : options.cacheControl;
+    const site = options.siteUrl.replace(/\/+$/, '');
+    return async () => {
+        const urls = options.entries
+            .map((entry) => {
+            const pathPart = entry.path.startsWith('/') ? entry.path : `/${entry.path}`;
+            const loc = escapeXml(`${site}${pathPart}`);
+            const lastmod = entry.lastModified.toISOString().split('T')[0];
+            const changefreq = entry.changeFreq ?? 'daily';
+            const priority = entry.priority ?? 0.8;
+            return `  <url contentType="structuredData/schema.org">
+    <loc>${loc}</loc>
+    <lastmod>${lastmod}</lastmod>
+    <changefreq>${changefreq}</changefreq>
+    <priority>${priority}</priority>
+  </url>`;
+        })
+            .join('\n');
+        const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${urls}
+</urlset>`;
+        const headers = { 'Content-Type': 'application/xml' };
+        if (cacheControl !== null)
+            headers['Cache-Control'] = cacheControl;
+        return new Response(xml, { headers });
+    };
+}
+//# sourceMappingURL=routes.js.map

package/dist/routes.js.map

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

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@jdevalk/astro-seo-graph",
+  "version": "0.1.0-alpha.1",
+  "description": "Astro integration for @jdevalk/seo-graph-core. Seo component, route factories, content-collection aggregator, Zod content helpers.",
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "astro-component",
+    "schema.org",
+    "json-ld",
+    "seo",
+    "agent-ready",
+    "structured-data"
+  ],
+  "author": "Joost de Valk <joost@joost.blog>",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./Seo.astro": "./dist/components/Seo.astro"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jdevalk/seo-graph.git",
+    "directory": "packages/astro-seo-graph"
+  },
+  "bugs": "https://github.com/jdevalk/seo-graph/issues",
+  "homepage": "https://github.com/jdevalk/seo-graph/tree/main/packages/astro-seo-graph#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "astro": "^5.0.0 || ^6.0.0"
+  },
+  "dependencies": {
+    "astro-seo": "^1.1.0",
+    "schema-dts": "^2.0.0",
+    "zod": "^3.24.0",
+    "@jdevalk/seo-graph-core": "0.1.0-alpha.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "astro": "^6.0.5",
+    "typescript": "^5.6.0",
+    "vitest": "^2.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && mkdir -p dist/components && cp src/components/*.astro dist/components/",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
+}