@autoblogwriter/sdk 2.0.5 → 2.0.6

package/README.md

@@ -12,6 +12,33 @@ npm install @autoblogwriter/sdk
 
 > Requires Node.js 18+ and native `fetch`. Bundles ship as ESM, CJS, and types via `tsup`.
 
+## Entry Points
+
+```ts
+// Core client, types, and utilities
+import { createBlogAutoClient } from "@autoblogwriter/sdk";
+
+// Next.js App Router helpers (server-side)
+import { fetchBlogPosts, fetchBlogPost } from "@autoblogwriter/sdk/next";
+
+// React components
+import { BlogPost, BlogPostList, Markdown } from "@autoblogwriter/sdk/react";
+
+// Webhook signature verification (server-side)
+import { verifyWebhookSignature } from "@autoblogwriter/sdk/revalidate";
+
+// Default styles
+import "@autoblogwriter/sdk/styles.css";
+```
+
+| Entry Point | Environment | Description |
+| --- | --- | --- |
+| `@autoblogwriter/sdk` | Server | Core client, markdown renderer, sitemap/robots builders |
+| `@autoblogwriter/sdk/next` | Server (Next.js) | `fetchBlogPosts`, `fetchBlogPost`, `generatePostMetadata`, `generateBlogSitemap`, `generateBlogRobots`, `createEnvRevalidateHandler` |
+| `@autoblogwriter/sdk/react` | Client or Server | `<BlogPost>`, `<BlogPostList>`, `<Markdown>` components |
+| `@autoblogwriter/sdk/revalidate` | Server | `createRevalidateRouteHandler`, `verifyWebhookSignature` |
+| `@autoblogwriter/sdk/styles.css` | Client | Default dark-theme styles for all components |
+
 ## Security Notes (Read First)
 - Never ship AutoBlogWriter API keys in public, client-side code.
 - Run the SDK inside Next.js server components, route handlers, or your own backend proxy.
@@ -45,198 +72,319 @@ const client = createBlogAutoClient({
 | `fetch` | `typeof fetch` | no | Provide a custom fetch implementation (e.g., for SSR polyfills). |
 | `timeoutMs` | `number` | no | Optional request timeout enforced client-side. |
 
-## Next.js App Router Usage
+## Next.js Helper Functions (`@autoblogwriter/sdk/next`)
+
+The `next` entry point provides high-level helpers that read configuration from environment variables automatically (via `createBlogAutoFromEnv`). Set these env vars and the helpers handle client creation, cache tagging, and metadata for you:
+
+| Env Variable | Required | Description |
+| --- | --- | --- |
+| `BLOGAUTO_API_KEY` | yes | Workspace API key |
+| `BLOGAUTO_WORKSPACE_SLUG` | yes | Workspace slug for content APIs |
+| `BLOGAUTO_API_URL` | no | Defaults to `https://api.autoblogwriter.app` |
+| `BLOGAUTO_WORKSPACE_ID` | no | Optional workspace ID |
+| `SITE_URL` or `NEXT_PUBLIC_SITE_URL` | no | Defaults to `http://localhost:3000` |
+| `BLOGAUTO_REVALIDATE_SECRET` | no | Required for the revalidation handler |
 
-All examples assume you run in server files where environment variables are available. **Do not** move these snippets to client components without a secure proxy.
+### `fetchBlogPosts(options?)`
 
-### `app/blog/page.tsx`
+Fetches a paginated list of posts with automatic cache tagging.
 
 ```ts
-// app/blog/page.tsx
-import { createBlogAutoClient, renderMarkdownToHtml } from "@autoblogwriter/sdk";
+import { fetchBlogPosts } from "@autoblogwriter/sdk/next";
 
-const workspaceSlug = process.env.BLOGAUTO_WORKSPACE!;
-const blogClient = createBlogAutoClient({
-  apiUrl: process.env.BLOGAUTO_API_URL!,
-  apiKey: process.env.BLOGAUTO_API_KEY!,
-  workspaceSlug,
-});
+const { posts, nextCursor } = await fetchBlogPosts({ limit: 20 });
+```
 
-export default async function BlogIndexPage() {
-  const { posts } = await blogClient.getPosts({
-    limit: 20,
-    next: { tags: [`blogauto:${workspaceSlug}:posts`] },
-  });
-
-  return (
-    <div>
-      {posts.map((post) => (
-        <article key={post.id}>
-          <h2>{post.title}</h2>
-          <div dangerouslySetInnerHTML={{ __html: renderMarkdownToHtml(post.excerpt ?? "") }} />
-        </article>
-      ))}
-    </div>
-  );
+### `fetchBlogPost(slug)`
+
+Fetches a single post by slug. Automatically calls `notFound()` if the post doesn't exist.
+
+```ts
+import { fetchBlogPost } from "@autoblogwriter/sdk/next";
+
+const post = await fetchBlogPost(params.slug);
+```
+
+### `generatePostMetadata(slug)`
+
+Returns a Next.js `Metadata` object (title, description, Open Graph, Twitter cards) for a blog post. Use it in your `generateMetadata` export.
+
+```ts
+import { generatePostMetadata } from "@autoblogwriter/sdk/next";
+
+export async function generateMetadata({ params }: Props) {
+  return generatePostMetadata(params.slug);
 }
 ```
 
-### `app/blog/[slug]/page.tsx`
+### `generateBlogSitemap()`
+
+Returns a `MetadataRoute.Sitemap` array for `app/sitemap.ts`.
 
 ```ts
-// app/blog/[slug]/page.tsx
-import { notFound } from "next/navigation";
-import { createBlogAutoClient, renderMarkdownToHtml } from "@autoblogwriter/sdk";
+import { generateBlogSitemap } from "@autoblogwriter/sdk/next";
 
-const workspaceSlug = process.env.BLOGAUTO_WORKSPACE!;
-const blogClient = createBlogAutoClient({
-  apiUrl: process.env.BLOGAUTO_API_URL!,
-  apiKey: process.env.BLOGAUTO_API_KEY!,
-  workspaceSlug,
-});
+export default async function sitemap() {
+  return generateBlogSitemap();
+}
+```
+
+### `generateBlogRobots()`
+
+Returns a `MetadataRoute.Robots` object for `app/robots.ts`.
+
+```ts
+import { generateBlogRobots } from "@autoblogwriter/sdk/next";
+
+export default function robots() {
+  return generateBlogRobots();
+}
+```
+
+### `createEnvRevalidateHandler()`
+
+Creates a POST route handler for webhook-based revalidation. Reads `BLOGAUTO_REVALIDATE_SECRET` from env, verifies the HMAC signature, and calls `revalidatePath`/`revalidateTag`.
+
+```ts
+// app/api/blogauto/revalidate/route.ts
+import { createEnvRevalidateHandler } from "@autoblogwriter/sdk/next";
+
+export const POST = createEnvRevalidateHandler();
+```
+
+### Full Next.js Example
+
+```ts
+// app/blog/page.tsx
+import { fetchBlogPosts } from "@autoblogwriter/sdk/next";
+import { BlogPostList } from "@autoblogwriter/sdk/react";
+
+export default async function BlogIndexPage() {
+  const { posts } = await fetchBlogPosts({ limit: 20 });
+  return <BlogPostList posts={posts} />;
+}
+```
+
+```ts
+// app/blog/[slug]/page.tsx
+import { fetchBlogPost, generatePostMetadata } from "@autoblogwriter/sdk/next";
+import { BlogPost } from "@autoblogwriter/sdk/react";
 
 interface Props {
   params: { slug: string };
 }
 
+export async function generateMetadata({ params }: Props) {
+  return generatePostMetadata(params.slug);
+}
+
 export default async function BlogPostPage({ params }: Props) {
-  const post = await blogClient.getPostBySlug(params.slug, {
-    next: { tags: [`blogauto:${workspaceSlug}:post:${params.slug}`] },
-  });
-  if (!post) {
-    notFound();
-  }
-
-  return (
-    <article>
-      <h1>{post.title}</h1>
-      <time dateTime={post.publishedAt ?? post.updatedAt}>{post.publishedAt}</time>
-      <div dangerouslySetInnerHTML={{ __html: renderMarkdownToHtml(post.content) }} />
-    </article>
-  );
+  const post = await fetchBlogPost(params.slug);
+  return <BlogPost post={post} />;
 }
 ```
 
-### `app/sitemap.ts`
+## React Components (`@autoblogwriter/sdk/react`)
 
-```ts
-// app/sitemap.ts
-import { buildSitemap, createBlogAutoClient } from "@autoblogwriter/sdk";
+Pre-built components for rendering blog content. Works in Next.js, Vite, or any React 18+ app.
 
-const blogClient = createBlogAutoClient({
-  apiUrl: process.env.BLOGAUTO_API_URL!,
-  apiKey: process.env.BLOGAUTO_API_KEY!,
-  workspaceSlug: process.env.BLOGAUTO_WORKSPACE!,
-});
+### `<Markdown>`
 
-export default async function sitemap() {
-  const entries = await blogClient.getSitemapEntries();
-  return buildSitemap({
-    siteUrl: process.env.SITE_URL!,
-    entries,
-    routePrefix: "/blog",
-  });
-}
+Renders a markdown string to HTML using the built-in renderer.
+
+```tsx
+import { Markdown } from "@autoblogwriter/sdk/react";
+
+<Markdown source={post.content} />
+<Markdown source={post.content} className="custom-markdown" />
 ```
 
-### `app/robots.ts`
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `source` | `string \| null` | — | Markdown string to render. Returns `null` if empty. |
+| `className` | `string` | `"ba-markdown"` | CSS class on the wrapper `<div>`. |
+
+### `<BlogPost>`
+
+Renders a full blog post with title, date, reading time, and markdown content.
+
+```tsx
+import { BlogPost } from "@autoblogwriter/sdk/react";
+
+<BlogPost post={post} />
+<BlogPost post={post} showDate={false} />
+<BlogPost post={post} renderContent={(md) => <MyCustomRenderer source={md} />} />
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `post` | `BlogPost` | — | The post object from the SDK. |
+| `showTitle` | `boolean` | `true` | Show the post title as an `<h1>`. |
+| `showDate` | `boolean` | `true` | Show the published/updated date. |
+| `className` | `string` | `"ba-post"` | CSS class on the `<article>`. |
+| `renderContent` | `(content: string) => ReactNode` | — | Override the default `<Markdown>` renderer. |
+
+### `<BlogPostList>`
+
+Renders a list of post cards with titles, dates, and excerpts.
+
+```tsx
+import { BlogPostList } from "@autoblogwriter/sdk/react";
+
+<BlogPostList posts={posts} />
+<BlogPostList posts={posts} title="Blog" routePrefix="/articles" />
+```
+
+With Next.js `<Link>`:
+
+```tsx
+import Link from "next/link";
+
+<BlogPostList posts={posts} linkComponent={Link} />
+```
+
+With a custom card:
+
+```tsx
+<BlogPostList
+  posts={posts}
+  renderCard={(post, href) => (
+    <a href={href}>{post.title} — {post.excerpt}</a>
+  )}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `posts` | `BlogPost[]` | — | Array of post objects. |
+| `title` | `string` | `"Latest posts"` | Section heading. Pass empty string to hide. |
+| `routePrefix` | `string` | `"/blog"` | URL prefix for post links (`{routePrefix}/{slug}`). |
+| `linkComponent` | `React.ComponentType` | `<a>` | Custom link component (e.g. Next.js `Link`). |
+| `className` | `string` | `"ba-listing"` | CSS class on the `<section>`. |
+| `renderCard` | `(post, href) => ReactNode` | — | Override the default card rendering. |
+
+## Styles (`@autoblogwriter/sdk/styles.css`)
+
+The SDK ships a default dark-theme stylesheet that styles all the React components out of the box. Import it in your app entry point:
 
 ```ts
-// app/robots.ts
-import { buildRobots } from "@autoblogwriter/sdk";
+// app/layout.tsx or src/main.tsx
+import "@autoblogwriter/sdk/styles.css";
+```
 
-export default function robots() {
-  return buildRobots({
-    siteUrl: process.env.SITE_URL!,
-    sitemapPath: "/sitemap.xml",
-  });
+All values are driven by CSS custom properties on `:root`, so you can override them to match your theme:
+
+```css
+:root {
+  --ba-color-bg: #0c0d10;
+  --ba-color-text: #f2f4f8;
+  --ba-color-text-muted: rgba(242, 244, 248, 0.6);
+  --ba-color-link: #6cf;
+  --ba-color-link-hover: #8df;
+  --ba-color-border: rgba(255, 255, 255, 0.08);
+  --ba-color-card-bg: rgba(255, 255, 255, 0.02);
+  --ba-color-card-bg-hover: rgba(255, 255, 255, 0.04);
+  --ba-color-code-bg: rgba(255, 255, 255, 0.1);
+  --ba-color-pre-bg: rgba(255, 255, 255, 0.05);
+  --ba-radius: 8px;
+  --ba-max-width: 720px;
+  --ba-font-sans: system-ui, -apple-system, sans-serif;
+  --ba-font-mono: ui-monospace, SFMono-Regular, monospace;
 }
 ```
 
-## Vite/React Usage with Server Proxy
+For a light theme, override the color variables:
+
+```css
+:root {
+  --ba-color-bg: #ffffff;
+  --ba-color-text: #1a1a1a;
+  --ba-color-text-muted: rgba(0, 0, 0, 0.5);
+  --ba-color-text-secondary: rgba(0, 0, 0, 0.7);
+  --ba-color-text-content: rgba(0, 0, 0, 0.85);
+  --ba-color-link: #0066cc;
+  --ba-color-link-hover: #0052a3;
+  --ba-color-border: rgba(0, 0, 0, 0.1);
+  --ba-color-card-bg: rgba(0, 0, 0, 0.02);
+  --ba-color-card-bg-hover: rgba(0, 0, 0, 0.04);
+  --ba-color-code-bg: rgba(0, 0, 0, 0.06);
+  --ba-color-pre-bg: rgba(0, 0, 0, 0.03);
+}
+```
+
+### CSS Class Reference
+
+| Class | Used by | Description |
+| --- | --- | --- |
+| `.ba-listing` | `<BlogPostList>` | Outer section wrapper |
+| `.ba-listing-title` | `<BlogPostList>` | Section heading |
+| `.ba-posts` | `<BlogPostList>` | Flex column container for cards |
+| `.ba-post-card` | `<BlogPostList>` | Individual post card |
+| `.ba-post-card-title` | `<BlogPostList>` | Card title |
+| `.ba-post-card-link` | `<BlogPostList>` | Title link |
+| `.ba-post-card-meta` | `<BlogPostList>` | Card date |
+| `.ba-post-card-excerpt` | `<BlogPostList>` | Card excerpt |
+| `.ba-post` | `<BlogPost>` | Article wrapper |
+| `.ba-post-title` | `<BlogPost>` | Post title |
+| `.ba-post-meta` | `<BlogPost>` | Date and reading time |
+| `.ba-markdown` | `<Markdown>` | Markdown content wrapper |
 
-Never pipe the API key directly to the browser. Instead, add a tiny proxy route inside your server (Express, Fastify, Next API route, etc.) that calls the SDK.
+## Low-Level Client Configuration
+
+For advanced use cases where you need more control than the env-based helpers provide, you can create a client directly:
 
 ```ts
-// server/routes/blogauto.ts (Express example)
-import express from "express";
 import { createBlogAutoClient } from "@autoblogwriter/sdk";
 
-const router = express.Router();
-const blogClient = createBlogAutoClient({
-  apiUrl: process.env.BLOGAUTO_API_URL!,
+const client = createBlogAutoClient({
+  apiUrl: "https://api.autoblogwriter.app",
   apiKey: process.env.BLOGAUTO_API_KEY!,
-  workspaceId: process.env.BLOGAUTO_WORKSPACE_ID!,
+  workspaceId: process.env.BLOGAUTO_WORKSPACE_ID,
+  workspaceSlug: process.env.BLOGAUTO_WORKSPACE_SLUG,
+  authMode: "bearer",           // or "x-api-key"
+  headers: { "x-trace-id": "..." },
+  timeoutMs: 10_000,
+  fetch: globalThis.fetch,       // optional custom fetch
 });
+```
 
-router.get("/posts", async (req, res) => {
-  const { posts, nextCursor } = await blogClient.getPosts({
-    limit: Number(req.query.limit) || 10,
-    cursor: req.query.cursor?.toString(),
-  });
-  res.json({ posts, nextCursor });
-});
+| Option | Type | Required | Description |
+| --- | --- | --- | --- |
+| `apiUrl` | `string` | yes | Root API URL, e.g. `https://api.autoblogwriter.app`. Trailing slash removed automatically. |
+| `apiKey` | `string` | yes | Workspace-scoped API key created in the AutoBlogWriter dashboard. |
+| `workspaceId` | `string` | one of `workspaceId` or `workspaceSlug` | Optional; used for account scoping. |
+| `workspaceSlug` | `string` | one of `workspaceId` or `workspaceSlug` | Required for public content APIs (`/v1/public/:workspaceSlug/...`). |
+| `authMode` | `"bearer" \| "x-api-key"` | no (default `"bearer"`) | Sends the API key via `Authorization: Bearer` or `x-api-key`. |
+| `headers` | `Record<string, string>` | no | Additional static headers (merged on each request). |
+| `fetch` | `typeof fetch` | no | Provide a custom fetch implementation (e.g., for SSR polyfills). |
+| `timeoutMs` | `number` | no | Optional request timeout enforced client-side. |
 
-router.get("/posts/:slug", async (req, res) => {
-  const post = await blogClient.getPostBySlug(req.params.slug);
-  if (!post) {
-    return res.status(404).json({ error: "Not Found" });
-  }
-  res.json(post);
-});
+## Revalidation
 
-export default router;
-```
+When AutoBlogWriter publishes a post it can ping your Next.js site so cached pages refresh immediately.
 
-React (client) calls your proxy:
+**Quick setup** (env-based, one line):
 
 ```ts
-// src/pages/Blog.tsx
-import useSWR from "swr";
-
-const fetcher = (url: string) => fetch(url).then((res) => res.json());
-
-export function BlogList() {
-  const { data } = useSWR("/api/blogauto/posts", fetcher);
-  if (!data) return <p>Loading…</p>;
-
-  return (
-    <ul>
-      {data.posts.map((post: any) => (
-        <li key={post.id}>{post.title}</li>
-      ))}
-    </ul>
-  );
-}
-```
+// app/api/blogauto/revalidate/route.ts
+import { createEnvRevalidateHandler } from "@autoblogwriter/sdk/next";
 
-## Automatic Revalidation Setup
+export const POST = createEnvRevalidateHandler();
+```
 
-When AutoBlogWriter publishes a post it can ping your Next.js App Router site so sitemap, robots, and cached blog pages refresh immediately.
+Set `BLOGAUTO_REVALIDATE_SECRET` in your environment and configure the webhook URL in the AutoBlogWriter dashboard under **Workspace Settings → Revalidation URL**.
 
-1. **Configure your workspace**
-   - In the AutoBlogWriter dashboard open **Workspace Settings → Revalidation URL** and set your endpoint (e.g., `https://yoursite.com/api/blogauto/revalidate`).
-   - Generate a **Revalidation Webhook secret**, copy the plain secret once, and store it as `BLOGAUTO_REVALIDATE_SECRET`.
-2. **Create the route handler**
+**Advanced setup** (manual control via `@autoblogwriter/sdk/revalidate`):
 
 ```ts
 // app/api/blogauto/revalidate/route.ts
 import { revalidatePath, revalidateTag } from "next/cache";
 import { createRevalidateRouteHandler } from "@autoblogwriter/sdk/revalidate";
 
-const secret = process.env.BLOGAUTO_REVALIDATE_SECRET;
-if (!secret) {
-  throw new Error("Set BLOGAUTO_REVALIDATE_SECRET on the server");
-}
-
 export const POST = createRevalidateRouteHandler({
-  secret,
+  secret: process.env.BLOGAUTO_REVALIDATE_SECRET!,
   revalidatePath,
   revalidateTag,
-  // Optional overrides:
-  // allowedSkewSeconds: 600,
-  // revalidatePaths: (payload) => [...custom paths...],
-  // revalidateTags: (payload) => [...custom tags...],
 });
 ```
 
@@ -245,50 +393,18 @@ The handler verifies the `X-BlogAuto-Signature` HMAC header, enforces timestamp
 - Paths: `/sitemap.xml`, `/robots.txt`, `/blog`, `/blog/:slug`
 - Tags: `blogauto:<workspaceSlug>:sitemap`, `blogauto:<workspaceSlug>:posts`, and `blogauto:<workspaceSlug>:post:<slug>`
 
-3. **Tag your data fetches**
-
-Use the `next` option when calling SDK methods so `revalidateTag` knows which caches to expire:
-
-```ts
-await blogClient.getPosts({
-  limit: 20,
-  next: { tags: [`blogauto:${workspaceSlug}:posts`] },
-});
-
-await blogClient.getPostBySlug(slug, {
-  next: { tags: [`blogauto:${workspaceSlug}:post:${slug}`] },
-});
-```
-
-### Cache Invalidation Notes
-
-- In production, rely on tag-based revalidation via the webhook handler above. This prevents users from needing hard refreshes after publishing.
-- For very dynamic pages, you can opt out of caching per request with `cache: "no-store"` in the fetch options.
-- For client-side lists (SWR/React Query), call `mutate`/`invalidateQueries` after your proxy endpoint updates, or on a webhook-driven event from your backend.
-
-4. **Need manual verification?**
+For manual signature verification:
 
 ```ts
 import { verifyWebhookSignature } from "@autoblogwriter/sdk/revalidate";
 
 const isValid = verifyWebhookSignature({
-  rawBody, // string or Buffer
+  rawBody,
   signature: req.headers.get("x-blogauto-signature"),
   secret: process.env.BLOGAUTO_REVALIDATE_SECRET!,
 });
 ```
 
-Reject missing/invalid signatures or stale timestamps to prevent replay attacks, and avoid logging the secret or signature hash.
-
-## Markdown Rendering Helper
-
-`renderMarkdownToHtml(markdown: string)` ships a dependency-free renderer that covers headings, links, emphasis, inline/code fences, and paragraphs. For richer formatting you can bring your own renderer—this helper simply provides a safe default.
-
-## Dynamic Sitemaps & Robots
-
-- `buildSitemap({ siteUrl, entries, routePrefix })` returns a `MetadataRoute.Sitemap` array ready for `app/sitemap.ts`.
-- `buildRobots({ siteUrl, sitemapPath })` outputs a `MetadataRoute.Robots` structure. Defaults: route prefix `/blog`, sitemap path `/sitemap.xml`.
-
 ## Testing
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autoblogwriter/sdk",
-  "version": "2.0.5",
+  "version": "2.0.6",
   "description": "Official AutoBlogWriter SDK for fetching posts, building sitemaps, rendering helpers, and revalidation utilities.",
   "license": "MIT",
   "type": "module",