@autoblogwriter/sdk 1.0.2

package/README.md

@@ -0,0 +1,296 @@
+# @blogauto/sdk
+
+Official TypeScript SDK for BlogAuto. It keeps server-side integration tiny, adds helpers for Next.js App Router and Vite/React apps, and ships revalidation utilities that respect BlogAuto's API contract.
+
+## Installation
+
+```bash
+npm install @blogauto/sdk
+```
+
+> Requires Node.js 18+ and native `fetch`. Bundles ship as ESM, CJS, and types via `tsup`.
+
+## Security Notes (Read First)
+- Never ship BlogAuto API keys in public, client-side code.
+- Run the SDK inside Next.js server components, route handlers, or your own backend proxy.
+- If you must expose functionality to the browser, issue scoped public tokens or proxy through your server. Do **not** mint new auth schemes.
+
+## Client Configuration
+
+```ts
+import { createBlogAutoClient } from "@blogauto/sdk";
+
+const client = createBlogAutoClient({
+  apiUrl: "https://api.blogauto.io",
+  apiKey: process.env.BLOGAUTO_API_KEY!,
+  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
+});
+```
+
+| Option | Type | Required | Description |
+| --- | --- | --- | --- |
+| `apiUrl` | `string` | yes | Root API URL, e.g. `https://api.blogauto.io`. Trailing slash removed automatically. |
+| `apiKey` | `string` | yes | Workspace-scoped API key created in the BlogAuto 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. |
+
+## Next.js App Router Usage
+
+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.
+
+### `app/blog/page.tsx`
+
+```ts
+// app/blog/page.tsx
+import { createBlogAutoClient, renderMarkdownToHtml } from "@blogauto/sdk";
+
+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 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>
+  );
+}
+```
+
+### `app/blog/[slug]/page.tsx`
+
+```ts
+// app/blog/[slug]/page.tsx
+import { notFound } from "next/navigation";
+import { createBlogAutoClient, renderMarkdownToHtml } from "@blogauto/sdk";
+
+const workspaceSlug = process.env.BLOGAUTO_WORKSPACE!;
+const blogClient = createBlogAutoClient({
+  apiUrl: process.env.BLOGAUTO_API_URL!,
+  apiKey: process.env.BLOGAUTO_API_KEY!,
+  workspaceSlug,
+});
+
+interface Props {
+  params: { slug: string };
+}
+
+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>
+  );
+}
+```
+
+### `app/sitemap.ts`
+
+```ts
+// app/sitemap.ts
+import { buildSitemap, createBlogAutoClient } from "@blogauto/sdk";
+
+const blogClient = createBlogAutoClient({
+  apiUrl: process.env.BLOGAUTO_API_URL!,
+  apiKey: process.env.BLOGAUTO_API_KEY!,
+  workspaceSlug: process.env.BLOGAUTO_WORKSPACE!,
+});
+
+export default async function sitemap() {
+  const entries = await blogClient.getSitemapEntries();
+  return buildSitemap({
+    siteUrl: process.env.SITE_URL!,
+    entries,
+    routePrefix: "/blog",
+  });
+}
+```
+
+### `app/robots.ts`
+
+```ts
+// app/robots.ts
+import { buildRobots } from "@blogauto/sdk";
+
+export default function robots() {
+  return buildRobots({
+    siteUrl: process.env.SITE_URL!,
+    sitemapPath: "/sitemap.xml",
+  });
+}
+```
+
+## Vite/React Usage with Server Proxy
+
+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.
+
+```ts
+// server/routes/blogauto.ts (Express example)
+import express from "express";
+import { createBlogAutoClient } from "@blogauto/sdk";
+
+const router = express.Router();
+const blogClient = createBlogAutoClient({
+  apiUrl: process.env.BLOGAUTO_API_URL!,
+  apiKey: process.env.BLOGAUTO_API_KEY!,
+  workspaceId: process.env.BLOGAUTO_WORKSPACE_ID!,
+});
+
+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 });
+});
+
+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);
+});
+
+export default router;
+```
+
+React (client) calls your proxy:
+
+```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>
+  );
+}
+```
+
+## Automatic Revalidation Setup
+
+When BlogAuto publishes a post it can ping your Next.js App Router site so sitemap, robots, and cached blog pages refresh immediately.
+
+1. **Configure your workspace**
+   - In the BlogAuto 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**
+
+```ts
+// app/api/blogauto/revalidate/route.ts
+import { revalidatePath, revalidateTag } from "next/cache";
+import { createRevalidateRouteHandler } from "@blogauto/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,
+  revalidatePath,
+  revalidateTag,
+  // Optional overrides:
+  // allowedSkewSeconds: 600,
+  // revalidatePaths: (payload) => [...custom paths...],
+  // revalidateTags: (payload) => [...custom tags...],
+});
+```
+
+The handler verifies the `X-BlogAuto-Signature` HMAC header, enforces timestamp skew (default 5 minutes), and revalidates:
+
+- 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?**
+
+```ts
+import { verifyWebhookSignature } from "@blogauto/sdk/revalidate";
+
+const isValid = verifyWebhookSignature({
+  rawBody, // string or Buffer
+  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
+npm test
+```
+
+Tests cover config validation, auth headers, 404 handling, sitemap output, and revalidation helpers.