@rezamirzapour/pod-sdk 1.0.0 → 1.0.2

package/README.md

@@ -77,131 +77,266 @@ export const podSdk = createPodSdk({
 
 POD CMS stores dynamic fields inside a `metadata.content` array of `{ code, value, type }` objects. `@rezamirzapour/pod-sdk` automatically formats these into clean typed key-value pairs (`item.formatted`) and allows an optional custom `normalizer` function (`item.__normalized`).
 
-### 1. Defining Types and Fetching CMS Articles with `getContent<T, P>`
+### 🏗️ Clean Architecture Pattern: Dedicated Data Access Layer (`NewsApi`)
 
-```tsx
-// app/news/page.tsx (Server Component)
+In enterprise Next.js applications, avoid calling SDK clients directly inside UI components. Instead, encapsulate CMS queries, generics, normalizers, and caching logic inside a dedicated Data Access Layer (`services/newsApi.ts`).
+
+#### Step 1: Create the Data Access Layer (`services/newsApi.ts`)
+
+```typescript
+// services/newsApi.ts
 import { podSdk } from '@/lib/pod';
 
-// 1. Define the formatted structure of your CMS content type
-interface NewsArticle {
+// 1. Define the raw CMS Formatted Metadata schema (T)
+export interface NewsArticleFormatted {
   title: string;
   coverImage: string; // Auto-transformed from hash to full Podspace CDN URL!
   lead: string;
   body: string;
-  publishDate: string;
+  author?: string;
+}
+
+// 2. Define computed / normalized domain attributes (P)
+export interface NewsArticleNormalized {
+  summary: string;
+  readTime: number;
 }
 
-// 2. Optional: Define normalized helper fields computed on the fly
-interface NewsNormalized {
+// 3. Define the Clean Domain Model consumed by your React Components
+export interface NewsItem {
+  id: number;
+  entityId: number;
+  title: string;
+  coverImage: string;
   summary: string;
-  readTimeEstimate: number;
+  body: string;
+  readTime: number;
+  publishedAt?: number;
 }
 
-export default async function NewsPage() {
-  // Call getContent with exact generic parameters: <T, P>
-  const response = await podSdk.cms.getContent<NewsArticle, NewsNormalized>(
-    {
-      contentTypeUniqueId: 'company_news',
-      size: 10,
-      offset: 0,
-    },
-    {
-      // Optional: compute custom normalized fields
-      normalizer: (item) => ({
-        summary: item.formatted.lead || item.formatted.title,
-        readTimeEstimate: Math.ceil((item.formatted.body?.length || 0) / 500),
-      }),
-      // Next.js ISR options
-      revalidate: 1800,
+export interface GetNewsListParams {
+  page?: number;
+  pageSize?: number;
+  tagTrees?: string[];
+}
+
+export class NewsApi {
+  private static readonly CONTENT_TYPE = 'company_news';
+
+  /**
+   * Fetches published news articles with Next.js App Router ISR Caching
+   */
+  public static async getNewsList({
+    page = 1,
+    pageSize = 10,
+    tagTrees,
+  }: GetNewsListParams = {}): Promise<{ items: NewsItem[]; total: number }> {
+    const offset = (page - 1) * pageSize;
+
+    // Call getContent with exact generics: <NewsArticleFormatted, NewsArticleNormalized>
+    const response = await podSdk.cms.getContent<NewsArticleFormatted, NewsArticleNormalized>(
+      {
+        contentTypeUniqueId: this.CONTENT_TYPE,
+        size: pageSize,
+        offset,
+        tagTrees,
+      },
+      {
+        // Custom normalizer executed during data formatting
+        normalizer: (item) => ({
+          summary: item.formatted.lead || item.formatted.title,
+          readTime: Math.max(1, Math.ceil((item.formatted.body?.length || 0) / 500)),
+        }),
+        revalidate: 1800, // Next.js ISR: cache for 30 minutes
+      }
+    );
+
+    if (response.hasError || !Array.isArray(response.result)) {
+      return { items: [], total: 0 };
     }
-  );
+
+    const items: NewsItem[] = response.result.map((item) => ({
+      id: item.id,
+      entityId: item.entityId,
+      title: item.formatted.title,
+      coverImage: item.formatted.coverImage,
+      summary: item.__normalized.summary,
+      body: item.formatted.body,
+      readTime: item.__normalized.readTime,
+      publishedAt: item.timestamp,
+    }));
+
+    return {
+      items,
+      total: response.count || items.length,
+    };
+  }
+
+  /**
+   * Fetches a single news article by its entity ID
+   */
+  public static async getNewsById(entityId: number): Promise<NewsItem | null> {
+    const response = await podSdk.cms.getContentByEntityId<NewsArticleFormatted, NewsArticleNormalized>({
+      entityId,
+      contentTypeUniqueId: this.CONTENT_TYPE,
+    });
+
+    const item = response.result?.[0];
+    if (!item) return null;
+
+    return {
+      id: item.id,
+      entityId: item.entityId,
+      title: item.formatted.title,
+      coverImage: item.formatted.coverImage,
+      summary: item.formatted.lead || item.formatted.title,
+      body: item.formatted.body,
+      readTime: Math.max(1, Math.ceil((item.formatted.body?.length || 0) / 500)),
+      publishedAt: item.timestamp,
+    };
+  }
+
+  /**
+   * Publishes a new article to CMS
+   */
+  public static async publishNews(data: {
+    title: string;
+    lead: string;
+    body: string;
+    imageHash: string;
+  }) {
+    return podSdk.cms.addContent({
+      contentTypeUniqueId: this.CONTENT_TYPE,
+      body: {
+        name: data.title,
+        fieldCode: ['title', 'lead', 'body', 'coverImage'],
+        fieldValue: [data.title, data.lead, data.body, data.imageHash],
+        canComment: true,
+        canLike: true,
+        enable: true,
+        isSearchable: true,
+      },
+    });
+  }
+}
+```
+
+---
+
+#### Step 2: Consume `NewsApi` in Next.js Server Components (`app/news/page.tsx`)
+
+Notice how clean the UI layer becomes! No low-level SDK parameters, headers, or raw hashes leaked into your views:
+
+```tsx
+// app/news/page.tsx (Server Component)
+import { NewsApi } from '@/services/newsApi';
+import Link from 'next/link';
+
+interface NewsPageProps {
+  searchParams: { page?: string };
+}
+
+export default async function NewsPage({ searchParams }: NewsPageProps) {
+  const page = Number(searchParams.page) || 1;
+  const { items, total } = await NewsApi.getNewsList({ page, pageSize: 12 });
 
   return (
-    <div className="container mx-auto p-6">
-      <h1 className="text-2xl font-bold mb-4">Latest News</h1>
-      <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
-        {response.result.map((item) => (
-          <article key={item.id} className="border rounded-lg p-4 shadow">
-            {/* item.formatted is 100% typed as NewsArticle */}
-            {item.formatted.coverImage && (
+    <main className="container mx-auto py-8 px-4">
+      <h1 className="text-3xl font-bold mb-6">Company News</h1>
+
+      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
+        {items.map((news) => (
+          <article key={news.entityId} className="border rounded-xl overflow-hidden shadow-sm hover:shadow-md transition">
+            {news.coverImage && (
               <img
-                src={item.formatted.coverImage}
-                alt={item.formatted.title}
-                className="w-full h-48 object-cover rounded"
+                src={news.coverImage}
+                alt={news.title}
+                className="w-full h-48 object-cover"
               />
             )}
-            <h2 className="text-xl font-semibold mt-2">{item.formatted.title}</h2>
-            <p className="text-gray-600 mt-1">{item.__normalized.summary}</p>
-            <span className="text-xs text-gray-400">
-              Estimated read: {item.__normalized.readTimeEstimate} min
-            </span>
+            <div className="p-4">
+              <h2 className="text-xl font-semibold mb-2">
+                <Link href={`/news/${news.entityId}`}>{news.title}</Link>
+              </h2>
+              <p className="text-gray-600 text-sm line-clamp-2">{news.summary}</p>
+              <div className="mt-4 flex items-center justify-between text-xs text-gray-400">
+                <span>{news.readTime} min read</span>
+                <Link href={`/news/${news.entityId}`} className="text-blue-600 font-medium hover:underline">
+                  Read more →
+                </Link>
+              </div>
+            </div>
           </article>
         ))}
       </div>
-    </div>
+    </main>
   );
 }
 ```
 
-### 2. Fetching Single Content by Entity ID: `getContentByEntityId<T>`
+---
 
-```typescript
-// app/news/[id]/page.tsx
-import { podSdk } from '@/lib/pod';
+#### Step 3: Detail Page with `NewsApi.getNewsById` (`app/news/[id]/page.tsx`)
+
+```tsx
+// app/news/[id]/page.tsx (Server Component)
+import { NewsApi } from '@/services/newsApi';
 import { notFound } from 'next/navigation';
 
-interface ArticleDetail {
-  title: string;
-  content: string;
-  author: string;
-  coverImage: string;
+interface NewsDetailPageProps {
+  params: { id: string };
 }
 
-export default async function NewsDetailPage({ params }: { params: { id: string } }) {
-  const res = await podSdk.cms.getContentByEntityId<ArticleDetail>({
-    entityId: Number(params.id),
-    contentTypeUniqueId: 'company_news',
-  });
+export default async function NewsDetailPage({ params }: NewsDetailPageProps) {
+  const news = await NewsApi.getNewsById(Number(params.id));
 
-  const article = res.result?.[0];
-  if (!article) notFound();
+  if (!news) {
+    notFound();
+  }
 
   return (
-    <main>
-      <h1>{article.formatted.title}</h1>
-      <p>By {article.formatted.author}</p>
-      <div dangerouslySetInnerHTML={{ __html: article.formatted.content }} />
-    </main>
+    <article className="max-w-3xl mx-auto py-10 px-4">
+      {news.coverImage && (
+        <img
+          src={news.coverImage}
+          alt={news.title}
+          className="w-full h-72 object-cover rounded-xl mb-6"
+        />
+      )}
+      <h1 className="text-3xl font-bold mb-3">{news.title}</h1>
+      <p className="text-sm text-gray-500 mb-6">{news.readTime} min read</p>
+      <div className="prose lg:prose-lg" dangerouslySetInnerHTML={{ __html: news.body }} />
+    </article>
   );
 }
 ```
 
-### 3. Adding and Editing CMS Content: `addContent<T>` & `editContent<T>`
+---
+
+#### Step 4: Server Action for CMS Publishing (`app/actions/news.ts`)
 
 ```typescript
-// app/actions/cms.ts
+// app/actions/news.ts
 'use server';
 
-import { podSdk } from '@/lib/pod';
+import { NewsApi } from '@/services/newsApi';
+import { revalidatePath } from 'next/cache';
 
-export async function createNewsArticle(data: {
-  title: string;
-  body: string;
-  imageHash: string;
-}) {
-  return podSdk.cms.addContent({
-    contentTypeUniqueId: 'company_news',
-    body: {
-      name: data.title,
-      fieldCode: ['title', 'body', 'coverImage'],
-      fieldValue: [data.title, data.body, data.imageHash],
-      canComment: true,
-      canLike: true,
-      enable: true,
-      isSearchable: true,
-    },
+export async function publishArticle(formData: FormData) {
+  const title = formData.get('title') as string;
+  const lead = formData.get('lead') as string;
+  const body = formData.get('body') as string;
+  const imageHash = formData.get('imageHash') as string;
+
+  const result = await NewsApi.publishNews({
+    title,
+    lead,
+    body,
+    imageHash,
   });
+
+  revalidatePath('/news');
+  return { success: !result.hasError };
 }
 ```
 
@@ -254,10 +389,12 @@ export async function createBlogPost(meta: BlogPostMeta) {
 
 ### 2. High-Level Generic CRUD Repository (`createCrud<DataType>`)
 
-Create an ORM-like typed repository for any entity type in seconds:
+Create an ORM-like typed repository for any entity type and expose it through a dedicated service layer:
+
+#### Step 1: Create the Products Repository & API (`services/productsApi.ts`)
 
 ```typescript
-// lib/products.ts
+// services/productsApi.ts
 import { podSdk } from '@/lib/pod';
 
 export interface ProductData {
@@ -269,62 +406,107 @@ export interface ProductData {
   entityId?: number;
 }
 
-// Instantiate typed CRUD service for "product_item"
-export const productCrud = podSdk.createCrud<ProductData>({
+// 1. Instantiate typed CRUD service for "product_entity"
+const productCrud = podSdk.createCrud<ProductData>({
   name: 'product_entity',
   type: 'commerce',
   detailedType: 'gadgets',
 });
-```
 
-All methods on `productCrud` are fully generic:
+// 2. Encapsulate business queries and domain operations
+export class ProductsApi {
+  /**
+   * Retrieves all products formatted as clean domain objects
+   */
+  public static async getProducts(): Promise<ProductData[]> {
+    const result = await productCrud.getAll();
+    return result.result.map((r) => r.item.metadata.data);
+  }
 
-```typescript
-// app/actions/products.ts
-'use server';
+  /**
+   * Retrieves a single product by numerical entity ID
+   */
+  public static async getProductById(id: number): Promise<ProductData | null> {
+    const res = await productCrud.getById(id);
+    return res.result?.[0]?.metadata.data || null;
+  }
 
-import { productCrud } from '@/lib/products';
-import { revalidatePath } from 'next/cache';
+  /**
+   * Creates a product and automatically binds the generated entityId
+   */
+  public static async createProduct(data: Omit<ProductData, 'entityId'>) {
+    return productCrud.createAndBindEntityId({
+      ...data,
+      inStock: true,
+    });
+  }
 
-// 1. Fetch all products
-export async function getProducts() {
-  const result = await productCrud.getAll();
-  return result.result.map((r) => r.item.metadata.data);
-}
+  /**
+   * Updates an existing product
+   */
+  public static async updateProduct(entityId: number, data: ProductData) {
+    return productCrud.update(entityId, data);
+  }
 
-// 2. Get single product by numerical ID
-export async function getProductById(id: number) {
-  const res = await productCrud.getById(id);
-  return res.result?.[0]?.metadata.data;
+  /**
+   * Soft-archives a product without deleting history
+   */
+  public static async archiveProduct(entityId: number, data: ProductData) {
+    return productCrud.archive(entityId, data);
+  }
+
+  /**
+   * Deletes a product permanently
+   */
+  public static async deleteProduct(entityId: number) {
+    return productCrud.delete(entityId);
+  }
 }
+```
 
-// 3. Create product and automatically bind entityId
-export async function saveNewProduct(data: { title: string; sku: string; price: number }) {
-  const res = await productCrud.createAndBindEntityId({
-    title: data.title,
-    sku: data.sku,
-    price: data.price,
-    inStock: true,
-    category: 'electronics',
-  });
+---
 
-  revalidatePath('/products');
-  return res;
-}
+#### Step 2: Consume `ProductsApi` in Server Components (`app/products/page.tsx`)
 
-// 4. Update product
-export async function updateProduct(entityId: number, data: ProductData) {
-  return productCrud.update(entityId, data);
-}
+```tsx
+// app/products/page.tsx (Server Component)
+import { ProductsApi } from '@/services/productsApi';
+
+export default async function ProductsPage() {
+  const products = await ProductsApi.getProducts();
 
-// 5. Archive (soft-disable without deleting)
-export async function archiveProduct(entityId: number, data: ProductData) {
-  return productCrud.archive(entityId, data);
+  return (
+    <main className="container mx-auto py-8 px-4">
+      <h1 className="text-2xl font-bold mb-6">Products Catalog</h1>
+      <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
+        {products.map((p) => (
+          <div key={p.sku} className="border p-4 rounded-lg shadow-sm">
+            <h2 className="font-semibold text-lg">{p.title}</h2>
+            <p className="text-gray-500 text-sm">SKU: {p.sku}</p>
+            <p className="text-blue-600 font-bold mt-2">${p.price.toLocaleString()}</p>
+          </div>
+        ))}
+      </div>
+    </main>
+  );
 }
+```
+
+---
 
-// 6. Delete permanently
-export async function deleteProduct(entityId: number) {
-  return productCrud.delete(entityId);
+#### Step 3: Mutate via Server Actions (`app/actions/products.ts`)
+
+```typescript
+// app/actions/products.ts
+'use server';
+
+import { ProductsApi } from '@/services/productsApi';
+import { revalidatePath } from 'next/cache';
+
+export async function addProduct(data: { title: string; sku: string; price: number; category: string }) {
+  const result = await ProductsApi.createProduct(data);
+  revalidatePath('/products');
+  return result;
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rezamirzapour/pod-sdk",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Unified, type-safe enterprise SDK for POD Platform microservices (SSO, CustomPost, Podspace, Podform, Notification, Social, CMS, IUMS) powered by @rezamirzapour/http.",
   "author": "Reza",
   "license": "MIT",