@rezamirzapour/pod-sdk 1.0.2 → 1.0.4

package/README.md

@@ -1,6 +1,6 @@
 # @rezamirzapour/pod-sdk
 
-> Unified, type-safe, enterprise-grade SDK for **POD Platform** microservices (SSO, CustomPost, Podspace, Podform, Notification, Social, CMS, IUMS), engineered specifically for **Next.js App Router**, **Server Components**, and **Server Actions**.
+> Unified, type-safe, enterprise-grade SDK for **POD Platform** microservices (CMS Content, CMS Product, SSO, CustomPost, Podspace, Podform, Notification, Social, IUMS), engineered specifically for **Next.js App Router**, **Server Components**, and **Server Actions**.
 
 [![npm version](https://img.shields.io/npm/v/@rezamirzapour/pod-sdk.svg)](https://www.npmjs.com/package/@rezamirzapour/pod-sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
@@ -10,10 +10,11 @@
 
 ## Features
 
-- 🌐 **Unified Multi-Service Architecture**: Single entry-point managing 8 POD microservices with official endpoints and configurations.
+- 🌐 **Unified Multi-Service Architecture**: Single entry-point managing official POD microservices with official endpoints and configurations.
 - ⚡ **Powered by `@rezamirzapour/http`**: Automatic exponential backoff retries, Next.js incremental static regeneration (ISR) caching (`next.revalidate`, tags), and isomorphic execution.
-- 🧬 **First-Class TypeScript Generics (`<T, P>`)**: CMS and CustomPost endpoints allow you to define and receive strongly typed metadata structures according to your business schemas.
-- 🎨 **Automatic CMS Data Formatter**: Automatically translates POD CMS nested `metadata.content` arrays into flat, strongly typed objects (`formatted[fieldCode]`) and resolves image hashes to CDN URLs.
+- 🧬 **First-Class TypeScript Generics (`<T, P>`)**: CMS Content, CMS Product, and CustomPost endpoints allow you to define and receive strongly typed metadata structures according to your business schemas.
+- 🎨 **Automatic CMS Data Formatter**: Automatically translates nested `metadata.content` and `metadata.product` arrays into flat, strongly typed objects (`formatted[fieldCode]`) and resolves image hashes to Podspace CDN URLs.
+- 🛍️ **Full CMS Product Module (RAD API Swagger)**: Complete support for published products, price/discount filters, barcodes, batch publish/unpublish, archiving, and AI timeline search.
 - 📦 **Generic CRUD Repository for CustomPost**: Instantiate typed data repositories on POD CustomPost in 2 lines with `create`, `getById`, `getAll`, `createAndBindEntityId`, and `archive`.
 - 🔐 **Zero-Dependency Web Crypto RSA Signing**: Built-in RSA-SHA256 signature calculation for POD SSO OTP handshakes using standard Web Crypto API (Node.js, Edge Runtime, Browsers).
 - 🚀 **Next.js App Router Ready**: Seamless support for Server Components, Server Actions, Route Handlers, and Client Components.
@@ -23,16 +24,18 @@
 
 ## Microservices Included
 
-| Service | Property | Description |
-| :--- | :--- | :--- |
-| **CMS** | `sdk.cms` | Fetch, publish, edit, and categorize CMS articles with generic metadata `<T, P>` and automatic image formatting. |
-| **CustomPost** | `sdk.customPost` | Search timeline by metadata `<T>`, custom post CRUD, and high-level typed repository. |
-| **SSO** | `sdk.sso` | OAuth2 handshake, OTP dispatch with digital RSA signature, OTP verify, token generation, and user profile. |
-| **Podspace** | `sdk.podspace` | File upload (FormData) and public/private download URL resolution. |
-| **Podform** | `sdk.podform` | Survey & form response submission, question/form structure retrieval. |
-| **Notification** | `sdk.notification` | SMS delivery and bulk messaging with tracking. |
-| **Social** | `sdk.social` | User comments, reactions (likes/dislikes), rates, and social post interactions. |
-| **IUMS** | `sdk.iums` | Student and user identity inspection by national code or student ID. |
+| Service | Accessor | Swagger Tag | Description |
+| :--- | :--- | :--- | :--- |
+| **CMS Content** | `sdk.cms` | `content` | Fetch, publish, edit, draft, archive, and categorize CMS articles with generic metadata `<T, P>`. |
+| **CMS Product** | `sdk.product` / `sdk.cms.products` | `product` | Product catalog, price & discount range filters, barcode lookup, batch publish, and AI search. |
+| **CMS Tags & Tree** | `sdk.tags` / `sdk.cms.tags` | `tags` | Manage tag categories and hierarchical tag trees (nodes, parent updates, ancestors, codes). |
+| **CustomPost** | `sdk.customPost` | - | Search timeline by metadata `<T>`, custom post CRUD, and high-level typed repository. |
+| **SSO** | `sdk.sso` | - | OAuth2 handshake, OTP dispatch with digital RSA signature, OTP verify, token generation, and user profile. |
+| **Podspace** | `sdk.podspace` | - | File upload (FormData) and public/private download URL resolution. |
+| **Podform** | `sdk.podform` | - | Survey & form response submission, question/form structure retrieval. |
+| **Notification** | `sdk.notification` | - | SMS delivery and bulk messaging with tracking. |
+| **Social** | `sdk.social` | - | User comments, reactions (likes/dislikes), rates, and social post interactions. |
+| **IUMS** | `sdk.iums` | - | Student and user identity inspection by national code or student ID. |
 
 ---
 
@@ -73,10 +76,13 @@ export const podSdk = createPodSdk({
 
 ---
 
-## Deep Dive: CMS & Generic Data Formatting
+## Deep Dive 1: CMS Content & Data Formatting
 
 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`).
 
+> [!NOTE]
+> `getContent2` has been removed. For authenticated/management content retrieval (using `Access-Token`), call `podSdk.cms.getAllContents()` or pass headers to `getContent()`.
+
 ### 🏗️ Clean Architecture Pattern: Dedicated Data Access Layer (`NewsApi`)
 
 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`).
@@ -221,12 +227,8 @@ export class NewsApi {
 }
 ```
 
----
-
 #### 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';
@@ -276,237 +278,298 @@ export default async function NewsPage({ searchParams }: NewsPageProps) {
 
 ---
 
-#### 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 NewsDetailPageProps {
-  params: { id: string };
-}
-
-export default async function NewsDetailPage({ params }: NewsDetailPageProps) {
-  const news = await NewsApi.getNewsById(Number(params.id));
-
-  if (!news) {
-    notFound();
-  }
+## Deep Dive 2: CMS Product Module (RAD API Swagger)
 
-  return (
-    <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>
-  );
-}
-```
+The CMS Product module connects directly to POD RAD API endpoints ([Swagger documentation](https://rad-sandbox.sandpod.ir/api/documentation?tag=product)). It handles products with prices, discounts, barcodes, dynamic `metadata.product` field formatting, and batch management.
 
----
+### Accessing Products
 
-#### Step 4: Server Action for CMS Publishing (`app/actions/news.ts`)
+You can access product methods either via `podSdk.product` or `podSdk.cms.products`:
 
 ```typescript
-// app/actions/news.ts
-'use server';
-
-import { NewsApi } from '@/services/newsApi';
-import { revalidatePath } from 'next/cache';
-
-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 };
-}
+// Both point to the same CmsProductService instance
+podSdk.product.getProducts(...);
+podSdk.cms.products.getProducts(...);
 ```
 
----
-
-## Deep Dive: CustomPost & Generic Typed Repositories
-
-`CustomPost` allows persisting arbitrary JSON schemas on the POD Platform. `@rezamirzapour/pod-sdk` provides two complementary approaches:
-
-1. **Direct Service Method Calls with Generics (`searchTimelineByMetadata<T>`, `getCustomPost<T>`, `addCustomPost<T>`)**
-2. **High-Level Typed CRUD Repository (`CustomPostCrudService<DataType>`)**
-
-### 1. Direct Generic Method Usage
+### 🛍️ Clean Architecture Pattern: Product Data Access Layer (`ProductsApi`)
 
 ```typescript
-// lib/blog.ts
+// services/productsApi.ts
 import { podSdk } from '@/lib/pod';
 
-export interface BlogPostMeta {
-  slug: string;
-  title: string;
-  summary: string;
-  views: number;
-  publishedAt: string;
+// 1. Raw formatted product metadata (T)
+export interface LaptopFormatted {
+  cpu: string;
+  ram: string;
+  storage: string;
+  displayPhoto: string; // Auto-transformed from hash to Podspace CDN URL
 }
 
-// 1. Search posts with typed metadata query
-export async function getPublishedPosts() {
-  const response = await podSdk.customPost.searchTimelineByMetadata<BlogPostMeta>({
-    entityName: 'blog_post',
-    metadata: { views: 100 }, // Partial match or query
-    size: 20,
-    offset: 0,
-  });
-
-  // response.result[i].item.metadata is strongly typed as BlogPostMeta
-  return response.result.map((r) => r.item.metadata);
+// 2. Computed / normalized presentation fields (P)
+export interface LaptopNormalized {
+  finalPrice: number;
+  discountBadge: string;
 }
 
-// 2. Add a new custom post with typed metadata
-export async function createBlogPost(meta: BlogPostMeta) {
-  return podSdk.customPost.addCustomPost<BlogPostMeta>({
-    name: 'blog_post',
-    content: meta.title,
-    metadata: meta, // Strongly typed
-    enable: true,
-  });
-}
-```
-
-### 2. High-Level Generic CRUD Repository (`createCrud<DataType>`)
-
-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
-// services/productsApi.ts
-import { podSdk } from '@/lib/pod';
-
-export interface ProductData {
-  title: string;
-  sku: string;
+// 3. Clean Domain Product Model
+export interface ProductItemModel {
+  entityId: number;
+  name: string;
   price: number;
-  inStock: boolean;
-  category: string;
-  entityId?: number;
+  finalPrice: number;
+  discountBadge: string;
+  photoUrl: string;
+  specs: {
+    cpu: string;
+    ram: string;
+    storage: string;
+  };
 }
 
-// 1. Instantiate typed CRUD service for "product_entity"
-const productCrud = podSdk.createCrud<ProductData>({
-  name: 'product_entity',
-  type: 'commerce',
-  detailedType: 'gadgets',
-});
-
-// 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);
-  }
+  private static readonly PRODUCT_TYPE = 'laptops';
 
   /**
-   * Retrieves a single product by numerical entity ID
+   * Fetches published products with price & discount filters
    */
-  public static async getProductById(id: number): Promise<ProductData | null> {
-    const res = await productCrud.getById(id);
-    return res.result?.[0]?.metadata.data || null;
-  }
+  public static async getProducts(params: {
+    fromPrice?: number;
+    toPrice?: number;
+    barcode?: string;
+    page?: number;
+    pageSize?: number;
+  } = {}): Promise<ProductItemModel[]> {
+    const { fromPrice, toPrice, barcode, page = 1, pageSize = 20 } = params;
+    const offset = (page - 1) * pageSize;
 
-  /**
-   * Creates a product and automatically binds the generated entityId
-   */
-  public static async createProduct(data: Omit<ProductData, 'entityId'>) {
-    return productCrud.createAndBindEntityId({
-      ...data,
-      inStock: true,
-    });
+    const response = await podSdk.product.getProducts<LaptopFormatted, LaptopNormalized>(
+      {
+        productTypeUniqueId: this.PRODUCT_TYPE,
+        fromPrice,
+        toPrice,
+        barcode,
+        size: pageSize,
+        offset,
+      },
+      {
+        normalizer: (item) => {
+          const discount = item.discount || 0;
+          const finalPrice = item.price ? item.price * (1 - discount / 100) : 0;
+          return {
+            finalPrice,
+            discountBadge: discount > 0 ? `${discount}% OFF` : '',
+          };
+        },
+        revalidate: 3600, // Next.js ISR: cache for 1 hour
+      }
+    );
+
+    if (response.hasError || !Array.isArray(response.result)) {
+      return [];
+    }
+
+    return response.result.map((item) => ({
+      entityId: item.entityId,
+      name: item.name || '',
+      price: item.price || 0,
+      finalPrice: item.__normalized.finalPrice,
+      discountBadge: item.__normalized.discountBadge,
+      photoUrl: item.formatted.displayPhoto,
+      specs: {
+        cpu: item.formatted.cpu,
+        ram: item.formatted.ram,
+        storage: item.formatted.storage,
+      },
+    }));
   }
 
   /**
-   * Updates an existing product
+   * Retrieves single product by entityId
    */
-  public static async updateProduct(entityId: number, data: ProductData) {
-    return productCrud.update(entityId, data);
+  public static async getProductById(entityId: number) {
+    const res = await podSdk.product.getProductByEntityId<LaptopFormatted, LaptopNormalized>({
+      entityId,
+      productTypeUniqueId: this.PRODUCT_TYPE,
+    });
+    return res.result?.[0] || null;
   }
 
   /**
-   * Soft-archives a product without deleting history
+   * Look up product by barcode scanner
    */
-  public static async archiveProduct(entityId: number, data: ProductData) {
-    return productCrud.archive(entityId, data);
+  public static async getProductByBarcode(barcode: string) {
+    return podSdk.product.getProductByBarcode<LaptopFormatted>(barcode);
   }
 
   /**
-   * Deletes a product permanently
+   * Adds and publishes a new product
    */
-  public static async deleteProduct(entityId: number) {
-    return productCrud.delete(entityId);
+  public static async createProduct(data: {
+    name: string;
+    price: number;
+    cpu: string;
+    ram: string;
+    storage: string;
+    photoHash: string;
+  }) {
+    return podSdk.product.addProduct({
+      productTypeUniqueId: this.PRODUCT_TYPE,
+      body: {
+        name: data.name,
+        enable: true,
+        fieldCode: ['cpu', 'ram', 'storage', 'displayPhoto', 'price'],
+        fieldValue: [data.cpu, data.ram, data.storage, data.photoHash, data.price],
+      },
+    });
   }
 }
 ```
 
+### CMS Methods Reference
+
+#### Content Methods (`podSdk.cms`)
+
+| Method | HTTP | Path | Description |
+| :--- | :--- | :--- | :--- |
+| `getContent<T, P>(params, opts)` | `GET` | `/api/core/contents/enable` | Get published enabled contents with generic typing. |
+| `getAllContents<T, P>(params, opts)` | `GET` | `/api/core/contents` | Get contents with managing credentials (`Access-Token`). |
+| `getMyContents<T, P>(params, opts)` | `GET` | `/api/core/contents/my` | Get current user/client contents. |
+| `getContentsByType<T, P>(typeId, params)` | `GET` | `/api/core/contents/{contentTypeUniqueId}` | Get contents by ContentType. |
+| `getContentByEntityId<T, P>(params)` | `GET` | `/api/core/contents/enable/{entityId}` | Get single published content item. |
+| `getContentByUniqueId<T, P>(uniqueId)` | `GET` | `/api/core/contents/{uniqueId}/byContentUniqueId/enable` | Get content by uniqueId. |
+| `searchContent<T, P>(params)` | `GET` | `/api/core/contents/search` | Search published contents by keyword. |
+| `addContent<T, P>(params)` | `POST` | `/api/core/contents/{contentTypeUniqueId}/add-publish` | Add and publish content item. |
+| `createContent<T, P>(params)` | `POST` | `/api/core/contents/{contentTypeUniqueId}` | Create unpublished/draft content. |
+| `editContent<T, P>(entityId, params)` | `POST` | `/api/core/contents/{typeId}/{entityId}/edit-publish` | Update and publish content item. |
+| `updateContent<T, P>(entityId, params)` | `POST` | `/api/core/contents/{typeId}/{entityId}` | Update content item. |
+| `patchContent<T, P>(entityId, params)` | `PATCH` | `/api/core/contents/{typeId}/{entityId}` | Partial update content. |
+| `publishContent(typeId, entityId)` | `POST` | `/api/core/contents/{typeId}/publish/{entityId}` | Publish single content item. |
+| `unpublishContent(typeId, entityId)` | `POST` | `/api/core/contents/{typeId}/unpublish/{entityId}` | Unpublish single content item. |
+| `batchPublish(params)` | `PUT` | `/api/core/contents/{typeId}/publish` | Batch publish multiple contents. |
+| `batchUnpublish(params)` | `PUT` | `/api/core/contents/{typeId}/unpublish` | Batch unpublish multiple contents. |
+| `archiveContent(params)` | `POST` | `/api/core/contents/{typeId}/archive` | Archive content items. |
+| `unarchiveContent(params)` | `POST` | `/api/core/contents/{typeId}/unarchive` | Unarchive content items. |
+| `getArchivedContents(params)` | `GET` | `/api/core/contents/archive` | Get archived contents list. |
+| `getDrafts(params)` | `GET` | `/api/core/contents/draft` | Get drafts list. |
+| `createDraft(params)` | `POST` | `/api/core/contents/{typeId}/draft` | Create a draft. |
+| `getComments(typeId, entityId)` | `GET` | `/api/core/contents/{typeId}/comments/{entityId}` | Get comments on content. |
+| `getLikes(uniqueId, entityId)` | `GET` | `/api/core/contents/{uniqueId}/like/{entityId}` | Get likes of content item. |
+| `getCategories(params)` | `GET` | `/api/core/tags/root/tree/enable` | Get category/tag tree. |
+| `timelineSearch(query)` | `GET` | `/api/core/contents/ai/timeline-search/enable` | Advanced AI timeline search. |
+
+#### Product Methods (`podSdk.product` / `podSdk.cms.products`)
+
+| Method | HTTP | Path | Description |
+| :--- | :--- | :--- | :--- |
+| `getProducts<T, P>(params, opts)` | `GET` | `/api/core/products/enable` | Get enabled published products with price/discount filters. |
+| `getAllProducts<T, P>(params, opts)` | `GET` | `/api/core/products` | Get products with provider credentials (`Access-Token`). |
+| `getManageProducts<T, P>(params, opts)`| `GET` | `/api/core/products/manage` | Get products for manager view. |
+| `getProductsByType<T, P>(typeId, params)`| `GET` | `/api/core/products/{productTypeUniqueId}` | Get products by ProductType. |
+| `getProductByEntityId<T, P>(params)` | `GET` | `/api/core/products/enable/{entityId}` | Get single product by entityId. |
+| `getProductByUniqueId<T, P>(uniqueId)` | `GET` | `/api/core/products/{uniqueId}/byProductUniqueId/enable` | Get product by uniqueId. |
+| `getProductByBarcode<T, P>(barcode)` | `GET` | `/api/core/products/barcode/enable` | Lookup products matching a barcode. |
+| `searchProducts<T, P>(params)` | `GET` | `/api/core/products/enable/search` | Search published products. |
+| `addProduct<T, P>(params)` | `POST` | `/api/core/products/{productTypeUniqueId}/add-publish` | Create and publish new product. |
+| `createProduct<T, P>(params)` | `POST` | `/api/core/products/{productTypeUniqueId}` | Create draft/unpublished product. |
+| `editProduct<T, P>(entityId, params)` | `POST` | `/api/core/products/{typeId}/{entityId}/edit-publish` | Edit and publish existing product. |
+| `updateProduct<T, P>(entityId, params)` | `POST` | `/api/core/products/{typeId}/{entityId}` | Update existing product. |
+| `patchProduct<T, P>(entityId, params)` | `PATCH` | `/api/core/products/{typeId}/{entityId}` | Partial update product. |
+| `publishProduct(typeId, entityId)` | `POST` | `/api/core/products/{typeId}/publish/{entityId}` | Publish product. |
+| `unpublishProduct(typeId, entityId)` | `POST` | `/api/core/products/{typeId}/unpublish/{entityId}` | Unpublish product. |
+| `batchPublish(params)` | `PUT` | `/api/core/products/publish` | Batch publish multiple products. |
+| `batchUnpublish(params)` | `PUT` | `/api/core/products/unpublish` | Batch unpublish multiple products. |
+| `archiveProduct(params)` | `POST` | `/api/core/products/archive` | Archive products. |
+| `unarchiveProduct(params)` | `POST` | `/api/core/products/unarchive` | Unarchive products. |
+| `getArchivedProducts(params)` | `GET` | `/api/core/products/archive` | Get archived products list. |
+| `timelineSearch(query)` | `GET` | `/api/core/products/ai/timeline-search/enable` | AI timeline search on products. |
+
 ---
 
-#### Step 2: Consume `ProductsApi` in Server Components (`app/products/page.tsx`)
+## Deep Dive 3: CMS Tags & Tag Categories (RAD API Swagger: tag=tags)
 
-```tsx
-// app/products/page.tsx (Server Component)
-import { ProductsApi } from '@/services/productsApi';
+Manage tag categories and multi-level hierarchical tag trees ([Swagger documentation](https://rad-sandbox.sandpod.ir/api/documentation?tag=tags)).
 
-export default async function ProductsPage() {
-  const products = await ProductsApi.getProducts();
+### Accessing Tag Services
 
-  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>
-  );
-}
+Access via `podSdk.tags` or `podSdk.cms.tags`:
+
+```typescript
+// Category Management (with Access-Token)
+const categories = await podSdk.tags.getTagCategories({ size: 20 });
+await podSdk.tags.createTagCategory({ name: 'Technology', desc: 'Tech articles' });
+await podSdk.tags.publishTagCategory(categoryId);
+
+// Public Hierarchical Tag Tree (without token, defaults to 'root')
+const rootTree = await podSdk.tags.getTagTree('root', { levelCount: 3 });
+
+// Backward-compatible shortcut
+const categoriesTree = await podSdk.cms.getCategories({ levelCount: 3 });
+
+// Tree Node Management (create, update parent, code, ancestors)
+await podSdk.tags.createTagTreeItem('technology', {
+  name: 'Next.js',
+  code: 'NEXTJS',
+  parentId: 10,
+});
+await podSdk.tags.updateTagTreeParent('technology', nodeId, newParentId);
+await podSdk.tags.updateTagTreeCode('technology', nodeId, 'NEW_CODE');
+const ancestors = await podSdk.tags.getTagTreeAncestors('technology', nodeId);
 ```
 
+### Tag Methods Reference (`podSdk.tags` / `podSdk.cms.tags`)
+
+| Method | HTTP | Path | Description |
+| :--- | :--- | :--- | :--- |
+| `getTagCategories(params)` | `GET` | `/api/core/tags/category` | List tag categories (manage). |
+| `createTagCategory(params)` | `POST` | `/api/core/tags/category` | Create new tag category. |
+| `getTagCategory(id)` | `GET` | `/api/core/tags/category/{id}` | Show single tag category. |
+| `updateTagCategory(id, params)` | `PUT` | `/api/core/tags/category/{id}` | Update tag category. |
+| `publishTagCategory(id)` | `PUT` | `/api/core/tags/category/{id}/publish` | Publish tag category. |
+| `unpublishTagCategory(id)` | `PUT` | `/api/core/tags/category/{id}/unpublish` | Unpublish tag category. |
+| `getTagTree(categoryId, params)` | `GET` | `/api/core/tags/{categoryId}/tree/enable` | Get enabled tag tree (public). |
+| `getManageTagTree(categoryId, params)` | `GET` | `/api/core/tags/{categoryId}/tree/manage` | Get tag tree (manage with token). |
+| `createTagTreeItem(categoryId, params)` | `POST` | `/api/core/tags/{categoryId}/tree` | Create tag tree node for category. |
+| `getTagTreeItem(categoryId, id)` | `GET` | `/api/core/tags/{categoryId}/tree/{id}/enable` | Show enabled tag tree node. |
+| `getManageTagTreeItem(categoryId, id)` | `GET` | `/api/core/tags/{categoryId}/tree/{id}/manage` | Show tag tree node (manage). |
+| `updateTagTreeItem(categoryId, id, params)` | `PUT` | `/api/core/tags/{categoryId}/tree/{id}` | Update tag tree node. |
+| `publishTagTreeItem(categoryId, id)` | `PUT` | `/api/core/tags/{categoryId}/tree/publish/{id}` | Publish tag tree node. |
+| `unpublishTagTreeItem(categoryId, id)` | `PUT` | `/api/core/tags/{categoryId}/tree/unpublish/{id}` | Unpublish tag tree node. |
+| `updateTagTreeParent(categoryId, id, parentId)` | `PUT` | `/api/core/tags/{categoryId}/tree/parent/{id}` | Update parent of tag tree node. |
+| `getTagTreeAncestors(categoryId, id, params)` | `GET` | `/api/core/tags/{categoryId}/tree/parent/{id}/enable` | Get node ancestors (public). |
+| `getManageTagTreeAncestors(categoryId, id, params)`| `GET` | `/api/core/tags/{categoryId}/tree/parent/{id}/manage` | Get node ancestors (manage). |
+| `updateTagTreeCode(categoryId, id, code)` | `PUT` | `/api/core/tags/{categoryId}/tree/code/{id}` | Update code of tag tree node. |
+
 ---
 
-#### Step 3: Mutate via Server Actions (`app/actions/products.ts`)
+## Deep Dive 4: CustomPost & Generic Typed Repositories
+
+`CustomPost` allows persisting arbitrary JSON schemas on the POD Platform. `@rezamirzapour/pod-sdk` provides two complementary approaches:
+
+1. **Direct Service Method Calls with Generics (`searchTimelineByMetadata<T>`, `getCustomPost<T>`, `addCustomPost<T>`)**
+2. **High-Level Typed CRUD Repository (`CustomPostCrudService<DataType>`)**
 
 ```typescript
-// app/actions/products.ts
-'use server';
+// lib/blog.ts
+import { podSdk } from '@/lib/pod';
 
-import { ProductsApi } from '@/services/productsApi';
-import { revalidatePath } from 'next/cache';
+export interface BlogPostMeta {
+  slug: string;
+  title: string;
+  summary: string;
+  views: number;
+}
 
-export async function addProduct(data: { title: string; sku: string; price: number; category: string }) {
-  const result = await ProductsApi.createProduct(data);
-  revalidatePath('/products');
-  return result;
+// Search posts with typed metadata query
+export async function getPublishedPosts() {
+  const response = await podSdk.customPost.searchTimelineByMetadata<BlogPostMeta>({
+    entityName: 'blog_post',
+    metadata: { views: 100 },
+    size: 20,
+    offset: 0,
+  });
+
+  return response.result.map((r) => r.item.metadata);
 }
 ```
 
@@ -514,7 +577,7 @@ export async function addProduct(data: { title: string; sku: string; price: numb
 
 ## Other POD Microservices
 
-### 3. POD SSO (OTP Handshake with Web Crypto RSA Signature)
+### 4. POD SSO (OTP Handshake with Web Crypto RSA Signature)
 
 ```typescript
 // app/actions/auth.ts
@@ -524,7 +587,6 @@ import { podSdk } from '@/lib/pod';
 
 // Step 1: Handshake and send OTP
 export async function sendOtp(phoneNumber: string, clientIp: string) {
-  // Handshake to obtain keyId
   const handshake = await podSdk.sso.handshake(`web-${Date.now()}`, clientIp);
   if (handshake.hasError || !handshake.result?.keyId) {
     throw new Error(handshake.message || 'SSO Handshake failed');
@@ -545,7 +607,6 @@ export async function verifyOtp(authorization: string, phoneNumber: string, code
     throw new Error(verify.message || 'OTP verification failed');
   }
 
-  // Exchange authorization code for JWT tokens
   const tokens = await podSdk.sso.generateToken(verify.result.code);
   return tokens.result; // { access_token, refresh_token, expires_in }
 }
@@ -559,7 +620,7 @@ export async function getProfile(accessToken: string) {
 
 ---
 
-### 4. Podspace (File Uploads & CDN URLs)
+### 5. Podspace (File Uploads & CDN URLs)
 
 ```typescript
 // app/actions/upload.ts
@@ -580,7 +641,7 @@ export async function uploadFile(formData: FormData) {
 
 ---
 
-### 5. Notification (SMS Delivery)
+### 6. Notification (SMS Delivery)
 
 ```typescript
 // app/actions/notify.ts
@@ -598,7 +659,7 @@ export async function sendSms(phoneNumber: string, text: string) {
 
 ---
 
-### 6. Social (Comments & Likes)
+### 7. Social (Comments & Likes)
 
 ```typescript
 // app/actions/social.ts
@@ -620,7 +681,7 @@ export async function likePost(postId: number) {
 
 ---
 
-### 7. IUMS (Identity & University Management Service)
+### 8. IUMS (Identity & University Management Service)
 
 ```typescript
 // app/actions/iums.ts