{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "publish-webhook",
  "title": "AgentBlog publish webhook",
  "description": "A publish endpoint that revalidates the metadata routes as well as the page routes, because sitemap.xml and feed.xml are cached route handlers that a naive webhook leaves stale, and then submits the URL to IndexNow with the response codes surfaced rather than swallowed.",
  "registryDependencies": [
    "@agentblog/blog-core"
  ],
  "files": [
    {
      "path": "registry/blog/app/api/publish/route.ts",
      "content": "/**\n * `POST /api/publish`: the publish webhook.\n *\n * ===========================================================================\n * WHAT THIS ENDPOINT IS FOR\n * ===========================================================================\n * One endpoint, three triggers. For an MDX-on-disk blog the trigger is a git\n * push (your host redeploys and this is optional). For a database-backed source\n * it is a row-change webhook. For a hosted publishing agent it is a direct call.\n * The body is always the same: `{ \"slug\": \"my-post\" }`.\n *\n * ===========================================================================\n * THE TWO CORRECTIONS THIS FILE EXISTS TO ENCODE\n * ===========================================================================\n *\n * ---------------------------------------------------------------------------\n * 1. REVALIDATE THE METADATA ROUTES, NOT ONLY THE PAGE ROUTES\n * ---------------------------------------------------------------------------\n * `sitemap.xml`, `feed.xml`, `robots.txt`, and every `opengraph-image` are\n * special Route Handlers that Next.js caches by default. Revalidating only\n * `/blog/<slug>` and `/blog` leaves the sitemap and the feed serving their\n * build-time output.\n *\n * The consequence is specific and bad: we then fire an IndexNow ping for a URL\n * that our own sitemap does not list. We are simultaneously telling a search\n * engine \"this page is new and important\" and \"this page does not exist on my\n * site\". On a filesystem-backed blog you will never see this, because publishing\n * is a deploy and the deploy rebuilds everything. On any database-backed source\n * it happens on every single publish.\n *\n * So `handlerPathsFor()` below is load-bearing. Do not delete it to make the\n * function faster.\n *\n * ---------------------------------------------------------------------------\n * 2. `revalidateTag('posts', { expire: 0 })`, NEVER `'max'`\n * ---------------------------------------------------------------------------\n * `'max'` is stale-while-revalidate: the tag is marked stale, and fresh data is\n * only fetched when a page using it is next visited. On a publish event that is\n * exactly backwards, because the IndexNow ping we are about to send is an\n * invitation for a crawler to BE that next visit. The crawler arrives, receives\n * the stale body, and triggers a background refresh it will never come back to\n * see. For a blog whose entire premise is what lands in the first response byte,\n * that undoes the point of the endpoint.\n *\n * In Next.js 16.3 the second argument is required by the type signature. The\n * single-argument form is deprecated rather than removed.\n *\n * ===========================================================================\n * ENVIRONMENT\n * ===========================================================================\n *   AGENTBLOG_REVALIDATE_SECRET   required. Shared secret for this endpoint.\n *   AGENTBLOG_DEPLOY_WAIT_MS      optional. Deploy wait budget, default 45000.\n *\n * @see https://docs.agentblog.dev/reference/files\n */\nimport { revalidatePath, revalidateTag } from 'next/cache'\nimport { createHash, timingSafeEqual } from 'node:crypto'\nimport { z } from 'zod'\n\nimport { authorPath, blogPath, categoryPath, config, postPath, postUrl } from '@/lib/config'\nimport { pingIndexNow } from '@/lib/indexnow'\nimport { getPost } from '@/lib/posts'\nimport { Slug } from '@/lib/schemas'\n\n/** Node APIs (`node:crypto`) and a real outbound fetch to our own origin. */\nexport const runtime = 'nodejs'\n\n/** Never cache a webhook. Every call must do the work it says it does. */\nexport const dynamic = 'force-dynamic'\n\n/**\n * The deploy wait below can hold the request open. 60 seconds is the ceiling on\n * a Vercel Hobby plan; raise it here and in `AGENTBLOG_DEPLOY_WAIT_MS` together\n * if your plan allows more.\n */\nexport const maxDuration = 60\n\n/* ========================================================================== */\n/*  Request contract                                                          */\n/* ========================================================================== */\n\n/**\n * `Slug` rather than `z.string()`.\n *\n * This value is interpolated into `revalidatePath()` and into a URL we then\n * fetch. The slug brand rejects slashes, dots, and anything that is not\n * lowercase-and-hyphens, which closes the path traversal that a bare string\n * would leave open. Validation at the boundary, as everywhere else in the block.\n */\nconst PublishRequestSchema = z.object({ slug: Slug })\n\n/* ========================================================================== */\n/*  Deploy wait tuning                                                        */\n/* ========================================================================== */\n\nconst DEFAULT_DEPLOY_WAIT_MS = 45_000\n\n/** Deploys never finish instantly. Probing immediately just burns the budget. */\nconst FIRST_PROBE_DELAY_MS = 8_000\nconst PROBE_INTERVAL_MS = 5_000\n\nfunction deployWaitBudgetMs(): number {\n  const raw = process.env.AGENTBLOG_DEPLOY_WAIT_MS\n  const parsed = raw === undefined ? Number.NaN : Number(raw)\n  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_DEPLOY_WAIT_MS\n}\n\n/* ========================================================================== */\n/*  Auth                                                                      */\n/* ========================================================================== */\n\n/**\n * Constant-time secret comparison.\n *\n * Both sides are hashed first so the buffers are always 32 bytes. That matters:\n * `timingSafeEqual` throws on unequal lengths, and the usual workaround (compare\n * lengths, bail early) leaks the secret's length through timing. Hashing removes\n * the question entirely.\n */\nfunction secretsMatch(presented: string, expected: string): boolean {\n  const a = createHash('sha256').update(presented, 'utf8').digest()\n  const b = createHash('sha256').update(expected, 'utf8').digest()\n  return timingSafeEqual(a, b)\n}\n\n/**\n * Accept the secret as `Authorization: Bearer <secret>` or as\n * `x-agentblog-secret: <secret>`. The first is what most platforms send; the\n * second is what most no-code webhook builders can actually configure.\n */\nfunction presentedSecret(request: Request): string | null {\n  const authorization = request.headers.get('authorization')\n  if (authorization && /^Bearer /i.test(authorization)) {\n    return authorization.slice('Bearer '.length).trim()\n  }\n  return request.headers.get('x-agentblog-secret')\n}\n\n/* ========================================================================== */\n/*  Revalidation                                                              */\n/* ========================================================================== */\n\n/**\n * Route handler paths that carry post data and are cached by default.\n *\n * `robots.txt` is deliberately absent: nothing in it derives from a post, so\n * revalidating it on every publish would be work that can never change a byte.\n *\n * `/sitemap.xml` and `/feed.xml` are literals rather than helper calls because\n * both end in a file extension, and the path helpers in `@/lib/config` never\n * append a trailing slash to a segment that looks like a file. They are already\n * in final form. The OG image path is built from `postPath` so the slug is\n * encoded exactly once, in the same place every other post URL is built.\n */\nfunction handlerPathsFor(slug: string): string[] {\n  return [\n    '/sitemap.xml',\n    '/feed.xml',\n    // Same reasoning as the two above: a cached route handler built from the\n    // post list, so a publish that does not invalidate it leaves a retrieval\n    // agent reading an index that is missing the post we just told IndexNow\n    // about.\n    '/llms.txt',\n    /**\n     * Best effort. Next.js derives its own route path for metadata image\n     * handlers and appends a generated suffix for cache busting, so this call\n     * may be a no-op depending on how your deployment names the route. It costs\n     * nothing when it misses, and the reliable invalidation for an OG image is a\n     * deploy. Say so out loud rather than implying a guarantee.\n     */\n    `${postPath(slug).replace(/\\/$/, '')}/opengraph-image`,\n  ]\n}\n\n/* ========================================================================== */\n/*  Deploy hook                                                               */\n/* ========================================================================== */\n\n/**\n * What we know about whether the new URL is actually servable.\n *\n * Read these as claims about the URL, not about the deploy platform:\n *\n *   'not-needed'      the route was already servable, or the source prerenders\n *                     new slugs without a rebuild.\n *   'confirmed-live'  we fired the hook and then observed the URL return a\n *                     non-404 from the public origin.\n *   'timed-out'       we fired the hook and never observed a non-404 inside the\n *                     budget. The deploy may still land later.\n *   'hook-failed'     the deploy hook itself did not accept the request.\n *   'not-configured'  the source needs a rebuild and no `deployHook` is set.\n */\ntype DeployOutcome =\n  'not-needed' | 'confirmed-live' | 'timed-out' | 'hook-failed' | 'not-configured'\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms))\n}\n\n/**\n * Does the public origin serve this URL right now?\n *\n * The cache-busting query parameter is the point of the function. Without it a\n * CDN can answer from its cached copy of the 404 we are trying to see disappear,\n * and we would report success or failure based on a stale edge object rather\n * than on the origin. Next.js ignores unknown query parameters when matching a\n * route, so the probe URL and the canonical URL resolve to the same page.\n */\nasync function urlIsServable(url: string): Promise<boolean> {\n  const separator = url.includes('?') ? '&' : '?'\n  try {\n    const response = await fetch(`${url}${separator}agentblog-probe=${Date.now()}`, {\n      method: 'GET',\n      cache: 'no-store',\n      redirect: 'follow',\n      headers: { accept: 'text/html', 'user-agent': 'agentblog-publish-webhook' },\n    })\n    return response.ok\n  } catch {\n    // A network failure is not evidence that the page exists.\n    return false\n  }\n}\n\n/**\n * Fire the deploy hook, then wait until the URL answers.\n *\n * ---------------------------------------------------------------------------\n * WHAT THIS GUARANTEES, AND WHAT IT DOES NOT\n * ---------------------------------------------------------------------------\n * Guaranteed: we do not ping IndexNow before we have seen the public origin\n * return a non-404 for the exact URL we are about to submit. That is the whole\n * requirement. Pinging first invites a crawler to a URL that does not exist yet,\n * and a crawler that receives a 404 on its first visit is expensive to convince\n * otherwise.\n *\n * NOT guaranteed, and worth knowing before you rely on this:\n *\n *   - We do not talk to your platform's deployment API. A deploy hook returns\n *     \"accepted\", not \"finished\", and there is no portable completion signal\n *     across Vercel, Netlify, Cloudflare Pages, and a self-hosted runner. So the\n *     URL responding is our proxy for \"the deploy succeeded\", and it is a proxy.\n *   - A non-404 is not proof the page is correct. It proves the route resolves.\n *     If the new build shipped a broken post, this reports success.\n *   - CDNs are regional. The URL answering from the region this function runs in\n *     does not prove it answers everywhere yet.\n *   - The wait is bounded (`AGENTBLOG_DEPLOY_WAIT_MS`, default 45s, inside a\n *     60s function ceiling). A slow build will time out. When it does we return\n *     202 and DO NOT ping, so a retry is safe and idempotent. Timing out is the\n *     honest answer, not a failure to handle.\n *   - Paths are revalidated before this runs, so a retry after a timeout costs\n *     one more ping and nothing else.\n */\nasync function fireDeployHookAndWait(url: string): Promise<DeployOutcome> {\n  const hook = config.deployHook\n  if (!hook) return 'not-configured'\n\n  try {\n    const response = await fetch(hook, { method: 'POST', cache: 'no-store' })\n    if (!response.ok) return 'hook-failed'\n  } catch {\n    return 'hook-failed'\n  }\n\n  const budget = deployWaitBudgetMs()\n  const deadline = Date.now() + budget\n\n  await sleep(Math.min(FIRST_PROBE_DELAY_MS, budget))\n\n  while (Date.now() < deadline) {\n    if (await urlIsServable(url)) return 'confirmed-live'\n    await sleep(PROBE_INTERVAL_MS)\n  }\n\n  return 'timed-out'\n}\n\n/* ========================================================================== */\n/*  Response shapes                                                           */\n/* ========================================================================== */\n\ninterface IndexNowReport {\n  readonly attempted: boolean\n  /** Present only when attempted. `200` submitted, `202` pending key validation. */\n  readonly status?: number\n  readonly ok?: boolean\n  readonly meaning?: string\n  /** Present only when skipped. */\n  readonly reason?: string\n}\n\nfunction json(status: number, body: Record<string, unknown>): Response {\n  return Response.json(body, { status })\n}\n\n/* ========================================================================== */\n/*  Handler                                                                   */\n/* ========================================================================== */\n\nexport async function POST(request: Request): Promise<Response> {\n  const expected = process.env.AGENTBLOG_REVALIDATE_SECRET\n  if (!expected) {\n    // A server misconfiguration, not an auth decision. Answering 401 here would\n    // make a dead endpoint indistinguishable from a live one with a bad secret,\n    // which is the exact debugging trap this product exists to remove.\n    return json(500, {\n      ok: false,\n      error: 'AGENTBLOG_REVALIDATE_SECRET is not set on this deployment.',\n    })\n  }\n\n  const presented = presentedSecret(request)\n  // One message for both \"no header\" and \"wrong secret\". A caller learns only\n  // that it is not authorized, which is all it is entitled to know.\n  if (presented === null || !secretsMatch(presented, expected)) {\n    return json(401, { ok: false, error: 'Unauthorized.' })\n  }\n\n  let raw: unknown\n  try {\n    raw = await request.json()\n  } catch {\n    return json(400, { ok: false, error: 'Request body must be JSON.', issues: [] })\n  }\n\n  const parsed = PublishRequestSchema.safeParse(raw)\n  if (!parsed.success) {\n    return json(400, {\n      ok: false,\n      error: 'Invalid request body.',\n      issues: parsed.error.issues.map((issue) => ({\n        path: issue.path.map(String).join('.') || '(root)',\n        message: issue.message,\n      })),\n    })\n  }\n\n  const { slug } = parsed.data\n  const url = postUrl(slug)\n  const strategy = config.source.prerenderStrategy\n\n  /**\n   * `getPost` returns `null` for a slug the source does not know, and also for a\n   * post still marked `draft`, because drafts are opted into rather than out of\n   * everywhere in this block.\n   *\n   * Either way we revalidate what we safely can and stop short of IndexNow.\n   * Summoning a crawler to a draft or to a slug that does not exist is worse\n   * than doing nothing at all.\n   */\n  const post = await getPost(slug)\n\n  const revalidated: string[] = []\n\n  const revalidatePage = (path: string): void => {\n    revalidatePath(path, 'page')\n    revalidated.push(path)\n  }\n  const revalidateHandler = (path: string): void => {\n    revalidatePath(path)\n    revalidated.push(path)\n  }\n\n  /*\n   * Every path here comes from a `@/lib/config` helper rather than from string\n   * concatenation, for the same reason every canonical does: the helpers are the\n   * one place that knows about `config.trailingSlash` and slug encoding, so the\n   * path revalidated and the path served are constructed by the same code.\n   * (`revalidatePath` strips a trailing slash of its own accord, so the two\n   * spellings invalidate the same entry either way. That is a reason not to worry\n   * about the helper's output, not a reason to hand-build the string.)\n   */\n  revalidatePage(postPath(slug))\n  revalidatePage(blogPath())\n  if (post) {\n    revalidatePage(categoryPath(post.category.slug))\n    revalidatePage(authorPath(post.author.slug))\n  }\n  for (const path of handlerPathsFor(slug)) revalidateHandler(path)\n\n  /**\n   * `{ expire: 0 }`, not `'max'`. See correction 2 in the file header. The\n   * second argument is required by the type signature in Next.js 16.3.\n   */\n  revalidateTag('posts', { expire: 0 })\n\n  if (!post) {\n    return json(202, {\n      ok: false,\n      slug,\n      url,\n      strategy,\n      revalidated,\n      deploy: { outcome: 'not-needed' },\n      indexnow: {\n        attempted: false,\n        reason: 'slug is unknown to the content source, or is a draft',\n      },\n      warning:\n        'Paths were revalidated but IndexNow was not pinged, because the content source does ' +\n        'not return a published post for this slug.',\n    })\n  }\n\n  /**\n   * Branch on how new slugs enter the prerendered set.\n   *\n   * Next.js does not re-run `generateStaticParams` during ISR, so a slug that\n   * did not exist at build time was never in the prerendered set and no amount\n   * of `revalidatePath` creates it: there is nothing cached to invalidate.\n   *\n   *   'build'       content lives in the repository, so the push that added the\n   *                 file is already the deploy. Nothing to wait for.\n   *   'on-demand'   the adapter accepts a request-time first render, so the URL\n   *                 resolves on first visit with `dynamicParams` at its default.\n   *   'deploy-hook' the URL may not exist yet. Probe first, because an existing\n   *                 slug whose content merely changed needs no rebuild at all,\n   *                 and a rebuild per edit is an expensive way to find that out.\n   */\n  let deployOutcome: DeployOutcome = 'not-needed'\n  if (strategy === 'deploy-hook') {\n    deployOutcome = (await urlIsServable(url)) ? 'not-needed' : await fireDeployHookAndWait(url)\n  }\n\n  const urlIsLive = deployOutcome === 'not-needed' || deployOutcome === 'confirmed-live'\n\n  let indexnow: IndexNowReport\n  if (!urlIsLive) {\n    indexnow = {\n      attempted: false,\n      reason: `deploy outcome was \"${deployOutcome}\"; the URL was not confirmed servable`,\n    }\n  } else {\n    const result = await pingIndexNow([url])\n    indexnow =\n      result === null\n        ? { attempted: false, reason: 'IndexNow is disabled in agentblog.config.ts' }\n        : { attempted: true, ok: result.ok, status: result.status, meaning: result.meaning }\n  }\n\n  /**\n   * Status codes the caller can act on.\n   *\n   *   200  everything this endpoint promises actually happened\n   *   202  revalidated, but the ping was deferred. Retrying is safe\n   *   502  the deploy hook itself refused the request\n   *\n   * A failed IndexNow ping does not fail the request: `403` (key invalid) and\n   * `422` (host mismatch) are configuration problems, and they are reported in\n   * the body rather than hidden behind a 200 that means nothing.\n   */\n  const status = deployOutcome === 'hook-failed' ? 502 : urlIsLive ? 200 : 202\n\n  return json(status, {\n    ok: urlIsLive,\n    slug,\n    url,\n    strategy,\n    revalidated,\n    deploy: { outcome: deployOutcome },\n    indexnow,\n  })\n}\n",
      "type": "registry:page",
      "target": "app/api/publish/route.ts"
    },
    {
      "path": "registry/blog/lib/indexnow.ts",
      "content": "/**\n * IndexNow submission, implemented against the spec rather than the folklore.\n *\n * ===========================================================================\n * WHAT INDEXNOW IS AND WHY THE BLOCK BOTHERS\n * ===========================================================================\n * One HTTP POST tells Bing, Yandex, Seznam, and Naver that a URL changed, and\n * they fetch it instead of waiting for a crawl. That matters more than its\n * search share suggests: ChatGPT's search surface has historically leaned on\n * Bing's index, so being in Bing quickly is part of being citable quickly.\n *\n * ===========================================================================\n * THE THREE THINGS EVERY NAIVE IMPLEMENTATION GETS WRONG\n * ===========================================================================\n * 1. **The limit is 10,000 URLs per request, not per day.** The \"per day\"\n *    reading is common and leads people to batch and throttle for no reason.\n *\n * 2. **403 and 422 are indistinguishable from success unless you look.** A fire\n *    and forget `fetch` that ignores the response reports a healthy publish\n *    pipeline while every single submission is being rejected, for months. 403\n *    means the key file is not where `keyLocation` says it is. 422 means a URL\n *    in the batch does not belong to `host`. Both are configuration mistakes\n *    that never surface on their own, which is why this function returns the\n *    status and a plain sentence explaining it rather than a boolean.\n *\n * 3. **The key file has to exist at the domain root.** `<key>.txt`, UTF-8,\n *    containing the key and nothing else. A key hosted under a subpath only\n *    authorizes URLs beneath that subpath, so the root is the only location that\n *    covers a whole blog.\n *\n * ===========================================================================\n * CONTRACT\n * ===========================================================================\n * Returns `null` when there is nothing to do: IndexNow is disabled, no key is\n * configured, or the URL list is empty. Never throws, because it is called from\n * the publish webhook after the revalidation has already succeeded, and a failed\n * ping must not turn a successful publish into a 500.\n *\n * @see https://docs.agentblog.dev/guides/write-with-your-agent\n */\nimport { absoluteUrl, config } from '@/lib/config'\n\nconst ENDPOINT = 'https://api.indexnow.org/indexnow'\n\n/** Per request, per the spec. Not per day, and not per domain. */\nconst MAX_URLS_PER_REQUEST = 10_000\n\n/**\n * Every status the spec defines, in the caller's words rather than the\n * protocol's. These strings are printed by `agentblog ping` and logged by the\n * publish webhook, so they say what to do, not just what happened.\n */\nconst MEANINGS: Readonly<Record<number, string>> = {\n  200: 'Submitted. The URLs were received and the key was validated.',\n  202: 'Accepted. The URLs were received and key validation is still pending.',\n  400: 'Bad request. The JSON body or one of the URLs in it is malformed.',\n  403:\n    'Forbidden. The key is invalid, or the key file is not served at its keyLocation. ' +\n    'Check that the file exists at the site root and contains the key and nothing else.',\n  422:\n    'Unprocessable. A submitted URL does not belong to the declared host, or the key does ' +\n    'not match the host. Check that siteUrl in agentblog.config.ts matches the URLs sent.',\n  429: 'Rate limited. Too many submissions; back off and retry later.',\n}\n\nexport interface IndexNowResult {\n  /** `true` only for 200 and 202. Everything else is a rejection. */\n  readonly ok: boolean\n  /** The HTTP status, or `0` when the request never completed. */\n  readonly status: number\n  /** A sentence you can log or print verbatim. */\n  readonly meaning: string\n}\n\n/**\n * Submit changed URLs to IndexNow.\n *\n * The key is read from `agentblog.config.ts` first and falls back to\n * `INDEXNOW_KEY` in the environment, so the secret never has to live in a\n * committed config file.\n */\nexport async function pingIndexNow(urls: readonly string[]): Promise<IndexNowResult | null> {\n  if (!config.indexnow.enabled) return null\n\n  const key = config.indexnow.key ?? process.env.INDEXNOW_KEY\n  if (!key) return null\n\n  const urlList = urls.slice(0, MAX_URLS_PER_REQUEST)\n  if (urlList.length === 0) return null\n\n  if (urls.length > MAX_URLS_PER_REQUEST) {\n    console.warn(\n      `[agentblog] IndexNow accepts ${MAX_URLS_PER_REQUEST} URLs per request; ` +\n        `submitting the first ${MAX_URLS_PER_REQUEST} of ${urls.length}. ` +\n        'Send the rest in a second call.',\n    )\n  }\n\n  let host: string\n  try {\n    host = new URL(config.siteUrl).host\n  } catch {\n    return null\n  }\n\n  try {\n    const response = await fetch(ENDPOINT, {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json; charset=utf-8' },\n      body: JSON.stringify({\n        host,\n        key,\n        // The key file lives at the site root. `absoluteUrl` leaves a path ending\n        // in a file extension alone, so this stays correct with trailingSlash on.\n        keyLocation: absoluteUrl(`/${key}.txt`),\n        urlList,\n      }),\n    })\n\n    const status = response.status\n    return {\n      ok: status === 200 || status === 202,\n      status,\n      meaning: MEANINGS[status] ?? `Unexpected status ${status} from ${ENDPOINT}.`,\n    }\n  } catch (cause) {\n    // A network failure is reported, never rethrown: the post is already\n    // published and revalidated by the time this runs.\n    const detail = cause instanceof Error ? cause.message : String(cause)\n    return {\n      ok: false,\n      status: 0,\n      meaning: `The request to ${ENDPOINT} did not complete: ${detail}`,\n    }\n  }\n}\n",
      "type": "registry:lib",
      "target": "lib/indexnow.ts"
    }
  ],
  "envVars": {
    "AGENTBLOG_REVALIDATE_SECRET": "",
    "INDEXNOW_KEY": ""
  },
  "docs": "Two empty entries were added to .env.local: AGENTBLOG_REVALIDATE_SECRET and INDEXNOW_KEY. They are placeholders, not keys. Run `npx agentblog@latest doctor --fix` to generate real values and write the matching public/<key>.txt file that IndexNow needs. If you keep secrets in a different env file, doctor check 13 runs `git check-ignore` on it and offers to move them somewhere untracked.",
  "categories": [
    "blog",
    "seo",
    "api"
  ],
  "type": "registry:block"
}