@jdevalk/astro-seo-graph 1.3.0 → 1.4.0

package/AGENTS.md

@@ -2516,10 +2516,89 @@ export const GET = createSchemaMap({
 **Schema map entry options:**
 | Field | Type | Default | Purpose |
 |---|---|---|---|
-| `path` | `string` | — | Relative path to schema endpoint |
-| `lastModified` | `Date` | — | Last modification date |
-| `changeFreq` | Sitemap frequency string | `'daily'` | Update frequency hint |
-| `priority` | `number` | `0.8` | Priority hint (0.0-1.0) |
+| `path` | `string` | — | Path of the schema endpoint. Leading slash optional. |
+| `lastModified` | `Date` | — | Last-modified date. Rendered as `YYYY-MM-DD`. |
+
+**`createSchemaMap` options:**
+| Option | Type | Default | Purpose |
+|---|---|---|---|
+| `siteUrl` | `string` | — | Canonical origin. Trailing slash stripped. |
+| `entries` | `SchemaMapEntry[]` | — | One entry per schema endpoint. |
+| `cacheControl` | `string \| null` | `'max-age=300'` | Cache-Control header. `null` to omit. |
+
+`<changefreq>` and `<priority>` are deliberately not emitted —
+Google and other major crawlers ignore them, and fabricating defaults
+is worse than omitting.
+
+### API catalog (RFC 9727)
+
+Serve a standards-compliant API catalog at `/.well-known/api-catalog`
+([RFC 9727](https://www.rfc-editor.org/rfc/rfc9727)) so agent crawlers
+can discover the site's APIs in one fetch:
+
+```ts
+// src/pages/.well-known/api-catalog.ts
+import { createApiCatalog } from '@jdevalk/astro-seo-graph';
+
+export const GET = createApiCatalog({
+    siteUrl: 'https://example.com',
+    schemaEndpoints: [
+        { path: '/schema/post.json', schemaType: 'BlogPosting', serviceDoc: '/seo-graph/' },
+        { path: '/schema/page.json', schemaType: 'WebPage', serviceDoc: '/seo-graph/' },
+    ],
+    schemaMap: { path: '/schemamap.xml', serviceDoc: '/seo-graph/' },
+    additional: [
+        { anchor: '/ask', serviceDoc: '/ask-docs/', type: 'https://schema.org/SearchAction' },
+    ],
+});
+```
+
+Output is `application/linkset+json` ([RFC 9264](https://www.rfc-editor.org/rfc/rfc9264)).
+`schemaEndpoints` get auto-typed as `https://schema.org/<schemaType>`;
+`schemaMap` is emitted without a `type` (no standard one exists);
+`additional` accepts free-form `anchor`/`serviceDoc`/`type` (each
+either `string` or `string[]`). Relative paths are absolutized against
+`siteUrl`; absolute URLs pass through unchanged.
+
+The package also exports a `CATALOG_PATH` constant
+(`'/.well-known/api-catalog'`) so callers can reference the canonical
+location without duplicating the string.
+
+**Options:**
+| Option | Type | Default | Purpose |
+|---|---|---|---|
+| `siteUrl` | `string` | — | Canonical origin. Trailing slash stripped. |
+| `schemaEndpoints` | `ApiCatalogSchemaEndpointEntry[]` | — | Schema.org JSON endpoints with `path` + `schemaType`. |
+| `schemaMap` | `ApiCatalogSchemaMapEntry` | — | Path of the `createSchemaMap` route. |
+| `additional` | `ApiCatalogEntry[]` | — | Site-specific APIs not covered by the package factories. |
+| `cacheControl` | `string \| null` | `'max-age=300'` | Cache-Control header. `null` to omit. |
+| `contentType` | `string` | `'application/linkset+json'` | Override only with reason. |
+| `indent` | `number` | `2` | JSON indentation. `0` for compact. |
+
+### Last-modified dates from git
+
+`gitLastmod` reads the committer date of the most recent git commit
+that touched a file, with configurable `excludeCommits` (skip bulk
+imports / reformats / renames) and `depth` (how many commits to
+inspect). Use it to feed `dateModified` on JSON-LD pieces or
+`<lastmod>` in sitemaps without trusting filesystem `mtime` (which
+gets rewritten on every CI checkout):
+
+```ts
+import { gitLastmod } from '@jdevalk/astro-seo-graph';
+
+const last = gitLastmod(`src/content/blog/${entry.id}/index.md`, {
+    excludeCommits: ['52130a9', '989dc47'],
+    depth: 20,
+});
+```
+
+Returns `null` when the file has no git history, git isn't on the
+PATH, or every commit in the inspected window is excluded — fall back
+to `publishDate` in that case. `excludeCommits` matches on the first 7
+characters of the SHA, so short hashes from `git log --oneline` work
+directly. Build-time only — shells out to the `git` binary via
+`execFileSync`.
 
 ### The `aggregate` function
 

package/README.md

@@ -32,6 +32,8 @@ schema.org best practices — see [AGENTS.md](https://github.com/jdevalk/seo-gra
 | **`createIndexNowKeyRoute`**   | Factory returning an `APIRoute` that serves the IndexNow key-verification file at `/<key>.txt`. Pair with the `indexNow` option on the integration to auto-submit built URLs on `astro:build:done`.                                                                     |
 | **`createMarkdownEndpoint`**   | Factory returning an `APIRoute` that serves a clean markdown version of a content-collection entry (frontmatter + body + token count). Pair with the auto-emitted `<link rel="alternate" type="text/markdown">` on `<Seo>` for AI-agent discovery.                      |
 | **`renderMarkdownAlternate`**  | Pure renderer behind the endpoint. Importable from non-Astro code for the same markdown output.                                                                                                                                                                         |
+| **`gitLastmod`**               | Reads the committer date of the most recent git commit that touched a file, skipping caller-supplied bulk commits. Use it to derive trustworthy `dateModified` / `<lastmod>` values from git history.                                                                   |
+| **`createApiCatalog`**         | Factory returning an `APIRoute` that serves an [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727) API catalog at `/.well-known/api-catalog`. Lists schema endpoints, the schema map, and any additional APIs as `application/linkset+json`.                             |
 
 ## Installation
 
@@ -396,6 +398,50 @@ const { markdown, tokenCount, canonicalHref } = renderMarkdownAlternate({
 });
 ```
 
+## Last-modified dates from git
+
+`gitLastmod` reads the committer date of the most recent git commit that
+touched a file. Use it to feed `dateModified` on JSON-LD pieces or
+`<lastmod>` in sitemaps without trusting filesystem `mtime` (which gets
+rewritten on every CI checkout).
+
+```ts
+import { gitLastmod } from '@jdevalk/astro-seo-graph';
+
+const last = gitLastmod(`src/content/blog/${entry.id}/index.md`, {
+    // Hashes of bulk commits (imports, reformats, renames) that
+    // shouldn't count as a "real" content update. Short or full SHAs.
+    excludeCommits: ['52130a9', '989dc47'],
+    // How many commits back to inspect. Default: 10.
+    depth: 20,
+});
+```
+
+Returns `null` when the file has no git history, when git isn't on the
+PATH, or when every commit in the inspected window is excluded — callers
+should fall back to `publishDate` (or skip the field) in that case.
+
+`excludeCommits` matches on the first 7 characters of the SHA, so short
+hashes from `git log --oneline` work directly. Increase `depth` if your
+exclusion list could shadow the real last-modified commit; the default
+of 10 is enough for most blogs.
+
+A common pattern is to use `gitLastmod` to compute an effective
+"updated" date only when it materially differs from the publish date:
+
+```ts
+function computeUpdatedDate(filePath: string, publishDate: Date): Date | null {
+    const last = gitLastmod(filePath);
+    if (!last) return null;
+    const ONE_DAY = 24 * 60 * 60 * 1000;
+    return last.getTime() - publishDate.getTime() > ONE_DAY ? last : null;
+}
+```
+
+`gitLastmod` shells out to the `git` binary, so it only works during
+build (Node) — not in browser bundles or edge runtimes that lack
+`child_process`. Resolve the path relative to your build CWD.
+
 ## Schema map discovery
 
 ```ts
@@ -411,6 +457,60 @@ export const GET = createSchemaMap({
 });
 ```
 
+## API catalog (RFC 9727)
+
+[RFC 9727](https://www.rfc-editor.org/rfc/rfc9727) defines
+`/.well-known/api-catalog` as the standard discovery point for a site's
+APIs. `createApiCatalog` returns an `APIRoute` that serves an
+`application/linkset+json` document ([RFC 9264](https://www.rfc-editor.org/rfc/rfc9264))
+listing each endpoint with its anchor URL, optional documentation
+links, and optional type pointers.
+
+```ts
+// src/pages/.well-known/api-catalog.ts
+import { createApiCatalog } from '@jdevalk/astro-seo-graph';
+
+export const GET = createApiCatalog({
+    siteUrl: 'https://example.com',
+    schemaEndpoints: [
+        { path: '/schema/post.json', schemaType: 'BlogPosting', serviceDoc: '/seo-graph/' },
+        { path: '/schema/page.json', schemaType: 'WebPage', serviceDoc: '/seo-graph/' },
+    ],
+    schemaMap: { path: '/schemamap.xml', serviceDoc: '/seo-graph/' },
+    additional: [
+        {
+            anchor: '/ask',
+            serviceDoc: '/ask-docs/',
+            type: 'https://schema.org/SearchAction',
+        },
+    ],
+});
+```
+
+Three categories of entry:
+
+- **`schemaEndpoints`** — the same set you wired into `createSchemaEndpoint`. Each becomes a linkset entry with `type: [{ href: 'https://schema.org/<schemaType>' }]` filled in for you.
+- **`schemaMap`** — the path of the route from `createSchemaMap`. Emitted without a `type` (no standard type exists for the schemamap format).
+- **`additional`** — site-specific APIs not covered by the package's own factories. Pass `anchor`, optional `serviceDoc`, and optional `type` (each accepting `string` or `string[]`).
+
+Relative paths in any field are absolutized against `siteUrl`; absolute
+URLs pass through unchanged. The trailing slash on `siteUrl` is
+stripped, mirroring `createSchemaMap`.
+
+The package also exports a `CATALOG_PATH` constant
+(`'/.well-known/api-catalog'`) for callers who want to reference the
+catalog from `_headers` files, the schemamap, or documentation links
+without duplicating the string.
+
+Response headers:
+
+- `Content-Type: application/linkset+json`
+- `Cache-Control: max-age=300` (override or pass `null` to omit)
+- `X-Robots-Tag: noindex, follow`
+
+Empty options yield `{ "linkset": [] }` — valid per RFC 9727 §3 and
+useful for sites that want to declare "no APIs" explicitly.
+
 ## Zod content helpers
 
 ```ts

package/dist/api-catalog.d.ts

@@ -0,0 +1,93 @@
+import type { APIRoute } from 'astro';
+/**
+ * Standard path for the API catalog per RFC 9727. Exported so callers
+ * can reference it from `_headers` files, schemamap entries, or
+ * documentation links without duplicating the string.
+ */
+export declare const CATALOG_PATH = "/.well-known/api-catalog";
+export interface ApiCatalogEntry {
+    /**
+     * URL or path of the API endpoint. Relative paths are resolved
+     * against `siteUrl`; absolute URLs pass through unchanged.
+     */
+    anchor: string;
+    /**
+     * Documentation URL(s). Single string is normalized to a one-item
+     * array. Relative paths resolved against `siteUrl`.
+     */
+    serviceDoc?: string | readonly string[];
+    /**
+     * Type URL(s). For schema.org endpoints, a `https://schema.org/<Type>`
+     * URL. For OpenAPI-described services, the OAS document URL. Single
+     * string is normalized to a one-item array.
+     */
+    type?: string | readonly string[];
+}
+export interface ApiCatalogSchemaEndpointEntry {
+    /** Path of the endpoint, e.g. `/schema/post.json`. */
+    path: string;
+    /**
+     * Schema.org type emitted, e.g. `BlogPosting`. Becomes
+     * `https://schema.org/<Type>` in the `type` field.
+     */
+    schemaType: string;
+    /** Optional documentation URL. */
+    serviceDoc?: string;
+}
+export interface ApiCatalogSchemaMapEntry {
+    /** Path of the schemamap, e.g. `/schemamap.xml`. */
+    path: string;
+    /** Optional documentation URL. */
+    serviceDoc?: string;
+}
+export interface ApiCatalogOptions {
+    /** Canonical site URL. Trailing slash is stripped. */
+    siteUrl: string;
+    /**
+     * Schema.org JSON endpoints, typically the same set wired into
+     * `createSchemaEndpoint` calls. Each entry is emitted with
+     * `type: [{ href: "https://schema.org/<schemaType>" }]`.
+     */
+    schemaEndpoints?: readonly ApiCatalogSchemaEndpointEntry[];
+    /**
+     * Schema map endpoint, typically the path of the route created by
+     * `createSchemaMap`. Emitted without a `type` (no standard type
+     * exists for the schemamap format).
+     */
+    schemaMap?: ApiCatalogSchemaMapEntry;
+    /** Site-specific APIs not covered by the package's own factories. */
+    additional?: readonly ApiCatalogEntry[];
+    /** Defaults to `max-age=300`. Pass `null` to omit. */
+    cacheControl?: string | null;
+    /**
+     * Content-Type header. Defaults to `application/linkset+json` per
+     * RFC 9727 / RFC 9264. Override only if you have a reason.
+     */
+    contentType?: string;
+    /** JSON indentation. Defaults to `2`. Pass `0` for compact output. */
+    indent?: number;
+}
+/**
+ * Returns an Astro `APIRoute` that serves an RFC 9727 API catalog
+ * (`application/linkset+json`, RFC 9264) at `/.well-known/api-catalog`.
+ *
+ * Lists the site's APIs — schema.org JSON endpoints, the schema map,
+ * and any additional services — with anchor URLs, optional service-doc
+ * URLs, and type pointers. Drop the returned handler into
+ * `src/pages/.well-known/api-catalog.ts`.
+ *
+ * @example
+ * ```ts
+ * import { createApiCatalog } from '@jdevalk/astro-seo-graph';
+ *
+ * export const GET = createApiCatalog({
+ *   siteUrl: 'https://example.com',
+ *   schemaEndpoints: [
+ *     { path: '/schema/post.json', schemaType: 'BlogPosting' },
+ *   ],
+ *   schemaMap: { path: '/schemamap.xml' },
+ * });
+ * ```
+ */
+export declare function createApiCatalog(options: ApiCatalogOptions): APIRoute;
+//# sourceMappingURL=api-catalog.d.ts.map

package/dist/api-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-catalog.d.ts","sourceRoot":"","sources":["../src/api-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,YAAY,6BAA6B,CAAC;AAEvD,MAAM,WAAW,eAAe;IAC5B;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IACxC;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,6BAA6B;IAC1C,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,wBAAwB;IACrC,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAC9B,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,eAAe,CAAC,EAAE,SAAS,6BAA6B,EAAE,CAAC;IAC3D;;;;OAIG;IACH,SAAS,CAAC,EAAE,wBAAwB,CAAC;IACrC,qEAAqE;IACrE,UAAU,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACxC,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAwBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,QAAQ,CA6CrE"}

package/dist/api-catalog.js

@@ -0,0 +1,88 @@
+/**
+ * Standard path for the API catalog per RFC 9727. Exported so callers
+ * can reference it from `_headers` files, schemamap entries, or
+ * documentation links without duplicating the string.
+ */
+export const CATALOG_PATH = '/.well-known/api-catalog';
+function absolutize(value, site) {
+    if (/^https?:\/\//i.test(value))
+        return value;
+    const path = value.startsWith('/') ? value : `/${value}`;
+    return `${site}${path}`;
+}
+function toHrefArray(value, site) {
+    if (value === undefined)
+        return undefined;
+    const arr = typeof value === 'string' ? [value] : value;
+    if (arr.length === 0)
+        return undefined;
+    return arr.map((v) => ({ href: absolutize(v, site) }));
+}
+/**
+ * Returns an Astro `APIRoute` that serves an RFC 9727 API catalog
+ * (`application/linkset+json`, RFC 9264) at `/.well-known/api-catalog`.
+ *
+ * Lists the site's APIs — schema.org JSON endpoints, the schema map,
+ * and any additional services — with anchor URLs, optional service-doc
+ * URLs, and type pointers. Drop the returned handler into
+ * `src/pages/.well-known/api-catalog.ts`.
+ *
+ * @example
+ * ```ts
+ * import { createApiCatalog } from '@jdevalk/astro-seo-graph';
+ *
+ * export const GET = createApiCatalog({
+ *   siteUrl: 'https://example.com',
+ *   schemaEndpoints: [
+ *     { path: '/schema/post.json', schemaType: 'BlogPosting' },
+ *   ],
+ *   schemaMap: { path: '/schemamap.xml' },
+ * });
+ * ```
+ */
+export function createApiCatalog(options) {
+    const cacheControl = options.cacheControl === undefined ? 'max-age=300' : options.cacheControl;
+    const contentType = options.contentType ?? 'application/linkset+json';
+    const indent = options.indent ?? 2;
+    const site = options.siteUrl.replace(/\/+$/, '');
+    return async () => {
+        const linkset = [];
+        if (options.schemaEndpoints) {
+            for (const e of options.schemaEndpoints) {
+                const entry = { anchor: absolutize(e.path, site) };
+                const sd = toHrefArray(e.serviceDoc, site);
+                if (sd)
+                    entry['service-doc'] = sd;
+                entry.type = [{ href: `https://schema.org/${e.schemaType}` }];
+                linkset.push(entry);
+            }
+        }
+        if (options.schemaMap) {
+            const entry = { anchor: absolutize(options.schemaMap.path, site) };
+            const sd = toHrefArray(options.schemaMap.serviceDoc, site);
+            if (sd)
+                entry['service-doc'] = sd;
+            linkset.push(entry);
+        }
+        if (options.additional) {
+            for (const e of options.additional) {
+                const entry = { anchor: absolutize(e.anchor, site) };
+                const sd = toHrefArray(e.serviceDoc, site);
+                if (sd)
+                    entry['service-doc'] = sd;
+                const t = toHrefArray(e.type, site);
+                if (t)
+                    entry.type = t;
+                linkset.push(entry);
+            }
+        }
+        const headers = {
+            'Content-Type': contentType,
+            'X-Robots-Tag': 'noindex, follow',
+        };
+        if (cacheControl !== null)
+            headers['Cache-Control'] = cacheControl;
+        return new Response(JSON.stringify({ linkset }, null, indent), { headers });
+    };
+}
+//# sourceMappingURL=api-catalog.js.map

package/dist/api-catalog.js.map

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

package/dist/git-lastmod.d.ts

@@ -0,0 +1,16 @@
+export interface GitLastmodOptions {
+    /** Commit hashes (short or full) to skip when searching for the last meaningful change. */
+    excludeCommits?: string[];
+    /** How many commits to inspect. Defaults to 10. */
+    depth?: number;
+}
+/**
+ * Returns the committer date of the most recent git commit that touched
+ * `filePath`, skipping any commits listed in `excludeCommits`. Useful for
+ * generating accurate `<lastmod>` values in sitemaps when bulk commits (
+ * imports, reformats, renames) would otherwise produce misleading dates.
+ *
+ * Returns `null` when the file has no git history or git is unavailable.
+ */
+export declare function gitLastmod(filePath: string, options?: GitLastmodOptions): Date | null;
+//# sourceMappingURL=git-lastmod.d.ts.map

package/dist/git-lastmod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-lastmod.d.ts","sourceRoot":"","sources":["../src/git-lastmod.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,iBAAiB;IAC9B,2FAA2F;IAC3F,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,IAAI,GAAG,IAAI,CAkBzF"}

package/dist/git-lastmod.js

@@ -0,0 +1,31 @@
+import { execFileSync } from 'child_process';
+/**
+ * Returns the committer date of the most recent git commit that touched
+ * `filePath`, skipping any commits listed in `excludeCommits`. Useful for
+ * generating accurate `<lastmod>` values in sitemaps when bulk commits (
+ * imports, reformats, renames) would otherwise produce misleading dates.
+ *
+ * Returns `null` when the file has no git history or git is unavailable.
+ */
+export function gitLastmod(filePath, options = {}) {
+    const { excludeCommits = [], depth = 10 } = options;
+    const excluded = new Set(excludeCommits.map((h) => h.slice(0, 7)));
+    try {
+        const log = execFileSync('git', ['log', `-${depth}`, '--format=%H\t%cI', '--', filePath], {
+            encoding: 'utf-8',
+        }).trim();
+        if (!log)
+            return null;
+        for (const line of log.split('\n')) {
+            const [hash, date] = line.split('\t');
+            if (!excluded.has(hash.slice(0, 7))) {
+                return date ? new Date(date) : null;
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=git-lastmod.js.map

package/dist/git-lastmod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-lastmod.js","sourceRoot":"","sources":["../src/git-lastmod.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAS7C;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,QAAgB,EAAE,UAA6B,EAAE;IACxE,MAAM,EAAE,cAAc,GAAG,EAAE,EAAE,KAAK,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC;IACpD,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACnE,IAAI,CAAC;QACD,MAAM,GAAG,GAAG,YAAY,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,IAAI,KAAK,EAAE,EAAE,kBAAkB,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE;YACtF,QAAQ,EAAE,OAAO;SACpB,CAAC,CAAC,IAAI,EAAE,CAAC;QACV,IAAI,CAAC,GAAG;YAAE,OAAO,IAAI,CAAC;QACtB,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACjC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAiC,CAAC;YACtE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAClC,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YACxC,CAAC;QACL,CAAC;QACD,OAAO,IAAI,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,IAAI,CAAC;IAChB,CAAC;AACL,CAAC"}

package/dist/index.d.ts

@@ -18,4 +18,8 @@ export { renderMarkdownAlternate, deriveMdUrl } from './markdown-alternate.js';
 export type { MarkdownAlternateFrontmatter, RenderMarkdownAlternateOptions, RenderedMarkdownAlternate, } from './markdown-alternate.js';
 export { createMarkdownEndpoint } from './markdown-routes.js';
 export type { MarkdownEndpointOptions } from './markdown-routes.js';
+export { gitLastmod } from './git-lastmod.js';
+export type { GitLastmodOptions } from './git-lastmod.js';
+export { createApiCatalog, CATALOG_PATH } from './api-catalog.js';
+export type { ApiCatalogOptions, ApiCatalogEntry, ApiCatalogSchemaEndpointEntry, ApiCatalogSchemaMapEntry, } from './api-catalog.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":"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,YAAY,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC7E,YAAY,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,YAAY,EAAE,aAAa,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAE/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,YAAY,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAEhE,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAC9F,YAAY,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAEnF,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE/E,OAAO,EAAE,uBAAuB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC/E,YAAY,EACR,4BAA4B,EAC5B,8BAA8B,EAC9B,yBAAyB,GAC5B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,YAAY,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC"}
+{"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,YAAY,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC7E,YAAY,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,YAAY,EAAE,aAAa,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAE/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,YAAY,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAEhE,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAC9F,YAAY,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAEnF,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE/E,OAAO,EAAE,uBAAuB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC/E,YAAY,EACR,4BAA4B,EAC5B,8BAA8B,EAC9B,yBAAyB,GAC5B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,YAAY,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAEpE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAClE,YAAY,EACR,iBAAiB,EACjB,eAAe,EACf,6BAA6B,EAC7B,wBAAwB,GAC3B,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -13,4 +13,6 @@ export { createIndexNowKeyRoute, submitToIndexNow, validateIndexNowKey } from '.
 export { renderLlmsTxt } from './llms-txt.js';
 export { renderMarkdownAlternate, deriveMdUrl } from './markdown-alternate.js';
 export { createMarkdownEndpoint } from './markdown-routes.js';
+export { gitLastmod } from './git-lastmod.js';
+export { createApiCatalog, CATALOG_PATH } from './api-catalog.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,+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;AAG9D,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAG7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAGtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAGtD,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAG9F,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG9C,OAAO,EAAE,uBAAuB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAO/E,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC"}
+{"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;AAG9D,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAG7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAGtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAGtD,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAG9F,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG9C,OAAO,EAAE,uBAAuB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAO/E,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAG9D,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jdevalk/astro-seo-graph",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Astro integration for @jdevalk/seo-graph-core. Seo component, route factories, content-collection aggregator, Zod content helpers.",
   "keywords": [
     "astro",