@rezamirzapour/pod-sdk 1.0.1 → 1.0.2

package/README.md

@@ -389,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 {
@@ -404,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.1",
+  "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",