Connect with your AI agent

Connect my website to Blogs for SEO by following the instructions below. Work in this repository. Ask me before doing anything outside it (deploying, changing DNS or paying for anything).

# Connect this website to Blogs for SEO

Blogs for SEO writes articles. This website must show them natively, on its own domain and in its own design, so Google and AI assistants (ChatGPT, Claude, Perplexity) can read, rank and cite them. Build the integration below in this codebase. It reads posts from a public, read-only JSON API.

## Values
- Content API base ({API} below): `https://blogsforseo.com/api/v1/sites/{SITE_KEY}`
- SITE_KEY: ask me for it. It's on the "Connect your website" page in the Blogs for SEO dashboard.
- Post URLs: not chosen yet. Use `/blog/{slug}` on my domain unless the site already has a blog path, then tell me the full pattern.
- INDEXNOW_KEY: ask me for it (same dashboard page), or skip step 7 and tell me.
- WEBHOOK_SECRET: never ask me to paste it to you. Read it from the env var `BLOGSFORSEO_WEBHOOK_SECRET` and tell me to set that var myself.

## Steps

### 0. Look before you build
- Work out the stack: framework, how pages render (server, static build, client-only), where it's hosted, and the existing layout, header, footer and styles.
- If I can't edit code (WordPress, Webflow, Shopify, Wix or Squarespace without code access), stop and tell me. Point me to https://blogsforseo.com/services for done-for-you setup.
- If pages render only in the browser (a plain single-page app), posts must still reach crawlers as HTML: use server rendering, prerendering at build time, or a server route. Client-side fetching alone fails, because AI crawlers don't run JavaScript.
- Tell me your plan in 5 lines or fewer, then build it.

### 1. Config
- Env vars: `BLOGSFORSEO_SITE_KEY` (required), `BLOGSFORSEO_API_URL` (defaults to `https://blogsforseo.com`), `BLOGSFORSEO_WEBHOOK_SECRET` (only if you build step 8).
- Add them to the project's env example file. Never hardcode the secret.
- Every response is JSON except `/llms.txt`. Only published posts are returned. No auth header is needed.
- JavaScript or TypeScript project? You may use `npm install @blogsforseo/sdk`: a typed client plus `headTags()`, `seoMeta()`, `sitemapXml()` and `verifyWebhook()` for the steps below. Other languages: plain HTTP.

### 2. Blog index page
- `GET {API}/posts?page=N&pageSize=12` returns `{ posts, page, totalPages, total }` (pageSize max 50).
- Each summary has `slug, title, metaDescription, shortAnswer, canonicalUrl, heroImage {url, alt, width, height} | null, tags, publishedAt, updatedAt, readingMinutes`.
- Show a card per post linking to its URL, plus pagination and an empty state ("No posts yet").

### 3. Post page, at the post URL pattern
- `GET {API}/posts/{slug}`. A 404 from the API must become a real 404 page with a 404 status.
- Render on the server: the title and body must be in the raw HTML response.
- Render, in this order:
  1. `<h1>` with `title`; then `author.name`, `publishedAt`, `updatedAt` (if different) and `readingMinutes`.
  2. `heroImage` if present, with alt, width and height.
  3. `shortAnswer` in a highlighted box, then `keyTakeaways` as a list.
  4. A table of contents from `toc` (`{id, text, level}`, linking to `#id`) when it has 3 or more entries.
  5. `bodyHtml`, inserted as raw HTML. It is already sanitised: don't escape it or strip its ids and links.
  6. `faqs` (`{question, answer}`), `sources` (`{label, url, asOf}`, as links) and `related` (`{slug, title, metaDescription, canonicalUrl}`, as links).
- Style the body's elements (h2, h3, p, ul, ol, table, blockquote, a, img, code) to match the site.
- In `<head>`:
  - `<title>` from `metaTitle`
  - meta description from `metaDescription`
  - `<link rel="canonical">` from `canonicalUrl` (when not null)
  - Open Graph title, description, image and `og:type=article`
  - `<script type="application/ld+json">` containing `JSON.stringify(post.jsonLd)`, with every `<` replaced by `\u003c`
- If the framework streams metadata after the body for some bots, make sure GPTBot, ClaudeBot, PerplexityBot and Googlebot get it in `<head>`.

### 4. Caching
- Cache API responses for up to 15 minutes (ISR, fetch cache, CDN or similar). Step 8 clears the cache sooner on every publish.
- If the site is a static build with no server, skip step 8. I'll paste the host's deploy hook URL into the dashboard instead, so every publish rebuilds the site.

### 5. Sitemap and robots.txt
- Add every entry from `GET {API}/sitemap` (`[{ url, lastmod }]`) and the blog index to the site's sitemap. Merge with the existing sitemap; don't replace it.
- robots.txt must not block Googlebot, Bingbot, GPTBot, OAI-SearchBot, ChatGPT-User, ClaudeBot, Claude-User, Claude-SearchBot, PerplexityBot or Perplexity-User. Change nothing else.

### 6. llms.txt
- If the site has no `/llms.txt`, serve `GET {API}/llms.txt` (plain text) at `/llms.txt`.
- If it has one, add a "Blog" section linking each post (title and URL from `/posts`).

### 7. IndexNow key file
- Serve `/{INDEXNOW_KEY}.txt` at the site root. The body is exactly the key, as text/plain. It lets Bing and ChatGPT search find new posts within minutes.

### 8. Publish webhook (skip for static builds; see step 4)
- Add a `POST` endpoint, e.g. `/api/blogsforseo`.
- Verify the `x-blogsforseo-signature` header before trusting the request:
  1. It looks like `t=<unix seconds>,v1=<hex>`.
  2. Compute the HMAC-SHA256 of `t + "." + rawBody` with `BLOGSFORSEO_WEBHOOK_SECRET`. Use the raw body bytes, before any JSON parsing.
  3. Compare it with `v1` in constant time.
  4. Reject with 401 if they differ, or if `t` is more than 300 seconds from now.
- The JSON body is `{ event, occurredAt, siteKey, post?: { slug, … }, previousSlug? }`. `event` is `post.published`, `post.updated`, `post.unpublished` or `test`.
- On a valid request: clear the cache for the blog index, the post page and the `previousSlug` page if present. Return 200 quickly, including for `test`.

## Verify, then report
Run the site locally and check each of these with curl. Fix anything that fails.
1. `curl -A GPTBot <blog index>` returns 200 and lists the posts, or the empty state if none are published yet.
2. If a post exists: `curl -A GPTBot <post URL>`. The raw HTML has the `<h1>`, body text, canonical, meta description and the `application/ld+json` script.
3. `curl -A GPTBot <post URL with a made-up slug>` returns status 404.
4. `/sitemap.xml`, `/robots.txt`, `/llms.txt` and `/{INDEXNOW_KEY}.txt` are correct.
5. Webhook: sign a test body with a throwaway secret in the env and send it with curl. It should get 200; a wrong signature should get 401.
6. Run the project's existing lint, typecheck and tests.

Then give me:
- A short summary: the files you changed, and the env vars I must set in production (including `BLOGSFORSEO_WEBHOOK_SECRET`, copied from the dashboard's "Signing secret").
- A checklist for the "Connect your website" page in the Blogs for SEO dashboard:
  1. Set the post URL pattern to the full pattern you used, e.g. `https://mydomain.com/blog/{slug}`.
  2. Set the webhook URL to the endpoint you made, or the deploy hook URL for a static site.
  3. Deploy, then press "Send test" and "Run health check".