@agentcms/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MC2 Ventures
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# @agentcms/react
+
+React SDK for the **AgentCMS headless API**. Use it in any React app (Next.js, Vite, Remix, etc.) to fetch posts, site context, and list/filter content from an AgentCMS-backed site.
+
+**Requires** a live AgentCMS site (e.g. [@agentcms/core](https://github.com/agentcms/agentcms) on Astro + Cloudflare) that exposes `/api/agent/context` and `/api/agent/posts`.
+
+## Install
+
+```bash
+npm install @agentcms/react
+# or
+pnpm add @agentcms/react
+```
+
+**Peer dependency:** React 18 or 19.
+
+## Setup
+
+Wrap your app (or the subtree that needs AgentCMS data) with `AgentCMSProvider` and pass the base URL of your AgentCMS site.
+
+```tsx
+import { AgentCMSProvider } from "@agentcms/react";
+
+function App() {
+  return (
+    <AgentCMSProvider baseUrl="https://your-blog.pages.dev">
+      <YourRoutes />
+    </AgentCMSProvider>
+  );
+}
+```
+
+Optional: `apiKey` for endpoints that require auth (e.g. draft or read-only agent key).
+
+```tsx
+<AgentCMSProvider baseUrl="https://..." apiKey="acms_live_...">
+  {children}
+</AgentCMSProvider>
+```
+
+## Usage
+
+### Hooks (recommended)
+
+**Paginated post list** — with optional `limit`, `offset`, `tag`, `category`:
+
+```tsx
+import { useAgentCMSPosts } from "@agentcms/react";
+
+function PostList() {
+  const { posts, total, hasMore, loading, error, refetch } = useAgentCMSPosts({
+    limit: 10,
+    tag: "ai",
+  });
+
+  if (loading) return <div>Loading…</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <ul>
+      {posts.map((p) => (
+        <li key={p.slug}>
+          <a href={`/blog/${p.slug}`}>{p.title}</a>
+        </li>
+      ))}
+      {hasMore && <button onClick={() => refetch()}>Load more</button>}
+    </ul>
+  );
+}
+```
+
+**Single post by slug:**
+
+```tsx
+import { useAgentCMSPost } from "@agentcms/react";
+
+function Post({ slug }: { slug: string }) {
+  const { post, loading, error } = useAgentCMSPost(slug);
+
+  if (loading) return <div>Loading…</div>;
+  if (error || !post) return <div>Not found</div>;
+
+  return (
+    <article>
+      <h1>{post.title}</h1>
+      <div dangerouslySetInnerHTML={{ __html: post.contentHtml ?? post.content }} />
+    </article>
+  );
+}
+```
+
+**Site context** (voice, guidelines, tags, categories — useful for agent UIs or discovery):
+
+```tsx
+import { useAgentCMSContext } from "@agentcms/react";
+
+function SiteInfo() {
+  const { context, loading } = useAgentCMSContext();
+
+  if (loading || !context) return null;
+  return (
+    <p>
+      {context.site.name} — {context.site.description}
+    </p>
+  );
+}
+```
+
+### Client (without hooks)
+
+If you need the client outside React or for one-off calls:
+
+```tsx
+import { AgentCMSProvider, useAgentCMSClient } from "@agentcms/react";
+
+function SomeComponent() {
+  const client = useAgentCMSClient();
+  const handleClick = async () => {
+    const ctx = await client.getContext();
+    const { posts } = await client.listPosts({ limit: 5 });
+  };
+  // ...
+}
+```
+
+Or instantiate directly (no provider):
+
+```tsx
+import { AgentCMSClient } from "@agentcms/react";
+
+const client = new AgentCMSClient({
+  baseUrl: "https://your-blog.pages.dev",
+  apiKey: "optional",
+});
+const context = await client.getContext();
+const { posts } = await client.listPosts({ limit: 10 });
+```
+
+## API
+
+| Export | Description |
+|--------|-------------|
+| `AgentCMSProvider` | Provider; props: `baseUrl`, `apiKey?`, `children` |
+| `useAgentCMSClient()` | Returns `AgentCMSClient` (must be used inside provider) |
+| `useAgentCMSPosts(params?)` | `{ posts, total, hasMore, loading, error, refetch }`; params: `limit?`, `offset?`, `tag?`, `category?` |
+| `useAgentCMSPost(slug \| null)` | `{ post, loading, error, refetch }` |
+| `useAgentCMSContext()` | `{ context, loading, error, refetch }` |
+| `AgentCMSClient` | `getContext()`, `listPosts(params?)`, `getPost(slug)` |
+| `AgentCMSError` | `Error` subclass with `status` (HTTP status code) |
+
+Types: `AgentCMSPost`, `PostListResponse`, `SiteContext`, `ListPostsParams`, `AgentCMSConfig` are exported for TypeScript.
+
+## Repo / publish
+
+Published as `@agentcms/react`. Source: [github.com/agentcms/react](https://github.com/agentcms/react). It can be used against any deployed AgentCMS site; no direct dependency on Astro or Cloudflare in your React app.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@agentcms/react",
+  "version": "0.1.0",
+  "description": "React SDK for AgentCMS headless API",
+  "type": "module",
+  "license": "MIT",
+  "author": "MC2 Ventures",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentcms/react"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "@tanstack/react-query": "^5.0.0"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@tanstack/react-query": "^5.64.0",
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/src/client.test.ts

@@ -0,0 +1,231 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { AgentCMSClient, AgentCMSError } from "./client.js";
+import type { PostListResponse, SiteContext, AgentCMSPost } from "./types.js";
+
+// --- Mock fetch ---
+
+const originalFetch = globalThis.fetch;
+let mockFetch: ReturnType<typeof vi.fn>;
+
+beforeEach(() => {
+  mockFetch = vi.fn();
+  globalThis.fetch = mockFetch;
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+function mockJsonResponse(data: unknown, status = 200) {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+// ============================================================================
+// Constructor
+// ============================================================================
+
+describe("AgentCMSClient", () => {
+  it("strips trailing slashes from baseUrl", () => {
+    const client = new AgentCMSClient({ baseUrl: "https://example.com///" });
+    // Verify by making a request and checking the URL
+    mockFetch.mockResolvedValue(mockJsonResponse({ posts: [] }));
+    client.listPosts();
+    expect(mockFetch).toHaveBeenCalledWith(
+      "https://example.com/api/agent/posts",
+      expect.any(Object)
+    );
+  });
+
+  it("includes Authorization header when apiKey is provided", async () => {
+    const client = new AgentCMSClient({
+      baseUrl: "https://example.com",
+      apiKey: "acms_live_test",
+    });
+    mockFetch.mockResolvedValue(mockJsonResponse({}));
+    await client.getContext();
+
+    const headers = mockFetch.mock.calls[0][1].headers;
+    expect(headers.Authorization).toBe("Bearer acms_live_test");
+  });
+
+  it("omits Authorization header when no apiKey", async () => {
+    const client = new AgentCMSClient({ baseUrl: "https://example.com" });
+    mockFetch.mockResolvedValue(mockJsonResponse({}));
+    await client.getContext();
+
+    const headers = mockFetch.mock.calls[0][1].headers;
+    expect(headers.Authorization).toBeUndefined();
+  });
+});
+
+// ============================================================================
+// getContext
+// ============================================================================
+
+describe("getContext", () => {
+  it("fetches /api/agent/context", async () => {
+    const client = new AgentCMSClient({ baseUrl: "https://blog.test" });
+    const ctx: SiteContext = {
+      site: {
+        name: "Test",
+        description: "Test blog",
+        url: "https://blog.test",
+        language: "en",
+      },
+      writingGuidelines: {
+        tone: "casual",
+        targetAudience: "devs",
+        preferredLength: "short",
+      },
+      existingContent: {
+        totalPosts: 5,
+        recentTitles: ["Hello"],
+        existingTags: ["test"],
+        existingCategories: ["General"],
+      },
+      capabilities: {
+        maxContentLength: 100000,
+        markdownFeatures: ["headings", "code"],
+      },
+    };
+    mockFetch.mockResolvedValue(mockJsonResponse(ctx));
+
+    const result = await client.getContext();
+    expect(result).toEqual(ctx);
+    expect(mockFetch).toHaveBeenCalledWith(
+      "https://blog.test/api/agent/context",
+      expect.objectContaining({ headers: expect.objectContaining({ Accept: "application/json" }) })
+    );
+  });
+});
+
+// ============================================================================
+// listPosts
+// ============================================================================
+
+describe("listPosts", () => {
+  it("fetches /api/agent/posts with no params", async () => {
+    const client = new AgentCMSClient({ baseUrl: "https://blog.test" });
+    const body: PostListResponse = {
+      posts: [],
+      total: 0,
+      limit: 20,
+      offset: 0,
+      hasMore: false,
+    };
+    mockFetch.mockResolvedValue(mockJsonResponse(body));
+
+    const result = await client.listPosts();
+    expect(result).toEqual(body);
+    expect(mockFetch).toHaveBeenCalledWith(
+      "https://blog.test/api/agent/posts",
+      expect.any(Object)
+    );
+  });
+
+  it("builds query string from params", async () => {
+    const client = new AgentCMSClient({ baseUrl: "https://blog.test" });
+    mockFetch.mockResolvedValue(
+      mockJsonResponse({ posts: [], total: 0, limit: 5, offset: 10, hasMore: false })
+    );
+
+    await client.listPosts({ limit: 5, offset: 10, tag: "ai", category: "Tech" });
+    const url = mockFetch.mock.calls[0][0] as string;
+    expect(url).toContain("limit=5");
+    expect(url).toContain("offset=10");
+    expect(url).toContain("tag=ai");
+    expect(url).toContain("category=Tech");
+  });
+
+  it("omits undefined params from query string", async () => {
+    const client = new AgentCMSClient({ baseUrl: "https://blog.test" });
+    mockFetch.mockResolvedValue(
+      mockJsonResponse({ posts: [], total: 0, limit: 20, offset: 0, hasMore: false })
+    );
+
+    await client.listPosts({ tag: "ai" });
+    const url = mockFetch.mock.calls[0][0] as string;
+    expect(url).toContain("tag=ai");
+    expect(url).not.toContain("limit");
+    expect(url).not.toContain("offset");
+    expect(url).not.toContain("category");
+  });
+});
+
+// ============================================================================
+// getPost
+// ============================================================================
+
+describe("getPost", () => {
+  it("fetches /api/agent/posts/:slug", async () => {
+    const client = new AgentCMSClient({ baseUrl: "https://blog.test" });
+    const post: AgentCMSPost = {
+      slug: "hello-world",
+      title: "Hello World",
+      description: "First post",
+      content: "# Hello",
+      author: "Agent",
+      authorType: "agent",
+      tags: ["intro"],
+      publishedAt: "2025-01-01T00:00:00.000Z",
+      updatedAt: "2025-01-01T00:00:00.000Z",
+      status: "published",
+      metadata: {},
+    };
+    mockFetch.mockResolvedValue(mockJsonResponse(post));
+
+    const result = await client.getPost("hello-world");
+    expect(result).toEqual(post);
+    expect(mockFetch).toHaveBeenCalledWith(
+      "https://blog.test/api/agent/posts/hello-world",
+      expect.any(Object)
+    );
+  });
+
+  it("encodes slug in URL", async () => {
+    const client = new AgentCMSClient({ baseUrl: "https://blog.test" });
+    mockFetch.mockResolvedValue(mockJsonResponse({}));
+    await client.getPost("hello world");
+    const url = mockFetch.mock.calls[0][0] as string;
+    expect(url).toContain("hello%20world");
+  });
+});
+
+// ============================================================================
+// Error handling
+// ============================================================================
+
+describe("error handling", () => {
+  it("throws AgentCMSError on non-OK response", async () => {
+    const client = new AgentCMSClient({ baseUrl: "https://blog.test" });
+    mockFetch.mockResolvedValue(
+      new Response("Not Found", { status: 404 })
+    );
+
+    try {
+      await client.getPost("nope");
+      expect.unreachable("should have thrown");
+    } catch (e) {
+      expect(e).toBeInstanceOf(AgentCMSError);
+      expect((e as AgentCMSError).message).toMatch(/404/);
+    }
+  });
+
+  it("AgentCMSError has status property", async () => {
+    const client = new AgentCMSClient({ baseUrl: "https://blog.test" });
+    mockFetch.mockResolvedValue(
+      new Response("Forbidden", { status: 403 })
+    );
+
+    try {
+      await client.getContext();
+      expect.unreachable("should have thrown");
+    } catch (e) {
+      expect(e).toBeInstanceOf(AgentCMSError);
+      expect((e as AgentCMSError).status).toBe(403);
+    }
+  });
+});

package/src/client.ts

@@ -0,0 +1,94 @@
+// ============================================================================
+// @agentcms/react — API Client
+// ============================================================================
+
+import type {
+  AgentCMSConfig,
+  AgentCMSPost,
+  GetPostsParams,
+  GetPostsResult,
+  GetCategoriesResult,
+  GetTagsResult,
+  SiteContext,
+} from "./types.js";
+
+export class AgentCMSClient {
+  private baseUrl: string;
+  private apiKey?: string;
+
+  constructor(config: AgentCMSConfig = {}) {
+    this.baseUrl = (config.baseUrl ?? "/api").replace(/\/+$/, "");
+    this.apiKey = config.apiKey;
+  }
+
+  private async fetch<T>(path: string, auth = false): Promise<T> {
+    const headers: Record<string, string> = {
+      Accept: "application/json",
+    };
+    if (auth && this.apiKey) {
+      headers.Authorization = `Bearer ${this.apiKey}`;
+    }
+
+    const res = await fetch(`${this.baseUrl}${path}`, { headers });
+    if (!res.ok) {
+      throw new AgentCMSError(res.status, await res.text());
+    }
+    return res.json() as Promise<T>;
+  }
+
+  // --- Public endpoints (no auth) ---
+
+  async getPosts(params: GetPostsParams = {}): Promise<GetPostsResult> {
+    const { page = 1, limit = 20, tag, category } = params;
+    const offset = (page - 1) * limit;
+    const qs = new URLSearchParams();
+    qs.set("limit", String(limit));
+    qs.set("offset", String(offset));
+    if (tag) qs.set("tag", tag);
+    if (category) qs.set("category", category);
+
+    const raw = await this.fetch<{
+      posts: AgentCMSPost[];
+      total: number;
+      limit: number;
+      offset: number;
+      hasMore: boolean;
+    }>(`/posts?${qs}`);
+
+    return {
+      posts: raw.posts,
+      total: raw.total,
+      totalPages: Math.ceil(raw.total / limit),
+      page,
+      hasMore: raw.hasMore,
+    };
+  }
+
+  async getPost(slug: string): Promise<AgentCMSPost> {
+    return this.fetch<AgentCMSPost>(`/posts/${encodeURIComponent(slug)}`);
+  }
+
+  async getCategories(): Promise<GetCategoriesResult> {
+    return this.fetch<GetCategoriesResult>("/categories");
+  }
+
+  async getTags(): Promise<GetTagsResult> {
+    return this.fetch<GetTagsResult>("/tags");
+  }
+
+  // --- Agent endpoints (auth required) ---
+
+  async getContext(): Promise<SiteContext> {
+    return this.fetch<SiteContext>("/agent/context", true);
+  }
+}
+
+export class AgentCMSError extends Error {
+  status: number;
+
+  constructor(status: number, body: string) {
+    super(`AgentCMS API error ${status}: ${body}`);
+    this.name = "AgentCMSError";
+    this.status = status;
+  }
+}

package/src/hooks.ts

@@ -0,0 +1,53 @@
+// ============================================================================
+// @agentcms/react — TanStack Query Hooks
+// ============================================================================
+
+import { useQuery, keepPreviousData } from "@tanstack/react-query";
+import { useAgentCMSClient } from "./provider.js";
+import type {
+  GetPostsParams,
+  GetPostsResult,
+  GetCategoriesResult,
+  GetTagsResult,
+  AgentCMSPost,
+} from "./types.js";
+
+const STALE_TIME = 60_000; // 60s — matches server Cache-Control
+
+export function useAgentCMSPosts(params: GetPostsParams = {}) {
+  const client = useAgentCMSClient();
+  return useQuery<GetPostsResult>({
+    queryKey: ["agentcms", "posts", params],
+    queryFn: () => client.getPosts(params),
+    staleTime: STALE_TIME,
+    placeholderData: keepPreviousData,
+  });
+}
+
+export function useAgentCMSPost(slug: string | undefined | null) {
+  const client = useAgentCMSClient();
+  return useQuery<AgentCMSPost>({
+    queryKey: ["agentcms", "post", slug],
+    queryFn: () => client.getPost(slug!),
+    enabled: !!slug,
+    staleTime: STALE_TIME,
+  });
+}
+
+export function useAgentCMSCategories() {
+  const client = useAgentCMSClient();
+  return useQuery<GetCategoriesResult>({
+    queryKey: ["agentcms", "categories"],
+    queryFn: () => client.getCategories(),
+    staleTime: STALE_TIME,
+  });
+}
+
+export function useAgentCMSTags() {
+  const client = useAgentCMSClient();
+  return useQuery<GetTagsResult>({
+    queryKey: ["agentcms", "tags"],
+    queryFn: () => client.getTags(),
+    staleTime: STALE_TIME,
+  });
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+// ============================================================================
+// @agentcms/react — React SDK for AgentCMS
+// ============================================================================
+
+// Client
+export { AgentCMSClient, AgentCMSError } from "./client.js";
+
+// Provider
+export { AgentCMSProvider, useAgentCMSClient } from "./provider.js";
+export type { AgentCMSProviderProps } from "./provider.js";
+
+// Hooks
+export {
+  useAgentCMSPosts,
+  useAgentCMSPost,
+  useAgentCMSCategories,
+  useAgentCMSTags,
+} from "./hooks.js";
+
+// Types
+export type {
+  AgentCMSPost,
+  GetPostsParams,
+  GetPostsResult,
+  GetCategoriesResult,
+  GetTagsResult,
+  SiteContext,
+  AgentCMSConfig,
+} from "./types.js";

package/src/provider.tsx

@@ -0,0 +1,40 @@
+// ============================================================================
+// @agentcms/react — Context Provider
+// ============================================================================
+
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+import { AgentCMSClient } from "./client.js";
+import type { AgentCMSConfig } from "./types.js";
+
+const AgentCMSContext = createContext<AgentCMSClient | null>(null);
+
+export interface AgentCMSProviderProps extends AgentCMSConfig {
+  children: ReactNode;
+}
+
+export function AgentCMSProvider({
+  baseUrl = "/api",
+  apiKey,
+  children,
+}: AgentCMSProviderProps) {
+  const client = useMemo(
+    () => new AgentCMSClient({ baseUrl, apiKey }),
+    [baseUrl, apiKey]
+  );
+
+  return (
+    <AgentCMSContext.Provider value={client}>
+      {children}
+    </AgentCMSContext.Provider>
+  );
+}
+
+export function useAgentCMSClient(): AgentCMSClient {
+  const client = useContext(AgentCMSContext);
+  if (!client) {
+    throw new Error(
+      "useAgentCMSClient must be used within an <AgentCMSProvider>"
+    );
+  }
+  return client;
+}

package/src/types.ts

@@ -0,0 +1,76 @@
+// ============================================================================
+// @agentcms/react — Client-side Types
+// ============================================================================
+
+export interface AgentCMSPost {
+  slug: string;
+  title: string;
+  description: string;
+  content: string;
+  contentHtml?: string;
+  author: string;
+  authorType: "agent" | "human";
+  tags: string[];
+  category?: string;
+  publishedAt: string;
+  updatedAt: string;
+  status: "published" | "draft" | "scheduled";
+  scheduledFor?: string;
+  featuredImage?: string;
+  ogImage?: string;
+  readingTime?: number;
+  featured?: boolean;
+  metadata: Record<string, unknown>;
+}
+
+export interface GetPostsParams {
+  page?: number;
+  limit?: number;
+  tag?: string;
+  category?: string;
+}
+
+export interface GetPostsResult {
+  posts: AgentCMSPost[];
+  total: number;
+  totalPages: number;
+  page: number;
+  hasMore: boolean;
+}
+
+export interface GetCategoriesResult {
+  categories: Array<{ category: string; count: number }>;
+}
+
+export interface GetTagsResult {
+  tags: Array<{ tag: string; count: number }>;
+}
+
+export interface SiteContext {
+  site: {
+    name: string;
+    description: string;
+    url: string;
+    language: string;
+  };
+  writingGuidelines: {
+    tone: string;
+    targetAudience: string;
+    preferredLength: string;
+  };
+  existingContent: {
+    totalPosts: number;
+    recentTitles: string[];
+    existingTags: string[];
+    existingCategories: string[];
+  };
+  capabilities: {
+    maxContentLength: number;
+    markdownFeatures: string[];
+  };
+}
+
+export interface AgentCMSConfig {
+  baseUrl?: string;
+  apiKey?: string;
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "jsx": "react-jsx",
+    "lib": ["ES2022", "DOM"]
+  },
+  "include": ["src"],
+  "exclude": ["src/**/*.test.*"]
+}