@softure-ai/blog 0.0.0-stage → 0.1.6

package/dist/discovery/refresh.js

@@ -0,0 +1,55 @@
+import { getBlogOptions, getBlogRefreshPath } from "../server/options.js";
+/** The variable both the route and the command read the shared secret from. */
+export const BLOG_REFRESH_SECRET_ENV = "BLOG_REFRESH_SECRET";
+/** A shorter secret is a setup bug: the route refuses to run with it and the command does not send it. */
+export const MIN_REFRESH_SECRET_LENGTH = 32;
+/** The security bucket the route counts in; `BLOG_RATE_LIMIT_BUCKETS` holds its default. */
+export const BLOG_REFRESH_RATE_LIMIT_BUCKET = "blog-refresh";
+const DEFAULT_TIMEOUT_MS = 10_000;
+/**
+ * Asks the running app to refresh the blog's cache after a publish run. Call it before the IndexNow
+ * submit, so a crawler that answers the ping finds the new text. Never throws for an expected
+ * failure: the refresh is an extra after a publish and must not undo it.
+ */
+export async function requestBlogRefresh(config, changes, options = {}) {
+    const { revalidateSeconds } = getBlogOptions(config);
+    if (changes.every((change) => change.action === "unchanged"))
+        return { kind: "skipped" };
+    const secret = ((options.env ?? process.env)[BLOG_REFRESH_SECRET_ENV] ?? "").trim();
+    if (secret === "")
+        return { kind: "not_configured", revalidateSeconds };
+    // Also on a dry run: the editor learns of a short secret before the commit that needs it.
+    if (secret.length < MIN_REFRESH_SECRET_LENGTH) {
+        return { kind: "failed", code: "blog.refresh_invalid_secret", reason: `${BLOG_REFRESH_SECRET_ENV} must be at least ${String(MIN_REFRESH_SECRET_LENGTH)} characters`, revalidateSeconds };
+    }
+    const url = new URL(getBlogRefreshPath(config), options.appUrl ?? config.appOrigin).toString();
+    if (options.commit !== true)
+        return { kind: "dry_run", url };
+    try {
+        const response = await (options.fetchImpl ?? fetch)(url, {
+            method: "POST",
+            headers: { authorization: `Bearer ${secret}` },
+            // Never followed: a redirect would carry the request, or drop the secret, somewhere else.
+            redirect: "manual",
+            signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+        });
+        if (response.status === 204 || response.status === 200)
+            return { kind: "refreshed", url };
+        return { kind: "failed", code: "blog.refresh_rejected", reason: `${url} answered ${String(response.status)}${describeStatus(response.status)}`, revalidateSeconds };
+    }
+    catch (error) {
+        return { kind: "failed", code: "blog.refresh_unreachable", reason: `${url} could not be reached: ${error instanceof Error ? error.message : String(error)}`, revalidateSeconds };
+    }
+}
+function describeStatus(status) {
+    if (status === 401)
+        return ` (the app has another ${BLOG_REFRESH_SECRET_ENV})`;
+    if (status === 404)
+        return " (mount refreshBlogCache at that path)";
+    if (status === 429)
+        return " (too many refreshes from this address)";
+    if (status >= 300 && status < 400)
+        return " (a redirect; pass the final origin with --app-url)";
+    return "";
+}
+//# sourceMappingURL=refresh.js.map

package/dist/discovery/refresh.js.map

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

package/dist/discovery/related.d.ts

@@ -0,0 +1,17 @@
+import type { BlogArticle } from "../contract.js";
+export type RelatedCandidate = Pick<BlogArticle, "id" | "cluster" | "isPillar">;
+/** How many texts "read next" shows under an article. */
+export declare const RELATED_LIMIT = 4;
+/** At most this many satellites under a pillar: its whole cluster, but a longer list is a listing. */
+export declare const PILLAR_RELATED_LIMIT = 6;
+/**
+ * - **A satellite:** the pillar of its cluster, the rest of the cluster, then pillars and texts of
+ *   other clusters; {@link RELATED_LIMIT} in total.
+ * - **A pillar:** every satellite of its cluster (up to {@link PILLAR_RELATED_LIMIT}), filled up to
+ *   {@link RELATED_LIMIT} from other clusters.
+ * - **No cluster:** pillars, then the newest.
+ *
+ * `published` comes newest first (the store's order); an article never recommends itself.
+ */
+export declare function getRelatedArticles<T extends RelatedCandidate>(article: RelatedCandidate, published: readonly T[]): T[];
+//# sourceMappingURL=related.d.ts.map

package/dist/discovery/related.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"related.d.ts","sourceRoot":"","sources":["../../src/discovery/related.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,WAAW,EAAE,IAAI,GAAG,SAAS,GAAG,UAAU,CAAC,CAAC;AAEhF,yDAAyD;AACzD,eAAO,MAAM,aAAa,IAAI,CAAC;AAE/B,sGAAsG;AACtG,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAOtC;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,gBAAgB,EAAE,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,EAAE,CAStH"}

package/dist/discovery/related.js

@@ -0,0 +1,28 @@
+/** How many texts "read next" shows under an article. */
+export const RELATED_LIMIT = 4;
+/** At most this many satellites under a pillar: its whole cluster, but a longer list is a listing. */
+export const PILLAR_RELATED_LIMIT = 6;
+/** Pillars first, then the input order (newest first). */
+function pillarsFirst(texts) {
+    return [...texts.filter((text) => text.isPillar), ...texts.filter((text) => !text.isPillar)];
+}
+/**
+ * - **A satellite:** the pillar of its cluster, the rest of the cluster, then pillars and texts of
+ *   other clusters; {@link RELATED_LIMIT} in total.
+ * - **A pillar:** every satellite of its cluster (up to {@link PILLAR_RELATED_LIMIT}), filled up to
+ *   {@link RELATED_LIMIT} from other clusters.
+ * - **No cluster:** pillars, then the newest.
+ *
+ * `published` comes newest first (the store's order); an article never recommends itself.
+ */
+export function getRelatedArticles(article, published) {
+    const others = published.filter((candidate) => candidate.id !== article.id);
+    const sameCluster = article.cluster === null ? [] : others.filter((candidate) => candidate.cluster === article.cluster);
+    const rest = pillarsFirst(others.filter((candidate) => !sameCluster.includes(candidate)));
+    if (article.isPillar) {
+        const satellites = sameCluster.slice(0, PILLAR_RELATED_LIMIT);
+        return [...satellites, ...rest].slice(0, Math.max(satellites.length, RELATED_LIMIT));
+    }
+    return [...pillarsFirst(sameCluster), ...rest].slice(0, RELATED_LIMIT);
+}
+//# sourceMappingURL=related.js.map

package/dist/discovery/related.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"related.js","sourceRoot":"","sources":["../../src/discovery/related.ts"],"names":[],"mappings":"AAKA,yDAAyD;AACzD,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC;AAE/B,sGAAsG;AACtG,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAEtC,0DAA0D;AAC1D,SAAS,YAAY,CAA6B,KAAmB;IACnE,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;AAC/F,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAA6B,OAAyB,EAAE,SAAuB;IAC/G,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,EAAE,KAAK,OAAO,CAAC,EAAE,CAAC,CAAC;IAC5E,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACxH,MAAM,IAAI,GAAG,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAC1F,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrB,MAAM,UAAU,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,oBAAoB,CAAC,CAAC;QAC9D,OAAO,CAAC,GAAG,UAAU,EAAE,GAAG,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;IACvF,CAAC;IACD,OAAO,CAAC,GAAG,YAAY,CAAC,WAAW,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC;AACzE,CAAC"}

package/dist/discovery/rss.d.ts

@@ -0,0 +1,30 @@
+import type { SiteUrls } from "@softure-ai/core";
+import type { BlogArticle } from "../contract.js";
+import { type BlogRoutes } from "../pages/paths.js";
+export type FeedText = Pick<BlogArticle, "id" | "slug" | "kind" | "title" | "description" | "cluster" | "publishedAt" | "updatedAt">;
+export interface FeedChannel {
+    readonly title: string;
+    readonly description: string;
+    /** The feed's language, e.g. `en` or `pl`. */
+    readonly language: string;
+}
+export interface BuildBlogRssInput {
+    readonly articles: readonly FeedText[];
+    readonly terms: readonly FeedText[];
+    /** The site's origin and canonical rule (`getSiteUrls(config)`): items and the channel link a page's canonical URL. */
+    readonly urls: SiteUrls;
+    readonly routes: BlogRoutes;
+    /** The feed's own path (`routes.rss`), for `atom:link rel="self"`. */
+    readonly feedPath: string;
+    readonly channel: FeedChannel;
+    /** An item's `<category>`: e.g. the cluster label of an article, the glossary title of a term; `null` for none. */
+    readonly getCategory: (text: FeedText) => string | null;
+}
+export declare function escapeXml(text: string): string;
+/**
+ * The feed of the published articles and terms together, newest publication first. `guid` is the
+ * text's id with `isPermaLink="false"`: it survives a slug change, so a reader never shows an old text
+ * again as new. `lastBuildDate` is the newest change, absent for an empty blog.
+ */
+export declare function buildBlogRss(input: BuildBlogRssInput): string;
+//# sourceMappingURL=rss.d.ts.map

package/dist/discovery/rss.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rss.d.ts","sourceRoot":"","sources":["../../src/discovery/rss.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAA+B,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGjF,MAAM,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,aAAa,GAAG,SAAS,GAAG,aAAa,GAAG,WAAW,CAAC,CAAC;AAErI,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,SAAS,QAAQ,EAAE,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IACpC,uHAAuH;IACvH,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,mHAAmH;IACnH,QAAQ,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,MAAM,GAAG,IAAI,CAAC;CACzD;AAID,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAmC7D"}

package/dist/discovery/rss.js

@@ -0,0 +1,48 @@
+import { getArticlePath, getTermPath } from "../pages/paths.js";
+import { getLatestModified, requirePublishedAt } from "./dates.js";
+const XML_ESCAPES = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&apos;" };
+export function escapeXml(text) {
+    return text.replace(/[&<>"']/g, (character) => XML_ESCAPES[character] ?? character);
+}
+/**
+ * The feed of the published articles and terms together, newest publication first. `guid` is the
+ * text's id with `isPermaLink="false"`: it survives a slug change, so a reader never shows an old text
+ * again as new. `lastBuildDate` is the newest change, absent for an empty blog.
+ */
+export function buildBlogRss(input) {
+    const lastModified = getLatestModified([...input.articles, ...input.terms]);
+    const items = [
+        ...input.articles.map((text) => ({ text, path: getArticlePath(input.routes, text.slug) })),
+        ...input.terms.map((text) => ({ text, path: getTermPath(input.routes, text.slug) })),
+    ]
+        .sort((a, b) => requirePublishedAt(b.text).getTime() - requirePublishedAt(a.text).getTime())
+        .map(({ text, path }) => {
+        const category = input.getCategory(text);
+        return [
+            "    <item>",
+            `      <title>${escapeXml(text.title)}</title>`,
+            `      <link>${escapeXml(input.urls.getCanonicalUrl(path))}</link>`,
+            `      <guid isPermaLink="false">${escapeXml(text.id)}</guid>`,
+            `      <description>${escapeXml(text.description)}</description>`,
+            `      <pubDate>${requirePublishedAt(text).toUTCString()}</pubDate>`,
+            ...(category === null ? [] : [`      <category>${escapeXml(category)}</category>`]),
+            "    </item>",
+        ].join("\n");
+    });
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">',
+        "  <channel>",
+        `    <title>${escapeXml(input.channel.title)}</title>`,
+        `    <link>${escapeXml(input.urls.getCanonicalUrl(input.routes.index))}</link>`,
+        `    <description>${escapeXml(input.channel.description)}</description>`,
+        `    <language>${escapeXml(input.channel.language)}</language>`,
+        `    <atom:link href="${escapeXml(`${input.urls.origin}${input.feedPath}`)}" rel="self" type="application/rss+xml"/>`,
+        ...(lastModified === null ? [] : [`    <lastBuildDate>${lastModified.toUTCString()}</lastBuildDate>`]),
+        ...items,
+        "  </channel>",
+        "</rss>",
+        "",
+    ].join("\n");
+}
+//# sourceMappingURL=rss.js.map

package/dist/discovery/rss.js.map

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

package/dist/discovery/sitemap.d.ts

@@ -0,0 +1,25 @@
+import type { BlogArticle } from "../contract.js";
+import { type BlogRoutes } from "../pages/paths.js";
+/** The shape of seo's `SitemapEntry`, written out so the blog needs no seo import. */
+export interface BlogSitemapEntry {
+    readonly path: string;
+    readonly lastModified?: Date;
+    readonly priority: number;
+}
+export type SitemapText = Pick<BlogArticle, "slug" | "isPillar" | "publishedAt" | "updatedAt">;
+export interface BlogSitemapInput {
+    /** Published articles. */
+    readonly articles: readonly SitemapText[];
+    /** Published glossary terms. */
+    readonly terms: readonly SitemapText[];
+    readonly routes: BlogRoutes;
+    /** The method page's path when the app mounts it, else `null`. */
+    readonly methodPath: string | null;
+}
+/**
+ * The listing and its articles, the glossary and its terms, and the method page. **An empty list adds
+ * no hub**: an empty listing or glossary is `noindex`, and a sitemap pointing at a page kept out of the
+ * index is a contradicting signal. The method page has no content date, so it has no `lastModified`.
+ */
+export declare function getBlogSitemapEntries({ articles, terms, routes, methodPath }: BlogSitemapInput): BlogSitemapEntry[];
+//# sourceMappingURL=sitemap.d.ts.map

package/dist/discovery/sitemap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sitemap.d.ts","sourceRoot":"","sources":["../../src/discovery/sitemap.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAA+B,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGjF,sFAAsF;AACtF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,UAAU,GAAG,aAAa,GAAG,WAAW,CAAC,CAAC;AAE/F,MAAM,WAAW,gBAAgB;IAC/B,0BAA0B;IAC1B,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;IAC1C,gCAAgC;IAChC,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAQD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CAsBnH"}

package/dist/discovery/sitemap.js

@@ -0,0 +1,31 @@
+import { getTermPath, getArticlePath } from "../pages/paths.js";
+import { getLatestModified, getTextLastModified } from "./dates.js";
+const HUB_PRIORITY = 0.7;
+const PILLAR_PRIORITY = 0.7;
+const ARTICLE_PRIORITY = 0.6;
+const GLOSSARY_PRIORITY = 0.5;
+const METHOD_PRIORITY = 0.3;
+/**
+ * The listing and its articles, the glossary and its terms, and the method page. **An empty list adds
+ * no hub**: an empty listing or glossary is `noindex`, and a sitemap pointing at a page kept out of the
+ * index is a contradicting signal. The method page has no content date, so it has no `lastModified`.
+ */
+export function getBlogSitemapEntries({ articles, terms, routes, methodPath }) {
+    const entries = [];
+    const listingModified = getLatestModified(articles);
+    if (listingModified !== null) {
+        entries.push({ path: routes.index, lastModified: listingModified, priority: HUB_PRIORITY }, ...articles.map((article) => ({
+            path: getArticlePath(routes, article.slug),
+            lastModified: getTextLastModified(article),
+            priority: article.isPillar ? PILLAR_PRIORITY : ARTICLE_PRIORITY,
+        })));
+    }
+    const glossaryModified = getLatestModified(terms);
+    if (glossaryModified !== null) {
+        entries.push({ path: routes.glossary, lastModified: glossaryModified, priority: GLOSSARY_PRIORITY }, ...terms.map((term) => ({ path: getTermPath(routes, term.slug), lastModified: getTextLastModified(term), priority: GLOSSARY_PRIORITY })));
+    }
+    if (methodPath !== null)
+        entries.push({ path: methodPath, priority: METHOD_PRIORITY });
+    return entries;
+}
+//# sourceMappingURL=sitemap.js.map

package/dist/discovery/sitemap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sitemap.js","sourceRoot":"","sources":["../../src/discovery/sitemap.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAmB,MAAM,mBAAmB,CAAC;AACjF,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAqBpE,MAAM,YAAY,GAAG,GAAG,CAAC;AACzB,MAAM,eAAe,GAAG,GAAG,CAAC;AAC5B,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAC7B,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAC9B,MAAM,eAAe,GAAG,GAAG,CAAC;AAE5B;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAoB;IAC7F,MAAM,OAAO,GAAuB,EAAE,CAAC;IACvC,MAAM,eAAe,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IACpD,IAAI,eAAe,KAAK,IAAI,EAAE,CAAC;QAC7B,OAAO,CAAC,IAAI,CACV,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,QAAQ,EAAE,YAAY,EAAE,EAC7E,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YAC5B,IAAI,EAAE,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC;YAC1C,YAAY,EAAE,mBAAmB,CAAC,OAAO,CAAC;YAC1C,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,gBAAgB;SAChE,CAAC,CAAC,CACJ,CAAC;IACJ,CAAC;IACD,MAAM,gBAAgB,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAClD,IAAI,gBAAgB,KAAK,IAAI,EAAE,CAAC;QAC9B,OAAO,CAAC,IAAI,CACV,EAAE,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE,YAAY,EAAE,gBAAgB,EAAE,QAAQ,EAAE,iBAAiB,EAAE,EACtF,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,YAAY,EAAE,mBAAmB,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,iBAAiB,EAAE,CAAC,CAAC,CACzI,CAAC;IACJ,CAAC;IACD,IAAI,UAAU,KAAK,IAAI;QAAE,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,eAAe,EAAE,CAAC,CAAC;IACvF,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/discovery/submit.d.ts

@@ -0,0 +1,44 @@
+import { type SoftureConfig } from "@softure-ai/core";
+import { type IndexNowChange } from "./indexnow.js";
+export type BlogIndexNowOutcome = 
+/** seo is not listed, or it has no IndexNow key: nothing is sent. */
+{
+    readonly kind: "not_configured";
+    readonly reason: string;
+}
+/** The run changed no public address. */
+ | {
+    readonly kind: "skipped";
+}
+/** No commit: the URLs a commit would submit, and no request. */
+ | {
+    readonly kind: "dry_run";
+    readonly endpoint: string;
+    readonly urls: readonly string[];
+} | {
+    readonly kind: "submitted";
+    readonly status: number;
+    readonly count: number;
+} | {
+    readonly kind: "failed";
+    readonly code: string;
+    readonly reason: string;
+};
+export interface BlogIndexNowSubmit {
+    /** The changed paths (`getIndexNowPaths`), also when nothing is sent. */
+    readonly paths: readonly string[];
+    readonly outcome: BlogIndexNowOutcome;
+}
+export interface SubmitBlogChangesOptions {
+    /** Sends the request only when `true`, i.e. after a committed run; otherwise a dry run. */
+    readonly commit?: boolean;
+    readonly fetchImpl?: typeof fetch;
+}
+/**
+ * Submits the addresses a publish run changed through seo's IndexNow, on seo's site origin. Refresh
+ * the app's cache first (`requestBlogRefresh`, or `revalidateTag("softure-blog", { expire: 0 })` inside
+ * Next), so a crawler that comes at once sees the new text.
+ * Never throws for an expected failure: a submit is an extra after a publish and must not undo it.
+ */
+export declare function submitBlogChanges(config: SoftureConfig, changes: readonly IndexNowChange[], options?: SubmitBlogChangesOptions): Promise<BlogIndexNowSubmit>;
+//# sourceMappingURL=submit.d.ts.map

package/dist/discovery/submit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"submit.d.ts","sourceRoot":"","sources":["../../src/discovery/submit.ts"],"names":[],"mappings":"AAIA,OAAO,EAAa,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjE,OAAO,EAAoB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAItE,MAAM,MAAM,mBAAmB;AAC7B,qEAAqE;AACnE;IAAE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AAC9D,yCAAyC;GACvC;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE;AAC9B,iEAAiE;GAC/D;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACzF;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC/E;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhF,MAAM,WAAW,kBAAkB;IACjC,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;CACvC;AAED,MAAM,WAAW,wBAAwB;IACvC,2FAA2F;IAC3F,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CACnC;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,SAAS,cAAc,EAAE,EAAE,OAAO,GAAE,wBAA6B,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA8BtK"}

package/dist/discovery/submit.js

@@ -0,0 +1,46 @@
+// The IndexNow submit after a publish: the CLI calls it after `softure-blog publish`, and an app with
+// its own publishing path calls it after `runBlogPublish`. It reaches `@softure-ai/seo` through a
+// dynamic import, and only when the config lists `seo()`: seo is an optional peer, so an app without
+// it still runs the blog.
+import { getModule } from "@softure-ai/core";
+import { getBlogRoutes } from "../server/options.js";
+import { getIndexNowPaths } from "./indexnow.js";
+const SEO_MODULE_ID = "seo";
+/**
+ * Submits the addresses a publish run changed through seo's IndexNow, on seo's site origin. Refresh
+ * the app's cache first (`requestBlogRefresh`, or `revalidateTag("softure-blog", { expire: 0 })` inside
+ * Next), so a crawler that comes at once sees the new text.
+ * Never throws for an expected failure: a submit is an extra after a publish and must not undo it.
+ */
+export async function submitBlogChanges(config, changes, options = {}) {
+    const paths = getIndexNowPaths(changes, getBlogRoutes(config));
+    const seoModule = getModule(config, SEO_MODULE_ID);
+    if (seoModule === undefined)
+        return { paths, outcome: { kind: "not_configured", reason: "the seo module is not enabled; add seo({ indexNow: { key } }) to modules" } };
+    const [{ buildCanonicalUrl, resolveSeoSettings }, { submitToIndexNow }] = await Promise.all([import("@softure-ai/seo"), import("@softure-ai/seo/server")]);
+    // The seo module factory parsed its options and declares both routes.
+    const settings = resolveSeoSettings(seoModule.options, {
+        appOrigin: config.appOrigin,
+        routes: seoModule.routes,
+    });
+    if (settings.indexNowKey === null)
+        return { paths, outcome: { kind: "not_configured", reason: "seo has no IndexNow key; set seo({ indexNow: { key } })" } };
+    // Canonical URLs (seo's host and trailing-slash rule), so the engines learn the address the pages declare.
+    const urls = paths.map((path) => buildCanonicalUrl(path, settings));
+    const result = await submitToIndexNow(urls, {
+        key: settings.indexNowKey,
+        siteOrigin: settings.siteOrigin,
+        keyPath: settings.routes.indexNowKey,
+        commit: options.commit === true,
+        ...(options.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+    });
+    switch (result.kind) {
+        case "dry_run":
+            return { paths, outcome: { kind: "dry_run", endpoint: result.endpoint, urls: result.body.urlList } };
+        case "failed":
+            return { paths, outcome: { kind: "failed", code: result.code, reason: result.reason } };
+        default:
+            return { paths, outcome: result };
+    }
+}
+//# sourceMappingURL=submit.js.map

package/dist/discovery/submit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"submit.js","sourceRoot":"","sources":["../../src/discovery/submit.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,kGAAkG;AAClG,qGAAqG;AACrG,0BAA0B;AAC1B,OAAO,EAAE,SAAS,EAAsB,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAuB,MAAM,eAAe,CAAC;AAEtE,MAAM,aAAa,GAAG,KAAK,CAAC;AAwB5B;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,MAAqB,EAAE,OAAkC,EAAE,UAAoC,EAAE;IACvI,MAAM,KAAK,GAAG,gBAAgB,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;IAC/D,MAAM,SAAS,GAAG,SAAS,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACnD,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,0EAA0E,EAAE,EAAE,CAAC;IAEvK,MAAM,CAAC,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,EAAE,EAAE,gBAAgB,EAAE,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC,wBAAwB,CAAC,CAAC,CAAC,CAAC;IAC3J,sEAAsE;IACtE,MAAM,QAAQ,GAAG,kBAAkB,CAAC,SAAS,CAAC,OAAmD,EAAE;QACjG,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,MAAM,EAAE,SAAS,CAAC,MAAuE;KAC1F,CAAC,CAAC;IACH,IAAI,QAAQ,CAAC,WAAW,KAAK,IAAI;QAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,yDAAyD,EAAE,EAAE,CAAC;IAE5J,2GAA2G;IAC3G,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,iBAAiB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;IACpE,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,IAAI,EAAE;QAC1C,GAAG,EAAE,QAAQ,CAAC,WAAW;QACzB,UAAU,EAAE,QAAQ,CAAC,UAAU;QAC/B,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW;QACpC,MAAM,EAAE,OAAO,CAAC,MAAM,KAAK,IAAI;QAC/B,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC;KAC7E,CAAC,CAAC;IACH,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,SAAS;YACZ,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;QACvG,KAAK,QAAQ;YACX,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;QAC1F;YACE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IACtC,CAAC;AACH,CAAC"}