@utilsy/cms-nextjs 0.1.0

package/README.md

@@ -0,0 +1,157 @@
+# @utilsy/cms-nextjs
+
+Headless Next.js SDK for [Utilsy gateway-cms](https://github.com/utilsy/utilsy-cms-nextjs-sdk) public blog APIs. Provides a typed HTTP client, domain mappers, server-friendly fetch helpers, and React hooks—bring your own UI.
+
+## Install
+
+```bash
+npm install @utilsy/cms-nextjs
+```
+
+Peer dependencies: `react` ^18 or ^19. `next` is optional (only needed if you pass `next.revalidate` to fetch).
+
+## Quick start
+
+### 1. Create a client
+
+**Direct gateway-cms** (default path prefix):
+
+```ts
+import { createCmsClient } from "@utilsy/cms-nextjs";
+
+export const cms = createCmsClient({
+  baseUrl: process.env.NEXT_PUBLIC_CMS_BASE_URL!,
+  siteId: process.env.NEXT_PUBLIC_CMS_SITE_ID,
+});
+```
+
+**Main API gateway** (prefix before `/public/blog`):
+
+```ts
+export const cms = createCmsClient({
+  baseUrl: process.env.NEXT_PUBLIC_CMS_BASE_URL!,
+  siteId: process.env.NEXT_PUBLIC_CMS_SITE_ID,
+  pathPrefix: "/api/backend/cms",
+});
+```
+
+### 2. Server Component (list posts)
+
+```tsx
+import { cms } from "@/lib/cms";
+
+export default async function BlogPage() {
+  const result = await cms.blog.listMappedPosts(
+    { page: 1, limit: 20 },
+    { next: { revalidate: 60 } },
+  );
+
+  if (!result?.posts.length) {
+    return <p>No posts yet.</p>;
+  }
+
+  return (
+    <ul>
+      {result.posts.map((post) => (
+        <li key={post.postId}>
+          <a href={`/blog/${post.slug}`}>{post.title}</a>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### 3. Client engagement (likes & comments)
+
+```tsx
+"use client";
+
+import { CmsProvider, useBlogLike, useBlogComments } from "@utilsy/cms-nextjs/react";
+import { cms } from "@/lib/cms";
+
+export function PostEngagement({ postId }: { postId: string }) {
+  return (
+    <CmsProvider client={cms}>
+      <Engagement postId={postId} />
+    </CmsProvider>
+  );
+}
+
+function Engagement({ postId }: { postId: string }) {
+  const { liked, likeCount, toggle, toggling } = useBlogLike(postId);
+  const { comments, submitComment, submitting } = useBlogComments(postId);
+
+  return (
+    <div>
+      <button type="button" onClick={toggle} disabled={toggling}>
+        {liked ? "Unlike" : "Like"} ({likeCount})
+      </button>
+      <ul>
+        {comments.map((c) => (
+          <li key={c.id}>{c.name}: {c.message}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+## Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `NEXT_PUBLIC_CMS_BASE_URL` | Gateway or API base URL (no trailing slash) |
+| `NEXT_PUBLIC_CMS_SITE_ID` | CMS site Mongo id — **recommended** when Host does not match a CMS domain |
+| `NEXT_PUBLIC_CMS_PATH_PREFIX` | Optional, e.g. `/api/backend/cms` |
+
+## Site resolution
+
+The CMS resolves the site from:
+
+1. `?siteId=` query param (SDK appends this when `siteId` is configured), or
+2. `Host` / `x-origin` header matching a registered domain.
+
+For local dev or gateway-only deployments, always set `siteId` in the client config.
+
+## API reference
+
+### Client (`createCmsClient`)
+
+| Method | Description |
+|--------|-------------|
+| `blog.listPosts(query?, init?)` | Paginated list (summary fields only) |
+| `blog.getPostBySlug(slug, init?)` | Full post DTO |
+| `blog.listCategories(init?)` | Active categories |
+| `blog.listComments(postId, init?)` | Approved comments |
+| `blog.createComment(postId, body)` | Create comment (throws on error) |
+| `blog.getEngagement(postId, { visitorId? }, init?)` | Stats + `likedByMe` |
+| `blog.toggleLike(postId, { visitorId? })` | Toggle like |
+| `blog.listMappedPosts(...)` | List + `mapCmsPostToBlogPost` |
+| `blog.getMappedPostBySlug(...)` | Single mapped `BlogPost` |
+| `blog.listMappedCategories(...)` | Mapped categories |
+| `blog.listMappedComments(...)` | Mapped comments |
+
+### React (`@utilsy/cms-nextjs/react`)
+
+| Export | Description |
+|--------|-------------|
+| `CmsProvider` | Context for hooks |
+| `useCmsClient` | Access client instance |
+| `useVisitorId` / `getVisitorId` | Anonymous visitor id for likes |
+| `useBlogEngagement` | Load engagement stats |
+| `useBlogLike` | Like toggle + counts |
+| `useBlogComments` | List + submit comments |
+
+## CORS
+
+Public blog reads from the browser require either:
+
+- Same-origin proxy (e.g. Next.js Route Handler forwarding to gateway), or
+- Server Components / Route Handlers calling the SDK server-side.
+
+Mutations (comments, likes) should run client-side with a proxy or configured CORS on the gateway.
+
+## License
+
+MIT

package/dist/client-C3E94syg.d.cts

@@ -0,0 +1,184 @@
+type CmsApiResponse<T> = {
+    message?: string;
+    data?: T;
+    success?: boolean;
+};
+type FetchRequestInit = RequestInit & {
+    next?: {
+        revalidate?: number | false;
+        tags?: string[];
+    };
+    cache?: RequestCache;
+};
+
+/** Wire DTO from CMS public blog API */
+type CmsBlogPostDto = {
+    id: string;
+    slug?: string;
+    title?: string;
+    excerpt?: string;
+    content?: string;
+    data?: Record<string, unknown>;
+    tags?: string[];
+    categories?: Array<{
+        id: string;
+        name: string;
+        slug: string;
+    }>;
+    stats?: {
+        viewCount: number;
+        likeCount: number;
+        commentCount: number;
+    };
+    createdAt?: string;
+    published_at?: string;
+    featured_image?: unknown;
+};
+type CmsBlogCommentDto = {
+    id: string;
+    name: string;
+    message: string;
+    avatarUrl?: string;
+    postedAt?: string;
+    replyComment?: Array<{
+        id: string;
+        userId: string;
+        message: string;
+        postedAt?: string;
+    }>;
+};
+type CmsBlogCategoryDto = {
+    id: string;
+    name: string;
+    slug: string;
+    description?: string;
+    sortOrder?: number;
+};
+type CmsBlogPostsPage = {
+    docs: CmsBlogPostDto[];
+    total: number;
+    page?: number;
+    limit?: number;
+};
+type BlogAuthor = {
+    name: string;
+    avatarInitials?: string;
+};
+type BlogPost = {
+    postId: string;
+    slug: string;
+    title: string;
+    excerpt: string;
+    category: string;
+    tags: string[];
+    publishedAt: string;
+    readMinutes: number;
+    author: BlogAuthor;
+    imageSrc?: string;
+    imageAlt?: string;
+    body: string;
+    stats?: {
+        viewCount: number;
+        likeCount: number;
+        commentCount: number;
+    };
+};
+type BlogCommentReply = {
+    id: string;
+    userId: string;
+    message: string;
+    postedAt?: string;
+};
+type BlogComment = {
+    id: string;
+    name: string;
+    message: string;
+    avatarUrl?: string;
+    postedAt?: string;
+    replies: BlogCommentReply[];
+};
+type BlogCategory = {
+    id: string;
+    name: string;
+    slug: string;
+    description?: string;
+    sortOrder?: number;
+};
+type BlogEngagement = {
+    viewCount: number;
+    likeCount: number;
+    commentCount: number;
+    likedByMe: boolean;
+};
+type BlogLikeResult = {
+    liked: boolean;
+    likeCount: number;
+};
+type CreateBlogCommentInput = {
+    message: string;
+    guestName?: string;
+    guestEmail?: string;
+    parentId?: string;
+};
+type CreateBlogCommentResult = {
+    id: string;
+    status: string;
+};
+type ListBlogPostsQuery = {
+    page?: number;
+    limit?: number;
+    search?: string;
+    tag?: string;
+};
+
+type BlogRequestContext = {
+    baseUrl: string;
+    blogBasePath: string;
+    siteId?: string;
+    fetchFn: typeof fetch;
+    defaultHeaders: Record<string, string>;
+};
+declare function createBlogApi(ctx: BlogRequestContext): {
+    listPosts(query?: ListBlogPostsQuery, init?: FetchRequestInit): Promise<CmsBlogPostsPage | null>;
+    getPostBySlug(slug: string, init?: FetchRequestInit): Promise<CmsBlogPostDto | null>;
+    listCategories(init?: FetchRequestInit): Promise<CmsBlogCategoryDto[] | null>;
+    listComments(postId: string, init?: FetchRequestInit): Promise<CmsBlogCommentDto[] | null>;
+    createComment(postId: string, body: CreateBlogCommentInput): Promise<CreateBlogCommentResult>;
+    getEngagement(postId: string, options?: {
+        visitorId?: string;
+    }, init?: FetchRequestInit): Promise<BlogEngagement | null>;
+    toggleLike(postId: string, options?: {
+        visitorId?: string;
+    }): Promise<BlogLikeResult>;
+    listMappedPosts(query?: ListBlogPostsQuery, init?: FetchRequestInit): Promise<{
+        posts: BlogPost[];
+        total: number;
+        page: number | undefined;
+        limit: number | undefined;
+    } | null>;
+    getMappedPostBySlug(slug: string, init?: FetchRequestInit): Promise<BlogPost | null>;
+    listMappedCategories(init?: FetchRequestInit): Promise<BlogCategory[] | null>;
+    listMappedComments(postId: string, init?: FetchRequestInit): Promise<BlogComment[] | null>;
+};
+type BlogApi = ReturnType<typeof createBlogApi>;
+
+type CmsClientConfig = {
+    /** Base URL, e.g. https://cms-gateway.example.com */
+    baseUrl: string;
+    /** CMS site Mongo id — appended as ?siteId= on every blog request */
+    siteId?: string;
+    /**
+     * Path prefix before /public/blog.
+     * Default '' for gateway-cms direct (/public/blog/...).
+     * Use '/api/backend/cms' when routing through the main API gateway.
+     */
+    pathPrefix?: string;
+    fetch?: typeof fetch;
+    defaultHeaders?: Record<string, string>;
+};
+type CmsClient = {
+    blog: BlogApi;
+};
+declare function createCmsClient(config: CmsClientConfig): CmsClient;
+
+export { type BlogApi as B, type CmsApiResponse as C, type FetchRequestInit as F, type ListBlogPostsQuery as L, type BlogAuthor as a, type BlogCategory as b, type BlogComment as c, type BlogCommentReply as d, type BlogEngagement as e, type BlogLikeResult as f, type BlogPost as g, type CmsBlogCategoryDto as h, type CmsBlogCommentDto as i, type CmsBlogPostDto as j, type CmsBlogPostsPage as k, type CmsClient as l, type CmsClientConfig as m, type CreateBlogCommentInput as n, type CreateBlogCommentResult as o, createCmsClient as p };

package/dist/client-C3E94syg.d.ts

@@ -0,0 +1,184 @@
+type CmsApiResponse<T> = {
+    message?: string;
+    data?: T;
+    success?: boolean;
+};
+type FetchRequestInit = RequestInit & {
+    next?: {
+        revalidate?: number | false;
+        tags?: string[];
+    };
+    cache?: RequestCache;
+};
+
+/** Wire DTO from CMS public blog API */
+type CmsBlogPostDto = {
+    id: string;
+    slug?: string;
+    title?: string;
+    excerpt?: string;
+    content?: string;
+    data?: Record<string, unknown>;
+    tags?: string[];
+    categories?: Array<{
+        id: string;
+        name: string;
+        slug: string;
+    }>;
+    stats?: {
+        viewCount: number;
+        likeCount: number;
+        commentCount: number;
+    };
+    createdAt?: string;
+    published_at?: string;
+    featured_image?: unknown;
+};
+type CmsBlogCommentDto = {
+    id: string;
+    name: string;
+    message: string;
+    avatarUrl?: string;
+    postedAt?: string;
+    replyComment?: Array<{
+        id: string;
+        userId: string;
+        message: string;
+        postedAt?: string;
+    }>;
+};
+type CmsBlogCategoryDto = {
+    id: string;
+    name: string;
+    slug: string;
+    description?: string;
+    sortOrder?: number;
+};
+type CmsBlogPostsPage = {
+    docs: CmsBlogPostDto[];
+    total: number;
+    page?: number;
+    limit?: number;
+};
+type BlogAuthor = {
+    name: string;
+    avatarInitials?: string;
+};
+type BlogPost = {
+    postId: string;
+    slug: string;
+    title: string;
+    excerpt: string;
+    category: string;
+    tags: string[];
+    publishedAt: string;
+    readMinutes: number;
+    author: BlogAuthor;
+    imageSrc?: string;
+    imageAlt?: string;
+    body: string;
+    stats?: {
+        viewCount: number;
+        likeCount: number;
+        commentCount: number;
+    };
+};
+type BlogCommentReply = {
+    id: string;
+    userId: string;
+    message: string;
+    postedAt?: string;
+};
+type BlogComment = {
+    id: string;
+    name: string;
+    message: string;
+    avatarUrl?: string;
+    postedAt?: string;
+    replies: BlogCommentReply[];
+};
+type BlogCategory = {
+    id: string;
+    name: string;
+    slug: string;
+    description?: string;
+    sortOrder?: number;
+};
+type BlogEngagement = {
+    viewCount: number;
+    likeCount: number;
+    commentCount: number;
+    likedByMe: boolean;
+};
+type BlogLikeResult = {
+    liked: boolean;
+    likeCount: number;
+};
+type CreateBlogCommentInput = {
+    message: string;
+    guestName?: string;
+    guestEmail?: string;
+    parentId?: string;
+};
+type CreateBlogCommentResult = {
+    id: string;
+    status: string;
+};
+type ListBlogPostsQuery = {
+    page?: number;
+    limit?: number;
+    search?: string;
+    tag?: string;
+};
+
+type BlogRequestContext = {
+    baseUrl: string;
+    blogBasePath: string;
+    siteId?: string;
+    fetchFn: typeof fetch;
+    defaultHeaders: Record<string, string>;
+};
+declare function createBlogApi(ctx: BlogRequestContext): {
+    listPosts(query?: ListBlogPostsQuery, init?: FetchRequestInit): Promise<CmsBlogPostsPage | null>;
+    getPostBySlug(slug: string, init?: FetchRequestInit): Promise<CmsBlogPostDto | null>;
+    listCategories(init?: FetchRequestInit): Promise<CmsBlogCategoryDto[] | null>;
+    listComments(postId: string, init?: FetchRequestInit): Promise<CmsBlogCommentDto[] | null>;
+    createComment(postId: string, body: CreateBlogCommentInput): Promise<CreateBlogCommentResult>;
+    getEngagement(postId: string, options?: {
+        visitorId?: string;
+    }, init?: FetchRequestInit): Promise<BlogEngagement | null>;
+    toggleLike(postId: string, options?: {
+        visitorId?: string;
+    }): Promise<BlogLikeResult>;
+    listMappedPosts(query?: ListBlogPostsQuery, init?: FetchRequestInit): Promise<{
+        posts: BlogPost[];
+        total: number;
+        page: number | undefined;
+        limit: number | undefined;
+    } | null>;
+    getMappedPostBySlug(slug: string, init?: FetchRequestInit): Promise<BlogPost | null>;
+    listMappedCategories(init?: FetchRequestInit): Promise<BlogCategory[] | null>;
+    listMappedComments(postId: string, init?: FetchRequestInit): Promise<BlogComment[] | null>;
+};
+type BlogApi = ReturnType<typeof createBlogApi>;
+
+type CmsClientConfig = {
+    /** Base URL, e.g. https://cms-gateway.example.com */
+    baseUrl: string;
+    /** CMS site Mongo id — appended as ?siteId= on every blog request */
+    siteId?: string;
+    /**
+     * Path prefix before /public/blog.
+     * Default '' for gateway-cms direct (/public/blog/...).
+     * Use '/api/backend/cms' when routing through the main API gateway.
+     */
+    pathPrefix?: string;
+    fetch?: typeof fetch;
+    defaultHeaders?: Record<string, string>;
+};
+type CmsClient = {
+    blog: BlogApi;
+};
+declare function createCmsClient(config: CmsClientConfig): CmsClient;
+
+export { type BlogApi as B, type CmsApiResponse as C, type FetchRequestInit as F, type ListBlogPostsQuery as L, type BlogAuthor as a, type BlogCategory as b, type BlogComment as c, type BlogCommentReply as d, type BlogEngagement as e, type BlogLikeResult as f, type BlogPost as g, type CmsBlogCategoryDto as h, type CmsBlogCommentDto as i, type CmsBlogPostDto as j, type CmsBlogPostsPage as k, type CmsClient as l, type CmsClientConfig as m, type CreateBlogCommentInput as n, type CreateBlogCommentResult as o, createCmsClient as p };