@utilsy/cms-nextjs 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @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.
+Headless Next.js SDK for [Utilsy gateway-cms](https://github.com/utilsy/utilsy-cms-nextjs-sdk) public CMS APIs: blog (`/public/blog`) and dynamic content types (`/public/api`). Provides a typed HTTP client, domain mappers, server-friendly fetch helpers, and React data hooks—bring your own UI.
 
 ## Install
 
@@ -25,7 +25,7 @@ export const cms = createCmsClient({
 });
 ```
 
-**Main API gateway** (prefix before `/public/blog`):
+**Main API gateway** (prefix before `/public/blog` and `/public/api`):
 
 ```ts
 export const cms = createCmsClient({
@@ -62,7 +62,35 @@ export default async function BlogPage() {
 }
 ```
 
-### 3. Client engagement (likes & comments)
+### 3. Server Component (filtered content by type)
+
+```tsx
+import { cms } from "@/lib/cms";
+
+export default async function ServicesPage() {
+  const result = await cms.content.listMappedEntries(
+    "services",
+    { page: 1, limit: 12, filters: { featured: true } },
+    { next: { revalidate: 60, tags: ["cms:services"] } },
+  );
+
+  if (!result?.entries.length) {
+    return <p>No services yet.</p>;
+  }
+
+  return (
+    <ul>
+      {result.entries.map((entry) => (
+        <li key={entry.id}>
+          <a href={`/services/${entry.data.slug}`}>{String(entry.data.title ?? "")}</a>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### 4. Client engagement (likes & comments)
 
 ```tsx
 "use client";
@@ -97,6 +125,80 @@ function Engagement({ postId }: { postId: string }) {
 }
 ```
 
+### 5. Lead capture (custom form via Server Action)
+
+Use a **LEAD_CAPTURE** content type in CMS (with field mapping configured). Submit from your own form UI—no hosted-form embed.
+
+```ts
+// app/actions/submit-lead.ts
+"use server";
+
+import { cms } from "@/lib/cms";
+
+export async function submitContactLead(data: Record<string, unknown>) {
+  return cms.leads.submit("contact-enquiries", data);
+}
+```
+
+```tsx
+"use client";
+
+import { submitContactLead } from "@/app/actions/submit-lead";
+
+export function ContactForm() {
+  return (
+    <form
+      action={async (formData) => {
+        await submitContactLead({
+          firstName: String(formData.get("firstName") ?? ""),
+          email: String(formData.get("email") ?? ""),
+          message: String(formData.get("message") ?? ""),
+        });
+      }}
+    >
+      {/* your fields */}
+    </form>
+  );
+}
+```
+
+Optional honeypot: include `_honeypot` in `data`; submissions with a non-empty value are rejected.
+
+### 6. Client content list (hooks)
+
+```tsx
+"use client";
+
+import { CmsProvider, useContentEntries } from "@utilsy/cms-nextjs/react";
+import { cms } from "@/lib/cms";
+
+export function ServicesList() {
+  return (
+    <CmsProvider client={cms}>
+      <ServicesListInner />
+    </CmsProvider>
+  );
+}
+
+function ServicesListInner() {
+  const { entries, loading, error } = useContentEntries("services", {
+    page: 1,
+    limit: 20,
+  });
+
+  if (loading) return <p>Loading…</p>;
+  if (error) return <p>Error: {error.message}</p>;
+
+  return (
+    <ul>
+      {entries.map((e) => (
+        <li key={e.id}>{String(e.data.title ?? "")}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
 ## Environment variables
 
 | Variable | Description |
@@ -114,10 +216,19 @@ The CMS resolves the site from:
 
 For local dev or gateway-only deployments, always set `siteId` in the client config.
 
+## Content types and filters
+
+- Endpoint: `GET /public/api/{contentTypeApiId}` (published entries only).
+- Content types must have `apiAccess: PUBLIC`.
+- `filters` are exact matches on `data.<field>` (JSON query param). Example: `{ category: "news" }`.
+- Use `contentTypeApiId` (kebab-case slug from CMS), not the Mongo content type id.
+
 ## API reference
 
 ### Client (`createCmsClient`)
 
+#### Blog
+
 | Method | Description |
 |--------|-------------|
 | `blog.listPosts(query?, init?)` | Paginated list (summary fields only) |
@@ -132,6 +243,29 @@ For local dev or gateway-only deployments, always set `siteId` in the client con
 | `blog.listMappedCategories(...)` | Mapped categories |
 | `blog.listMappedComments(...)` | Mapped comments |
 
+#### Content
+
+| Method | Description |
+|--------|-------------|
+| `content.listEntries(contentTypeApiId, query?, init?)` | Paginated raw DTOs |
+| `content.getEntry(contentTypeApiId, idOrSlug, init?)` | Single raw DTO |
+| `content.listMappedEntries(...)` | List + `mapCmsEntryToContentEntry` |
+| `content.getMappedEntry(...)` | Single mapped `ContentEntry` |
+
+Query params for `listEntries` / `listMappedEntries`: `page`, `limit`, `search`, `sort`, `order`, `filters` (object).
+
+Helpers: `serializeContentFilters`, `mapCmsEntryToContentEntry`.
+
+#### Leads
+
+| Method | Description |
+|--------|-------------|
+| `leads.submit(contentTypeApiId, data, options?)` | Submit lead fields; creates content entry + CRM enquiry (throws on error) |
+
+- Endpoint: `POST /public/api/{contentTypeApiId}/submissions`
+- Content type must be `LEAD_CAPTURE` and `apiAccess: PUBLIC`
+- Field keys in `data` must match the content type schema; CRM mapping uses `leadCaptureConfig` in admin
+
 ### React (`@utilsy/cms-nextjs/react`)
 
 | Export | Description |
@@ -142,15 +276,18 @@ For local dev or gateway-only deployments, always set `siteId` in the client con
 | `useBlogEngagement` | Load engagement stats |
 | `useBlogLike` | Like toggle + counts |
 | `useBlogComments` | List + submit comments |
+| `useContentEntries` | List mapped entries by content type |
+| `useContentEntry` | Single mapped entry by id or slug |
+| `useSubmitLead` | Submit lead from client (prefer Server Action for forms) |
 
 ## CORS
 
-Public blog reads from the browser require either:
+Public CMS 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.
+Mutations (comments, likes, lead submit) should run server-side (Server Action / Route Handler) or via a same-origin proxy with CORS configured on the gateway.
 
 ## License
 

package/dist/{client-C3E94syg.d.cts → client-Ba-p3TtH.d.cts}

@@ -11,6 +11,13 @@ type FetchRequestInit = RequestInit & {
     cache?: RequestCache;
 };
 
+type RequestContext = {
+    baseUrl: string;
+    siteId?: string;
+    fetchFn: typeof fetch;
+    defaultHeaders: Record<string, string>;
+};
+
 /** Wire DTO from CMS public blog API */
 type CmsBlogPostDto = {
     id: string;
@@ -131,12 +138,8 @@ type ListBlogPostsQuery = {
     tag?: string;
 };
 
-type BlogRequestContext = {
-    baseUrl: string;
+type BlogRequestContext = RequestContext & {
     blogBasePath: string;
-    siteId?: string;
-    fetchFn: typeof fetch;
-    defaultHeaders: Record<string, string>;
 };
 declare function createBlogApi(ctx: BlogRequestContext): {
     listPosts(query?: ListBlogPostsQuery, init?: FetchRequestInit): Promise<CmsBlogPostsPage | null>;
@@ -162,14 +165,99 @@ declare function createBlogApi(ctx: BlogRequestContext): {
 };
 type BlogApi = ReturnType<typeof createBlogApi>;
 
+type ContentFilters = Record<string, unknown>;
+declare function serializeContentFilters(filters: ContentFilters): string;
+
+type ListContentEntriesQuery = {
+    page?: number;
+    limit?: number;
+    search?: string;
+    sort?: string;
+    order?: "asc" | "desc";
+    filters?: ContentFilters;
+};
+type CmsContentTypeDto = {
+    _id?: string;
+    id?: string;
+    name?: string;
+    apiId?: string;
+    fields?: unknown[];
+    status?: string;
+};
+type CmsContentEntryDto = {
+    _id?: string;
+    id?: string;
+    contentTypeId?: string;
+    contentType?: CmsContentTypeDto;
+    siteId?: string;
+    status?: string;
+    data?: Record<string, unknown>;
+    createdAt?: string;
+    updatedAt?: string;
+};
+type CmsContentEntriesPage = {
+    message?: string;
+    docs: CmsContentEntryDto[];
+    totalDocs: number;
+};
+type ContentTypeMeta = {
+    id: string;
+    name: string;
+    apiId: string;
+    fields?: unknown[];
+    status?: string;
+};
+type ContentEntry = {
+    id: string;
+    contentTypeId: string;
+    contentType?: ContentTypeMeta;
+    status: string;
+    data: Record<string, unknown>;
+    createdAt?: string;
+    updatedAt?: string;
+};
+type MappedContentEntriesPage = {
+    entries: ContentEntry[];
+    totalDocs: number;
+};
+
+type ContentRequestContext = RequestContext & {
+    contentBasePath: string;
+};
+declare function createContentApi(ctx: ContentRequestContext): {
+    listEntries(contentTypeApiId: string, query?: ListContentEntriesQuery, init?: FetchRequestInit): Promise<CmsContentEntriesPage | null>;
+    getEntry(contentTypeApiId: string, idOrSlug: string, init?: FetchRequestInit): Promise<CmsContentEntryDto | null>;
+    listMappedEntries(contentTypeApiId: string, query?: ListContentEntriesQuery, init?: FetchRequestInit): Promise<MappedContentEntriesPage | null>;
+    getMappedEntry(contentTypeApiId: string, idOrSlug: string, init?: FetchRequestInit): Promise<ContentEntry | null>;
+};
+type ContentApi = ReturnType<typeof createContentApi>;
+
+type LeadSubmissionData = Record<string, unknown>;
+type SubmitLeadOptions = {
+    /** Entry status (defaults to PUBLISHED on the server) */
+    status?: "DRAFT" | "PUBLISHED" | "ARCHIVED";
+};
+type SubmitLeadResult = {
+    entryId: string;
+    enquiryId?: string;
+};
+
+type LeadsRequestContext = RequestContext & {
+    contentBasePath: string;
+};
+declare function createLeadsApi(ctx: LeadsRequestContext): {
+    submit(contentTypeApiId: string, data: LeadSubmissionData, options?: SubmitLeadOptions, init?: FetchRequestInit): Promise<SubmitLeadResult>;
+};
+type LeadsApi = ReturnType<typeof createLeadsApi>;
+
 type CmsClientConfig = {
     /** Base URL, e.g. https://cms-gateway.example.com */
     baseUrl: string;
-    /** CMS site Mongo id — appended as ?siteId= on every blog request */
+    /** CMS site Mongo id — appended as ?siteId= on every public request */
     siteId?: string;
     /**
-     * Path prefix before /public/blog.
-     * Default '' for gateway-cms direct (/public/blog/...).
+     * Path prefix before /public/blog and /public/api.
+     * Default '' for gateway-cms direct (/public/blog/..., /public/api/...).
      * Use '/api/backend/cms' when routing through the main API gateway.
      */
     pathPrefix?: string;
@@ -178,7 +266,9 @@ type CmsClientConfig = {
 };
 type CmsClient = {
     blog: BlogApi;
+    content: ContentApi;
+    leads: LeadsApi;
 };
 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 };
+export { createCmsClient as A, type BlogApi as B, type CmsApiResponse as C, serializeContentFilters as D, type FetchRequestInit as F, type LeadSubmissionData as L, type MappedContentEntriesPage as M, type SubmitLeadOptions as S, 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 CmsContentEntriesPage as n, type CmsContentEntryDto as o, type CmsContentTypeDto as p, type ContentApi as q, type ContentEntry as r, type ContentFilters as s, type ContentTypeMeta as t, type CreateBlogCommentInput as u, type CreateBlogCommentResult as v, type LeadsApi as w, type ListBlogPostsQuery as x, type ListContentEntriesQuery as y, type SubmitLeadResult as z };

package/dist/{client-C3E94syg.d.ts → client-Ba-p3TtH.d.ts}

@@ -11,6 +11,13 @@ type FetchRequestInit = RequestInit & {
     cache?: RequestCache;
 };
 
+type RequestContext = {
+    baseUrl: string;
+    siteId?: string;
+    fetchFn: typeof fetch;
+    defaultHeaders: Record<string, string>;
+};
+
 /** Wire DTO from CMS public blog API */
 type CmsBlogPostDto = {
     id: string;
@@ -131,12 +138,8 @@ type ListBlogPostsQuery = {
     tag?: string;
 };
 
-type BlogRequestContext = {
-    baseUrl: string;
+type BlogRequestContext = RequestContext & {
     blogBasePath: string;
-    siteId?: string;
-    fetchFn: typeof fetch;
-    defaultHeaders: Record<string, string>;
 };
 declare function createBlogApi(ctx: BlogRequestContext): {
     listPosts(query?: ListBlogPostsQuery, init?: FetchRequestInit): Promise<CmsBlogPostsPage | null>;
@@ -162,14 +165,99 @@ declare function createBlogApi(ctx: BlogRequestContext): {
 };
 type BlogApi = ReturnType<typeof createBlogApi>;
 
+type ContentFilters = Record<string, unknown>;
+declare function serializeContentFilters(filters: ContentFilters): string;
+
+type ListContentEntriesQuery = {
+    page?: number;
+    limit?: number;
+    search?: string;
+    sort?: string;
+    order?: "asc" | "desc";
+    filters?: ContentFilters;
+};
+type CmsContentTypeDto = {
+    _id?: string;
+    id?: string;
+    name?: string;
+    apiId?: string;
+    fields?: unknown[];
+    status?: string;
+};
+type CmsContentEntryDto = {
+    _id?: string;
+    id?: string;
+    contentTypeId?: string;
+    contentType?: CmsContentTypeDto;
+    siteId?: string;
+    status?: string;
+    data?: Record<string, unknown>;
+    createdAt?: string;
+    updatedAt?: string;
+};
+type CmsContentEntriesPage = {
+    message?: string;
+    docs: CmsContentEntryDto[];
+    totalDocs: number;
+};
+type ContentTypeMeta = {
+    id: string;
+    name: string;
+    apiId: string;
+    fields?: unknown[];
+    status?: string;
+};
+type ContentEntry = {
+    id: string;
+    contentTypeId: string;
+    contentType?: ContentTypeMeta;
+    status: string;
+    data: Record<string, unknown>;
+    createdAt?: string;
+    updatedAt?: string;
+};
+type MappedContentEntriesPage = {
+    entries: ContentEntry[];
+    totalDocs: number;
+};
+
+type ContentRequestContext = RequestContext & {
+    contentBasePath: string;
+};
+declare function createContentApi(ctx: ContentRequestContext): {
+    listEntries(contentTypeApiId: string, query?: ListContentEntriesQuery, init?: FetchRequestInit): Promise<CmsContentEntriesPage | null>;
+    getEntry(contentTypeApiId: string, idOrSlug: string, init?: FetchRequestInit): Promise<CmsContentEntryDto | null>;
+    listMappedEntries(contentTypeApiId: string, query?: ListContentEntriesQuery, init?: FetchRequestInit): Promise<MappedContentEntriesPage | null>;
+    getMappedEntry(contentTypeApiId: string, idOrSlug: string, init?: FetchRequestInit): Promise<ContentEntry | null>;
+};
+type ContentApi = ReturnType<typeof createContentApi>;
+
+type LeadSubmissionData = Record<string, unknown>;
+type SubmitLeadOptions = {
+    /** Entry status (defaults to PUBLISHED on the server) */
+    status?: "DRAFT" | "PUBLISHED" | "ARCHIVED";
+};
+type SubmitLeadResult = {
+    entryId: string;
+    enquiryId?: string;
+};
+
+type LeadsRequestContext = RequestContext & {
+    contentBasePath: string;
+};
+declare function createLeadsApi(ctx: LeadsRequestContext): {
+    submit(contentTypeApiId: string, data: LeadSubmissionData, options?: SubmitLeadOptions, init?: FetchRequestInit): Promise<SubmitLeadResult>;
+};
+type LeadsApi = ReturnType<typeof createLeadsApi>;
+
 type CmsClientConfig = {
     /** Base URL, e.g. https://cms-gateway.example.com */
     baseUrl: string;
-    /** CMS site Mongo id — appended as ?siteId= on every blog request */
+    /** CMS site Mongo id — appended as ?siteId= on every public request */
     siteId?: string;
     /**
-     * Path prefix before /public/blog.
-     * Default '' for gateway-cms direct (/public/blog/...).
+     * Path prefix before /public/blog and /public/api.
+     * Default '' for gateway-cms direct (/public/blog/..., /public/api/...).
      * Use '/api/backend/cms' when routing through the main API gateway.
      */
     pathPrefix?: string;
@@ -178,7 +266,9 @@ type CmsClientConfig = {
 };
 type CmsClient = {
     blog: BlogApi;
+    content: ContentApi;
+    leads: LeadsApi;
 };
 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 };
+export { createCmsClient as A, type BlogApi as B, type CmsApiResponse as C, serializeContentFilters as D, type FetchRequestInit as F, type LeadSubmissionData as L, type MappedContentEntriesPage as M, type SubmitLeadOptions as S, 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 CmsContentEntriesPage as n, type CmsContentEntryDto as o, type CmsContentTypeDto as p, type ContentApi as q, type ContentEntry as r, type ContentFilters as s, type ContentTypeMeta as t, type CreateBlogCommentInput as u, type CreateBlogCommentResult as v, type LeadsApi as w, type ListBlogPostsQuery as x, type ListContentEntriesQuery as y, type SubmitLeadResult as z };