@accountgroove/blog 0.1.0

package/README.md

@@ -0,0 +1,84 @@
+# @accountgroove/blog
+
+Client SDK for the AccountGroove **Content API**. Drop it into a client's
+**Astro** or **Next.js** site to render their published blog **on their own
+domain, with their own CSS** — subdirectory URLs (`client.com/blog`), great SEO,
+no iframe.
+
+This is the "Bucket A" delivery adapter from the platform architecture
+(`docs/PLATFORM-ARCHITECTURE.md` §7): for sites we build/control, the blog is
+rendered *inside* the site's own app, so styling matches automatically.
+
+## Install
+
+```bash
+npm install @accountgroove/blog
+```
+
+Set two env vars in the host site:
+
+```bash
+ACCOUNTGROOVE_API_BASE=https://mcp.accountgroove.ai   # Content API base (default)
+ACCOUNTGROOVE_LOCATION_ID=<the client's GHL locationId>
+```
+
+## Core usage (any framework)
+
+```ts
+import { createBlogClient } from "@accountgroove/blog";
+
+const blog = createBlogClient({
+  apiBase: process.env.ACCOUNTGROOVE_API_BASE!,
+  locationId: process.env.ACCOUNTGROOVE_LOCATION_ID!,
+});
+
+const posts = await blog.listPosts({ type: "blog", limit: 20 }); // BlogPostSummary[]
+const post = await blog.getPost("my-slug");                       // BlogPost | null
+```
+
+Only **published** posts (`status='posted'`) are ever returned, scoped to the
+location. `listPosts` gives an `excerpt`; `getPost` gives the full `body`.
+
+## Astro (primary)
+
+Copy the example routes:
+
+- `examples/astro/blog-index.astro` → `src/pages/blog/index.astro`
+- `examples/astro/blog-slug.astro` → `src/pages/blog/[slug].astro`
+
+They use `export const prerender = false` (Astro hybrid/SSR) so newly published
+posts appear immediately. Wrap them in your site layout so the blog inherits the
+nav/footer/CSS.
+
+## Next.js (App Router)
+
+Copy:
+
+- `examples/next/blog-page.tsx` → `app/blog/page.tsx`
+- `examples/next/blog-slug-page.tsx` → `app/blog/[slug]/page.tsx`
+- `examples/next/revalidate-route.ts` → `app/api/accountgroove/revalidate/route.ts`
+
+The pages tag their fetches (`ag-blog`, `ag-blog:<slug>`) and the revalidate
+route purges those tags on publish — **ISR + on-demand revalidation, no
+redeploy** (docs §11). Set `ACCOUNTGROOVE_REVALIDATE_SECRET` and register the
+route URL as the site's publish webhook in AccountGroove.
+
+## Freshness model
+
+| Mode | How fresh content arrives |
+| --- | --- |
+| Next (App Router) | publish → webhook → `revalidateTag` → live in seconds |
+| Astro (SSR/hybrid) | rendered per request → always current (add a CDN cache + purge for speed) |
+| Static build | rebuild/redeploy on publish (simplest, slowest) |
+
+## API
+
+- `createBlogClient(options): BlogClient`
+  - `options.apiBase` — Content API base URL
+  - `options.locationId` — the tenant's GHL locationId
+  - `options.fetch?` — fetch override
+- `client.listPosts(params?, init?) → Promise<BlogPostSummary[]>`
+  - `params`: `{ type?, limit?, offset? }` · `init`: standard `RequestInit`
+    (e.g. `{ next: { tags: ["ag-blog"], revalidate: 60 } }`)
+- `client.getPost(slug, init?) → Promise<BlogPost | null>` (`null` on 404)
+- Throws `BlogApiError` (`.status`, `.url`) on other non-OK responses.

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+export type ContentType = "blog" | "newsletter" | "social";
+/** A post as returned by the list endpoint (excerpt, no full body). */
+export interface BlogPostSummary {
+    id: string;
+    type: ContentType;
+    title: string | null;
+    slug: string | null;
+    postedAt: string | null;
+    excerpt: string | null;
+}
+/** A post as returned by the detail endpoint (full body, no excerpt). */
+export interface BlogPost {
+    id: string;
+    type: ContentType;
+    title: string | null;
+    slug: string | null;
+    postedAt: string | null;
+    body: string | null;
+}
+export interface BlogClientOptions {
+    /** Base URL of the Content API, e.g. "https://mcp.accountgroove.ai". */
+    apiBase: string;
+    /** The tenant's GHL locationId (their site key). */
+    locationId: string;
+    /** Optional fetch override (e.g. a Next-instrumented fetch for caching). */
+    fetch?: typeof fetch;
+}
+export interface ListPostsParams {
+    type?: ContentType;
+    /** 1–100, default 20 (server-clamped). */
+    limit?: number;
+    offset?: number;
+}
+/** Thrown when the Content API returns a non-OK, non-404 response. */
+export declare class BlogApiError extends Error {
+    readonly status: number;
+    readonly url: string;
+    constructor(message: string, status: number, url: string);
+}
+export interface BlogClient {
+    listPosts(params?: ListPostsParams, init?: RequestInit): Promise<BlogPostSummary[]>;
+    getPost(slug: string, init?: RequestInit): Promise<BlogPost | null>;
+}
+/**
+ * Create a Content API client bound to one tenant's site.
+ *
+ * Next.js: pass `init` with `{ next: { tags: ["ag-blog"], revalidate: 60 } }`
+ * to get ISR + on-demand revalidation (pair with the revalidate route handler).
+ */
+export declare function createBlogClient(options: BlogClientOptions): BlogClient;

package/dist/index.js

@@ -0,0 +1,71 @@
+// @accountgroove/blog — framework-agnostic client for the AccountGroove
+// Content API. Drop into an Astro/Next (or any JS) site to render a tenant's
+// published blog on the site's own domain, with the site's own CSS.
+//
+// Zero dependencies: uses the global fetch/URL. Works in Node, Astro, Next,
+// Cloudflare Workers, and the browser.
+//
+// The Content API surface it speaks to (public, read-only):
+//   GET {apiBase}/v1/sites/{locationId}/posts            -> { posts: BlogPostSummary[] }
+//   GET {apiBase}/v1/sites/{locationId}/posts/{slug}     -> { post: BlogPost }
+/** Thrown when the Content API returns a non-OK, non-404 response. */
+export class BlogApiError extends Error {
+    status;
+    url;
+    constructor(message, status, url) {
+        super(message);
+        this.status = status;
+        this.url = url;
+        this.name = "BlogApiError";
+    }
+}
+/**
+ * Create a Content API client bound to one tenant's site.
+ *
+ * Next.js: pass `init` with `{ next: { tags: ["ag-blog"], revalidate: 60 } }`
+ * to get ISR + on-demand revalidation (pair with the revalidate route handler).
+ */
+export function createBlogClient(options) {
+    const base = options.apiBase.replace(/\/+$/, "");
+    const doFetch = options.fetch ?? fetch;
+    const site = encodeURIComponent(options.locationId);
+    async function request(path, init) {
+        const url = `${base}/v1/sites/${site}${path}`;
+        let res;
+        try {
+            res = await doFetch(url, init);
+        }
+        catch (err) {
+            throw new BlogApiError(`Network error: ${err.message}`, 0, url);
+        }
+        return res;
+    }
+    return {
+        async listPosts(params = {}, init) {
+            const q = new URLSearchParams();
+            if (params.type)
+                q.set("type", params.type);
+            if (params.limit != null)
+                q.set("limit", String(params.limit));
+            if (params.offset != null)
+                q.set("offset", String(params.offset));
+            const qs = q.toString();
+            const res = await request(`/posts${qs ? `?${qs}` : ""}`, init);
+            if (!res.ok) {
+                throw new BlogApiError(`Failed to list posts (HTTP ${res.status})`, res.status, res.url);
+            }
+            const data = (await res.json());
+            return data.posts ?? [];
+        },
+        async getPost(slug, init) {
+            const res = await request(`/posts/${encodeURIComponent(slug)}`, init);
+            if (res.status === 404)
+                return null;
+            if (!res.ok) {
+                throw new BlogApiError(`Failed to get post (HTTP ${res.status})`, res.status, res.url);
+            }
+            const data = (await res.json());
+            return data.post ?? null;
+        },
+    };
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@accountgroove/blog",
+  "version": "0.1.0",
+  "description": "Client SDK for the AccountGroove Content API — render a tenant's published blog on their own Astro/Next site.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "sideEffects": false,
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  }
+}