@crayonscodetech/cms-sdk 1.0.8 → 1.0.10

package/README.md

@@ -777,15 +777,15 @@ Different page types follow different rendering strategies. Understanding these
 | `[[...slug]]` CMS pages | `page` (+ inline `page.sections`) | `fetchPageByUrl(siteId, urlPath)`                                                               |
 | `/about`                | `page` + `about-us`               | `fetchPageByUrl(siteId, "/about")` + `fetchAboutUs(siteId)`                                     |
 | `/services`             | `page` + `services`               | `fetchPageByUrl(siteId, "/services")` + `fetchServices(siteId)`                                 |
-| `/services/[slug]`      | `services`                        | `fetchServices(siteId)` (slug lookup) or `fetchServiceById(siteId, id)`                         |
+| `/services/[slug]`      | `services`                        | `fetchServiceBySlug(siteId, slug)`                                                              |
 | `/blog` or `/news`      | `page` + `blog`                   | `fetchPageByUrl(siteId, "/blog")` (or your CMS-defined base url) + `fetchBlogs(siteId, params)` |
 | `/blog/[slug]`          | `blog`                            | `fetchBlogBySlug(siteId, slug)`                                                                 |
 | `/events`               | `page` + `events`                 | `fetchPageByUrl(siteId, "/events")` + `fetchEvents(siteId, params)`                             |
-| `/events/[slug]`        | `events`                          | `fetchEvents(siteId, { limit })` (slug lookup) or `fetchEventById(siteId, id)`                  |
+| `/events/[slug]`        | `events`                          | `fetchEventBySlug(siteId, slug)`                                                                |
 | `/gallery`              | `page` + `albums`                 | `fetchPageByUrl(siteId, "/gallery")` + `fetchAlbums(siteId, params)`                            |
 | `/gallery/[slug]`       | `albums` + `album-items`          | `fetchAlbums(siteId, { limit })` + `fetchAlbumItems(siteId, { album: slug })`                   |
 | `/team/[slug]`          | `team-members`                    | `fetchTeamMembers(siteId)` (slug lookup) or custom `fetch`                                      |
-| `/contact`              | `contact` (form submissions)      | `submitContactForm(siteId, payload)`                                                            |
+| `/contact`              | `contact` (form submissions)      | `fetchContactConfig(siteId)` + `submitContactForm(siteId, payload, attachments?)`               |
 
 ### Home Page — Section Rendering with Targeting
 
@@ -1264,22 +1264,42 @@ export default async function AlbumDetailPage({
 
 The contact page does **not** use `RenderSections`. It is a dedicated form page that submits directly to the CMS via `submitContactForm`. Do not render CMS sections here — just build your form UI and wire it to the SDK.
 
+**If the site has Turnstile enabled, the form will not work without it.** Fetch the config
+on the server, render the widget with the site key, and forward the token through your own
+API route along with the rest of the payload.
+
 ```tsx
-// components/pages/ContactPage.tsx
+// components/pages/ContactPage.tsx  (server component)
 import { ContactForm } from "@/components/contact-form";
-import type { Page, SiteConfig } from "@crayons/cms-sdk";
+import { cms, SITE_ID } from "@/lib/cms";
+import type { Page, SiteConfig } from "@crayonscodetech/cms-sdk";
 
-export default function ContactPage({
+export default async function ContactPage({
   page,
   site,
 }: {
   page: Page;
   site?: SiteConfig | null;
 }) {
+  // Public site key only — safe to hand to the client.
+  const contactConfig = await cms.fetchContactConfig(SITE_ID);
+  const turnstile = contactConfig?.turnstile;
+
+  // enabled with no site key = misconfigured; the widget cannot render and every
+  // submission would be rejected, so do not show a form that cannot succeed.
+  if (turnstile?.enabled && !turnstile.site_key) {
+    return (
+      <main>
+        <h1>Contact Us</h1>
+        <p>The contact form is temporarily unavailable.</p>
+      </main>
+    );
+  }
+
   return (
     <main>
       <h1>Contact Us</h1>
-      <ContactForm />
+      <ContactForm turnstileSiteKey={turnstile?.enabled ? turnstile.site_key : null} />
     </main>
   );
 }
@@ -1289,39 +1309,63 @@ export default function ContactPage({
 // components/contact-form.tsx  (client component — handles submission)
 "use client";
 
-import { useState } from "react";
-import type { ContactPayload } from "@crayons/cms-sdk";
+import { useRef, useState } from "react";
+import { Turnstile, type TurnstileInstance } from "@marsidev/react-turnstile";
 
-export function ContactForm() {
+export function ContactForm({
+  turnstileSiteKey,
+}: {
+  turnstileSiteKey: string | null;
+}) {
   const [status, setStatus] = useState<
     "idle" | "sending" | "success" | "error"
   >("idle");
+  const [error, setError] = useState("");
+  const [token, setToken] = useState("");
+  const widget = useRef<TurnstileInstance>(null);
 
   async function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
     e.preventDefault();
+    if (turnstileSiteKey && !token) {
+      setError("Please complete the verification.");
+      return;
+    }
     setStatus("sending");
+    setError("");
 
     const form = e.currentTarget;
-    const payload: ContactPayload = {
+    const payload = {
       name: (form.elements.namedItem("name") as HTMLInputElement).value,
       email: (form.elements.namedItem("email") as HTMLInputElement).value,
       subject: (form.elements.namedItem("subject") as HTMLInputElement).value,
-      message: (form.elements.namedItem("message") as HTMLTextAreaElement)
-        .value,
+      message: (form.elements.namedItem("message") as HTMLTextAreaElement).value,
       type: "contact",
+      turnstile_token: token,
     };
 
     try {
-      // submitContactForm is called from a server action or API route to keep SITE_ID server-side
+      // Proxied through your own route so SITE_ID stays server-side.
       const res = await fetch("/api/contact", {
         method: "POST",
         body: JSON.stringify(payload),
         headers: { "Content-Type": "application/json" },
       });
 
-      setStatus(res.ok ? "success" : "error");
+      if (res.ok) {
+        setStatus("success");
+      } else {
+        const body = await res.json().catch(() => ({}));
+        setError(body.error ?? "Something went wrong. Please try again.");
+        setStatus("error");
+      }
     } catch {
+      setError("Something went wrong. Please try again.");
       setStatus("error");
+    } finally {
+      // Turnstile tokens are single-use — always reset, success or failure, or
+      // the next submit replays a spent token and is rejected.
+      widget.current?.reset();
+      setToken("");
     }
   }
 
@@ -1331,11 +1375,14 @@ export function ContactForm() {
       <input name="email" type="email" placeholder="Email" />
       <input name="subject" placeholder="Subject" />
       <textarea name="message" placeholder="Message" required />
+      {turnstileSiteKey && (
+        <Turnstile ref={widget} siteKey={turnstileSiteKey} onSuccess={setToken} />
+      )}
       <button type="submit" disabled={status === "sending"}>
         {status === "sending" ? "Sending…" : "Send"}
       </button>
       {status === "success" && <p>Message sent!</p>}
-      {status === "error" && <p>Something went wrong. Please try again.</p>}
+      {status === "error" && <p>{error}</p>}
     </form>
   );
 }
@@ -1344,12 +1391,30 @@ export function ContactForm() {
 ```ts
 // app/api/contact/route.ts  (server — keeps SITE_ID out of the client bundle)
 import { cms, SITE_ID } from "@/lib/cms";
-import type { ContactPayload } from "@crayons/cms-sdk";
+import { CmsError, type ContactPayload } from "@crayonscodetech/cms-sdk";
+
+export const dynamic = "force-dynamic";
 
 export async function POST(req: Request) {
   const payload: ContactPayload = await req.json();
-  const result = await cms.submitContactForm(SITE_ID, payload);
-  return Response.json(result);
+
+  try {
+    const contact = await cms.submitContactForm(SITE_ID, payload);
+    return Response.json({ ok: true, contact });
+  } catch (e) {
+    // submitContactForm throws rather than returning null, so the visitor can be
+    // told what actually went wrong.
+    if (e instanceof CmsError) {
+      const message =
+        e.status === 403
+          ? "Verification failed. Please try again."
+          : e.status === 429
+            ? "Too many attempts. Please wait a moment."
+            : e.message;
+      return Response.json({ ok: false, error: message }, { status: e.status ?? 502 });
+    }
+    return Response.json({ ok: false, error: "Submission failed" }, { status: 502 });
+  }
 }
 ```
 
@@ -2598,13 +2663,13 @@ export interface FetchOptions extends RequestInit {
 
 ### Other Entities
 
-- `fetchServices(siteId, options?)`: Returns all services.
-- `fetchServiceById(siteId, id, options?)`: Returns a single service by ID.
+- `fetchServices(siteId, params?, options?)`: Returns paginated services. Params: `{ page, limit }`. Only published services are returned — the backend filters on `is_published`, and each item carries `is_published` plus a nullable `published_at`.
+- `fetchServiceBySlug(siteId, slug, options?)`: Returns a single published service by slug, including its `extra.sections`. Returns `null` if not found or unpublished.
 - `fetchTeamMembers(siteId, params?, options?)`: Returns paginated team members. Params: `{ page, limit }`. Default limit: 20.
 - `fetchTeamMembersByCategory(siteId, params, options?)`: Returns paginated team members filtered by category. Params: `{ categoryId, page?, limit? }`. Default limit: 20. **Note:** `categoryId` is now inside the params object.
 - `fetchTestimonials(siteId, params?, options?)`: Returns paginated testimonials. Params: `{ type?, page?, limit? }`. Default limit: 20.
 - `fetchEvents(siteId, params?, options?)`: Returns paginated events. Params: `{ page, limit, search }`.
-- `fetchEventById(siteId, id, options?)`: Returns a single event by ID.
+- `fetchEventBySlug(siteId, slug, options?)`: Returns a single published event by slug. Returns `null` if not found or unpublished.
 - `fetchAlbums(siteId, params?, options?)`: Returns paginated albums. Params: `{ page, limit, search }`.
 - `fetchAlbumItems(siteId, params, options?)`: Returns paginated items for an album. Params: `{ album?, album_id?, page?, limit? }`. Default limit: 20.
 
@@ -2623,15 +2688,44 @@ export interface FetchOptions extends RequestInit {
 
 ### Forms & Submissions
 
-- `submitContactForm(siteId, payload, options?)`: Submits a contact form.
+- `fetchContactConfig(siteId, options?)`: Public Turnstile settings for the contact form.
+  Call it before rendering the form.
+  - **Returns**: `{ turnstile: { enabled: boolean; site_key: string | null } }`
+  - When `enabled` is true you MUST render the Turnstile widget with `site_key` and pass the
+    resulting token as `turnstile_token`, or every submission is rejected with 403.
+  - `enabled: true` with a null `site_key` means the site is misconfigured — hide the form
+    rather than submitting into a guaranteed rejection.
+
+- `submitContactForm(siteId, payload, attachments?, options?)`: Submits a contact form.
   - **Payload Structure**:
     ```typescript
     {
-      name: string;      // Required
-      message: string;   // Required
-      email?: string;    // Optional
-      subject?: string;  // Optional
-      type?: string;     // Default: "contact"
+      name: string;              // Required
+      message: string;           // Required
+      email?: string;            // Optional
+      subject?: string;          // Optional
+      type?: string;             // Default: "contact"
+      turnstile_token?: string;  // Required when Turnstile is enabled
+    }
+    ```
+  - **Attachments** (optional): `File[]`. Sending them switches the request to multipart.
+    Caps, enforced server-side and pre-checked client-side: max 3 files, 3 MiB total, and a
+    MIME allowlist (PDF, PNG, JPEG, WebP, GIF, plain text, DOC, DOCX).
+  - **Throws `CmsError` instead of returning `null`.** Unlike the read methods, a form needs
+    to distinguish rejection kinds, so failures throw with `error.status`:
+    `403` captcha failed (reset the widget — tokens are single-use), `429` rate limited,
+    `400` validation, `503` Turnstile misconfigured server-side.
+  - Never retried: a resend would duplicate the submission.
+
+    ```typescript
+    import { CmsError } from "@crayonscodetech/cms-sdk";
+
+    try {
+      const contact = await cms.submitContactForm(SITE_ID, payload, files);
+    } catch (e) {
+      if (e instanceof CmsError && e.status === 403) {
+        // captcha rejected — reset the widget and let the visitor retry
+      }
     }
     ```
 
@@ -2639,8 +2733,9 @@ export interface FetchOptions extends RequestInit {
 
 > All store methods use the `/api/public/store/` API prefix, not `/api/public/cms/`.
 
-- `fetchProductCategories(siteId, options?)`: Returns all product categories.
-- `fetchProductBrands(siteId, options?)`: Returns all product brands.
+- `fetchStoreSettings(siteId, options?)`: Returns `{ currency, price_visibility, is_store_enabled }`. Fetch this first — when `price_visibility` is false the API strips `price`, `sale_price` and `cost_price` from every variant, so the storefront must render an inquiry flow rather than prices.
+- `fetchProductCategories(siteId, params?, options?)`: Returns paginated product categories. Params: `{ page, limit, search, ordering, parent_id }`.
+- `fetchProductBrands(siteId, params?, options?)`: Returns paginated product brands. Params: `{ page, limit, search, ordering }`.
 - `fetchProducts(siteId, params?, options?)`: Returns paginated products. Params: `{ page, limit, search, category_id, tag_id, brand_id, is_featured }`.
   - `category_id` is hierarchy-aware on the backend and includes child/grandchild categories.
 - `fetchProductDetail(siteId, slug, options?)`: Returns a single product by slug, **including `variants`**.
@@ -2649,18 +2744,47 @@ export interface FetchOptions extends RequestInit {
   - Params: `{ page, limit, category_id }`
   - Works for both manual and smart collections
 - `fetchCollectionDetailById(siteId, id, params?, options?)`: Same as `fetchCollectionDetail`, but keyed by collection ID for CMS-driven product sections.
+- `fetchProductsByTag(siteId, tag, params?, options?)`: Returns paginated products carrying a tag. Params: `{ page, limit }`.
 - `placeOrder(siteId, payload, options?)`: Places an order. Call from a server API route — never client-side.
+  - `metadata` on the payload must be a **flat `Record<string, string>`** — the API validates it on a strict schema, so nested objects, numbers and arrays are rejected with a 400.
 
 ---
 
 ## Sitemap
 
-The SDK exposes four lightweight sitemap endpoints that return only the fields needed to build an XML sitemap (slug/URL, image, title/name). Each endpoint filters to published content only and defaults to up to **5,000 items per request** — enough for most sites without needing to paginate.
+The SDK exposes twelve lightweight sitemap endpoints that return only the fields needed to build an XML sitemap (slug/URL, image, title/name, plus `updatedAt` for `lastModified`). Each endpoint filters to published content only and defaults to up to **2,000 items per request** — enough for most sites without needing to paginate.
 
 > **These endpoints must only be called once per day.** Place them inside Next.js's `app/sitemap.ts` file and export `revalidate = 86400`. Never call them at request time.
 
 ### Methods
 
+Use `fetchSitemap(siteId, resource, params?, options?)` for any resource. The
+return type narrows automatically from the resource key:
+
+```typescript
+const pages = await cms.fetchSitemap(siteId, "pages");
+pages.data[0].url; // typed — pages are addressed by url
+const blogs = await cms.fetchSitemap(siteId, "blogs");
+blogs.data[0].slug; // typed — everything else is addressed by slug
+```
+
+| `resource`            | Namespace | Item type                     |
+| --------------------- | --------- | ----------------------------- |
+| `"blogs"`             | cms       | `SitemapBlogItem`             |
+| `"pages"`             | cms       | `SitemapPageItem`             |
+| `"services"`          | cms       | `SitemapServiceItem`          |
+| `"events"`            | cms       | `SitemapEventItem`            |
+| `"albums"`            | cms       | `SitemapAlbumItem`            |
+| `"team-members"`      | cms       | `SitemapTeamMemberItem`       |
+| `"team-categories"`   | cms       | `SitemapTeamCategoryItem`     |
+| `"brand-groups"`      | cms       | `SitemapBrandGroupItem`       |
+| `"products"`          | store     | `SitemapProductItem`          |
+| `"collections"`       | store     | `SitemapCollectionItem`       |
+| `"product-categories"`| store     | `SitemapProductCategoryItem`  |
+| `"product-brands"`    | store     | `SitemapProductBrandItem`     |
+
+These four remain available as named shortcuts:
+
 | Method                                                   | Returns                                        |
 | -------------------------------------------------------- | ---------------------------------------------- |
 | `fetchSitemapBlogs(siteId, params?, options?)`           | `PaginatedResponse<SitemapBlogItem>`           |
@@ -2668,32 +2792,42 @@ The SDK exposes four lightweight sitemap endpoints that return only the fields n
 | `fetchSitemapProducts(siteId, params?, options?)`        | `PaginatedResponse<SitemapProductItem>`        |
 | `fetchSitemapCollections(siteId, params?, options?)`     | `PaginatedResponse<SitemapCollectionItem>`     |
 
-All four accept optional `{ page?: number; limit?: number }` params.
+All accept optional `{ page?: number; limit?: number }` params.
+
+**Field naming:** most resources return `title`; `products` and `collections`
+return `name` instead (kept for backwards compatibility). `pages` is addressed
+by `url` rather than `slug`, and `pages`, `team-categories` and `brand-groups`
+have no `image` field.
 
 ### Types
 
 ```typescript
+// Every item type includes `updatedAt` — use it for `lastModified`.
 interface SitemapBlogItem {
   slug: string;
   image: string | null;
   title: string;
+  updatedAt: string;
 }
 
 interface SitemapPageItem {
   url: string;   // e.g. "/about", "/services"
   title: string;
+  updatedAt: string;
 }
 
 interface SitemapProductItem {
   slug: string;
   image: string | null;
   name: string;
+  updatedAt: string;
 }
 
 interface SitemapCollectionItem {
   slug: string;
   image: string | null;
   name: string;
+  updatedAt: string;
 }
 ```
 
@@ -2749,7 +2883,7 @@ export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
 }
 ```
 
-> **Note:** If your site has more than 5,000 entries for any content type, use the `limit` param together with Next.js's [`generateSitemaps`](https://nextjs.org/docs/app/api-reference/file-conventions/metadata/sitemap#generating-multiple-sitemaps) to split the output across multiple sitemap files.
+> **Note:** If your site has more than 2,000 entries for any content type, use the `limit` param together with Next.js's [`generateSitemaps`](https://nextjs.org/docs/app/api-reference/file-conventions/metadata/sitemap#generating-multiple-sitemaps) to split the output across multiple sitemap files.
 
 ## Type System