@sleekcms/client 0.1.5 → 1.0.0

package/README.md

@@ -22,7 +22,7 @@ const client = createClient({
 const content = await client.getContent();
 
 // Get specific pages
-const blogPosts = await client.findPages('/blog');
+const blogPosts = await client.getPages('/blog');
 ```
 
 ## Client Types
@@ -96,30 +96,60 @@ const homePage = await client.getContent('pages[?_path == `/`] | [0]');
 const siteTitle = await client.getContent<string>('config.title');
 ```
 
-### `findPages<T>(path, query?)`
+### `getPages(path, query?)`
 
-Find pages that start with the specified path.
+Get pages that start with the specified path.
 
 **Parameters:**
 - `path` (required): Path prefix to filter pages (e.g., `/blog`, `/products`)
 - `query` (optional): JMESPath query to further filter results
 
-**Returns:** `Promise<T>` (async) or `T` (sync)
+**Returns:** `Promise<SleekSiteContent["pages"]>` (async) or `SleekSiteContent["pages"]` (sync)
 
 **Examples:**
 
 ```typescript
 // Get all blog posts
-const blogPosts = await client.findPages('/blog');
+const blogPosts = await client.getPages('/blog');
 
 // Get blog posts with custom query
-const publishedPosts = await client.findPages(
+const publishedPosts = await client.getPages(
   '/blog',
   '[?published == `true`]'
 );
 
 // Get post titles only
-const titles = await client.findPages('/blog', '[].title');
+const titles = await client.getPages('/blog', '[].title');
+```
+
+### `getPage(path)`
+
+Get a single page by its exact path.
+
+**Parameters:**
+- `path` (required): Exact page path (e.g., `/blog/my-post`, `/about`)
+
+**Returns:** `Promise<Page>` (async) or `Page | null` (sync)
+
+**Note:** Async client throws an error if page is not found. Sync client returns `null`.
+
+**Examples:**
+
+```typescript
+// Async client - throws if not found
+try {
+  const aboutPage = await client.getPage('/about');
+  console.log(aboutPage.title);
+} catch (error) {
+  console.error('Page not found');
+}
+
+// Sync client - returns null if not found
+const syncClient = await createSyncClient({ siteToken: '...' });
+const aboutPage = syncClient.getPage('/about');
+if (aboutPage) {
+  console.log(aboutPage.title);
+}
 ```
 
 ### `getImages()`
@@ -167,6 +197,27 @@ const categories = await client.getList('categories');
 // [{ label: "Technology", value: "tech" }, ...]
 ```
 
+### `getSlugs(path)`
+
+Get an array of slugs from pages that start with the specified path. Only includes pages that have a `_slug` property.
+
+**Parameters:**
+- `path` (required): Path prefix to filter pages (e.g., `/blog`, `/products`)
+
+**Returns:** `Promise<string[]>` (async) or `string[]` (sync)
+
+**Example:**
+
+```typescript
+// Get all blog post slugs
+const slugs = await client.getSlugs('/blog');
+// ["my-first-post", "second-post", "latest-update"]
+
+// Useful for generating static paths in Next.js
+const productSlugs = await client.getSlugs('/products');
+// ["laptop", "keyboard", "mouse"]
+```
+
 ## Content Structure
 
 The SleekCMS content has the following structure:
@@ -228,7 +279,7 @@ export default async function BlogPage() {
     env: 'published',
   });
 
-  const posts = await client.findPages('/blog');
+  const posts = await client.getPages('/blog');
 
   return (
     <div>
@@ -255,12 +306,96 @@ const client = await createSyncClient({
 });
 
 // Generate static pages
-const pages = client.findPages('/');
+const pages = client.getPages('/');
 const images = client.getImages();
 
 // All subsequent calls are synchronous and instant
 ```
 
+### Next.js Static Params (generateStaticParams)
+
+Use `getSlugs()` to generate static paths for dynamic routes in Next.js:
+
+```typescript
+// app/blog/[slug]/page.tsx
+import { createClient } from '@sleekcms/client';
+
+// Generate static paths at build time
+export async function generateStaticParams() {
+  const client = createClient({
+    siteToken: process.env.SLEEKCMS_TOKEN!,
+    env: 'published',
+  });
+
+  const slugs = await client.getSlugs('/blog');
+
+  return slugs.map((slug) => ({
+    slug: slug,
+  }));
+}
+
+// Render the page
+export default async function BlogPost({ params }: { params: { slug: string } }) {
+  const client = createClient({
+    siteToken: process.env.SLEEKCMS_TOKEN!,
+    env: 'published',
+  });
+
+  const post = await client.getPage(`/blog/${params.slug}`);
+
+  return (
+    <article>
+      <h1>{post.title}</h1>
+      <div>{post.content}</div>
+    </article>
+  );
+}
+```
+
+**Pages Router Example:**
+
+```typescript
+// pages/blog/[slug].tsx
+import { createClient } from '@sleekcms/client';
+import type { GetStaticPaths, GetStaticProps } from 'next';
+
+export const getStaticPaths: GetStaticPaths = async () => {
+  const client = createClient({
+    siteToken: process.env.SLEEKCMS_TOKEN!,
+    env: 'published',
+  });
+
+  const slugs = await client.getSlugs('/blog');
+
+  return {
+    paths: slugs.map((slug) => ({ params: { slug } })),
+    fallback: false,
+  };
+};
+
+export const getStaticProps: GetStaticProps = async ({ params }) => {
+  const client = createClient({
+    siteToken: process.env.SLEEKCMS_TOKEN!,
+    env: 'published',
+  });
+
+  const post = await client.getPage(`/blog/${params!.slug}`);
+
+  return {
+    props: { post },
+  };
+};
+
+export default function BlogPost({ post }: any) {
+  return (
+    <article>
+      <h1>{post.title}</h1>
+      <div>{post.content}</div>
+    </article>
+  );
+}
+```
+
 ### Browser Usage
 
 ```typescript
@@ -316,7 +451,10 @@ interface BlogPost {
   _path: string;
 }
 
-const posts = await client.findPages<BlogPost[]>('/blog');
+const posts = await client.getPages('/blog');
+
+// Get a single page with error handling
+const aboutPage = await client.getPage('/about');
 ```
 
 ## License

package/index.cjs

@@ -33,6 +33,8 @@ __export(index_exports, {
   createSyncClient: () => createSyncClient
 });
 module.exports = __toCommonJS(index_exports);
+
+// src/lib.ts
 var jmespath = __toESM(require("jmespath"), 1);
 function isDevToken(token) {
   return token.startsWith("dev-");
@@ -41,149 +43,164 @@ function getBaseUrl(token) {
   let [env, siteId, ...rest] = token.split("-");
   return `https://${env}.sleekcms.com/${siteId}`;
 }
-async function fetchSiteContent(options, searchQuery) {
-  const { siteToken, env = "latest", mock } = options;
-  if (!siteToken) {
-    throw new Error("[SleekCMS] siteToken is required");
-  }
-  const baseUrl = getBaseUrl(siteToken).replace(/\/$/, "");
-  const url = new URL(`${baseUrl}/${env}`);
-  if (searchQuery) {
-    url.searchParams.set("search", searchQuery);
-  }
-  if (mock && isDevToken(siteToken)) {
-    url.searchParams.set("mock", "true");
-  }
-  const res = await fetch(url.toString(), {
-    method: "GET",
-    headers: {
-      "Content-Type": "application/json",
-      Authorization: siteToken
-    }
-  });
-  if (!res.ok) {
-    let message = res.statusText;
-    try {
-      const data = await res.json();
-      if (data && data.message) message = data.message;
-    } catch {
-    }
-    throw new Error(`[SleekCMS] Request failed (${res.status}): ${message}`);
-  }
-  return res.json();
-}
 function applyJmes(data, query) {
   if (!query) return data;
   return jmespath.search(data, query);
 }
-function createClient(options) {
-  const dev = isDevToken(options.siteToken);
-  let cacheMode = !!options.cache || !!options.mock && dev;
+function createFetchSiteContent(options) {
+  const { siteToken, env = "latest", mock } = options;
+  const dev = isDevToken(siteToken);
+  let cacheMode = !!options.cache || !!mock && dev;
   let cachedContent = null;
-  async function ensureCacheLoaded() {
-    if (cachedContent) return cachedContent;
-    const data = await fetchSiteContent(options);
-    cachedContent = data;
-    return data;
-  }
-  async function getContent(query) {
-    if (cacheMode) {
-      const data2 = await ensureCacheLoaded();
-      return applyJmes(data2, query);
+  return async function fetchSiteContent(searchQuery) {
+    if (!siteToken) {
+      throw new Error("[SleekCMS] siteToken is required");
+    }
+    if (cachedContent) {
+      return applyJmes(cachedContent, searchQuery);
     }
-    if (!query) {
-      const data2 = await fetchSiteContent(options);
-      cachedContent = data2;
+    const baseUrl = getBaseUrl(siteToken).replace(/\/$/, "");
+    const url = new URL(`${baseUrl}/${env}`);
+    if (searchQuery && !cacheMode && !cachedContent) {
+      url.searchParams.set("search", searchQuery);
+    }
+    if (mock && dev) {
+      url.searchParams.set("mock", "true");
+    }
+    const res = await fetch(url.toString(), {
+      method: "GET",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: siteToken
+      }
+    });
+    if (!res.ok) {
+      let message = res.statusText;
+      try {
+        const data2 = await res.json();
+        if (data2 && data2.message) message = data2.message;
+      } catch {
+      }
+      throw new Error(`[SleekCMS] Request failed (${res.status}): ${message}`);
+    }
+    const data = await res.json();
+    if (!searchQuery) {
+      cachedContent = data;
       cacheMode = true;
-      return data2;
     }
-    const data = await fetchSiteContent(options, query);
     return data;
+  };
+}
+
+// src/index.ts
+function extractSlugs(pages, path) {
+  const slugs = [];
+  const pagesList = pages ?? [];
+  for (const page of pagesList) {
+    const pth = typeof page._path === "string" ? page._path : "";
+    if (pth.startsWith(path) && "_slug" in page && typeof page._slug === "string") {
+      slugs.push(page._slug);
+    }
+  }
+  return slugs;
+}
+function filterPagesByPath(pages, path) {
+  const pagesList = pages ?? [];
+  return pagesList.filter((p) => {
+    const pth = typeof p._path === "string" ? p._path : "";
+    return pth.startsWith(path);
+  });
+}
+function createClient(options) {
+  const fetchSiteContent = createFetchSiteContent(options);
+  async function getContent(query) {
+    return await fetchSiteContent(query);
   }
-  async function findPages(path, query) {
+  async function getPages(path, query) {
     if (!path) {
-      throw new Error("[SleekCMS] path is required for findPages");
+      throw new Error("[SleekCMS] path is required for getPages");
     }
-    if (cacheMode) {
-      const data = await ensureCacheLoaded();
-      const pages2 = data.pages ?? [];
-      const filtered2 = pages2.filter((p) => {
-        const pth = typeof p._path === "string" ? p._path : "";
-        return pth.startsWith(path);
-      });
-      return applyJmes(filtered2, query);
+    const data = await fetchSiteContent();
+    const filtered = filterPagesByPath(data.pages, path);
+    return applyJmes(filtered, query);
+  }
+  async function getPage(path) {
+    if (!path) {
+      throw new Error("[SleekCMS] path is required for getPage");
     }
-    const pages = await fetchSiteContent(
-      options,
-      "pages"
-    );
-    const filtered = (pages ?? []).filter((p) => {
+    const data = await fetchSiteContent();
+    const pages = data.pages ?? [];
+    const page = pages.find((p) => {
       const pth = typeof p._path === "string" ? p._path : "";
-      return pth.startsWith(path);
+      return pth === path;
     });
-    return applyJmes(filtered, query);
+    if (!page) {
+      throw new Error(`[SleekCMS] Page not found: ${path}`);
+    }
+    return page;
   }
-  async function getImages() {
-    if (cacheMode) {
-      const data = await ensureCacheLoaded();
-      return data.images ?? {};
+  async function getSlugs(path) {
+    if (!path) {
+      throw new Error("[SleekCMS] path is required for getSlugs");
     }
-    const images = await fetchSiteContent(
-      options,
-      "images"
-    );
-    return images ?? {};
+    const data = await fetchSiteContent();
+    return extractSlugs(data.pages, path);
+  }
+  async function getImages() {
+    const data = await fetchSiteContent();
+    return data.images ?? {};
   }
   async function getImage(name) {
     if (!name) return void 0;
-    if (cacheMode) {
-      const data = await ensureCacheLoaded();
-      return data.images ? data.images[name] : void 0;
-    }
-    const images = await fetchSiteContent(
-      options,
-      "images"
-    );
-    return images ? images[name] : void 0;
+    const data = await fetchSiteContent();
+    return data.images ? data.images[name] : void 0;
   }
   async function getList(name) {
     if (!name) return void 0;
-    if (cacheMode) {
-      const data = await ensureCacheLoaded();
-      const lists2 = data.lists ?? {};
-      const list2 = lists2[name];
-      return Array.isArray(list2) ? list2 : void 0;
-    }
-    const lists = await fetchSiteContent(
-      options,
-      "lists"
-    );
-    const list = lists ? lists[name] : void 0;
+    const data = await fetchSiteContent();
+    const lists = data.lists ?? {};
+    const list = lists[name];
     return Array.isArray(list) ? list : void 0;
   }
   return {
     getContent,
-    findPages,
+    getPages,
+    getPage,
+    getSlugs,
     getImages,
     getImage,
     getList
   };
 }
 async function createSyncClient(options) {
-  const data = await fetchSiteContent(options);
+  const fetchSiteContent = createFetchSiteContent(options);
+  const data = await fetchSiteContent();
   function getContent(query) {
     return applyJmes(data, query);
   }
-  function findPages(path, query) {
+  function getPages(path, query) {
     if (!path) {
-      throw new Error("[SleekCMS] path is required for findPages");
+      throw new Error("[SleekCMS] path is required for getPages");
+    }
+    const filtered = filterPagesByPath(data.pages, path);
+    return applyJmes(filtered, query);
+  }
+  function getPage(path) {
+    if (!path) {
+      throw new Error("[SleekCMS] path is required for getPage");
     }
     const pages = data.pages ?? [];
-    const filtered = pages.filter((p) => {
+    const page = pages.find((p) => {
       const pth = typeof p._path === "string" ? p._path : "";
-      return pth.startsWith(path);
+      return pth === path;
     });
-    return applyJmes(filtered, query);
+    return page ?? null;
+  }
+  function getSlugs(path) {
+    if (!path) {
+      throw new Error("[SleekCMS] path is required for getSlugs");
+    }
+    return extractSlugs(data.pages, path);
   }
   function getImages() {
     return data.images ?? {};
@@ -200,7 +217,9 @@ async function createSyncClient(options) {
   }
   return {
     getContent,
-    findPages,
+    getPages,
+    getPage,
+    getSlugs,
     getImages,
     getImage,
     getList

package/index.d.cts

@@ -32,8 +32,10 @@ interface ClientOptions {
  * Async SleekCMS client: methods return Promises.
  */
 interface SleekClient {
-    getContent<T = SleekSiteContent>(query?: string): Promise<T>;
-    findPages<T = unknown>(path: string, query?: string): Promise<T>;
+    getContent(query?: string): Promise<SleekSiteContent>;
+    getPages(path: string, query?: string): Promise<SleekSiteContent["pages"]>;
+    getPage(path: string): Promise<Page>;
+    getSlugs(path: string): Promise<string[]>;
     getImages(): Promise<SleekSiteContent["images"]>;
     getImage(name: string): Promise<unknown | undefined>;
     getList<T = unknown>(name: string): Promise<T[] | undefined>;
@@ -42,8 +44,10 @@ interface SleekClient {
  * Sync client: prefetches full content once; subsequent calls are in-memory only.
  */
 interface SleekSyncClient {
-    getContent<T = SleekSiteContent>(query?: string): T;
-    findPages<T = unknown>(path: string, query?: string): T;
+    getContent(query?: string): SleekSiteContent;
+    getPages(path: string, query?: string): SleekSiteContent["pages"];
+    getPage(path: string): Page | null;
+    getSlugs(path: string): string[];
     getImages(): SleekSiteContent["images"];
     getImage(name: string): unknown | undefined;
     getList<T = unknown>(name: string): T[] | undefined;

package/index.d.ts

@@ -32,8 +32,10 @@ interface ClientOptions {
  * Async SleekCMS client: methods return Promises.
  */
 interface SleekClient {
-    getContent<T = SleekSiteContent>(query?: string): Promise<T>;
-    findPages<T = unknown>(path: string, query?: string): Promise<T>;
+    getContent(query?: string): Promise<SleekSiteContent>;
+    getPages(path: string, query?: string): Promise<SleekSiteContent["pages"]>;
+    getPage(path: string): Promise<Page>;
+    getSlugs(path: string): Promise<string[]>;
     getImages(): Promise<SleekSiteContent["images"]>;
     getImage(name: string): Promise<unknown | undefined>;
     getList<T = unknown>(name: string): Promise<T[] | undefined>;
@@ -42,8 +44,10 @@ interface SleekClient {
  * Sync client: prefetches full content once; subsequent calls are in-memory only.
  */
 interface SleekSyncClient {
-    getContent<T = SleekSiteContent>(query?: string): T;
-    findPages<T = unknown>(path: string, query?: string): T;
+    getContent(query?: string): SleekSiteContent;
+    getPages(path: string, query?: string): SleekSiteContent["pages"];
+    getPage(path: string): Page | null;
+    getSlugs(path: string): string[];
     getImages(): SleekSiteContent["images"];
     getImage(name: string): unknown | undefined;
     getList<T = unknown>(name: string): T[] | undefined;

package/index.mjs

@@ -0,0 +1,195 @@
+// src/lib.ts
+import * as jmespath from "jmespath";
+function isDevToken(token) {
+  return token.startsWith("dev-");
+}
+function getBaseUrl(token) {
+  let [env, siteId, ...rest] = token.split("-");
+  return `https://${env}.sleekcms.com/${siteId}`;
+}
+function applyJmes(data, query) {
+  if (!query) return data;
+  return jmespath.search(data, query);
+}
+function createFetchSiteContent(options) {
+  const { siteToken, env = "latest", mock } = options;
+  const dev = isDevToken(siteToken);
+  let cacheMode = !!options.cache || !!mock && dev;
+  let cachedContent = null;
+  return async function fetchSiteContent(searchQuery) {
+    if (!siteToken) {
+      throw new Error("[SleekCMS] siteToken is required");
+    }
+    if (cachedContent) {
+      return applyJmes(cachedContent, searchQuery);
+    }
+    const baseUrl = getBaseUrl(siteToken).replace(/\/$/, "");
+    const url = new URL(`${baseUrl}/${env}`);
+    if (searchQuery && !cacheMode && !cachedContent) {
+      url.searchParams.set("search", searchQuery);
+    }
+    if (mock && dev) {
+      url.searchParams.set("mock", "true");
+    }
+    const res = await fetch(url.toString(), {
+      method: "GET",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: siteToken
+      }
+    });
+    if (!res.ok) {
+      let message = res.statusText;
+      try {
+        const data2 = await res.json();
+        if (data2 && data2.message) message = data2.message;
+      } catch {
+      }
+      throw new Error(`[SleekCMS] Request failed (${res.status}): ${message}`);
+    }
+    const data = await res.json();
+    if (!searchQuery) {
+      cachedContent = data;
+      cacheMode = true;
+    }
+    return data;
+  };
+}
+
+// src/index.ts
+function extractSlugs(pages, path) {
+  const slugs = [];
+  const pagesList = pages ?? [];
+  for (const page of pagesList) {
+    const pth = typeof page._path === "string" ? page._path : "";
+    if (pth.startsWith(path) && "_slug" in page && typeof page._slug === "string") {
+      slugs.push(page._slug);
+    }
+  }
+  return slugs;
+}
+function filterPagesByPath(pages, path) {
+  const pagesList = pages ?? [];
+  return pagesList.filter((p) => {
+    const pth = typeof p._path === "string" ? p._path : "";
+    return pth.startsWith(path);
+  });
+}
+function createClient(options) {
+  const fetchSiteContent = createFetchSiteContent(options);
+  async function getContent(query) {
+    return await fetchSiteContent(query);
+  }
+  async function getPages(path, query) {
+    if (!path) {
+      throw new Error("[SleekCMS] path is required for getPages");
+    }
+    const data = await fetchSiteContent();
+    const filtered = filterPagesByPath(data.pages, path);
+    return applyJmes(filtered, query);
+  }
+  async function getPage(path) {
+    if (!path) {
+      throw new Error("[SleekCMS] path is required for getPage");
+    }
+    const data = await fetchSiteContent();
+    const pages = data.pages ?? [];
+    const page = pages.find((p) => {
+      const pth = typeof p._path === "string" ? p._path : "";
+      return pth === path;
+    });
+    if (!page) {
+      throw new Error(`[SleekCMS] Page not found: ${path}`);
+    }
+    return page;
+  }
+  async function getSlugs(path) {
+    if (!path) {
+      throw new Error("[SleekCMS] path is required for getSlugs");
+    }
+    const data = await fetchSiteContent();
+    return extractSlugs(data.pages, path);
+  }
+  async function getImages() {
+    const data = await fetchSiteContent();
+    return data.images ?? {};
+  }
+  async function getImage(name) {
+    if (!name) return void 0;
+    const data = await fetchSiteContent();
+    return data.images ? data.images[name] : void 0;
+  }
+  async function getList(name) {
+    if (!name) return void 0;
+    const data = await fetchSiteContent();
+    const lists = data.lists ?? {};
+    const list = lists[name];
+    return Array.isArray(list) ? list : void 0;
+  }
+  return {
+    getContent,
+    getPages,
+    getPage,
+    getSlugs,
+    getImages,
+    getImage,
+    getList
+  };
+}
+async function createSyncClient(options) {
+  const fetchSiteContent = createFetchSiteContent(options);
+  const data = await fetchSiteContent();
+  function getContent(query) {
+    return applyJmes(data, query);
+  }
+  function getPages(path, query) {
+    if (!path) {
+      throw new Error("[SleekCMS] path is required for getPages");
+    }
+    const filtered = filterPagesByPath(data.pages, path);
+    return applyJmes(filtered, query);
+  }
+  function getPage(path) {
+    if (!path) {
+      throw new Error("[SleekCMS] path is required for getPage");
+    }
+    const pages = data.pages ?? [];
+    const page = pages.find((p) => {
+      const pth = typeof p._path === "string" ? p._path : "";
+      return pth === path;
+    });
+    return page ?? null;
+  }
+  function getSlugs(path) {
+    if (!path) {
+      throw new Error("[SleekCMS] path is required for getSlugs");
+    }
+    return extractSlugs(data.pages, path);
+  }
+  function getImages() {
+    return data.images ?? {};
+  }
+  function getImage(name) {
+    if (!name) return void 0;
+    return data.images ? data.images[name] : void 0;
+  }
+  function getList(name) {
+    if (!name) return void 0;
+    const lists = data.lists ?? {};
+    const list = lists[name];
+    return Array.isArray(list) ? list : void 0;
+  }
+  return {
+    getContent,
+    getPages,
+    getPage,
+    getSlugs,
+    getImages,
+    getImage,
+    getList
+  };
+}
+export {
+  createClient,
+  createSyncClient
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleekcms/client",
-  "version": "0.1.5",
+  "version": "1.0.0",
   "description": "Official SleekCMS content client for Node 18+ and browser",
   "type": "module",
   "main": "index.cjs",
@@ -15,7 +15,7 @@
     }
   },
   "scripts": {
-    "build": "npm run clean && tsup src/index.ts --dts --format esm,cjs && cp README.md dist/ && jq '.private = false | .files = [\"index.cjs\", \"index.mjs\", \"index.d.ts\", \"index.d.cts\", \"README.md\"]' package.json > dist/package.json",
+    "build": "npm run clean && tsup && cp README.md dist/ && cp .npmrc dist/ && jq '.private = false | .files = [\"index.cjs\", \"index.mjs\", \"index.d.ts\", \"index.d.cts\", \"README.md\"]' package.json > dist/package.json",
     "clean": "rimraf dist || true",
     "test": "vitest run",
     "test:watch": "vitest",