@rezamirzapour/pod-sdk 1.0.3 → 1.0.5

package/README.md

@@ -1,656 +1,742 @@
-# @rezamirzapour/pod-sdk
-
-> 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)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue?logo=typescript)](https://www.typescriptlang.org/)
-
----
-
-## Features
-
-- 🌐 **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 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.
-- 🌳 **Treeshakeable & Dual ESM/CJS**: Ships clean ES modules (`.mjs`) and CommonJS (`.js`) with 100% complete TypeScript declarations (`.d.ts`).
-
----
-
-## Microservices Included
-
-| 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. |
-| **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. |
-
----
-
-## Installation
-
-```bash
-npm install @rezamirzapour/pod-sdk @rezamirzapour/http @rezamirzapour/logger
-```
-
----
-
-## Quickstart
-
-### 1. Initialize the Client
-
-```typescript
-// lib/pod.ts
-import { createPodSdk } from '@rezamirzapour/pod-sdk';
-
-export const podSdk = createPodSdk({
-  apiToken: process.env.POD_API_TOKEN,
-  clientId: process.env.POD_CLIENT_ID,
-  clientSecret: process.env.POD_CLIENT_SECRET,
-  privateKeyPem: process.env.POD_PRIVATE_KEY_PEM, // RSA Private Key for SSO OTP signing
-  revalidate: 3600, // Default ISR revalidation in seconds
-  urls: {
-    // Optional overrides (defaults to official POD endpoints)
-    accounts: 'https://accounts.pod.ir',
-    apiPod: 'https://api.pod.ir',
-    cms: 'https://cms.pod.ir',
-    podspace: 'https://podspace.pod.ir',
-    podform: 'https://podform.pod.ir',
-    notification: 'https://notification.pod.ir',
-    iums: 'https://iums.pod.ir',
-  },
-});
-```
-
----
-
-## 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`).
-
-#### Step 1: Create the Data Access Layer (`services/newsApi.ts`)
-
-```typescript
-// services/newsApi.ts
-import { podSdk } from '@/lib/pod';
-
-// 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;
-  author?: string;
-}
-
-// 2. Define computed / normalized domain attributes (P)
-export interface NewsArticleNormalized {
-  summary: string;
-  readTime: number;
-}
-
-// 3. Define the Clean Domain Model consumed by your React Components
-export interface NewsItem {
-  id: number;
-  entityId: number;
-  title: string;
-  coverImage: string;
-  summary: string;
-  body: string;
-  readTime: number;
-  publishedAt?: number;
-}
-
-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`)
-
-```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 (
-    <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={news.coverImage}
-                alt={news.title}
-                className="w-full h-48 object-cover"
-              />
-            )}
-            <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>
-    </main>
-  );
-}
-```
-
----
-
-## Deep Dive 2: CMS Product Module (RAD API Swagger)
-
-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
-
-You can access product methods either via `podSdk.product` or `podSdk.cms.products`:
-
-```typescript
-// Both point to the same CmsProductService instance
-podSdk.product.getProducts(...);
-podSdk.cms.products.getProducts(...);
-```
-
-### 🛍️ Clean Architecture Pattern: Product Data Access Layer (`ProductsApi`)
-
-```typescript
-// services/productsApi.ts
-import { podSdk } from '@/lib/pod';
-
-// 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
-}
-
-// 2. Computed / normalized presentation fields (P)
-export interface LaptopNormalized {
-  finalPrice: number;
-  discountBadge: string;
-}
-
-// 3. Clean Domain Product Model
-export interface ProductItemModel {
-  entityId: number;
-  name: string;
-  price: number;
-  finalPrice: number;
-  discountBadge: string;
-  photoUrl: string;
-  specs: {
-    cpu: string;
-    ram: string;
-    storage: string;
-  };
-}
-
-export class ProductsApi {
-  private static readonly PRODUCT_TYPE = 'laptops';
-
-  /**
-   * Fetches published products with price & discount filters
-   */
-  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;
-
-    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,
-      },
-    }));
-  }
-
-  /**
-   * Retrieves single product by entityId
-   */
-  public static async getProductById(entityId: number) {
-    const res = await podSdk.product.getProductByEntityId<LaptopFormatted, LaptopNormalized>({
-      entityId,
-      productTypeUniqueId: this.PRODUCT_TYPE,
-    });
-    return res.result?.[0] || null;
-  }
-
-  /**
-   * Look up product by barcode scanner
-   */
-  public static async getProductByBarcode(barcode: string) {
-    return podSdk.product.getProductByBarcode<LaptopFormatted>(barcode);
-  }
-
-  /**
-   * Adds and publishes a new product
-   */
-  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. |
-
----
-
-## Deep Dive 3: 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
-// lib/blog.ts
-import { podSdk } from '@/lib/pod';
-
-export interface BlogPostMeta {
-  slug: string;
-  title: string;
-  summary: string;
-  views: number;
-}
-
-// 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);
-}
-```
-
----
-
-## Other POD Microservices
-
-### 4. POD SSO (OTP Handshake with Web Crypto RSA Signature)
-
-```typescript
-// app/actions/auth.ts
-'use server';
-
-import { podSdk } from '@/lib/pod';
-
-// Step 1: Handshake and send OTP
-export async function sendOtp(phoneNumber: string, clientIp: string) {
-  const handshake = await podSdk.sso.handshake(`web-${Date.now()}`, clientIp);
-  if (handshake.hasError || !handshake.result?.keyId) {
-    throw new Error(handshake.message || 'SSO Handshake failed');
-  }
-
-  // Automatic RSA-SHA256 signature using Web Crypto API
-  const otpRes = await podSdk.sso.sendOtpCode(handshake.result.keyId, phoneNumber);
-  return {
-    success: !otpRes.hasError,
-    authorization: otpRes.authorization,
-  };
-}
-
-// Step 2: Verify OTP code & exchange for tokens
-export async function verifyOtp(authorization: string, phoneNumber: string, code: string) {
-  const verify = await podSdk.sso.verifyOtpCode(authorization, phoneNumber, code);
-  if (verify.hasError || !verify.result?.code) {
-    throw new Error(verify.message || 'OTP verification failed');
-  }
-
-  const tokens = await podSdk.sso.generateToken(verify.result.code);
-  return tokens.result; // { access_token, refresh_token, expires_in }
-}
-
-// Step 3: Fetch profile with access token
-export async function getProfile(accessToken: string) {
-  const profile = await podSdk.sso.getUserProfile(accessToken);
-  return profile.result;
-}
-```
-
----
-
-### 5. Podspace (File Uploads & CDN URLs)
-
-```typescript
-// app/actions/upload.ts
-'use server';
-
-import { podSdk } from '@/lib/pod';
-
-export async function uploadFile(formData: FormData) {
-  const res = await podSdk.podspace.uploadFile(formData, '/uploads', true);
-  if (res.hasError) {
-    throw new Error(res.message || 'Upload failed');
-  }
-
-  const publicUrl = podSdk.podspace.getFileUrl(res.result.hash, true);
-  return { url: publicUrl, hash: res.result.hash };
-}
-```
-
----
-
-### 6. Notification (SMS Delivery)
-
-```typescript
-// app/actions/notify.ts
-'use server';
-
-import { podSdk } from '@/lib/pod';
-
-export async function sendSms(phoneNumber: string, text: string) {
-  return podSdk.notification.sendSms({
-    receptor: phoneNumber,
-    message: text,
-  });
-}
-```
-
----
-
-### 7. Social (Comments & Likes)
-
-```typescript
-// app/actions/social.ts
-'use server';
-
-import { podSdk } from '@/lib/pod';
-
-export async function addComment(postId: number, content: string) {
-  return podSdk.social.addComment({
-    postId,
-    text: content,
-  });
-}
-
-export async function likePost(postId: number) {
-  return podSdk.social.likePost(postId);
-}
-```
-
----
-
-### 8. IUMS (Identity & University Management Service)
-
-```typescript
-// app/actions/iums.ts
-'use server';
-
-import { podSdk } from '@/lib/pod';
-
-export async function getStudentByNationalCode(nationalCode: string) {
-  return podSdk.iums.getStudentInformationByNationalCode(nationalCode);
-}
-```
-
----
-
-## Environment Variables Reference
-
-```env
-# .env.local
-POD_API_TOKEN=your_api_token_here
-POD_CLIENT_ID=your_client_id_here
-POD_CLIENT_SECRET=your_client_secret_here
-POD_PRIVATE_KEY_PEM="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
-```
-
----
-
-## License
-
-MIT © [Reza](https://github.com/rezamirzapour2)
+# @rezamirzapour/pod-sdk
+
+> 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)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue?logo=typescript)](https://www.typescriptlang.org/)
+
+---
+
+## Features
+
+- 🌐 **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 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.
+- 🌳 **Treeshakeable & Dual ESM/CJS**: Ships clean ES modules (`.mjs`) and CommonJS (`.js`) with 100% complete TypeScript declarations (`.d.ts`).
+
+---
+
+## Microservices Included
+
+| 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. |
+
+---
+
+## Installation
+
+```bash
+npm install @rezamirzapour/pod-sdk @rezamirzapour/http @rezamirzapour/logger
+```
+
+---
+
+## Environment Variables & URL Configuration
+
+The SDK natively discovers official POD Platform URLs from your Next.js / Node.js `.env` configuration, or falls back to production defaults automatically:
+
+```env
+# POD Platform Production URLs
+NEXT_PUBLIC_ACCOUNTS_URL=https://accounts.pod.ir
+NEXT_PUBLIC_API_POD_URL=https://api.pod.ir
+NEXT_PUBLIC_API_POD_SANDBOX_URL=https://api.sandpod.ir
+NEXT_PUBLIC_CMS_URL=https://api.pod.ir/srv/cms-server
+NEXT_PUBLIC_IUMS_URL=https://indra.khatam.ac.ir/srv
+NEXT_PUBLIC_NOTIFICATION_URL=https://api.pod.ir/srv/notification
+NEXT_PUBLIC_PODREPORT_URL=https://reporting.pod.ir
+NEXT_PUBLIC_PODSPACE_URL=https://podspace.pod.ir
+
+# Sandbox Endpoints (Development & Staging)
+NEXT_PUBLIC_SANDBOX_CMS_URL=http://api.sandpod.ir/srv/cms-sandbox
+NEXT_PUBLIC_SANDBOX_CMS_CLIENT_URL=https://api.sandpod.ir/srv/cms-sandbox
+NEXT_PUBLIC_SANDBOX_PODSPACE_URL=http://podspace.sandpod.ir
+NEXT_PUBLIC_SANDBOX_STREAM_URL=https://sandbox-offline-stream.sandpod.ir
+```
+
+> [!TIP]
+> If you have defined these `NEXT_PUBLIC_*` variables in your `.env` or `.env.local`, `@rezamirzapour/pod-sdk` will automatically detect and apply them without any manual URL mapping.
+
+---
+
+## Quickstart
+
+### 1. Initialize the Client
+
+```typescript
+// lib/pod.ts
+import { createPodSdk, DEFAULT_POD_URLS, SANDBOX_POD_URLS } from '@rezamirzapour/pod-sdk';
+
+export const podSdk = createPodSdk({
+  apiToken: process.env.POD_API_TOKEN,
+  clientId: process.env.POD_CLIENT_ID,
+  clientSecret: process.env.POD_CLIENT_SECRET,
+  privateKeyPem: process.env.POD_PRIVATE_KEY_PEM, // RSA Private Key for SSO OTP signing
+  revalidate: 3600, // Default ISR revalidation in seconds
+  // sandbox: true, // Optional: automatically routes to POD Sandbox endpoints
+  urls: {
+    // Optional programmatic overrides (defaults to official POD endpoints & env vars)
+    accounts: 'https://accounts.pod.ir',
+    apiPod: 'https://api.pod.ir',
+    cms: 'https://api.pod.ir/srv/cms-server',
+    iums: 'https://indra.khatam.ac.ir/srv',
+    notification: 'https://api.pod.ir/srv/notification',
+    podreport: 'https://reporting.pod.ir',
+    podspace: 'https://podspace.pod.ir',
+    podform: 'https://podform.pod.ir',
+  },
+});
+```
+
+---
+
+## 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`).
+
+#### Step 1: Create the Data Access Layer (`services/newsApi.ts`)
+
+```typescript
+// services/newsApi.ts
+import { podSdk } from '@/lib/pod';
+
+// 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;
+  author?: string;
+}
+
+// 2. Define computed / normalized domain attributes (P)
+export interface NewsArticleNormalized {
+  summary: string;
+  readTime: number;
+}
+
+// 3. Define the Clean Domain Model consumed by your React Components
+export interface NewsItem {
+  id: number;
+  entityId: number;
+  title: string;
+  coverImage: string;
+  summary: string;
+  body: string;
+  readTime: number;
+  publishedAt?: number;
+}
+
+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`)
+
+```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 (
+    <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={news.coverImage}
+                alt={news.title}
+                className="w-full h-48 object-cover"
+              />
+            )}
+            <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>
+    </main>
+  );
+}
+```
+
+---
+
+## Deep Dive 2: CMS Product Module (RAD API Swagger)
+
+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
+
+You can access product methods either via `podSdk.product` or `podSdk.cms.products`:
+
+```typescript
+// Both point to the same CmsProductService instance
+podSdk.product.getProducts(...);
+podSdk.cms.products.getProducts(...);
+```
+
+### 🛍️ Clean Architecture Pattern: Product Data Access Layer (`ProductsApi`)
+
+```typescript
+// services/productsApi.ts
+import { podSdk } from '@/lib/pod';
+
+// 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
+}
+
+// 2. Computed / normalized presentation fields (P)
+export interface LaptopNormalized {
+  finalPrice: number;
+  discountBadge: string;
+}
+
+// 3. Clean Domain Product Model
+export interface ProductItemModel {
+  entityId: number;
+  name: string;
+  price: number;
+  finalPrice: number;
+  discountBadge: string;
+  photoUrl: string;
+  specs: {
+    cpu: string;
+    ram: string;
+    storage: string;
+  };
+}
+
+export class ProductsApi {
+  private static readonly PRODUCT_TYPE = 'laptops';
+
+  /**
+   * Fetches published products with price & discount filters
+   */
+  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;
+
+    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,
+      },
+    }));
+  }
+
+  /**
+   * Retrieves single product by entityId
+   */
+  public static async getProductById(entityId: number) {
+    const res = await podSdk.product.getProductByEntityId<LaptopFormatted, LaptopNormalized>({
+      entityId,
+      productTypeUniqueId: this.PRODUCT_TYPE,
+    });
+    return res.result?.[0] || null;
+  }
+
+  /**
+   * Look up product by barcode scanner
+   */
+  public static async getProductByBarcode(barcode: string) {
+    return podSdk.product.getProductByBarcode<LaptopFormatted>(barcode);
+  }
+
+  /**
+   * Adds and publishes a new product
+   */
+  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. |
+
+---
+
+## Deep Dive 3: CMS Tags & Tag Categories (RAD API Swagger: tag=tags)
+
+Manage tag categories and multi-level hierarchical tag trees ([Swagger documentation](https://rad-sandbox.sandpod.ir/api/documentation?tag=tags)).
+
+### Accessing Tag Services
+
+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. |
+
+---
+
+## 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
+// lib/blog.ts
+import { podSdk } from '@/lib/pod';
+
+export interface BlogPostMeta {
+  slug: string;
+  title: string;
+  summary: string;
+  views: number;
+}
+
+// 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);
+}
+```
+
+---
+
+## Other POD Microservices
+
+### 4. POD SSO (OTP Handshake with Web Crypto RSA Signature)
+
+```typescript
+// app/actions/auth.ts
+'use server';
+
+import { podSdk } from '@/lib/pod';
+
+// Step 1: Handshake and send OTP
+export async function sendOtp(phoneNumber: string, clientIp: string) {
+  const handshake = await podSdk.sso.handshake(`web-${Date.now()}`, clientIp);
+  if (handshake.hasError || !handshake.result?.keyId) {
+    throw new Error(handshake.message || 'SSO Handshake failed');
+  }
+
+  // Automatic RSA-SHA256 signature using Web Crypto API
+  const otpRes = await podSdk.sso.sendOtpCode(handshake.result.keyId, phoneNumber);
+  return {
+    success: !otpRes.hasError,
+    authorization: otpRes.authorization,
+  };
+}
+
+// Step 2: Verify OTP code & exchange for tokens
+export async function verifyOtp(authorization: string, phoneNumber: string, code: string) {
+  const verify = await podSdk.sso.verifyOtpCode(authorization, phoneNumber, code);
+  if (verify.hasError || !verify.result?.code) {
+    throw new Error(verify.message || 'OTP verification failed');
+  }
+
+  const tokens = await podSdk.sso.generateToken(verify.result.code);
+  return tokens.result; // { access_token, refresh_token, expires_in }
+}
+
+// Step 3: Fetch profile with access token
+export async function getProfile(accessToken: string) {
+  const profile = await podSdk.sso.getUserProfile(accessToken);
+  return profile.result;
+}
+```
+
+---
+
+### 5. Podspace (File Uploads & CDN URLs)
+
+```typescript
+// app/actions/upload.ts
+'use server';
+
+import { podSdk } from '@/lib/pod';
+
+export async function uploadFile(formData: FormData) {
+  const res = await podSdk.podspace.uploadFile(formData, '/uploads', true);
+  if (res.hasError) {
+    throw new Error(res.message || 'Upload failed');
+  }
+
+  const publicUrl = podSdk.podspace.getFileUrl(res.result.hash, true);
+  return { url: publicUrl, hash: res.result.hash };
+}
+```
+
+---
+
+### 6. Notification (SMS Delivery)
+
+```typescript
+// app/actions/notify.ts
+'use server';
+
+import { podSdk } from '@/lib/pod';
+
+export async function sendSms(phoneNumber: string, text: string) {
+  return podSdk.notification.sendSms({
+    receptor: phoneNumber,
+    message: text,
+  });
+}
+```
+
+---
+
+### 7. Social (Comments & Likes)
+
+```typescript
+// app/actions/social.ts
+'use server';
+
+import { podSdk } from '@/lib/pod';
+
+export async function addComment(postId: number, content: string) {
+  return podSdk.social.addComment({
+    postId,
+    text: content,
+  });
+}
+
+export async function likePost(postId: number) {
+  return podSdk.social.likePost(postId);
+}
+```
+
+---
+
+### 8. IUMS (Identity & University Management Service)
+
+```typescript
+// app/actions/iums.ts
+'use server';
+
+import { podSdk } from '@/lib/pod';
+
+export async function getStudentByNationalCode(nationalCode: string) {
+  return podSdk.iums.getStudentInformationByNationalCode(nationalCode);
+}
+```
+
+---
+
+## Environment Variables Reference
+
+```env
+# .env.local
+POD_API_TOKEN=your_api_token_here
+POD_CLIENT_ID=your_client_id_here
+POD_CLIENT_SECRET=your_client_secret_here
+POD_PRIVATE_KEY_PEM="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
+```
+
+---
+
+## License
+
+MIT © [Reza](https://github.com/rezamirzapour2)